Storyboards should negotiate exact AdCP version: 3.0 emits no version, 3.1 opts in

[bokelley]

Summary

The storyboard runner currently appears to choose schema/storyboard semantics from the installed JS SDK package line, rather than from an explicit buyer-requested AdCP version and/or exact seller capability metadata.

This makes 3.0 and 3.1 compatibility hard to validate against the same seller:

• A 3.0 storyboard should emit no version marker, because exact version negotiation did not exist for those clients. Sellers should treat an omitted version as legacy 3.0 compatibility.
• A 3.1 storyboard should explicitly opt in to 3.1 semantics, so adaptive sellers can return the 3.1 shape.
• The runner should not infer "3.0 vs 3.1" only from whichever @adcp/sdk package line happened to be installed.

Why this matters

In 3.1 beta, create/update media-buy responses split protocol envelope status from media-buy lifecycle status:

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

A legacy 3.0 buyer/storyboard expects lifecycle status at top-level status:

{
  "status": "pending_creatives"
}

One unversioned response cannot satisfy both contracts. The seller needs to know whether the buyer is asking for 3.0 compatibility or 3.1 semantics.

Repro / observed behavior

Against a local Sales Agent using Python SDK adcp==6.1.0b2:

python adcp package: 6.1.0b2
get_adcp_spec_version(): 3.1.0-beta.3

The agent capabilities currently advertise only:

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

Running the default storyboard runner used @adcp/sdk 7.10.2 (AdCP 3.0.12) and failed both MCP and A2A on 3.0 status expectations:

3.0 MCP: 25 passed, 2 failed, 32 skipped; schemas: 3.0.12
3.0 A2A: 25 passed, 2 failed, 32 skipped; schemas: 3.0.12

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

Running the beta storyboard runner used @adcp/sdk 8.1.0-beta.9 (AdCP 3.1.0-beta.3) and the status/media_buy_status issue disappeared:

3.1 MCP: 37 passed, 1 failed, 52 skipped; schemas: 3.1.0-beta.3
3.1 A2A: 37 passed, 1 failed, 52 skipped; schemas: 3.1.0-beta.3

The remaining 3.1 failure is unrelated local seller policy about duplicate product IDs across packages.

Expected behavior

The runner should make version intent explicit:

1. 3.0 storyboards should send no exact version marker / no new 3.1 negotiation field. This preserves legacy behavior for buyers that predate exact version negotiation.
2. 3.1 storyboards should send an explicit 3.1 marker on requests, or otherwise execute through a versioned negotiation path that an adaptive seller can observe.
3. If a seller advertises exact supported versions, the runner should use that to select compatible storyboards/schemas or at least report a clear mismatch.
4. The runner should distinguish "seller supports major v3" from "seller supports the exact 3.1 beta shape".

Notes

This is separate from #1961. That issue was about beta runner post-processing injecting a synthetic status. This issue is about version selection/negotiation across 3.0 and 3.1 storyboards.

[bokelley]

Triage

Classification: Bug (conformance runner design gap + wire version emission gap)
Bucket(s): conformance, library, cli
Status: ready-to-implement

What the experts said:

• ad-tech-protocol-expert: Wire semantics are correct — bundleSupportsAdcpVersionField + buildVersionEnvelope already encode the right intent; the actual bug is that the storyboard runner never plumbs a version pin into callTool, so adcp_version is always derived from the compile-time ADCP_VERSION constant regardless of which storyboard bundle is selected. The proposed --adcp-version CLI flag is non-breaking and additive.
• ad-tech-protocol-expert (on minor-version gating): checkVersionGate deliberately ignores the minor in introduced_in because get_adcp_capabilities only carries major_versions. Teaching the gate to filter on minor requires a new field in get_adcp_capabilities — that's a spec PR on adcontextprotocol/adcp, not an SDK change. Don't bake the minor-gating logic in here before the spec field exists.

My take: Both layers are real gaps but they're independent and the SDK-layer fix ships first. The narrow change (CLI flag + protocol client wiring) is non-breaking, well-scoped, and the infrastructure already exists (ResolveOptions.version is already accepted by every compliance loader function; buildVersionEnvelope already branches on the pin). The one open design question before implementation is whether the npm package should ship multiple compliance cache directories (3.0.x alongside 3.1.x) or rely on ADCP_COMPLIANCE_DIR for cross-version runs — that needs a call before touching the cache packaging.

Implementation scope:

• bin/adcp.js — add --adcp-version <version> flag to adcp storyboard run; thread into testOptions and replace the hardcoded ADCP_VERSION in buildComplianceSummary call.
• src/lib/testing/types.ts — add a buyer-side adcpVersionPin?: string field to TestOptions (distinct from the agent-detection-side adcp_version?: 'v2' | 'v3').
• src/lib/testing/compliance/comply.ts — pass adcpVersionPin into ResolveOptions.version when calling resolveStoryboardsForCapabilities (so the right compliance cache is loaded), and forward it to createTestClient so buildVersionEnvelope uses the explicit pin on every tool call.
• src/lib/testing/storyboard/compliance.ts — no change needed; ResolveOptions.version override already works throughout.
• Open design question (cache shipping): SDK 8.x ships only compliance/cache/3.1.x/. Running --adcp-version 3.0 against a 3.1 SDK install would fail with complianceMissingMessage unless (a) the 3.0 cache is also shipped in the package, (b) the user points ADCP_COMPLIANCE_DIR at a 3.0 SDK install, or (c) the CLI auto-fetches the bundle. Decide before starting the PR.
• Out of scope until spec PR: Minor-version-aware checkVersionGate — needs a minor_versions (or equivalent) field added to get_adcp_capabilities in adcontextprotocol/adcp first. File a companion issue/PR there before implementing.

---

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

---

Generated by Claude Code

[bokelley]

Triage addendum — code-reviewer findings landed after the initial brief; three corrections worth flagging:

1. The wire-threading gap is a specific one-liner. createTestClient in src/lib/testing/client.ts:177 constructs ADCPMultiAgentClient without forwarding adcpVersion from TestOptions. ADCPMultiAgentClient does accept config.adcpVersion — it's just never passed. This one line must be part of the scope or the protocol client will always use the compile-time ADCP_VERSION regardless of the CLI flag.

2. The npm package already ships multiple compliance caches. prepublishOnly calls sync-schemas:all which syncs both the GA pin and the beta pin. The cache-availability concern in the initial brief was unfounded — the flag just needs to validate that the user-supplied version resolves to a directory that actually exists on disk, and emit a helpful error listing the available versions if not (the generic "compliance cache missing" message won't be enough here).

3. Minor-version gating in checkVersionGate is in scope for this feature, not post-spec-PR. The gate can key off the user-supplied --adcp-version flag rather than agent-advertised capabilities — no spec field needed. When the user explicitly passes --adcp-version 3.0, storyboards with introduced_in: 3.1 should be filtered to not_applicable, otherwise they'll run against a 3.0 seller and produce structurally misleading failures. This is a behavioral correctness requirement, not a cosmetic improvement. The separate spec PR for minor_versions in get_adcp_capabilities is still worth filing, but it's not a prerequisite.

---

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

---

Generated by Claude Code

[bokelley]

Update after new releases:

Tested against Sales Agent with Python SDK adcp==6.1.1b2:

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

3.1 beta runner (@adcp/sdk@8.1.0-beta.10) on a fresh DB:

MCP: 37 passed, 1 failed, 52 skipped
A2A: 37 passed, 1 failed, 52 skipped

The one remaining 3.1 failure is unrelated to status negotiation:

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 (@adcp/sdk@7.11.0) on a fresh DB still does not pass:

MCP: 11 passed, 6 failed, 42 skipped
A2A: 26 passed, 2 failed, 31 skipped

The MCP 3.0 failures are now output schema validation errors on legacy-shaped create responses, e.g. raw result includes:

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

Runner reports:

Output validation error: {... 'status': 'pending_creatives', ...} is not valid under any of the given schemas
expected /schemas/3.0.12/media-buy/create-media-buy-response.json

So 6.1.1b2 appears to have moved MCP 3.0 toward legacy lifecycle status output, but the 3.0 JS runner/schema still rejects that shape. The original ask here still stands: a 3.0 storyboard should behave like a pre-negotiation buyer (no exact version marker), and the SDK/storyboard stack needs a consistent schema/serialization path for that legacy request.