A2A 1.0 follow-ups: wrapper policy, webhook envelope, test coverage

[bokelley]

Follow-up issue after PR #261 landed the a2a-sdk 1.0 migration. Reviewing against the A2A 1.0 extraction/placement rules that just landed in the adcp spec+docs repo (see bokelley/a2a-1.0-update — docs PR pending), we found two policy conflicts and three test-coverage gaps worth addressing.

Some of these may resolve cleanly when a2a-sdk 1.0.1 ships upstream — the shim layer in tests/a2a_compat_shim.py and the MessageToDict post-processing dance are the kind of thing that gets smaller as the Python SDK matures. Suggest revisiting this list after the next upstream drop before committing to any of the fixes.

Policy conflicts (need alignment across repos)

1. Wrapper policy — docs say reject, Python unwraps silently

adcp docs (a2a-response-extraction.mdx) state the normative rule clients MUST throw or log when a DataPart's .data is a single-key { response: {...} } wrapper — it's a server-side bug.

This PR continues to silently unwrap in _extract_result_from_task and _process_task_response (src/adcp/protocols/a2a.py), and test_extract_from_a2a_with_response_wrapper / test_extract_from_a2a_with_nested_response_wrapper actively assert unwrap behavior.

Options:

• Soften the docs to "MAY unwrap with warning; MUST NOT silently consume in strict mode." Matches deployed Python behavior and preserves pressure on buggy servers without breaking consumers that already rely on forgiving extraction.
• Flip Python to reject. Aligns with current docs but risks breaking any production buyer relying on the forgiving behavior.

Leaning toward softening the docs — but wanted to surface the divergence.

2. Webhook envelope wrapping — docs say StreamResponse-wrapped, Python emits bare

adcp docs state push-notification payloads use the A2A 1.0 StreamResponse wrapper ({ task } / { statusUpdate } / { artifactUpdate } / { message }), citing A2A 1.0 §4.3.3.

This PR emits bare Task and TaskStatusUpdateEvent in create_a2a_webhook_payload (src/adcp/webhooks.py) — looks like an intentional choice for v0.3 consumer compat.

Action: direct re-read of A2A 1.0 §4.3.3. If wrapping is normative, Python needs a future fix (potentially controlled by the same enable_v0_3_compat flag so 0.3 consumers keep the bare shape). If peer-choice, adcp docs should note Python emits bare for compat and new servers SHOULD wrap.

Test coverage gaps

3. No extraction tests for rejected / auth-required

The tolerant enum maps (src/adcp/protocols/a2a.py, src/adcp/webhooks.py) include both new 1.0 states, but no test asserts adcp_error extraction from a TASK_STATE_REJECTED artifact DataPart, or auth-challenge extraction from a TASK_STATE_AUTH_REQUIRED status message.

adcp repo has vectors for both — worth mirroring in the Python test suite.

4. No integration test for 1.0 client → 0.3 server

tests/integration/test_a2a_wire_compat.py covers 0.3 client → 1.0 server (the deployment direction most likely to break). The reverse — 1.0 Python client talking to a 0.3-only peer via force_a2a_version=\"0.3\" — has unit coverage of the version-filter logic but no end-to-end regression guard.

5. CHANGELOG 4.1.0 should flag subclasser breakage

The 4.1.0 release is pragmatically a minor bump given near-zero A2A adopter population, but subclassers face breaking changes:

• a2a.utils.errors.ServerError → A2AError
• get_agent_info() no longer returns adcp_version / protocols_supported
• a2a-sdk type import paths shifted

Worth a top-level entry in CHANGELOG 4.1.0 so downstream integrators see it.

Related

• adcp spec+docs: bokelley/a2a-1.0-update branch (PR pending)
• Original PR: feat(a2a): migrate to a2a-sdk 1.0 with 0.3 wire-compat shim (Release-As: 4.1.0) #261
• A2A 1.0 milestone context: https://medium.com/google-cloud/the-a2a-1-0-milestone-ensuring-and-testing-backward-compatibility-4aadb007c49b

🤖 Filed with Claude Code after expert review of the 1.0 migration.

[bokelley]

/triage

[bokelley]

Triage

Classification: bug + docs (multi-item follow-up)
Bucket(s): client (a2a), docs — no matching label in repo, see run-summary gap note
Status: drafting-pr (items 4 + 5); ready-for-human (items 1, 2, 3)
Milestone: none declared

What the experts said:

• ad-tech-protocol-expert: items 1–2 NEEDS-CROSS-REPO (docs PR on bokelley/a2a-1.0-update + §4.3.3 re-read are blockers); item 3 is correctness but BREAKING (flips status == SUBMITTED branches to FAILED for existing callers); item 4 SAFE-TO-SHIP.
• code-reviewer: ship reverse e2e (items 4) now; defer CHANGELOG 4.1.0 hand-edit — release-please owns CHANGELOG.md, use a named migration file instead; item 3 tests codify a bug either way without a maintainer call on classification.
• dx-expert: subclassers hit ImportError / KeyError and grep the repo — a named MIGRATION_v4_0_to_v4_1.md is the grep-able artifact, CHANGELOG notes get lost in feature-commit noise.

My take: Shipping items 4 (1.0→0.3 reverse-direction e2e) and 5 (as MIGRATION_v4_0_to_v4_1.md, not a CHANGELOG edit) in #268 — both purely additive, non-breaking, independent of the a2a-sdk 1.0.1 drop. Items 1, 2, 3 stay open on this issue as you suggested pending the upstream drop and the docs branch landing.

One-line PR summary: adds reverse-direction wire-compat tests + subclasser migration doc covering ServerError→A2AError, get_agent_info() trim, and proto import-path shifts.

---

Triaged by Claude Code. Session: https://claude.ai/code/${CLAUDE_CODE_REMOTE_SESSION_ID}

---

Generated by Claude Code

[bokelley]

/triage

[bokelley]

Triage

Classification: Bug (items 1–3), Feature request (item 4), Documentation (item 5)
Bucket(s): client (items 1, 3, 4), cross-repo (items 1, 2), docs (item 5)
Status: drafting-pr (item 3) / ready-for-human (items 1, 2, 4, 5)

What the experts said:

• ad-tech-protocol-expert: Item 1 is a cross-repo normative conflict that needs a deliberate policy decision — there is also a narrower code bug independent of the policy question ("response" in data check lacks the len == 1 guard that the webhook path already has). Item 2 needs spec confirmation on whether A2A 1.0 §4.3.3 is normative for webhook POST bodies (not just SSE streaming).
• code-reviewer: Item 3 is non-breaking and straightforward using existing fixtures; item 4 requires a custom 0.3-only server fixture that doesn't exist — significant infrastructure for marginal coverage gain.
• docs-expert: CHANGELOG.md is bot-managed (release-please would clobber a direct edit); MIGRATION_v3_to_v4.md is the right venue for item 5 but needs confirmation that it's sufficient.

My take: Item 3 is clearly executable and shipped as PR #270 (3 new tests documenting current TaskResult behavior for rejected/auth-required, including the adcp_error DataPart gap). Items 1, 2, 4, 5 need @bokelley's call before any code changes.

---

Item 3 — done: #270

Tests assert TaskResult(status=SUBMITTED, data=None, metadata={"status": "rejected"/"auth-required"}) for both states. A gap-documenting test shows that a REJECTED task's adcp_error DataPart is silently dropped today.

---

Items 1, 2, 4, 5 — flagged for @bokelley

Item 1 — wrapper policy: Two separable questions:

1. Code bug (narrower): _extract_result_from_task uses if "response" in data with no len == 1 guard, so multi-key dicts containing response silently drop sibling keys. The webhook path (extract_webhook_result_data) correctly gates on len == 1. Fixing the client extraction to match is non-breaking for any payload that was a genuine single-key wrapper, but is a behavior change for multi-key payloads. Should we align the client to len == 1 before the broader policy question is settled?

2. Normative policy: Docs say MUST reject/log; Python silently unwraps. The soften-docs path ("MAY unwrap with warning; strict-mode MUST NOT") preserves deployed behavior. Does the 1.0 spec intend strict rejection or is MAY-with-warning acceptable?

Item 2 — webhook envelope: Does A2A 1.0 §4.3.3 normatively require StreamResponse wrapping for HTTP push payloads (not just SSE streaming)? If yes, the enable_v0_3_compat flag pattern is the right dual-serving path. Can you confirm the normative scope of §4.3.3?

Item 4 — 1.0 client → 0.3 server integration test: Would require a bespoke hand-crafted 0.3 JSON-RPC server fixture (the SDK has no 0.3-only server mode). Is this worth the infrastructure investment, or does the existing force_a2a_version unit coverage suffice?

Item 5 — CHANGELOG / migration note: CHANGELOG.md is owned by release-please and editing it now would be clobbered when the 4.1.0 release PR is generated. MIGRATION_v3_to_v4.md (adding a ## Migrating to 4.1.0 section for subclassers) is the right venue. Is that sufficient, or do you also want a note staged for the release-please PR?

---

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

---

Generated by Claude Code