design: AdCP tasks/get tool vs A2A native tasks/get JSON-RPC method — collision and lifecycle semantics

[bokelley]

Context

Discovered while reviewing PR #968 (closed). The SDK currently routes tasks/get through ProtocolClient.callTool for both MCP and A2A (src/lib/core/TaskExecutor.ts:1293). For A2A, this dispatches as message/send { skill: 'tasks/get' }.

Tension

AdCP 3.0 defines tasks/get as a buyer-callable tool with bundled request/response schemas at schemas/cache/<v>/bundled/core/tasks-get-{request,response}.json. The tool tracks AdCP work lifecycle (submitted/working/completed/failed/etc on the actual buyer task), which is what buyers need.

A2A 0.3.0 defines tasks/get as a native JSON-RPC method (alongside message/send, tasks/cancel, etc). On the wire, native A2A tasks/get polls TRANSPORT-call lifecycle — for AdCP submitted-arm sellers, Task.state is always 'completed' because the message was successfully accepted; the work lifecycle lives in the artifact.

These are different surfaces tracking different lifecycles. The names collide.

Failure modes

1. Seller built on @a2a-js/sdk's DefaultRequestHandler: the SDK routes JSON-RPC method names directly. A buyer sending message/send { skill: 'tasks/get' } may surface as a method-not-found from the seller's tool registry, even though the AdCP-tool implementation exists in the seller's handler chain.

2. Buyer using A2A native tasks/get: gets transport-state, not AdCP work-state. Submitted arms always look "completed" — wrong polling lifecycle, breaks SubmittedContinuation.waitForCompletion().

Possible resolutions

• (A) Sellers register the same handler under both surfaces (AdCP tool + A2A native method). The SDK could probe via tools/list on first call and prefer the AdCP-tool path when present.
• (B) AdCP spec asserts that A2A sellers MUST route the native tasks/get JSON-RPC to the AdCP work-lifecycle handler (i.e., make the native method an AdCP-defined surface). Rename to disambiguate downstream.
• (C) The SDK probes capability and uses native A2A tasks/get only when the seller advertises it as a polling method (e.g., capability flag), defaulting to the AdCP-tool path.
• (D) Status quo: tool-only path on ProtocolClient.callTool, document that A2A sellers MUST register tasks/get as a buyer-callable tool over message/send.

Prior art

PR #968 (closed) implemented (C)-ish but only the native-A2A side, without the capability probe. The expert reviews flagged the rationale was sound but the path bypassed AdCP's work-lifecycle semantics.

Action

1. Discuss with adcontextprotocol/adcp maintainers — this is upstream design.
2. Once resolved, update getTaskStatus to match the chosen path.
3. Defensive fix worth applying independently of the design question: cherry-pick the typeof-guard from PR fix(protocols): use native A2A tasks/get JSON-RPC for polling (#963) #968's ca513b27 to mapTasksGetResponseToTaskInfo so non-string status values don't silently mis-compare against ADCP_STATUS.*.

[bokelley]

Triage

Classification: Design / RFC — A2A–AdCP protocol naming collision, with an embedded upstream spec gap
Bucket(s): library, cross-repo (neither label found in repo — flagged in run summary)
Status: ready-for-human

What the experts said:

• ad-tech-protocol-expert: Option D (tool-only path + docs) is most spec-aligned today; blocker — AdCP 3.0 contains no normative MUST requiring A2A sellers to register tasks/get as an AdCP tool, so any client-side resolution of options A/B/C would be opinion baked into the SDK without spec backing; file upstream on adcontextprotocol/adcp first.
• code-reviewer: Item 3 (defensive typeof-guard) is already present — mapTasksGetResponseToTaskInfo uses stringField(flat.status) ?? 'unknown' (line 123) where stringField does typeof value === 'string'; no non-string status can reach an ADCP_STATUS.* comparison; no code change needed.
• adtech-product-expert: Design-debt, not an immediate production blocker — the SDK routes correctly today via message/send; the breakage scenario arises when buyers use native A2A tooling (outside this SDK) to poll task state, which is forward-looking risk.

My take: The three-expert panel converges: item 3 is already resolved by existing code; items 1–2 need an upstream issue on adcontextprotocol/adcp to establish whether A2A sellers are normatively required to register tasks/get as a buyer-callable AdCP tool — without that spec anchor, any client change (A/B/C) bakes in opinion. Recommend opening that upstream issue and linking it here so this resurfaces once the spec call is made.

---

Triaged by Claude Code. Session: https://claude.ai/code/session_01HiTwBX6hniPykRkLWD1HPE

---

Generated by Claude Code