From 8ec81b62a8ee7f96671d40dd76dc1631e09d0519 Mon Sep 17 00:00:00 2001 From: Brian O'Kelley Date: Thu, 15 Oct 2026 17:56:58 +0000 Subject: [PATCH 1/3] fix(testing): validate capabilities against the served release; key compliance_testing in the cross-check Capability discovery strictly validated get_adcp_capabilities against the caller's pin. A 3.0 pin sends only adcp_major_version: 3, so the seller serves and echoes its highest 3.x release, and the SDK reported that release's shapes as false capabilities_schema_issues (and failed getAdcpCapabilities() in strict mode). discoverAgentProfile and TaskExecutor now validate against the echoed adcp_version when it is a same-major release the SDK bundles, falling back to the pin otherwise, per the versioning spec ("Server echoes"). Validation stays strict. The testCapabilityDiscovery protocol/tool cross-check keyed comply_test_controller as "compliance" while the capabilities parser reports "compliance_testing", so every agent declaring the block failed with "Tools suggest unreported protocols: compliance". The key is now compliance_testing and the table's keys are type-checked against AdcpProtocol. Fixes #3278 Fixes #3279 Co-Authored-By: Claude Opus 5.5 (1M context) --- ...bilities-compliance-testing-cross-check.md | 5 + .../capabilities-served-release-validation.md | 5 + src/lib/core/TaskExecutor.ts | 12 +- src/lib/testing/client.ts | 7 +- src/lib/testing/scenarios/capabilities.ts | 9 +- src/lib/validation/served-version.ts | 60 ++++ ...bilities-served-release-validation.test.js | 273 ++++++++++++++++++ 7 files changed, 366 insertions(+), 5 deletions(-) create mode 100644 .changeset/capabilities-compliance-testing-cross-check.md create mode 100644 .changeset/capabilities-served-release-validation.md create mode 100644 src/lib/validation/served-version.ts create mode 100644 test/lib/capabilities-served-release-validation.test.js diff --git a/.changeset/capabilities-compliance-testing-cross-check.md b/.changeset/capabilities-compliance-testing-cross-check.md new file mode 100644 index 000000000..31abe3e1d --- /dev/null +++ b/.changeset/capabilities-compliance-testing-cross-check.md @@ -0,0 +1,5 @@ +--- +'@adcp/sdk': patch +--- + +The `testCapabilityDiscovery` protocol/tool cross-check now keys `comply_test_controller` under `compliance_testing`, the protocol the capabilities parser reports for the `compliance_testing` block (#3279). It used `compliance`, so every agent that correctly declared the block failed with "Tools suggest unreported protocols: compliance (has: [comply_test_controller])". A `compliance_testing` block without `comply_test_controller` is now reported as a declared protocol with no matching tools. The table's keys are now type-checked against `AdcpProtocol`. diff --git a/.changeset/capabilities-served-release-validation.md b/.changeset/capabilities-served-release-validation.md new file mode 100644 index 000000000..160da175e --- /dev/null +++ b/.changeset/capabilities-served-release-validation.md @@ -0,0 +1,5 @@ +--- +'@adcp/sdk': patch +--- + +Capability discovery now validates `get_adcp_capabilities` against the release the seller served instead of the caller's pin (#3278). A 3.0 pin cannot carry `adcp_version`, so the SDK sends only `adcp_major_version: 3`. The seller then serves its highest 3.x release and echoes it in `adcp_version`, and the versioning spec says buyers validate against that echo. `discoverAgentProfile` (used by `testCapabilityDiscovery`, `comply()` and the storyboard runner) and `TaskExecutor` validated a 3.2 response strictly against 3.0. A conformant agent got false `capabilities_schema_issues` (for example `media_buy.features.bidding_policy must be boolean`, or the closed 3.0 `compliance_testing.scenarios` enum), and `getAdcpCapabilities()` failed in strict mode. Both now use the echoed release when it is in the pin's major and the SDK bundles its schema. They fall back to the pin when the echo is missing, from another major, or not bundled. Validation stays strict. diff --git a/src/lib/core/TaskExecutor.ts b/src/lib/core/TaskExecutor.ts index 04d09ca54..3cf09da83 100644 --- a/src/lib/core/TaskExecutor.ts +++ b/src/lib/core/TaskExecutor.ts @@ -34,6 +34,7 @@ import { type ValidationMode, } from '../validation/client-hooks'; import { formatIssues } from '../validation/schema-validator'; +import { resolveServedValidationVersion } from '../validation/served-version'; import { ADCP_VERSION } from '../version'; import { unwrapProtocolResponse, isAdcpOperationSuccess } from '../utils/response-unwrapper'; import { extractAdcpErrorInfo, extractCorrelationId } from '../utils/error-extraction'; @@ -6124,10 +6125,19 @@ export class TaskExecutor { // Normal dispatch uses lastKnownServerVersion; restart recovery passes // the persisted continuation version explicitly so concurrent or fresh // executors cannot validate the seller's response against another wire. - const validationVersion = + let validationVersion = (serverVersion ?? this.lastKnownServerVersion) === 'v2' ? 'v2.5' : (this.responseAdcpVersionForValidation() ?? this.config.adcpVersion ?? ADCP_VERSION); + // Capabilities are negotiated before any pin applies: a 3.0 pin (or a + // major-only envelope) is served the seller's highest release in the + // major, echoed in `adcp_version`. Validate against that release, as the + // versioning spec requires ("Server echoes"), falling back to the pin + // when there is no usable echo. Only the validator's version changes; + // the unwrapper keeps `effectiveResponseAdcpVersion()`. + if (taskName === 'get_adcp_capabilities' && validationVersion !== 'v2.5') { + validationVersion = resolveServedValidationVersion(response, validationVersion); + } const normalizedResponse = this.normalizeResponseForValidation(response, taskName, validationVersion === 'v2.5'); // TaskExecutor owns the user-facing log entry below. Passing debugLogs // into the lower-level hook would emit a second, unversioned duplicate. diff --git a/src/lib/testing/client.ts b/src/lib/testing/client.ts index 868150928..457767b06 100644 --- a/src/lib/testing/client.ts +++ b/src/lib/testing/client.ts @@ -28,6 +28,7 @@ import type { AgentRequestSigningConfig } from '../types/adcp'; import { createHmac, hkdfSync, randomBytes } from 'node:crypto'; import { AsyncLocalStorage } from 'node:async_hooks'; import { validateIncomingResponse } from '../validation/client-hooks'; +import { resolveServedValidationVersion } from '../validation/served-version'; import { extractVersionUnsupportedDetails } from '../utils/error-extraction'; import { buildAgentSigningContext } from '../signing/client'; import type { VerifierCapability } from '../signing/types'; @@ -844,12 +845,16 @@ export async function discoverAgentProfile( step.error = versionUnsupported; } else if (caps?.data) { profile.raw_capabilities = caps.data; + // Validate against the release the seller served (its echoed + // `adcp_version`), not the pin. A 3.0 pin negotiates major-only, so + // the seller serves its highest 3.x release (versioning spec, + // "Server echoes"). Falls back to the pin when there is no usable echo. const validation = validateIncomingResponse( 'get_adcp_capabilities', caps.data, 'strict', undefined, - schemaAdcpVersion ?? client.getAdcpVersion() + resolveServedValidationVersion(caps.data, schemaAdcpVersion ?? client.getAdcpVersion()) ); if (!validation.valid) { profile.capabilities_schema_issues = validation.issues.map(issue => ({ diff --git a/src/lib/testing/scenarios/capabilities.ts b/src/lib/testing/scenarios/capabilities.ts index 093112a98..20c50841e 100644 --- a/src/lib/testing/scenarios/capabilities.ts +++ b/src/lib/testing/scenarios/capabilities.ts @@ -311,15 +311,18 @@ function crossValidateProtocolsAndTools(capabilities: AdcpCapabilities, tools: s const issues: string[] = []; const warnings: string[] = []; - const protocolToolMap: Record = { + // Keys must be `AdcpProtocol` values as reported by `parseCapabilitiesResponse` + // (`satisfies` rejects any other key at compile time). `compliance_testing` + // is promoted from the top-level capability block, not `supported_protocols`. + const protocolToolMap: Readonly> = { media_buy: MEDIA_BUY_TOOLS, signals: SIGNALS_TOOLS, governance: GOVERNANCE_TOOLS, creative: CREATIVE_TOOLS, sponsored_intelligence: SPONSORED_INTELLIGENCE_TOOLS, trusted_match: TRUSTED_MATCH_TOOLS, - compliance: COMPLIANCE_TOOLS, - }; + compliance_testing: COMPLIANCE_TOOLS, + } satisfies Partial>; // Check each reported protocol has at least one corresponding tool const perProtocolDiffs: Record = {}; diff --git a/src/lib/validation/served-version.ts b/src/lib/validation/served-version.ts new file mode 100644 index 000000000..579e96d9e --- /dev/null +++ b/src/lib/validation/served-version.ts @@ -0,0 +1,60 @@ +/** + * Select the AdCP release a seller response is validated against. + * + * The versioning spec (`docs/reference/versioning.mdx`, "Server echoes") + * says the seller echoes the release it actually served in `adcp_version`, + * and buyers SHOULD validate the response against that release's schema, + * not against their pin. When the response omits `adcp_version`, buyers + * validate against their own pin. + * + * The gap matters most for `get_adcp_capabilities` under a 3.0 pin: the 3.0 + * bundle has no `adcp_version` request field, so the SDK sends only + * `adcp_major_version: 3`, and the seller serves (and echoes) its highest 3.x + * release. Validating that response against 3.0 reports every newer shape as + * a schema violation. + * + * @internal — not part of the public API surface; may change without a major bump. + */ + +import { hasSchemaBundle, toReleasePrecisionWire } from './schema-loader'; + +/** `core/version-envelope.json`'s `adcp_version` wire pattern (release precision). */ +const RELEASE_PRECISION = /^(\d+)\.\d+(?:-[a-zA-Z0-9.-]+)?$/; +/** Major of a numeric pin: `'3.0'`, `'3.0.25'`, `'3.1-beta'`, `'3.1.0-beta.1'`. */ +const NUMERIC_PIN_MAJOR = /^(\d+)\.\d+/; + +/** + * Return the version to validate `response` against: the echoed + * `adcp_version` when it is a usable release, otherwise `pinnedVersion`. + * + * The echo is used only when it is a release-precision string in the same + * major as the pin and the SDK has a schema bundle for it. Validation stays + * strict either way: an echo from another major, a malformed echo, or one the + * SDK cannot validate falls back to the pin rather than skipping validation. + * When the echo names the pinned release itself, the exact pin is returned so + * a patch-precise pin (and any external schema root bound to it) still + * applies. `supported_versions` is deliberately not consulted: with no echo + * the spec says to validate against the pin. + */ +export function resolveServedValidationVersion(response: unknown, pinnedVersion: string): string { + const pinMajor = NUMERIC_PIN_MAJOR.exec(pinnedVersion)?.[1]; + // Legacy aliases ('v2.5', 'v3') have their own adapter paths; leave them alone. + if (pinMajor === undefined) return pinnedVersion; + + const echoed = + response !== null && typeof response === 'object' + ? (response as { adcp_version?: unknown }).adcp_version + : undefined; + if (typeof echoed !== 'string') return pinnedVersion; + const echoMajor = RELEASE_PRECISION.exec(echoed)?.[1]; + if (echoMajor === undefined || echoMajor !== pinMajor) return pinnedVersion; + + let pinnedRelease: string; + try { + pinnedRelease = toReleasePrecisionWire(pinnedVersion); + } catch { + return pinnedVersion; + } + if (echoed === pinnedRelease) return pinnedVersion; + return hasSchemaBundle(echoed) ? echoed : pinnedVersion; +} diff --git a/test/lib/capabilities-served-release-validation.test.js b/test/lib/capabilities-served-release-validation.test.js new file mode 100644 index 000000000..6c043b51d --- /dev/null +++ b/test/lib/capabilities-served-release-validation.test.js @@ -0,0 +1,273 @@ +/** + * Capability discovery validates `get_adcp_capabilities` against the release + * the seller served, not the caller's pin, and cross-checks the + * `compliance_testing` block against `comply_test_controller` under the key + * the capabilities parser actually reports. + * + * A 3.0 pin cannot carry `adcp_version` (the 3.0 bundle predates the field), + * so the SDK sends only `adcp_major_version: 3`. Per the versioning spec a + * major-only request is served the seller's highest release in that major, + * and the seller echoes it in `adcp_version` ("Server echoes": buyers SHOULD + * validate against that release's schema, not their pin). Before the fix, + * `discoverAgentProfile` and `TaskExecutor` both validated a 3.2 response + * strictly against 3.0 and reported false `capabilities_schema_issues`. + */ + +const { describe, test, after } = require('node:test'); +const assert = require('node:assert/strict'); +const http = require('node:http'); + +process.env.ADCP_ALLOW_INTERNAL_PROBES = '1'; + +const { ADCPMultiAgentClient } = require('../../dist/lib/index.js'); +const { testCapabilityDiscovery } = require('../../dist/lib/testing/scenarios/capabilities.js'); +const { closeMCPConnections } = require('../../dist/lib/protocols/mcp.js'); +const { resolveServedValidationVersion } = require('../../dist/lib/validation/served-version.js'); + +/** A conformant AdCP 3.2 capabilities response, invalid against 3.0 and 3.1. */ +function capabilities32(overrides = {}) { + return { + status: 'completed', + adcp_version: '3.2', + adcp: { + major_versions: [3], + supported_versions: ['3.0', '3.1', '3.2'], + idempotency: { supported: true, replay_ttl_seconds: 86400 }, + }, + supported_protocols: ['media_buy'], + account: { require_operator_auth: false, supported_billing: ['operator'] }, + // 3.2 widened `features` entries: 3.0/3.1 require booleans here. + media_buy: { features: { bidding_policy: { media_buy: { fixed: { modes: ['bid_amount'] } } } } }, + // 3.0 closes `scenarios` to six values; 3.1+ opens the list. + compliance_testing: { scenarios: ['force_creative_status', 'force_create_media_buy_arm', 'seed_product'] }, + ...overrides, + }; +} + +const MEDIA_BUY_TOOLS = ['get_products', 'create_media_buy']; + +async function startSeller({ payload, tools = [...MEDIA_BUY_TOOLS, 'comply_test_controller'] }) { + const capabilityRequests = []; + const { createMcpHandler, McpServer } = require('@modelcontextprotocol/server'); + const { toNodeHandler } = require('@modelcontextprotocol/node'); + const { z } = require('zod'); + const handler = createMcpHandler(() => { + const server = new McpServer({ name: 'served-release-seller', version: '1.0.0' }); + server.registerTool( + 'get_adcp_capabilities', + { description: 'AdCP capabilities', inputSchema: z.object({}).passthrough() }, + async args => { + capabilityRequests.push(args); + return { content: [{ type: 'text', text: JSON.stringify(payload) }], structuredContent: payload }; + } + ); + for (const name of tools) { + server.registerTool(name, { description: name }, async () => ({ + content: [{ type: 'text', text: '{}' }], + structuredContent: {}, + })); + } + return server; + }); + const serveMcp = toNodeHandler(handler); + const server = http.createServer(async (req, res) => { + if (req.url !== '/mcp' && req.url !== '/mcp/') { + res.writeHead(404).end('not found'); + return; + } + await serveMcp(req, res); + }); + await new Promise(resolve => server.listen(0, '127.0.0.1', resolve)); + return { + url: `http://127.0.0.1:${server.address().port}/mcp`, + capabilityRequests, + async close() { + await handler.close(); + server.closeAllConnections(); + await new Promise(resolve => server.close(resolve)); + }, + }; +} + +async function withSeller(t, options) { + await closeMCPConnections(); + const seller = await startSeller(options); + t.after(async () => { + await closeMCPConnections(); + await seller.close(); + }); + return seller; +} + +const stepNamed = (steps, name) => steps.find(step => step.step === name); +const failedSteps = steps => steps.filter(step => !step.passed && !step.skipped); + +describe('resolveServedValidationVersion', () => { + test('uses a bundled same-major echo instead of the pin', () => { + assert.equal(resolveServedValidationVersion({ adcp_version: '3.2' }, '3.0'), '3.2'); + assert.equal(resolveServedValidationVersion({ adcp_version: '3.1' }, '3.0.25'), '3.1'); + assert.equal(resolveServedValidationVersion({ adcp_version: '3.0' }, '3.2'), '3.0'); + }); + + test('keeps the exact pin when the echo is the pinned release', () => { + // Preserves a patch-precise pin (and any external schema root bound to it). + assert.equal(resolveServedValidationVersion({ adcp_version: '3.0' }, '3.0.25'), '3.0.25'); + assert.equal(resolveServedValidationVersion({ adcp_version: '3.2' }, '3.2'), '3.2'); + }); + + test('falls back to the pin when there is no usable echo', () => { + assert.equal(resolveServedValidationVersion({}, '3.0'), '3.0', 'no echo'); + assert.equal(resolveServedValidationVersion(undefined, '3.0'), '3.0', 'no payload'); + assert.equal(resolveServedValidationVersion({ adcp_version: 3.2 }, '3.0'), '3.0', 'non-string echo'); + assert.equal(resolveServedValidationVersion({ adcp_version: '3.2.4' }, '3.0'), '3.0', 'not release precision'); + assert.equal(resolveServedValidationVersion({ adcp_version: '../3.2' }, '3.0'), '3.0', 'garbage'); + assert.equal(resolveServedValidationVersion({ adcp_version: '4.0' }, '3.0'), '3.0', 'different major'); + assert.equal(resolveServedValidationVersion({ adcp_version: '2.5' }, '3.0'), '3.0', 'older major'); + assert.equal(resolveServedValidationVersion({ adcp_version: '3.99' }, '3.0'), '3.0', 'no bundled schema'); + assert.equal(resolveServedValidationVersion({ adcp_version: '3.2' }, 'v2.5'), 'v2.5', 'legacy v2 pin'); + }); + + test('does not consult supported_versions', () => { + // Spec: with no echo, validate against the pin. + assert.equal(resolveServedValidationVersion({ adcp: { supported_versions: ['3.0', '3.2'] } }, '3.0'), '3.0'); + }); +}); + +describe('capability discovery with a 3.0 pin against a seller serving 3.2', () => { + after(() => closeMCPConnections()); + + test('validates the response against the served release, so a conformant 3.2 response passes', async t => { + const seller = await withSeller(t, { payload: capabilities32() }); + + const discovery = await testCapabilityDiscovery(seller.url, { protocol: 'mcp', adcpVersion: '3.0' }); + + // The probe really was major-only: a 3.0 pin cannot carry adcp_version. + assert.ok(seller.capabilityRequests.length > 0, 'seller received get_adcp_capabilities'); + for (const args of seller.capabilityRequests) { + assert.equal(args.adcp_major_version, 3); + assert.equal(args.adcp_version, undefined); + } + + assert.deepEqual(discovery.profile?.capabilities_schema_issues, undefined); + assert.deepEqual(failedSteps(discovery.steps), [], JSON.stringify(discovery.steps, null, 2)); + assert.equal(stepNamed(discovery.steps, 'Get AdCP capabilities (v3)')?.passed, true); + }); + + test('still validates strictly: a response invalid against the served release is reported', async t => { + // minProperties: 1 on the 3.2 bidding_policy object. + const payload = capabilities32({ media_buy: { features: { bidding_policy: {} } } }); + const seller = await withSeller(t, { payload }); + + const discovery = await testCapabilityDiscovery(seller.url, { protocol: 'mcp', adcpVersion: '3.0' }); + + const issues = discovery.profile?.capabilities_schema_issues ?? []; + assert.ok( + issues.some(issue => issue.pointer === '/media_buy/features/bidding_policy'), + JSON.stringify(issues) + ); + // Reported against 3.2 (fewer properties), not 3.0 (must be boolean). + assert.ok( + issues.every(issue => !/must be boolean|must be one of/.test(issue.message)), + JSON.stringify(issues) + ); + }); + + test('falls back to the pin when the seller omits adcp_version', async t => { + const { adcp_version: _omitted, ...payload } = capabilities32(); + const seller = await withSeller(t, { payload }); + + const discovery = await testCapabilityDiscovery(seller.url, { protocol: 'mcp', adcpVersion: '3.0' }); + + const issues = discovery.profile?.capabilities_schema_issues ?? []; + assert.ok( + issues.some(issue => issue.pointer === '/media_buy/features/bidding_policy'), + JSON.stringify(issues) + ); + }); + + test('does not pass an echo from a different major; validates against the pin', async t => { + const seller = await withSeller(t, { payload: capabilities32({ adcp_version: '4.0' }) }); + + const discovery = await testCapabilityDiscovery(seller.url, { protocol: 'mcp', adcpVersion: '3.0' }); + + const issues = discovery.profile?.capabilities_schema_issues ?? []; + assert.ok(issues.length > 0, 'a 4.0 echo must not silence 3.0 validation'); + }); + + test('does not pass an echo the SDK has no schema for; validates against the pin', async t => { + const seller = await withSeller(t, { payload: capabilities32({ adcp_version: '3.99' }) }); + + const discovery = await testCapabilityDiscovery(seller.url, { protocol: 'mcp', adcpVersion: '3.0' }); + + const issues = discovery.profile?.capabilities_schema_issues ?? []; + assert.ok(issues.length > 0, 'an unvalidatable echo must not silence 3.0 validation'); + }); + + test('TaskExecutor validates getAdcpCapabilities against the served release in strict mode', async t => { + const seller = await withSeller(t, { payload: capabilities32() }); + const client = new ADCPMultiAgentClient( + [{ id: 'seller', name: 'Seller', agent_uri: seller.url, protocol: 'mcp' }], + { adcpVersion: '3.0', validation: { responses: 'strict' } } + ); + + const result = await client.agent('seller').getAdcpCapabilities({}); + + assert.equal(result.success, true, result.error); + }); + + test('TaskExecutor keeps strict validation against the served release', async t => { + const payload = capabilities32({ media_buy: { features: { bidding_policy: {} } } }); + const seller = await withSeller(t, { payload }); + const client = new ADCPMultiAgentClient( + [{ id: 'seller', name: 'Seller', agent_uri: seller.url, protocol: 'mcp' }], + { adcpVersion: '3.0', validation: { responses: 'strict', logSchemaViolations: false } } + ); + + const result = await client.agent('seller').getAdcpCapabilities({}); + + assert.equal(result.success, false); + assert.match(result.error ?? '', /bidding_policy/); + assert.doesNotMatch(result.error ?? '', /must be boolean/); + }); +}); + +describe('capability cross-check keys comply_test_controller as compliance_testing', () => { + after(() => closeMCPConnections()); + + const CROSS_CHECK = 'Cross-validate protocols and tools'; + + test('an agent declaring compliance_testing with comply_test_controller passes', async t => { + const seller = await withSeller(t, { payload: capabilities32() }); + + const discovery = await testCapabilityDiscovery(seller.url, { protocol: 'mcp', adcpVersion: '3.2' }); + + const step = stepNamed(discovery.steps, CROSS_CHECK); + assert.ok(step, 'cross-check step ran'); + assert.equal(step.passed, true, step.error); + assert.doesNotMatch(step.details ?? '', /unreported/); + }); + + test('comply_test_controller without the compliance_testing block is flagged under compliance_testing', async t => { + const { compliance_testing: _omitted, ...payload } = capabilities32(); + const seller = await withSeller(t, { payload }); + + const discovery = await testCapabilityDiscovery(seller.url, { protocol: 'mcp', adcpVersion: '3.2' }); + + const step = stepNamed(discovery.steps, CROSS_CHECK); + assert.equal(step?.passed, false); + assert.match( + step.error, + /Tools suggest unreported protocols: compliance_testing \(has: \[comply_test_controller\]\)/ + ); + }); + + test('a compliance_testing block without comply_test_controller is flagged', async t => { + const seller = await withSeller(t, { payload: capabilities32(), tools: MEDIA_BUY_TOOLS }); + + const discovery = await testCapabilityDiscovery(seller.url, { protocol: 'mcp', adcpVersion: '3.2' }); + + const step = stepNamed(discovery.steps, CROSS_CHECK); + assert.equal(step?.passed, false); + assert.match(step.error, /Protocol 'compliance_testing' reported but no matching tools found/); + }); +}); From 9fc0f8ce5dc8075e51d5291c49119c52d3fe4a57 Mon Sep 17 00:00:00 2001 From: Brian O'Kelley Date: Thu, 15 Oct 2026 18:13:45 +0000 Subject: [PATCH 2/3] fix(testing): let an external schema root bound to the pin win over the echo; cover prerelease and major-only pins Matches the storyboard runner's response_schema precedence. Documents the deliberate downshift acceptance and tightens the cross-check changeset. Co-Authored-By: Claude Opus 5.5 (1M context) --- ...bilities-compliance-testing-cross-check.md | 2 +- .../capabilities-served-release-validation.md | 2 +- src/lib/validation/served-version.ts | 15 +++++++- ...bilities-served-release-validation.test.js | 37 +++++++++++++++++++ 4 files changed, 53 insertions(+), 3 deletions(-) diff --git a/.changeset/capabilities-compliance-testing-cross-check.md b/.changeset/capabilities-compliance-testing-cross-check.md index 31abe3e1d..5145da4b1 100644 --- a/.changeset/capabilities-compliance-testing-cross-check.md +++ b/.changeset/capabilities-compliance-testing-cross-check.md @@ -2,4 +2,4 @@ '@adcp/sdk': patch --- -The `testCapabilityDiscovery` protocol/tool cross-check now keys `comply_test_controller` under `compliance_testing`, the protocol the capabilities parser reports for the `compliance_testing` block (#3279). It used `compliance`, so every agent that correctly declared the block failed with "Tools suggest unreported protocols: compliance (has: [comply_test_controller])". A `compliance_testing` block without `comply_test_controller` is now reported as a declared protocol with no matching tools. The table's keys are now type-checked against `AdcpProtocol`. +The `testCapabilityDiscovery` protocol/tool cross-check now keys `comply_test_controller` under `compliance_testing`, the protocol the capabilities parser reports for the `compliance_testing` block (#3279). It used `compliance`, so every agent that correctly declared the block failed with "Tools suggest unreported protocols: compliance (has: [comply_test_controller])". An agent that declares a `compliance_testing` block but does not expose `comply_test_controller` now fails the cross-check ("Protocol 'compliance_testing' reported but no matching tools found"), since the block declares the controller. The table's keys are now type-checked against `AdcpProtocol`. diff --git a/.changeset/capabilities-served-release-validation.md b/.changeset/capabilities-served-release-validation.md index 160da175e..908773ce6 100644 --- a/.changeset/capabilities-served-release-validation.md +++ b/.changeset/capabilities-served-release-validation.md @@ -2,4 +2,4 @@ '@adcp/sdk': patch --- -Capability discovery now validates `get_adcp_capabilities` against the release the seller served instead of the caller's pin (#3278). A 3.0 pin cannot carry `adcp_version`, so the SDK sends only `adcp_major_version: 3`. The seller then serves its highest 3.x release and echoes it in `adcp_version`, and the versioning spec says buyers validate against that echo. `discoverAgentProfile` (used by `testCapabilityDiscovery`, `comply()` and the storyboard runner) and `TaskExecutor` validated a 3.2 response strictly against 3.0. A conformant agent got false `capabilities_schema_issues` (for example `media_buy.features.bidding_policy must be boolean`, or the closed 3.0 `compliance_testing.scenarios` enum), and `getAdcpCapabilities()` failed in strict mode. Both now use the echoed release when it is in the pin's major and the SDK bundles its schema. They fall back to the pin when the echo is missing, from another major, or not bundled. Validation stays strict. +Capability discovery now validates `get_adcp_capabilities` against the release the seller served instead of the caller's pin (#3278). A 3.0 pin cannot carry `adcp_version`, so the SDK sends only `adcp_major_version: 3`. The seller then serves its highest 3.x release and echoes it in `adcp_version`, and the versioning spec says buyers validate against that echo. `discoverAgentProfile` (used by `testCapabilityDiscovery`, `comply()` and the storyboard runner) and `TaskExecutor` validated a 3.2 response strictly against 3.0. A conformant agent got false `capabilities_schema_issues` (for example `media_buy.features.bidding_policy must be boolean`, or the closed 3.0 `compliance_testing.scenarios` enum), and `getAdcpCapabilities()` failed in strict mode. Both now use the echoed release when it is in the pin's major and the SDK bundles its schema. They fall back to the pin when the echo is missing, from another major, or not bundled. Validation stays strict, and an external `schemaRoot` bound to the pin still takes precedence. diff --git a/src/lib/validation/served-version.ts b/src/lib/validation/served-version.ts index 579e96d9e..6958aa21d 100644 --- a/src/lib/validation/served-version.ts +++ b/src/lib/validation/served-version.ts @@ -16,7 +16,7 @@ * @internal — not part of the public API surface; may change without a major bump. */ -import { hasSchemaBundle, toReleasePrecisionWire } from './schema-loader'; +import { hasSchemaBundle, isExternalSchemaRootActive, toReleasePrecisionWire } from './schema-loader'; /** `core/version-envelope.json`'s `adcp_version` wire pattern (release precision). */ const RELEASE_PRECISION = /^(\d+)\.\d+(?:-[a-zA-Z0-9.-]+)?$/; @@ -35,11 +35,24 @@ const NUMERIC_PIN_MAJOR = /^(\d+)\.\d+/; * a patch-precise pin (and any external schema root bound to it) still * applies. `supported_versions` is deliberately not consulted: with no echo * the spec says to validate against the pin. + * + * Two deliberate consequences: + * - An external schema root the caller bound to the pin (`schemaRoot`, + * `withExternalSchemaRoot`) wins over the echo, matching the storyboard + * runner's `response_schema` precedence: the caller chose that protocol + * source explicitly. + * - An echo older than the pin (pin 3.2, served 3.0) is validated against the + * older release. That is the spec's downshift rule, not a loosening bug. */ export function resolveServedValidationVersion(response: unknown, pinnedVersion: string): string { const pinMajor = NUMERIC_PIN_MAJOR.exec(pinnedVersion)?.[1]; // Legacy aliases ('v2.5', 'v3') have their own adapter paths; leave them alone. if (pinMajor === undefined) return pinnedVersion; + try { + if (isExternalSchemaRootActive(pinnedVersion)) return pinnedVersion; + } catch { + return pinnedVersion; + } const echoed = response !== null && typeof response === 'object' diff --git a/test/lib/capabilities-served-release-validation.test.js b/test/lib/capabilities-served-release-validation.test.js index 6c043b51d..92b633b4d 100644 --- a/test/lib/capabilities-served-release-validation.test.js +++ b/test/lib/capabilities-served-release-validation.test.js @@ -16,6 +16,7 @@ const { describe, test, after } = require('node:test'); const assert = require('node:assert/strict'); const http = require('node:http'); +const path = require('node:path'); process.env.ADCP_ALLOW_INTERNAL_PROBES = '1'; @@ -23,6 +24,7 @@ const { ADCPMultiAgentClient } = require('../../dist/lib/index.js'); const { testCapabilityDiscovery } = require('../../dist/lib/testing/scenarios/capabilities.js'); const { closeMCPConnections } = require('../../dist/lib/protocols/mcp.js'); const { resolveServedValidationVersion } = require('../../dist/lib/validation/served-version.js'); +const { withExternalSchemaRoot } = require('../../dist/lib/validation/schema-loader.js'); /** A conformant AdCP 3.2 capabilities response, invalid against 3.0 and 3.1. */ function capabilities32(overrides = {}) { @@ -131,6 +133,27 @@ describe('resolveServedValidationVersion', () => { // Spec: with no echo, validate against the pin. assert.equal(resolveServedValidationVersion({ adcp: { supported_versions: ['3.0', '3.2'] } }, '3.0'), '3.0'); }); + + test('handles prerelease and legacy pins', () => { + assert.equal(resolveServedValidationVersion({ adcp_version: '3.2' }, '3.1-beta'), '3.2', 'stable echo, beta pin'); + assert.equal(resolveServedValidationVersion({ adcp_version: '3.1-beta.1' }, '3.1.0-beta.1'), '3.1.0-beta.1'); + assert.equal( + resolveServedValidationVersion({ adcp_version: '3.4-rc.1' }, '3.0'), + '3.0', + 'unbundled prerelease echo' + ); + assert.equal(resolveServedValidationVersion({ adcp_version: '3.2' }, 'v3'), 'v3', 'legacy alias pin'); + }); + + test('an external schema root bound to the pin wins over the echo', () => { + // Same precedence as the storyboard runner's response_schema check. + const root = path.join(__dirname, '../../dist/lib/schemas-data/3.0'); + const selected = withExternalSchemaRoot('3.0', root, () => + resolveServedValidationVersion({ adcp_version: '3.2' }, '3.0') + ); + assert.equal(selected, '3.0'); + assert.equal(resolveServedValidationVersion({ adcp_version: '3.2' }, '3.0'), '3.2', 'scope ended'); + }); }); describe('capability discovery with a 3.0 pin against a seller serving 3.2', () => { @@ -215,6 +238,20 @@ describe('capability discovery with a 3.0 pin against a seller serving 3.2', () assert.equal(result.success, true, result.error); }); + test('TaskExecutor uses the echo under an explicit major-only envelope', async t => { + // responseAdcpVersionForValidation() pins major-only validation to 3.0. + const seller = await withSeller(t, { payload: capabilities32() }); + const client = new ADCPMultiAgentClient( + [{ id: 'seller', name: 'Seller', agent_uri: seller.url, protocol: 'mcp' }], + { adcpVersion: '3.2', versionEnvelope: 'major-only', validation: { responses: 'strict' } } + ); + + const result = await client.agent('seller').getAdcpCapabilities({}); + + assert.equal(result.success, true, result.error); + assert.equal(seller.capabilityRequests.at(-1)?.adcp_version, undefined); + }); + test('TaskExecutor keeps strict validation against the served release', async t => { const payload = capabilities32({ media_buy: { features: { bidding_policy: {} } } }); const seller = await withSeller(t, { payload }); From 182120e5a4ff66f13a0fe8b36865d663c4e776e3 Mon Sep 17 00:00:00 2001 From: Brian O'Kelley Date: Thu, 15 Oct 2026 18:20:45 +0000 Subject: [PATCH 3/3] refactor(validation): keep resolveServedValidationVersion in schema-loader A separate module grew the @adcp/sdk/client/core eager graph past its 210-module budget and the packed file count past 6630. Co-Authored-By: Claude Opus 5.5 (1M context) --- src/lib/core/TaskExecutor.ts | 2 +- src/lib/testing/client.ts | 2 +- src/lib/validation/schema-loader.ts | 66 +++++++++++++++++ src/lib/validation/served-version.ts | 73 ------------------- ...bilities-served-release-validation.test.js | 6 +- 5 files changed, 72 insertions(+), 77 deletions(-) delete mode 100644 src/lib/validation/served-version.ts diff --git a/src/lib/core/TaskExecutor.ts b/src/lib/core/TaskExecutor.ts index 3cf09da83..a7fc4fcd7 100644 --- a/src/lib/core/TaskExecutor.ts +++ b/src/lib/core/TaskExecutor.ts @@ -34,7 +34,7 @@ import { type ValidationMode, } from '../validation/client-hooks'; import { formatIssues } from '../validation/schema-validator'; -import { resolveServedValidationVersion } from '../validation/served-version'; +import { resolveServedValidationVersion } from '../validation/schema-loader'; import { ADCP_VERSION } from '../version'; import { unwrapProtocolResponse, isAdcpOperationSuccess } from '../utils/response-unwrapper'; import { extractAdcpErrorInfo, extractCorrelationId } from '../utils/error-extraction'; diff --git a/src/lib/testing/client.ts b/src/lib/testing/client.ts index 457767b06..bf9b411b0 100644 --- a/src/lib/testing/client.ts +++ b/src/lib/testing/client.ts @@ -28,7 +28,7 @@ import type { AgentRequestSigningConfig } from '../types/adcp'; import { createHmac, hkdfSync, randomBytes } from 'node:crypto'; import { AsyncLocalStorage } from 'node:async_hooks'; import { validateIncomingResponse } from '../validation/client-hooks'; -import { resolveServedValidationVersion } from '../validation/served-version'; +import { resolveServedValidationVersion } from '../validation/schema-loader'; import { extractVersionUnsupportedDetails } from '../utils/error-extraction'; import { buildAgentSigningContext } from '../signing/client'; import type { VerifierCapability } from '../signing/types'; diff --git a/src/lib/validation/schema-loader.ts b/src/lib/validation/schema-loader.ts index 28bfbef4b..d0e76b89a 100644 --- a/src/lib/validation/schema-loader.ts +++ b/src/lib/validation/schema-loader.ts @@ -1280,6 +1280,72 @@ export function hasSchemaBundle(version: string): boolean { } } +/** Major of an echoed release-precision `adcp_version` (`core/version-envelope.json` wire pattern). */ +const SERVED_RELEASE_MAJOR = /^(\d+)\.\d+(?:-[a-zA-Z0-9.-]+)?$/; +/** Major of a numeric pin: `'3.0'`, `'3.0.25'`, `'3.1-beta'`, `'3.1.0-beta.1'`. */ +const NUMERIC_PIN_MAJOR = /^(\d+)\.\d+/; + +/** + * Select the AdCP release a seller response is validated against. + * + * The versioning spec (`docs/reference/versioning.mdx`, "Server echoes") says + * the seller echoes the release it actually served in `adcp_version`, and + * buyers SHOULD validate against that release's schema, not their pin; with + * no echo, against the pin. This matters most for `get_adcp_capabilities` + * under a 3.0 pin: the 3.0 bundle has no `adcp_version` request field, so the + * SDK sends only `adcp_major_version: 3` and the seller serves (and echoes) + * its highest 3.x release. + * + * Returns the version to validate `response` against: the echoed + * `adcp_version` when it is a usable release, otherwise `pinnedVersion`. + * + * The echo is used only when it is a release-precision string in the same + * major as the pin and the SDK has a schema bundle for it. Validation stays + * strict either way: an echo from another major, a malformed echo, or one the + * SDK cannot validate falls back to the pin rather than skipping validation. + * When the echo names the pinned release itself, the exact pin is returned so + * a patch-precise pin (and any external schema root bound to it) still + * applies. `supported_versions` is deliberately not consulted: with no echo + * the spec says to validate against the pin. + * + * Two deliberate consequences: + * - An external schema root the caller bound to the pin (`schemaRoot`, + * `withExternalSchemaRoot`) wins over the echo, matching the storyboard + * runner's `response_schema` precedence: the caller chose that protocol + * source explicitly. + * - An echo older than the pin (pin 3.2, served 3.0) is validated against the + * older release. That is the spec's downshift rule, not a loosening bug. + * + * @internal — not part of the public API surface; may change without a major bump. + */ +export function resolveServedValidationVersion(response: unknown, pinnedVersion: string): string { + const pinMajor = NUMERIC_PIN_MAJOR.exec(pinnedVersion)?.[1]; + // Legacy aliases ('v2.5', 'v3') have their own adapter paths; leave them alone. + if (pinMajor === undefined) return pinnedVersion; + try { + if (isExternalSchemaRootActive(pinnedVersion)) return pinnedVersion; + } catch { + return pinnedVersion; + } + + const echoed = + response !== null && typeof response === 'object' + ? (response as { adcp_version?: unknown }).adcp_version + : undefined; + if (typeof echoed !== 'string') return pinnedVersion; + const echoMajor = SERVED_RELEASE_MAJOR.exec(echoed)?.[1]; + if (echoMajor === undefined || echoMajor !== pinMajor) return pinnedVersion; + + let pinnedRelease: string; + try { + pinnedRelease = toReleasePrecisionWire(pinnedVersion); + } catch { + return pinnedVersion; + } + if (echoed === pinnedRelease) return pinnedVersion; + return hasSchemaBundle(echoed) ? echoed : pinnedVersion; +} + const mcpToolSchemaCache = new Map> | null>(); const mcpToolSummaryCache = new Map(); diff --git a/src/lib/validation/served-version.ts b/src/lib/validation/served-version.ts deleted file mode 100644 index 6958aa21d..000000000 --- a/src/lib/validation/served-version.ts +++ /dev/null @@ -1,73 +0,0 @@ -/** - * Select the AdCP release a seller response is validated against. - * - * The versioning spec (`docs/reference/versioning.mdx`, "Server echoes") - * says the seller echoes the release it actually served in `adcp_version`, - * and buyers SHOULD validate the response against that release's schema, - * not against their pin. When the response omits `adcp_version`, buyers - * validate against their own pin. - * - * The gap matters most for `get_adcp_capabilities` under a 3.0 pin: the 3.0 - * bundle has no `adcp_version` request field, so the SDK sends only - * `adcp_major_version: 3`, and the seller serves (and echoes) its highest 3.x - * release. Validating that response against 3.0 reports every newer shape as - * a schema violation. - * - * @internal — not part of the public API surface; may change without a major bump. - */ - -import { hasSchemaBundle, isExternalSchemaRootActive, toReleasePrecisionWire } from './schema-loader'; - -/** `core/version-envelope.json`'s `adcp_version` wire pattern (release precision). */ -const RELEASE_PRECISION = /^(\d+)\.\d+(?:-[a-zA-Z0-9.-]+)?$/; -/** Major of a numeric pin: `'3.0'`, `'3.0.25'`, `'3.1-beta'`, `'3.1.0-beta.1'`. */ -const NUMERIC_PIN_MAJOR = /^(\d+)\.\d+/; - -/** - * Return the version to validate `response` against: the echoed - * `adcp_version` when it is a usable release, otherwise `pinnedVersion`. - * - * The echo is used only when it is a release-precision string in the same - * major as the pin and the SDK has a schema bundle for it. Validation stays - * strict either way: an echo from another major, a malformed echo, or one the - * SDK cannot validate falls back to the pin rather than skipping validation. - * When the echo names the pinned release itself, the exact pin is returned so - * a patch-precise pin (and any external schema root bound to it) still - * applies. `supported_versions` is deliberately not consulted: with no echo - * the spec says to validate against the pin. - * - * Two deliberate consequences: - * - An external schema root the caller bound to the pin (`schemaRoot`, - * `withExternalSchemaRoot`) wins over the echo, matching the storyboard - * runner's `response_schema` precedence: the caller chose that protocol - * source explicitly. - * - An echo older than the pin (pin 3.2, served 3.0) is validated against the - * older release. That is the spec's downshift rule, not a loosening bug. - */ -export function resolveServedValidationVersion(response: unknown, pinnedVersion: string): string { - const pinMajor = NUMERIC_PIN_MAJOR.exec(pinnedVersion)?.[1]; - // Legacy aliases ('v2.5', 'v3') have their own adapter paths; leave them alone. - if (pinMajor === undefined) return pinnedVersion; - try { - if (isExternalSchemaRootActive(pinnedVersion)) return pinnedVersion; - } catch { - return pinnedVersion; - } - - const echoed = - response !== null && typeof response === 'object' - ? (response as { adcp_version?: unknown }).adcp_version - : undefined; - if (typeof echoed !== 'string') return pinnedVersion; - const echoMajor = RELEASE_PRECISION.exec(echoed)?.[1]; - if (echoMajor === undefined || echoMajor !== pinMajor) return pinnedVersion; - - let pinnedRelease: string; - try { - pinnedRelease = toReleasePrecisionWire(pinnedVersion); - } catch { - return pinnedVersion; - } - if (echoed === pinnedRelease) return pinnedVersion; - return hasSchemaBundle(echoed) ? echoed : pinnedVersion; -} diff --git a/test/lib/capabilities-served-release-validation.test.js b/test/lib/capabilities-served-release-validation.test.js index 92b633b4d..77444c780 100644 --- a/test/lib/capabilities-served-release-validation.test.js +++ b/test/lib/capabilities-served-release-validation.test.js @@ -23,8 +23,10 @@ process.env.ADCP_ALLOW_INTERNAL_PROBES = '1'; const { ADCPMultiAgentClient } = require('../../dist/lib/index.js'); const { testCapabilityDiscovery } = require('../../dist/lib/testing/scenarios/capabilities.js'); const { closeMCPConnections } = require('../../dist/lib/protocols/mcp.js'); -const { resolveServedValidationVersion } = require('../../dist/lib/validation/served-version.js'); -const { withExternalSchemaRoot } = require('../../dist/lib/validation/schema-loader.js'); +const { + resolveServedValidationVersion, + withExternalSchemaRoot, +} = require('../../dist/lib/validation/schema-loader.js'); /** A conformant AdCP 3.2 capabilities response, invalid against 3.0 and 3.1. */ function capabilities32(overrides = {}) {