feat(server/a2a): structured error parity with MCP — emit field/details/retry_after, catch decisioning AdcpError

[bokelley]

Motivation

PR #525 (closes #509) shipped structured `adcp_error` envelopes on the MCP side — `CallToolResult.structuredContent.adcp_error` now carries the full structured shape (`code`, `message`, `recovery`, `field`, `details`, `retry_after`).

The A2A surface in `src/adcp/server/a2a_server.py` has two parity gaps that would make A2A storyboards (when they exercise structured error checks) report "actual: ..." failures the same way the MCP side did before #509:

1. `_send_adcp_error` only catches `adcp.exceptions.ADCPError`. Decisioning-layer `AdcpError` raises (which adopters using `DecisioningPlatform` produce) fall into the generic `except Exception` and render as a plain "Skill execution failed" text message — losing the structured shape entirely.

2. It only emits `code` / `message` / `recovery` / `suggestion`. The fields `field`, `details`, and `retry_after` are dropped from the wire envelope even when the raised error carries them. MCP's feat(server): MCP error responses populate structuredContent.adcp_error (closes #509) #525 fix populates all of them.

Why this matters

Structured A2A error envelopes are a wire-spec thing — buyers using A2A clients should get the same `adcp_error` shape as MCP buyers. Storyboards graded against A2A-served sellers will surface this gap as a wire-conformance failure once the storyboard runner's structured-error checks are run against A2A surfaces (or the same checks via #1527's storyboard runner UX work).

Proposed fix

Mirror PR #525's MCP path:

1. Catch decisioning-layer `AdcpError` AND `ADCPError` together in the A2A handler. Same field-extraction logic (`_extract_structured_fields`) feat(server): MCP error responses populate structuredContent.adcp_error (closes #509) #525 factored into `translate.py` can be reused — both projections feed off the same source-of-truth shape.

2. Populate the full envelope. The A2A `DataPart` for the failed-task envelope should carry `{code, message, recovery, field, details, retry_after}` whenever the raised error has those fields populated; omit when None.

3. Add tests parametrized over the same code set as MCP (`MEDIA_BUY_NOT_FOUND`, `PACKAGE_NOT_FOUND`, `TERMS_REJECTED`, `BUDGET_TOO_LOW`) verifying the A2A `DataPart` carries all fields.

Should be ~50 LOC + tests, mirrors the structure of the MCP fix.

Refs

• PR feat(server): MCP error responses populate structuredContent.adcp_error (closes #509) #525 — MCP-side fix (closed feat(server): MCP error responses must populate structuredContent.adcp_error.code (not just text) #509). `_extract_structured_fields` + `build_mcp_error_result` are reusable.
• PR feat(server): MCP error responses populate structuredContent.adcp_error (closes #509) #525 agent's followup observation: "A2A parity status: needs follow-up issue (not blocking feat(server): MCP error responses must populate structuredContent.adcp_error.code (not just text) #509)"
• adcp-client#1527 — upstream storyboard runner UX. When the runner adds structured-error checks to A2A storyboards, this gap becomes a wire-conformance failure.

[bokelley]

Triage

Classification: Bug (wire-conformance gap — A2A adcp_error envelope missing fields present on MCP path)
Bucket(s): handlers (note: handlers label not found in repo — flagged for run summary)
Status: drafting-pr
Milestone: (omitted — no target version named)

What the experts said:

• code-reviewer: approved — no blockers; nits on lazy-import duplication and exc: Any footgun for future callers (both deferred)
• ad-tech-protocol-expert: one blocker fixed before push — recovery must be emitted unconditionally to match transport-errors.mdx §A2A Binding; fixed in final diff

My take: Straightforward parity fix mirroring what #525 did for MCP. _extract_structured_fields from translate.py handles all three exception shapes; the A2A path now delegates to it and emits the full {code, message, recovery, field, details, retry_after} envelope. Non-breaking addition.

PR: #542 — catch decisioning AdcpError in execute() + emit full structured envelope via _extract_structured_fields

---

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

---

Generated by Claude Code