feat(v3.19): skill_id routing — POST /message/send supports skill_id field; client-directed skill selection (A2A #1989 aligned); 8/8 tests pass

Author: J.A.R.V.I.S.

heartbeat-state.json

@@ -5,9 +5,9 @@
     "calendar": null,
     "weather": null
   },
-  "notes": "2026-06-26 05:34 — 测试轮 Round 47 完成。v3.18 全量回归：196 passed, 0 failed, 8 timeout (test_context_query.py, BUG-026 已知多relay端口竞争). 无新Bug。",
-  "next_round": "research",
-  "today_rounds_completed": 48,
-  "last_research": "scan46",
+  "notes": "2026-06-28 05:34 — 研究轮 scan47 完成。A2A v1.1 规划启动(#1942,21评论)、官方CLI(#1929,17评论)、skill调用标准(#2008)；ANP 多语言SDK 0.8.8；A2A 24.5k stars。",
+  "next_round": "develop",
+  "today_rounds_completed": 49,
+  "last_research": "scan47",
   "pending_push": null
 }

relay/acp_relay.py

@@ -163,7 +163,7 @@
 logging.basicConfig(level=logging.INFO, format="%(asctime)s [acp] %(message)s", datefmt="%H:%M:%S")
 log = logging.getLogger("acp-p2p")
 
-VERSION = "3.18.0"  # v3.18: POST /verify/http-signature — RFC 9421 HTTP Message Signatures; Ed25519 keyid from DID doc; POST /sign/http-request for test/SDK; transport-layer security complementing per-message signing (v3.0); capabilities.http_signatures=true; aligned with A2A #1829
+VERSION = "3.19.0"  # v3.19: skill_id routing — POST /message/send & /tasks/create 支持 skill_id 字段; client-directed skill selection (A2A #1989 aligned); capabilities.skill_id_routing=true
 
 _heartbeat_period_ms = None   # v2.80: optional heartbeat period in ms declared in AgentCard
 
@@ -278,6 +278,7 @@ async def _proxy_ws_connect(uri, **kwargs):
 ERR_CONFIRM_NOT_PENDING  = "ERR_CONFIRM_NOT_PENDING"  # v2.51: task not in input_required/confirmation_pending state
 ERR_SKILL_DEPRECATED     = "ERR_SKILL_DEPRECATED"     # v2.52: informational — skill is deprecated (task still created, warning injected)
 ERR_RATE_LIMIT           = "ERR_RATE_LIMIT"           # v2.53: caller has exceeded skill.rate_limit (429)
+ERR_SKILL_NOT_FOUND      = "ERR_SKILL_NOT_FOUND"      # v3.19: skill_id specified in /message/send but skill not declared in AgentCard (400)
 ERR_ACK_TIMEOUT          = "ERR_ACK_TIMEOUT"          # v3.16: waiting for acp.ack timed out (408)
 
 def _err(code: str, message: str, http_status: int = 400,
@@ -2355,6 +2356,7 @@ def _make_agent_card(name, skills):
             "acp_json_media_type":         True,                               # v3.14: application/acp+json; charset=utf-8 Content-Type support (A2A application/a2a+json aligned)
             "transport_bindings":          True,                               # v3.5: AgentCard.transport_bindings (supported/experimental); --experimental-transport flag (pre-SlimRPC #1723)
             "http_signatures":              True,                               # v3.18: RFC 9421 HTTP Message Signatures — POST /verify/http-signature validates transport-layer Ed25519 signatures; POST /sign/http-request for test/SDK
+            "skill_id_routing":        True,                               # v3.19: skill_id field in /message/send and /tasks/create — client-directed skill selection (A2A #1989 aligned)
         },
 
         "identity": ({
@@ -2457,6 +2459,7 @@ def _make_agent_card(name, skills):
             "jwks":           "/.well-known/jwks.json",  # v2.18: JWKS endpoint (RFC 7517) — public key set for Ed25519 identity
             "http_signatures_verify": "/verify/http-signature",  # v3.18: POST — verify RFC 9421 HTTP Message Signatures (transport-layer Ed25519)
             "http_signatures_sign":   "/sign/http-request",       # v3.18: POST — generate RFC 9421 signature for test/SDK
+            "skill_id_routing":       "/message:send,/tasks/create",  # v3.19: skill_id field supported on these endpoints (A2A #1989 aligned)
         },
     }
     # v0.9: inject capabilities.groups — structured grouping of flat capabilities (A2A v1.0 aligned)
@@ -5680,7 +5683,7 @@ def _append_audit(task: dict, event_type: str, detail: dict | None = None):
     log_list.append(entry)
 
 
-def _create_task(payload, message_id=None, task_id=None, context_id=None, initial_state=None):
+def _create_task(payload, message_id=None, task_id=None, context_id=None, initial_state=None, skill_id=None):
     # BUG-006 fix: honour client-supplied task_id (idempotent — return existing if already known)
     if task_id and task_id in _tasks:
         return _tasks[task_id]
@@ -5704,6 +5707,8 @@ def _create_task(payload, message_id=None, task_id=None, context_id=None, initia
         task["origin_message_id"] = message_id
     if context_id:
         task["context_id"] = context_id
+    if skill_id:
+        task["skill_id"] = skill_id
     if state == TASK_CONFIRMATION_PENDING:
         task["confirmation_required"] = True  # v2.51: flag for callers
     # v2.52: seed audit_log with creation event
@@ -5713,6 +5718,8 @@ def _create_task(payload, message_id=None, task_id=None, context_id=None, initia
     evt: dict = {"task_id": task_id, "state": state}
     if context_id:
         evt["context_id"] = context_id
+    if skill_id:
+        evt["skill_id"] = skill_id
     if state == TASK_CONFIRMATION_PENDING:
         evt["confirmation_required"] = True
     _broadcast_sse_event("status", evt)
@@ -5749,16 +5756,52 @@ def _update_task(task_id, state, artifact=None, error=None, message=None):
         evt: dict = {"task_id": task_id, "state": state, "error": error}
         if ctx:
             evt["context_id"] = ctx
+        task_skill = task.get("skill_id")
+        if task_skill:
+            evt["skill_id"] = task_skill
         _broadcast_sse_event("status", evt)
     if artifact:
         aevt: dict = {"task_id": task_id, "artifact": artifact}
         if ctx:
             aevt["context_id"] = ctx
+        task_skill = task.get("skill_id")
+        if task_skill:
+            aevt["skill_id"] = task_skill
         _broadcast_sse_event("artifact", aevt)
 
     return task
 
 
+def _validate_skill_id(skill_id: str | None, peer_id: str | None = None) -> tuple[bool, str | None]:
+    """v3.19: Validate that a skill_id exists in the peer's AgentCard.
+
+    If skill_id is None or empty → always valid (no routing required).
+    If peer_id is provided → check that peer's agent_card skills.
+    If no peer_id → check this relay's own skills (for self-routing).
+
+    Returns (valid: bool, error_message: str or None)
+    """
+    if not skill_id:
+        return True, None
+
+    skills = []
+    if peer_id and peer_id in _peers:
+        peer_card = _peers[peer_id].get("agent_card") or {}
+        skills = list(peer_card.get("skills", []))
+    else:
+        # No peer_id or peer not found — check this relay's own skills
+        card = _status.get("agent_card") or {}
+        skills = list(card.get("skills", []))
+
+    known_skill_ids = [s.get("id", "") if isinstance(s, dict) else str(s) for s in skills]
+    if skill_id not in known_skill_ids:
+        if peer_id:
+            return False, f"skill_id '{skill_id}' not found in peer '{peer_id}' AgentCard (known: {known_skill_ids})"
+        else:
+            return False, f"skill_id '{skill_id}' not found in AgentCard (known: {known_skill_ids})"
+    return True, None
+
+
 # ══════════════════════════════════════════════════════════════════════════════
 # Persistence
 # ══════════════════════════════════════════════════════════════════════════════
@@ -11970,6 +12013,18 @@ def _do_POST_inner(self):
                 message_id = _explicit_id or _make_id("msg")
                 _client_supplied_id = bool(_explicit_id)
 
+                # ── v3.19: skill_id routing — client-directed skill selection ────────
+                # If skill_id is provided, validate it against peer's AgentCard skills.
+                # If invalid, return 400 ERR_SKILL_NOT_FOUND.
+                _req_skill_id = body.get("skill_id")
+                if _req_skill_id:
+                    _skill_valid, _skill_err = _validate_skill_id(_req_skill_id, peer_id=_req_peer_id)
+                    if not _skill_valid:
+                        e_body, e_code = _err(ERR_SKILL_NOT_FOUND, _skill_err, 400,
+                                              failed_message_id=_client_msg_id)
+                        self._json(e_body, e_code)
+                        return
+
                 # ── v2.32: HTTP-level message idempotency (30s TTL dedup) ────
                 # Only applies when the client supplies their own message_id.
                 # Auto-generated IDs are never duplicates.
@@ -12061,6 +12116,8 @@ def _do_POST_inner(self):
                     msg["task_id"] = body["task_id"]
                 if body.get("context_id"):
                     msg["context_id"] = body["context_id"]
+                if _req_skill_id:
+                    msg["skill_id"] = _req_skill_id  # v3.19: skill_id routing
                 # v2.56: on_behalf_of — OBO principal chain
                 # If caller supplies "on_behalf_of" (str DID or list[str] DIDs),
                 # attach principal_chain to the outgoing message.
@@ -12193,6 +12250,7 @@ def _do_POST_inner(self):
                         "parts":      parts,
                         "task_id":    msg.get("task_id"),
                         "context_id": msg.get("context_id"),   # v2.15: include context_id for context query
+                        "skill_id":   msg.get("skill_id"),     # v3.19: skill_id routing
                         "direction":  "outbound",
                     })
                     # v2.32: store server_seq in dedup cache so replay returns it
@@ -12329,6 +12387,25 @@ def _do_POST_inner(self):
                 # ── Build message_id ───────────────────────────────────────
                 message_id = _client_msg_id or _make_id("msg")
 
+                # ── v3.19: skill_id routing — client-directed skill selection ──────────
+                # When a client specifies skill_id, the message is routed to the target skill.
+                # This complements QuerySkill() (capability query) with actual skill invocation routing.
+                # Aligned with A2A #1989 (Client-directed skill selection).
+                skill_id = body.get("skill_id")
+                if skill_id:
+                    # Validate: skill must be declared in this relay's AgentCard skills list
+                    card_skills = (_status.get("agent_card") or {}).get("skills", [])
+                    declared_skill_ids = set()
+                    for s in card_skills:
+                        if isinstance(s, dict):
+                            declared_skill_ids.add(s.get("id"))
+                    if skill_id not in declared_skill_ids:
+                        e_body, e_code = _err(ERR_SKILL_NOT_FOUND,
+                                              f"skill_id '{skill_id}' not declared in AgentCard",
+                                              400, failed_message_id=_client_msg_id)
+                        self._json(e_body, e_code)
+                        return
+
                 # ── Construct Direct Message response ──────────────────────
                 # Aligned with A2A Message data model:
                 # { message_id, context_id?, task_id?, role, parts[], metadata? }
@@ -12346,11 +12423,13 @@ def _do_POST_inner(self):
                 task_id = body.get("task_id")
                 if task_id:
                     dm_response["task_id"] = task_id
+                if skill_id:
+                    dm_response["skill_id"] = skill_id
                 metadata = body.get("metadata")
                 if metadata and isinstance(metadata, dict):
                     dm_response["metadata"] = metadata
 
-                log.debug(f"[direct_message] {message_id} role={role_raw} parts={len(parts)}")
+                log.debug(f"[direct_message] {message_id} role={role_raw} parts={len(parts)} skill_id={skill_id or 'none'}")
                 self._json(dm_response, 200)
 
             except Exception as e: