Server helpers should adapt response shape by requested AdCP version and advertise exact 3.1 support

[bokelley]

Summary

Python seller/server helpers should make 3.0/3.1 version compatibility automatic:

• If the buyer omits an exact AdCP version, default to legacy 3.0 semantics.
• If the buyer explicitly requests 3.1, return the 3.1 response shape.
• Capabilities should advertise exact supported spec versions, not only major_versions: [3], so buyers/storyboards can select the right contract.

Why this matters

AdCP 3.1 beta splits protocol envelope status from media-buy lifecycle status. For example, create_media_buy in 3.1 should return:

{
  "status": "completed",
  "media_buy_status": "pending_creatives"
}

Legacy 3.0 buyers/storyboards expect the media-buy lifecycle at top-level status:

{
  "status": "pending_creatives"
}

If a seller always returns the 3.1 shape, 3.0 storyboards fail. If a seller always returns the 3.0 shape, 3.1 schemas fail. The server layer needs a consistent way to resolve the requested spec version and serialize the response accordingly.

Observed behavior

In a Sales Agent integration using Python SDK adcp==6.1.0b2:

adcp.__version__ = 6.1.0b2
get_adcp_spec_version() = 3.1.0-beta.3

Capabilities exposed to the JS storyboard runner contain only:

{
  "adcp": {
    "major_versions": [3]
  }
}

That is not enough to distinguish 3.0.x from 3.1 beta.

When the seller returns the 3.1 shape unconditionally, the 3.0 storyboard runner (@adcp/sdk 7.10.2, schemas 3.0.12) fails on lifecycle status:

media_buy_seller/pending_creatives_to_start/create_buy_no_creatives:
Status is pending_creatives because no creatives supplied at /status
expected=pending_creatives actual=completed

The 3.1 beta runner (@adcp/sdk 8.1.0-beta.9, schemas 3.1.0-beta.3) no longer fails on that status/media_buy_status split.

Expected behavior

Python server/seller support should provide a standard version negotiation path:

1. Resolve the buyer-requested AdCP version from request metadata/fields/headers using a single helper.
2. Treat omitted version as legacy 3.0 compatibility, because 3.0 buyers predate exact 3.1 negotiation.
3. Serialize create/update media-buy responses using top-level lifecycle status for 3.0 buyers.
4. Serialize create/update media-buy responses using envelope status plus media_buy_status for 3.1 buyers.
5. Advertise exact supported versions in capabilities if the 3.1 capability schema has a field for it, or add one if it does not.

Related JS runner issue

Filed the paired storyboard-runner issue here:

adcontextprotocol/adcp-client#1987

[bokelley]

Triage

Classification: Bug (real 3.0 storyboard failures) + Feature (version negotiation plumbing)
Bucket(s): handlers, middleware (labels not yet in repo — noted in run summary)
Status: ready-to-implement

What the experts said:

• code-reviewer: The fix belongs in _normalize_response_envelope (mcp_tools.py), not in the response builders — the normalization function already runs after the dict is returned and overwrites status; adding a requested_version kwarg only to the builders creates a false API surface that gets clobbered at the wire boundary.
• dx-expert: detect_wire_version in adcp.validation.envelope already collapses both adcp_version (string) and adcp_major_version (int) into a release-precision string — re-export it from adcp.server rather than creating a parallel helper, which would split the symbol space for agents and humans alike.
• ad-tech-protocol-expert: Critical protocol correction — the spec (core/version-envelope.json) says "When omitted, the seller assumes its highest supported version," not 3.0. The correct default is to serve 3.1 shape; 3.0 buyers must explicitly request it via adcp_version: "3.0" or adcp_major_version: 3. Also: major_versions cannot be dropped — servers MUST continue emitting it alongside supported_versions through all of 3.x per the 3.1 schema deprecation note.

My take: The observable bug is confirmed — _normalize_response_envelope currently promotes unconditionally to 3.1 shape without inspecting the buyer's requested version; a 3.0 buyer sending adcp_major_version: 3 will always receive the wrong shape. The fix is a well-scoped, non-breaking addition: wire the already-available detect_wire_version into the normalization path and extend auto-capabilities to declare supported_versions. The protocol expert's inversion of the default (3.1-when-omitted, not 3.0-when-omitted) is the only significant departure from the issue's proposed design.

Implementation scope (non-breaking):

• src/adcp/server/mcp_tools.py — _normalize_response_envelope (line 49): Call detect_wire_version(raw_params) to resolve the buyer's requested version. When the resolved version is "3.0" (i.e., buyer sent adcp_major_version: 3 with no adcp_version string, or sent adcp_version: "3.0"), emit the 3.0 shape (status = lifecycle_status, omit media_buy_status). When 3.1 or omitted (no version signal → seller's highest = 3.1), emit the current 3.1 shape. detect_wire_version is already importable from adcp.validation.envelope.
• src/adcp/server/__init__.py: Re-export detect_wire_version as resolve_requested_adcp_version (one-liner) for adopter use in handler methods; document that it handles both adcp_version string and adcp_major_version integer.
• src/adcp/server/builder.py — ADCPServerBuilder.build_handler (line 177): In the auto-capabilities handler, add supported_versions=list(COMPATIBLE_ADCP_VERSIONS) alongside the existing adcp_version=pinned_version. Also ensure major_versions=[3] is still emitted (it's the capabilities_response default, so no change needed there). COMPATIBLE_ADCP_VERSIONS is importable from adcp._version.
• Tests: Add unit tests for _normalize_response_envelope with adcp_major_version: 3 params (expect 3.0 shape) and with omitted version (expect 3.1 shape); add a test that ADCPServerBuilder.build_handler() auto-capabilities includes supported_versions with both "3.0" and "3.1".
• Required checks: pytest tests/ (full non-integration tier), mypy src/adcp/server/, ruff check src/. No dep version bumps, no generated-code edits, no changes to .github/ or pyproject.toml.

---

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

---

Generated by Claude Code

[bokelley]

Update after adcp==6.1.1b2 and @adcp/sdk@8.1.0-beta.10:

Container/runtime confirms:

adcp.__version__ = 6.1.1b2
get_adcp_spec_version() = 3.1.0-beta.3

3.1 beta storyboard runner now behaves consistently across transports:

@adcp/sdk@8.1.0-beta.10 / AdCP 3.1.0-beta.3
MCP: 37 passed, 1 failed, 52 skipped
A2A: 37 passed, 1 failed, 52 skipped

The only 3.1 failure is local seller policy, not version serialization:

media_buy_seller/dependency_impairment_cardinality/create_buy_two_packages:
INVALID_REQUEST: Duplicate product_id(s) found in packages: demo_display_300x250.

3.0 runner results with the same Python SDK are still not passing:

@adcp/sdk@7.11.0 / AdCP 3.0.12
MCP: 11 passed, 6 failed, 42 skipped
A2A: 26 passed, 2 failed, 31 skipped

Notably, the MCP 3.0 failures now show the server returning legacy-style lifecycle status:

{
  "media_buy_id": "...",
  "packages": [...],
  "status": "pending_creatives",
  "context": {"correlation_id": "..."}
}

but the runner reports output validation errors against /schemas/3.0.12/media-buy/create-media-buy-response.json:

Output validation error: {... 'status': 'pending_creatives', ...} is not valid under any of the given schemas

So 6.1.1b2 appears to have improved/adapted part of the 3.0 serialization path, but there is still a cross-SDK/schema mismatch for legacy 3.0 storyboard validation. The Python side still needs a clear, documented version-resolution contract: omitted exact version means legacy 3.0 behavior, explicit 3.1 means 3.1 envelope + media_buy_status, and capabilities should advertise exact supported spec versions where available.

[bokelley]

Follow-up from the Sales Agent beta integration: #866 tracks the remaining MCP outputSchema validation mismatch after the 6.2.0b3 resolver work. The server is returning the negotiated 3.0 media-buy status shape, but MCP tool output validation still rejects it against the generated success schema.

[bokelley]

One more follow-up from the same integration pass: #868 tracks making this automatic in server dispatch. #855 gave adopters the resolver, but Sales Agent still has generic protocol code in its delegate to resolve/request-shape media-buy responses by version; that should eventually move into the SDK so seller handlers stay business-logic only.