Skip to content

Accept or publish AdCP 3.1-beta.5 wire version #883

Closed

Description

@bokelley

Summary

The current Python SDK release used by Sales Agent rejects requests that carry the current JS SDK / Agentic wire envelope value:

{"adcp_version": "3.1-beta.5"}

Local runtime with adcp @ git+https://github.com/adcontextprotocol/adcp-client-python.git@v6.3.0-beta.4 reports:

adcp.validation.envelope.SUPPORTED_WIRE_VERSIONS = ('3.0', '3.1-beta.4', '2.5')

and detect_wire_version({"adcp_version": "3.1-beta.5"}) raises UnsupportedVersionError because normalize_to_release_precision() preserves the prerelease patch label and the strict supported set does not include beta.5.

Downstream impact

Prebid Sales Agent had to add a local compatibility shim in bokelley/salesagent#632 so embedded/managed tenants can interoperate with current buyers emitting 3.1-beta.5 while the Python SDK pin is still on 3.1-beta.4.

That shim patches:

  • adcp.validation.envelope.SUPPORTED_WIRE_VERSIONS
  • adcp.validation.envelope.detect_wire_version

so the strict dispatcher path accepts 3.1-beta.5 as wire-compatible.

Ask

Please either:

  1. publish a Python SDK prerelease whose SUPPORTED_WIRE_VERSIONS includes 3.1-beta.5, or
  2. make detect_wire_version() tolerant of wire-compatible 3.1 beta patch aliases when the request/response envelope shape has not changed.

Suggested acceptance criteria

  • detect_wire_version({"adcp_version": "3.1-beta.5"}) returns "3.1-beta.5" or another documented compatible 3.1 release-precision value instead of raising.
  • Server dispatch/envelope validation accepts 3.1-beta.5 requests without adopter monkeypatching.
  • Capabilities helpers advertise the exact supported wire versions consistently with runtime validation.

Related downstream validation

Sales Agent PR #632 is green with the local shim:

  • make quality
  • focused managed-tenant webhook integration slice
  • GitHub CI: lint/typecheck, unit, integration shards, E2E, quickstart, security audit, storyboard gates, GHCR build

Activity

  1. added
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on May 27, 2026
  2. bokelley commented on May 27, 2026

    @bokelley
    ContributorAuthor

    Triage

    Classification: Bug
    Bucket(s): validation (no validation label exists in repo — noted in run summary)
    Status: ready-for-human
    Milestone: (omitted — prerelease cycle)

    What the experts said:

    • ad-tech-protocol-expert: Option B (fuzzy beta-patch matching) is unsound — each 3.1-beta.N is its own schema-cache bucket (schemas/cache/3.1.0-beta.3/, 3.1.0-beta.4/ are distinct); accepting 3.1-beta.5 while serving 3.1-beta.4 schemas violates the context-echo contract and causes a schema-loader cache miss. Option A (bump ADCP_VERSION to beta.5) is protocol-correct; VERSION_UNSUPPORTED + supported_versions is the designed buyer-retry path.
    • code-reviewer: Blocker on Option A — get_supported_adcp_versions() removes 3.1-beta.4 from SUPPORTED_WIRE_VERSIONS entirely on a version bump, hard-rejecting existing beta.4 sellers. Option B's return value is wrong (returning the claimed "3.1-beta.5" causes a schema-loader KeyError unless the loader is family-aware). Recommends Option C: add SUPPORTED_PRERELEASE_SIBLINGS = ("3.1-beta.5",) into SUPPORTED_WIRE_VERSIONS construction in envelope.py, plus a schema-loader alias "3.1-beta.5" → "3.1-beta.4".

    My take: Experts diverge on whether dropping beta.4 buyers is acceptable (protocol says yes; code-reviewer says regression for mixed deployments). The hard blocker for all options is the missing schemas/cache/3.1.0-beta.5/ directory — any path that accepts 3.1-beta.5 wire requests will fail at schema validation without new schema files or a loader alias.

    Decision needed from @bokelley before implementation:

    • Option A (bump ADCP_VERSION → 3.1.0-beta.5): run python scripts/sync_schemas.py to populate schemas/cache/3.1.0-beta.5/, bump pyproject.toml to 6.3.0b5; beta.4 sellers get VERSION_UNSUPPORTED (spec-correct retry path).
    • Option C (dual sibling support): add SUPPORTED_PRERELEASE_SIBLINGS = ("3.1-beta.5",) to SUPPORTED_WIRE_VERSIONS in src/adcp/validation/envelope.py; add a schema-loader alias in src/adcp/validation/schema_loader.py mapping "3.1-beta.5" → "3.1-beta.4" (no new schema files needed); keeps both beta versions accepted simultaneously. Either option needs new tests in tests/test_validation_envelope.py covering prerelease-sibling accept/reject cases and pinned return value.

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


    Generated by Claude Code

  3. added
    bugSomething isn't working
    and removed
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on May 27, 2026
  4. bokelley commented on Jun 6, 2026

    @bokelley
    ContributorAuthor

    Closing as obsolete. Confirmed with the buyer side: no live buyers still emit 3.1-beta.5 now that the SDK reference (and the JS SDK) are pinned to 3.1.0-rc.9. The supported wire set has moved past beta.5 entirely, and the context-echo / distinct-schema-cache objection from triage stands against a fuzzy alias. If a beta.5 buyer ever reappears, the correct fix is an explicit schema-loader alias plus a SUPPORTED_WIRE_VERSIONS entry with a pinned test — not a regex. Closing alongside #894.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions