[bokelley]

Problem

Reported in AdCP Slack. A registration check on the 3.3 beta SDK kept saying a 3.0-only seller "does not look like an AdCP agent". The check called get_adcp_capabilities pinned to adcp_version: "3.3-beta.5". The seller correctly answered VERSION_UNSUPPORTED with supported_versions: ["3.0"], and nothing retried. We reproduced it against 17.0.0-beta.22 with a local 3.0-only seller.

Rule implemented here: a buyer sends a preview pin only to a peer that advertises that exact release, and preview pins never negotiate down. Discovery goes out unpinned, and on VERSION_UNSUPPORTED the buyer retries unpinned.

Changes

1. Public discovery (SingleAgentClient)

• One shared helper, capabilityDiscoveryEnvelope() in adapters/version/negotiate.ts. getAdcpCapabilities() and the internal probe both dispatch through executeCapabilityDiscovery().
• A preview wire release (wireAdcpVersion ?? adcpVersion) goes out unpinned.
• A refused stable pin is retried once unpinned. The retry runs with its own correlation id and the same deadline. Only a successful retry replaces the pinned refusal.
• Nothing is overridden when the caller chose the pin: adcp_version / adcp_major_version in params, or an explicit versionEnvelope. The refusal comes back with adcpError.details.supported_versions.
• A call with a caller operationId is not retried, so the returned task keeps that id.

2. Testing and storyboard discovery

• applyAdcpVersionRunOptions() / applyStoryboardVersionOptions() leave versionEnvelope unset for AdCP 3 runs. That is the SDK default: ordinary calls still send auto. Before, they set an explicit auto, which pinned profile discovery.
• Authored get_adcp_capabilities storyboard steps still send the configured pin (storyboardCapabilityStepEnvelope). The universal/version-negotiation storyboard grades the seller's answer to that pin.
• A 3.0-only seller tested on a preview pin is now profiled. comply() then reaches its version check and fails with CapabilityResolutionError (unsupported_adcp_version, supportedVersions: ['3.0']), not "Agent unreachable — VERSION_UNSUPPORTED".
• Harnesses that set versionEnvelope keep pinned discovery. VERSION_UNSUPPORTED: classification in comply.ts is unchanged.
• Discovery diagnostics name a requested release only when one was sent (testClientDiscoveryWireAdcpVersion).

3. MCP server/discover 401 (mcp-modern.ts)

• A client with no credential now gets one legacy initialize attempt when a seller 401s/403s only server/discover, as a static-credential client already did. AdCP capability discovery is anonymous.
• If the legacy attempt fails for any reason other than a throttle or a cancellation (another 401, a 5xx, a 404), the probe's original 401 is rethrown. An uncredentialed caller sees exactly the error and challenge it saw before, not "endpoint not found". 429, a 503 with Retry-After, and aborts still reach the caller as themselves.
• OAuth-provider clients are unchanged. A status-only debug log line records that the probe was refused.

4. Registry types sync (unrelated, needed for green CI)

• The published registry OpenAPI gained the brand logo asset endpoints. "Generated, Docs & Formatting" therefore fails on every open PR. This regenerates schemas/registry/registry.yaml and src/lib/registry/types.generated.ts, all additive, with its own changeset, the same as chore(registry): sync generated registry types with the published OpenAPI #3669.

Tests

• test/lib/prerelease-capability-discovery.test.js (new). A 3.0-only seller with a client on the 3.3.0-beta.5 pin:
  • unpinned getAdcpCapabilities() / getCapabilities();
  • an explicit params or envelope pin is preserved, and the refusal carries supported_versions;
  • stable-pin retry, both public and internal;
  • a stable wire override is sent;
  • operationId skips the retry;
  • a failed retry keeps the pinned refusal;
  • discoverAgentProfile succeeds;
  • storyboard steps stay pinned;
  • comply reports unsupported_adcp_version.
• test/lib/mcp-negotiation-401-legacy-fallback.test.js:
  • a seller that 401s only server/discover is discovered anonymously, with no credential sent and no OAuth walk;
  • a seller that 401s everything still yields AuthenticationRequiredError with the Basic challenge, after one legacy attempt per URL;
  • the probe challenge survives a non-auth legacy failure.
• protocol-client-needs-auth (unchanged) caught that a bare legacy 401 replaced the probe's 401 for an uncredentialed caller. That is fixed by keeping the probe error.
• Updated tests whose wire expectations change on purpose: capabilities-probe-wire-version, storyboard-version-negotiation, storyboard-capability-discovery-terminal.

Review

• Security review (Claude security-reviewer, mcp-modern.ts): no High or Medium findings. Low items L1 (lost challenge on a non-auth legacy failure), L3 (debug log) and L4 (challenge-scheme assertion) are fixed here. L2 (an uncredentialed client against an everything-401 seller now sends one extra initialize per candidate URL) is accepted: it's bounded, and it's what makes anonymous discovery work.
• Code review (Claude code-reviewer):
  • Fixed: the CI blocker; storyboard steps losing the pin; operationId on the retry; a failed retry hiding the refusal; a stable wire override on a preview client.
  • Out of scope: a seller that serves initialize anonymously but 401s tools/call gets a generic invalid_token error rather than AuthenticationRequiredError. The same seller without the server/discover gate already behaves that way on main: the call path rethrows the raw 401 when the RFC 9728 walk can't be validated. Worth a follow-up.
• npm run review:codex -- --all, with the diff on stdin because codex's sandbox can't run shell commands on this host:
  • Security: no actionable findings.
  • Code and protocol: one shared item, that test-client reuse treats an unset envelope and auto as equal. Kept deliberately: both send the same envelope on ordinary calls and authored steps, and differ only in the reused client's own preview discovery probe, which follows that client's config. Making it strict would stop existing _client reuse in harnesses built with auto.

🤖 Generated with Claude Code

[aao-secretariat]

Ladon verdict: Approve

Approve — discovery-pinning fix verified clean, no blocking or medium findings.

What I checked:

• Witness-not-translator: the failed unpinned retry returns the real pinned refusal (VERSION_UNSUPPORTED) with no fabrication — witness preserved. No mock/fallback data injected.
• capabilityDiscoveryEnvelope behavior confirmed (preview→'none', stable→undefined, explicit wins); executeCapabilityDiscovery retry gating correctly skips for callerPinned/operationId/'none'.
• mcp-modern.ts fallback is fail-closed: legacy auth/abort/throttle supersede, OAuth providers excluded, skipProbe bounds it to one legacy attempt. Uses official MCP client path.
• Operational readiness: unpinned retry preserves deadline/signal via childTaskOptions; get_adcp_capabilities idempotent; cost is one extra round-trip.
• Changeset present (patch) and defensible for an additive-helper bugfix — no removed/renamed exports or response-shape change that would understate impact.
• Test coverage strong: prerelease-capability-discovery.test.js asserts discoveryCalls deepEqual, pinning retry ordering ['3.1', undefined] and no preview-pin leak.

Gate checks: high_risk is true only via src/lib/protocols/mcp-modern.ts (modified), but with no medium-or-higher finding the modification is presumed safe (row 5 does not fire). gated_paths is false. No no-auto-approve team match. review_decision REVIEW_REQUIRED does not block since gated_paths is false. No findings → rows 1–8 do not fire; falls through to row 9 = approve.

[aao-secretariat]

Ladon verdict: Approve

Approve — purely additive registry snapshot refresh, no blocking or medium findings.

What I checked:

• Delta pass over 3 files: a patch changeset, a vendored registry OpenAPI snapshot (schemas/registry/registry.yaml) adding two brand-logo endpoints (getBrandLogoAsset, getBrandLogoLegacy) plus background-field documentation, and the regenerated types.generated.ts.
• Changeset type (patch) and impact are correct — these are registry endpoint types, not agent-response reshaping, so no witness/wire-shape concerns.
• high_risk: true is driven by (modified) entries on schemas/registry/registry.yaml and src/lib/protocols/mcp-modern.ts, but the reviewer found no medium-or-higher concerns, so the modifications are presumed safe (no row-5 trigger).
• gated_paths: false; no no-auto-approve team match.
• Prior decision was approve with no findings; this run also surfaces none — net clean.

No critical/high/medium findings. Rows 1–8 do not fire (review_decision REVIEW_REQUIRED does not block since gated_paths is false; high_risk alone with no medium finding does not escalate). Falls through to row 9.

[aao-secretariat]

Ladon verdict: Approve

Approve.

Subsequent review: the prior decision was a clean approve with no findings. The delta is a single non-generated file (src/lib/protocols/mcp-modern.ts, ~47 lines) consisting of comment rewrites plus narrowing legacyFailureSupersedesProbe to drop isNegotiationAuthFailure, so a second 401 on the legacy initialize attempt defers to the probe's original challenge rather than replacing it. The logic is consistent with the surrounding no-credential fallback and preserves witness behavior (surfaces the seller's real 401 + WWW-Authenticate chain, no fabrication). Covered by the updated 401-legacy-fallback tests, and a changeset is present.

Decision-table walk: no critical/high findings (row 1 n/a); gated_paths is false (row 2 n/a); high_risk is true but reasons are (modified), not (deleted) (row 3 n/a); no medium findings at all (rows 4, 5, 8 n/a — the high-risk (modified) paths carry no medium concern); prior decision was approve, not escalate (row 6 n/a); no no-auto-approve team match (row 7 n/a). Falls through to row 9 → approve.