Skip to content

bug(capabilities): get_adcp_capabilities advertises supported_versions the dispatcher cannot serve #1280

Closed

Description

@bokelley

Summary

get_adcp_capabilities publishes whatever adcp.supported_versions the seller declares. It never checks that the dispatcher will accept those versions or that the SDK bundles schemas to validate them. A seller can therefore advertise a version that every request is rejected at, and nothing flags it at boot.

Depending on how the seller widened version detection, a buyer that selects the advertised version gets one of two errors:

  • VERSION_UNSUPPORTED from detect_wire_version, when the version isn't in the accepted wire set; or
  • VALIDATION_ERROR at / with keyword schema_unavailable, from _missing_explicit_schema_outcome (adcp/validation/schema_validator.py:132-175), when detection accepts it but no bundle exists.

The second is a misleading code. The request body is fine; the server can't speak the version it negotiated.

Reproduction (adcp 8.0.0)

import asyncio

from adcp.server import ADCPHandler
from adcp.server.mcp_tools import create_tool_caller
from adcp.server.responses import capabilities_response
from adcp.validation import validate_request


class Seller(ADCPHandler):
    async def get_products(self, params, context=None):
        return {"products": []}


async def main():
    caps = capabilities_response(["media_buy"], major_versions=[3], supported_versions=["3.1-beta.5", "3.2"])
    print("advertised:", caps["adcp"]["supported_versions"])
    request = {"adcp_version": "3.1-beta.5", "buying_mode": "brief", "brief": "video"}
    try:
        await create_tool_caller(Seller(), "get_products")(request)
    except Exception as exc:
        print("dispatch:", exc.errors[0].code)
    outcome = validate_request("get_products", request, version="3.1-beta.5")
    print("validator:", outcome.valid, outcome.issues[0].keyword)

asyncio.run(main())

Output:

advertised: ['3.1-beta.5', '3.2']
dispatch: VERSION_UNSUPPORTED
validator: False schema_unavailable

Why an adopter hits this

This happened in production. Embedded Sales Agent advertised 3.1-beta.5, a compatibility alias added while #883 was open. When adcp 7.0.0 started failing closed on explicit versions without a bundle, every 3.1-beta.5 request began failing with schema_unavailable. The capability kept advertising the version for months, and no boot check or log line pointed at the mismatch.

Ask

  1. At boot (validate_capabilities_response_shape, or serve()), reject or warn when an advertised supported_versions entry isn't in the accepted wire set, or has no bundled validator.
  2. When detection accepts an explicit version but no bundle exists, return VERSION_UNSUPPORTED (with supported_versions in details), not VALIDATION_ERROR at /.

Activity

  1. added
    bugSomething isn't working
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on Oct 2, 2026
  2. bokelley commented on Oct 2, 2026

    @bokelley
    ContributorAuthor

    Triage

    Classification: Bug (two related sub-bugs in the validation/capabilities boundary)
    Bucket(s): validation, handlers (no matching repo labels found; noted for maintainer)
    Status: ready-for-human
    Milestone: omitted (no target version specified)

    What the experts said:

    • ad-tech-protocol-expert: VERSION_UNSUPPORTED is the correct wire code for sub-bug 2 — compliance storyboards (exact_nonempty_reject_rc0) assert exactly that for the "server accepted a version it cannot validate" case. Technically breaking but a conformance correction. For sub-bug 1, recommends raising (not warning) at boot when supported_versions is explicitly supplied, scoped only to caller-supplied lists.
    • code-reviewer: Sub-bug 2 has a blocker-level semantic concern — VERSION_UNSUPPORTED would be actively misleading here, because the dispatcher just accepted the version; the buyer would downgrade unnecessarily. INTERNAL_ERROR is the correct code (server misconfiguration, not a bad request). For sub-bug 1, the warning belongs in capabilities_response() directly (not just in _validate_response_dict), fires only when supported_versions is not None, and must compare against SUPPORTED_WIRE_VERSIONS (not get_supported_adcp_versions()) to avoid false positives on legacy versions like "2.5".

    My take: The two sub-bugs need separate decisions. Sub-bug 1's warning-only path is non-breaking and both experts agree on the capabilities_response() location and the SUPPORTED_WIRE_VERSIONS comparison set — that piece could land independently. Sub-bug 2 requires a human call: the protocol expert says VERSION_UNSUPPORTED, the code reviewer says INTERNAL_ERROR, and they make different arguments from spec conformance vs. buyer UX. Either choice is a breaking wire change.

    Open questions for @bokelley:

    1. Sub-bug 2 — which code? Protocol expert cites storyboard precedent for VERSION_UNSUPPORTED. Code reviewer argues INTERNAL_ERROR is semantically correct (buyer can't fix a missing schema bundle by downgrading). Which is the intended wire contract?
    2. Sub-bug 1 — warn or raise at boot? Raising at boot on explicitly-supplied bad versions (protocol expert's preference) is breaking for adopters with stale configs. Warning-only (code reviewer) is non-breaking but softer. What's the right tradeoff for adopters who already shipped supported_versions=["3.1-beta.5"]?
    3. Before shipping sub-bug 2's fix, exact_nonempty_reject_rc0 and any partner storyboards asserting VALIDATION_ERROR for schema_unavailable would need updating — is there a storyboard audit step in scope here?

    Implementation scope (for when the decisions above are made):

    • Sub-bug 1 (non-breaking warning path): src/adcp/server/responses.py lines 257–350 — add if supported_versions is not None: guard before the merge block; iterate entries against SUPPORTED_WIRE_VERSIONS from adcp.validation.envelope; emit warnings.warn(..., stacklevel=2) for any miss. No import circularity risk.
    • Sub-bug 2 (breaking, after code decision): src/adcp/validation/schema_validator.py lines 160–174 (_missing_explicit_schema_outcome) — change returned keyword/code; src/adcp/validation/schema_errors.py line 74 (build_adcp_validation_error_payload) — add a parallel builder or keyword-based routing; src/adcp/server/mcp_tools.py lines 3307–3320 and 3607–3614 — add dispatcher routing on the new keyword.

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


    Generated by Claude Code

  3. added and removed
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on Oct 2, 2026
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