A2A-native clients: Submitted envelopes don't set A2A Task state

[bokelley]

Context

When a handler returns (or the framework narrows to) an AdCP Submitted envelope via `createAdcpServer`, the payload lands on the wire as:

```json
{
"content": [{ "type": "text", "text": "Task tk_xyz submitted" }],
"structuredContent": { "status": "submitted", "task_id": "tk_xyz", "message": "..." }
}
```

MCP-based clients detect async by reading `structuredContent.status === 'submitted'` per the AdCP `protocol-envelope.json` contract — that works today.

Gap

A2A-native clients (anything consuming the agent over A2A's JSON-RPC transport rather than MCP) expect async work to be signaled via A2A's own `Task` state model — `state: 'submitted' | 'working' | 'input-required' | 'completed' | 'failed' | ...`. They poll on A2A's `tasks/get` using the A2A `Task.id`, not on AdCP's `task_id` field.

Right now `src/lib/server/create-adcp-server.ts`'s `wrapSubmittedEnvelope` only mirrors the AdCP payload onto `structuredContent`; there's no A2A adapter path that also emits a `TaskStatusUpdateEvent` (or picks `state: 'submitted'` on the A2A `Task` artifact) so A2A-native clients can discover this is async and needs polling. A2A clients currently get a `completed` `Task` whose artifact carries `status: 'submitted'` in-band — they'd need AdCP-aware parsing to realize the work isn't actually done.

Scope

Flagged during ad-tech-protocol-expert review on #874. Out of scope for that PR (which widened handler return types but didn't touch transport). Needs a coordinated change across:

• `src/lib/server/create-adcp-server.ts` dispatcher (ideally emits a protocol-neutral signal)
• `src/lib/server/serve.ts` / `express-adapter.ts` (MCP-side, unchanged)
• Whatever A2A adapter sits alongside `createAdcpServer` (out-of-tree today — likely lives in `scope3data/agentic-adapters` or similar downstream consumers; check whether `@adcp/client` should own a first-party A2A serve adapter)

Related

• PR feat(sdk): address 5.15.0 DX feedback on handler types, error shape, extraction #874 (widened handler return types, added Submitted-arm narrowing)
• AdCP 3.0 `schemas/cache/3.0.0/core/protocol-envelope.json` (the `status` discriminant)
• `@a2a-js/sdk` `TaskStatusUpdateEvent` / `Task.state` enum

Acceptance

An A2A-native client calling a tool whose handler returns `{ status: 'submitted', task_id }` should observe A2A `Task.state === 'submitted'` (not `'completed'`) on the response, and be able to poll the same A2A `Task.id` to completion.

[bokelley]

Triage

Classification: Bug + feature request (A2A server transport gap)
Bucket(s): library, docs (neither label exists in repo — gap noted in run summary)
Status: ready-for-human

What the experts said:

• ad-tech-protocol-expert: state: 'completed' is a protocol lie; state: 'submitted' is the correct mapping — but AdCP task_id and A2A Task.id are separate ID spaces (AdCP task_id must be carried as artifact metadata, not reused as Task.id); A2A's tasks/get polling contract requires a task-store bridge because AdCP completion is push-only via webhooks — three blockers before implementation.
• code-reviewer: the right extension point is an optional onSubmittedResult callback on AdcpServerConfig (fires inside the per-tool closure after wrapSubmittedEnvelope, not on AdcpPreTransport); alternatively a ADCP_SUBMITTED_ENVELOPE symbol stamp is a zero-API-surface alternative; wrap-envelope.ts:6 docstring claims "MCP or A2A handlers" but A2A server is not implemented — misleads builders.
• dx-expert: serveA2A() is the wrong first move; a thin dispatchToA2A helper is cleaner; docs/guides/BUILD-AN-AGENT.md and docs/llms.txt both silently omit the MCP-only server constraint — A2A builders will generate broken code from those docs.

My take: All three agree on the diagnosis and on "minimal hook first, not full transport" — but split on hook shape (symbol vs. callback vs. dispatchToA2A). The task_id↔Task.id identity gap and the polling-vs-push bridge are load-bearing correctness decisions that need an explicit owner. @bokelley — doc fixes (BUILD-AN-AGENT.md, llms.txt, wrap-envelope.ts docstring) are ready to execute now; which hook interface do you want to commit to for the code side?

---

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

---

Generated by Claude Code

[bokelley]

Closed — superseded by adcp-client#899 (A2A serve adapter) and the #971/#979/#981/#980 polling-cycle work.

The acceptance criterion in this issue was based on a reading of A2A 0.3.0 that turned out to be wrong: 'submitted' is the initial lifecycle state, not a terminal state, so emitting state: 'submitted' with final: true would violate the spec. The protocol expert review on #952 confirmed this.

The actual architecture: A2A Task.state reflects the HTTP-call lifecycle ('completed' for AdCP submitted arms); the AdCP work lifecycle lives on artifact.parts[0].data.status ('submitted' / 'working' / 'completed'). A2A buyers read the AdCP layer for work-status polling.

This is now wired end-to-end:

• adcp-client#899 — createA2AAdapter produces the post-feat(server): A2A transport adapter (preview) peer to MCP serve() #899 wire shape
• adcp-client#971 (fix(core): pollTaskCompletion uses local UUID instead of server-assigned task ID #966 + fix(core): AdCP tasks/get polling — fix param naming, response mapping, drop wrong-lifecycle MCP-experimental primary path #967) — buyer-side server-task-id plumbing + AdCP tasks/get polling
• adcp-client#981 (fix(core): A2A submitted-arm responses misclassified as completed by responseParser #973) — buyer-side parser reads AdCP work-layer fields from A2A wrapped Task responses
• adcp-client#979 (feat(testing): a2a_context_continuity validator for multi-step storyboards #962) — a2a_context_continuity cross-step storyboard validator
• adcp-client#980 (fix(core): pollTaskCompletion doesn't handle rejected | input-required | auth-required terminal/paused states #977) — pollTaskCompletion handles all non-progressing statuses
• feat(compliance): add create_media_buy async submitted → completed storyboard adcp#3083 — create_media_buy_async_submitted storyboard
• feat(schema): add result and include_result to tasks/get adcp#3126 — typed tasks/get include_result/result fields

A real submitted → completed roundtrip over A2A now works end-to-end against any createA2AAdapter-backed seller (verified by test/server-a2a-submitted-end-to-end.test.js).