fix(server): echo request context on AdcpError error envelopes

[bokelley]

Closes #557

Summary

Fixes a context-passthrough gap on the AdcpError raise path. The success path runs inject_context(raw_params, response) so a request's context extension echoes back to the buyer. The error path built the structured adcp_error envelope without doing the same — buyers lost correlation IDs and idempotency hints across the raise-AdcpError boundary, and three storyboard runners were failing on this assertion.

What changed

• build_mcp_error_result(exc, params=None) now accepts the raw request dict. When supplied, it runs inject_context on the structuredContent dict so context lands as a sibling of adcp_error, mirroring the success path's wire shape.
• MCP catch sites (src/adcp/server/serve.py) pass kwargs through on both branches — the ADCPError catch and the decisioning-AdcpError re-projection.
• ADCPAgentExecutor._send_adcp_error(...) now accepts params and runs inject_context on the DataPart payload before sending the failed task.
• execute() in the A2A executor passes the parsed params into _send_adcp_error.

The change is backwards-compatible: both new params are optional. Existing callers (proxies, custom transports invoking build_mcp_error_result directly) keep working without context echo until they wire it through.

Tests

• tests/test_mcp_structured_error.py — added TestBuildMcpErrorResultContextEcho (4 unit tests) covering: no params, params without context, params with context, sibling-not-nested placement; plus an end-to-end test_context_echo_round_trips_through_register_tool.
• tests/test_a2a_structured_error.py — added 3 executor-level tests covering: echo on raise, no-context omission, sibling-not-nested placement.
• All 29 MCP + 14 A2A structured-error tests pass; wider regression run on tests/test_translate.py + tests/test_a2a_server.py + tests/test_server_helpers.py (128 tests) green.

Test plan

• pytest tests/test_mcp_structured_error.py tests/test_a2a_structured_error.py — pass
• pytest tests/test_translate.py tests/test_a2a_server.py tests/test_server_helpers.py — pass
• ruff check — pass
• pre-commit (black, ruff, mypy, bandit) — all hooks pass
• Storyboard runners pick up the fix on the 3 previously-failing assertions

🤖 Generated with Claude Code

[bokelley]

Updated based on expert review (code-reviewer + ad-tech-protocol-expert):

Expanded scope: code review caught that the A2A success path (_send_result) also skips inject_context — the original PR would have left a strange asymmetry (context echoed on A2A errors, dropped on A2A successes). Fixed in the same PR since it's the same bug class and a one-line addition; updated docstrings/tests accordingly.

Other review fixes:

• build_mcp_error_result(exc, *, params=None) is now keyword-only — locks the API shape against future positional drift.
• Added 64KB-cap drop test on the error path so the security note about buyer-controlled context size is enforced by a test, not just the docstring.
• Added A2A success-path echo + no-context-omission tests.

Open question for reviewer: ad-tech-protocol-expert flagged that transport-errors.mdx couldn't be fetched to confirm normative wire shape (sibling vs. nested). The PR matches the success-path convention (context at structuredContent / DataPart top level, not inside adcp_error), which is the safest reading. If upstream spec disagrees we'd want to align there before merging.

[bokelley]

On the open wire-shape question: ran a second pass with ad-tech-protocol-expert specifically on sibling vs. nested placement. Verdict: sibling is correct — proceed with confidence.

Three reasons:

1. inject_context() is a top-level key injector by design (response["context"] = ctx). Calling it on {"adcp_error": {...}} is exactly the intended usage — there's no alternative injection point, and it guards against double-injection.
2. The success-path convention is {"products": [...], "context": {...}}. Placing context alongside adcp_error rather than inside it keeps the envelope shape symmetric across both outcomes: context is always a sibling of the payload key, never nested within it.
3. adcp_error is a typed schema object with defined fields (code, message, recovery, field, suggestion, retry_after, details). Injecting context inside it would mutate that schema to carry an opaque, variable-size blob — the schema-fidelity violation is the nesting case, not the sibling case.

One scoping note the expert raised (not a blocker): verify params in _send_adcp_error is the parsed wire-request dict that carries the context field, not a reduced/re-projected view. Checked the diff — execute() passes params directly through, so this is already correct.

The transport-errors.mdx fetch failure remains unresolved, but the symmetry argument is strong enough that this shouldn't block merge — if the spec later specifies nesting (which would be unusual given how context-passthrough is defined), it'd be a one-line fix.

---

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

---

Generated by Claude Code

[bokelley]

Two pre-merge follow-ups noted by @bokelley (filed as no-triage):

• verify: dispatcher non-AdcpError wrap path preserves context echo on error #562 — verify dispatcher non-AdcpError wrap path preserves context echo (any code path between handler and serve.py:1798 that re-raises a non-DecisioningAdcpError skips the new echo).
• feat: TaskHandoff registry.fail path should echo request context (PR #560 follow-up) #563 — TaskHandoff background-task failures route through registry.fail and aren't touched by this PR. Same fix shape needed there.

Shipping this PR now and tracking those two separately.