You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Server helpers should adapt response shape by requested AdCP version and advertise exact 3.1 support #851
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:
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:
Resolve the buyer-requested AdCP version from request metadata/fields/headers using a single helper.
Treat omitted version as legacy 3.0 compatibility, because 3.0 buyers predate exact 3.1 negotiation.
Serialize create/update media-buy responses using top-level lifecycle status for 3.0 buyers.
Serialize create/update media-buy responses using envelope status plus media_buy_status for 3.1 buyers.
Advertise exact supported versions in capabilities if the 3.1 capability schema has a field for it, or add one if it does not.
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.
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:
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.
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.
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.
Activity
bokelley commentedon May 24, 2026
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:
_normalize_response_envelope(mcp_tools.py), not in the response builders — the normalization function already runs after the dict is returned and overwritesstatus; adding arequested_versionkwarg only to the builders creates a false API surface that gets clobbered at the wire boundary.detect_wire_versioninadcp.validation.envelopealready collapses bothadcp_version(string) andadcp_major_version(int) into a release-precision string — re-export it fromadcp.serverrather than creating a parallel helper, which would split the symbol space for agents and humans alike.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 viaadcp_version: "3.0"oradcp_major_version: 3. Also:major_versionscannot be dropped — servers MUST continue emitting it alongsidesupported_versionsthrough all of 3.x per the 3.1 schema deprecation note.My take: The observable bug is confirmed —
_normalize_response_envelopecurrently promotes unconditionally to 3.1 shape without inspecting the buyer's requested version; a 3.0 buyer sendingadcp_major_version: 3will always receive the wrong shape. The fix is a well-scoped, non-breaking addition: wire the already-availabledetect_wire_versioninto the normalization path and extend auto-capabilities to declaresupported_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): Calldetect_wire_version(raw_params)to resolve the buyer's requested version. When the resolved version is"3.0"(i.e., buyer sentadcp_major_version: 3with noadcp_versionstring, or sentadcp_version: "3.0"), emit the 3.0 shape (status = lifecycle_status, omitmedia_buy_status). When 3.1 or omitted (no version signal → seller's highest = 3.1), emit the current 3.1 shape.detect_wire_versionis already importable fromadcp.validation.envelope.src/adcp/server/__init__.py: Re-exportdetect_wire_versionasresolve_requested_adcp_version(one-liner) for adopter use in handler methods; document that it handles bothadcp_versionstring andadcp_major_versioninteger.src/adcp/server/builder.py—ADCPServerBuilder.build_handler(line 177): In the auto-capabilities handler, addsupported_versions=list(COMPATIBLE_ADCP_VERSIONS)alongside the existingadcp_version=pinned_version. Also ensuremajor_versions=[3]is still emitted (it's thecapabilities_responsedefault, so no change needed there).COMPATIBLE_ADCP_VERSIONSis importable fromadcp._version._normalize_response_envelopewithadcp_major_version: 3params (expect 3.0 shape) and with omitted version (expect 3.1 shape); add a test thatADCPServerBuilder.build_handler()auto-capabilities includessupported_versionswith both"3.0"and"3.1".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/orpyproject.toml.Triaged by Claude Code. Session: https://claude.ai/code/cse_01VhwWtiZ5qAGspEd26ccsvd
Generated by Claude Code
bokelley commentedon May 25, 2026
Update after
adcp==6.1.1b2and@adcp/sdk@8.1.0-beta.10:Container/runtime confirms:
3.1 beta storyboard runner now behaves consistently across transports:
The only 3.1 failure is local seller policy, not version serialization:
3.0 runner results with the same Python SDK are still not passing:
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:So
6.1.1b2appears 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 commentedon May 26, 2026
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 commentedon May 26, 2026
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.