From bb74004a5fc123f2790dd77e1201f52e042f5357 Mon Sep 17 00:00:00 2001 From: Brian O'Kelley Date: Sun, 15 Nov 2026 10:29:21 -0500 Subject: [PATCH 1/2] fix: keep stable pins off prerelease previews on SDK 16 (#3597) Backport of #3707. selectServedAdcpRelease let a release pin downshift onto an advertised prerelease, and let an unlisted prerelease pin resolve to a different one. SDK 16 packages no prerelease, but a seller can set adcpVersion to a preview it registers with registerExternalSchemaRoot. With supported_versions ['3.2', '3.3-rc.0'], a 3.3 or 3.4 pin was served 3.3-rc.0, and 3.3-rc.1 was served 3.3-rc.0. Release pins now select only releases, prerelease pins match exactly, and MCP tools/list stamps each framework tool with the selected release. The production change is identical to main. The main tests used ADCP_VERSION as the preview, which is 3.2.10 on 16.x, so the tests register a minimal external 3.3.0-rc.0 root instead (test/helpers/ external-preview-root.js). The changeset is reworded for 16.x. (cherry picked from commit 5f61fde22855689e484accdb29e026c4158edaab) Co-Authored-By: Claude Opus 5.5 --- .changeset/prerelease-preview-pins-16.md | 5 ++ src/lib/server/create-adcp-server.ts | 62 +++++++++++++++++---- src/lib/server/mcp-modern-server.ts | 4 +- test/helpers/external-preview-root.js | 42 +++++++++++++++ test/lib/mcp-modern-negotiation.test.js | 1 + test/server-a2a-adapter.test.js | 33 ++++++++++++ test/server-create-adcp-server.test.js | 68 ++++++++++++++++++++++++ test/server-idempotency.test.js | 33 ++++++++++++ 8 files changed, 238 insertions(+), 10 deletions(-) create mode 100644 .changeset/prerelease-preview-pins-16.md create mode 100644 test/helpers/external-preview-root.js diff --git a/.changeset/prerelease-preview-pins-16.md b/.changeset/prerelease-preview-pins-16.md new file mode 100644 index 000000000..a11e34b59 --- /dev/null +++ b/.changeset/prerelease-preview-pins-16.md @@ -0,0 +1,5 @@ +--- +'@adcp/sdk': patch +--- + +Keep stable AdCP pins on stable releases when a server's `adcpVersion` is a prerelease preview registered with `registerExternalSchemaRoot`. A release pin such as `3.3` or `3.4` no longer resolves onto the preview, and a prerelease pin must match an advertised prerelease exactly or get `VERSION_UNSUPPORTED`. MCP tool discovery reports the selected release in each framework tool's `_meta.adcp_version`. Backport of #3707. diff --git a/src/lib/server/create-adcp-server.ts b/src/lib/server/create-adcp-server.ts index fa273738a..f67eaa5bf 100644 --- a/src/lib/server/create-adcp-server.ts +++ b/src/lib/server/create-adcp-server.ts @@ -1,4 +1,5 @@ import { isPre31AdcpVersion } from '../utils/adcp-version-config'; +import { parseAdcpRelease as parseFullAdcpRelease } from '../adapters/version/negotiate'; import { assertWebBotAuthSigningKey, getWebBotAuthLegacyOriginGate } from '../signing/web-bot-auth'; import { downgradeResponse, @@ -82,6 +83,7 @@ import { IdentityAuthorizationError, TrustRecordUnavailableError } from '../iden import { z } from 'zod'; import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'; +import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js'; import { COMPATIBLE_ADCP_VERSIONS, parseAdcpMajorVersion, @@ -5186,7 +5188,16 @@ function selectServedAdcpRelease( }); } selected = supported - .filter(candidate => candidate.major === requested.major && compareAdcpRelease(candidate, requested) <= 0) + .filter(candidate => + requested.prerelease !== undefined + ? candidate.major === requested.major && + candidate.minor === requested.minor && + parseFullAdcpRelease(candidate.exactValue)?.patch === parseFullAdcpRelease(requested.exactValue)?.patch && + candidate.prerelease === requested.prerelease + : candidate.major === requested.major && + candidate.prerelease === undefined && + compareAdcpRelease(candidate, requested) <= 0 + ) .sort((left, right) => compareAdcpRelease(right, left))[0]; } else if (requestedMajor !== undefined && Number.isFinite(requestedMajor)) { // A major-only request may be a 3.0 buyer that cannot send @@ -9824,6 +9835,18 @@ export function createAdcpServer(config: AdcpServerConfig(MEDIA_BUY_MCP_TOOL_PROFILE); + const discoveryFallback = (requestedVersion: unknown): ServedAdcpRelease | undefined => { + if (!parseAdcpRelease(requestedVersion)?.prerelease) return undefined; + if (!parseAdcpRelease(selectedDefault.validationVersion)?.prerelease) return selectedDefault; + const ceiling = parseAdcpRelease(adcpVersion)!; + const stable = selectServedAdcpRelease( + { adcp_version: `${ceiling.major}.${ceiling.minor}` }, + capConfig, + adcpVersion, + defaultAdcpVersion + ); + return isMcpToolResponse(stable) ? undefined : stable; + }; const wrappedToolsList = wrapSdkRequestHandler(server, 'tools/list', async (original, request, extra) => { const response = await original(request, extra); if (response == null || typeof response !== 'object') return response; @@ -9846,9 +9869,16 @@ export function createAdcpServer(config: AdcpServerConfig(config: AdcpServerConfig { - if (listMcpToolProfile !== 'media-buy') return tool; const toolName = (tool as { name?: unknown } | null)?.name; if (typeof toolName !== 'string') return tool; - const inputSchema = getMcpProfileInputSchema(toolName, 'media-buy', listRelease.validationVersion); - return inputSchema ? { ...(tool as Record), inputSchema } : tool; + const toolRecord = tool as Record; + const meta = isPlainObject(toolRecord._meta) ? toolRecord._meta : undefined; + const frameworkAdcpTool = meta?.adcp_version === adcpVersion; + const inputSchema = + listMcpToolProfile === 'media-buy' + ? getMcpProfileInputSchema(toolName, 'media-buy', listRelease.validationVersion) + : undefined; + return { + ...toolRecord, + ...(frameworkAdcpTool && { + _meta: { ...meta, adcp_version: listRelease.advertisedVersion ?? listRelease.validationVersion }, + }), + ...(inputSchema && { inputSchema }), + }; }); return { @@ -10003,9 +10044,12 @@ export function createAdcpServer(config: AdcpServerConfig [tool, {}])) }) + ); + for (const [tool, domain] of Object.entries(TOOLS)) { + const dir = path.join(root, 'bundled', domain); + fs.mkdirSync(dir, { recursive: true }); + for (const kind of ['request', 'response']) { + const file = `${tool.replace(/_/g, '-')}-${kind}.json`; + fs.writeFileSync( + path.join(dir, file), + JSON.stringify({ $id: `https://adcontextprotocol.org/schemas/${version}/${domain}/${file}`, type: 'object' }) + ); + } + } + registerExternalSchemaRoot(version, root); + try { + return await fn(version); + } finally { + unregisterExternalSchemaRoot(version); + fs.rmSync(root, { recursive: true, force: true }); + } +} + +module.exports = { EXTERNAL_PREVIEW, withExternalPreviewRoot }; diff --git a/test/lib/mcp-modern-negotiation.test.js b/test/lib/mcp-modern-negotiation.test.js index 64c432a47..c8a76d8c6 100644 --- a/test/lib/mcp-modern-negotiation.test.js +++ b/test/lib/mcp-modern-negotiation.test.js @@ -862,6 +862,7 @@ test('modern discovery and direct calls apply the requested per-tool version ava assert.ok(names30.includes('get_products')); assert.ok(!names30.includes('get_signals')); assert.equal(listed30._meta.adcp_version, '3.0.25'); + assert.equal(listed30.tools.find(tool => tool.name === 'get_products')._meta.adcp_version, '3.0.25'); const rejected = await client.callTool({ name: 'get_signals', arguments: { adcp_version: '3.0.25' } }); assert.equal(rejected.isError, true); diff --git a/test/server-a2a-adapter.test.js b/test/server-a2a-adapter.test.js index 50cecd204..b3b11f4f7 100644 --- a/test/server-a2a-adapter.test.js +++ b/test/server-a2a-adapter.test.js @@ -1,4 +1,6 @@ const { describe, it } = require('node:test'); +const { toReleasePrecisionVersion } = require('../dist/lib/version.js'); +const { withExternalPreviewRoot } = require('./helpers/external-preview-root'); const assert = require('node:assert'); const express = require('express'); const { Role, SendMessageRequest, TaskState } = require('@a2a-js/sdk'); @@ -619,6 +621,37 @@ describe('createA2AAdapter', () => { }); describe('message/send routing', () => { + it('negotiates stable and exact preview pins through the executor', () => + withExternalPreviewRoot(async previewVersion => { + const adcp = createAdcpServer({ + name: 'Preview', + version: '1.0.0', + adcpVersion: previewVersion, + defaultAdcpVersion: '3.2.1', + capabilities: { supported_versions: ['3.2.1', previewVersion] }, + mediaBuy: { getProducts: async () => ({ products: [], cache_scope: 'public' }) }, + }); + const app = mountAdapter(createA2AAdapter({ server: adcp, agentCard: baseCard() })); + for (const [pin, expected] of [ + ['3.4', '3.2'], + [previewVersion, toReleasePrecisionVersion(previewVersion)], + ]) { + const res = await postJsonRpc(app, messageSend(dataPartMessage('get_products', { adcp_version: pin }))); + assert.strictEqual(res.body.result.status.state, 'completed', JSON.stringify(res.body)); + const data = res.body.result.artifacts[0].parts.find(part => part.kind === 'data').data; + assert.strictEqual(data.adcp_version, expected); + } + const refused = await postJsonRpc( + app, + messageSend( + dataPartMessage('get_products', { + adcp_version: previewVersion.replace(/(\d+)$/, (_, n) => String(Number(n) + 1)), + }) + ) + ); + assert.match(JSON.stringify(refused.body), /VERSION_UNSUPPORTED/); + })); + it('Success arm → Task.state=completed + DataPart artifact', async () => { const adcp = createAdcpServer({ mediaBuy: { getProducts: async () => ({ products: [{ product_id: 'p1' }] }) }, diff --git a/test/server-create-adcp-server.test.js b/test/server-create-adcp-server.test.js index ca91c529a..10a80a7e3 100644 --- a/test/server-create-adcp-server.test.js +++ b/test/server-create-adcp-server.test.js @@ -1,4 +1,6 @@ const { describe, it, mock } = require('node:test'); +const { toReleasePrecisionVersion } = require('../dist/lib/version.js'); +const { withExternalPreviewRoot } = require('./helpers/external-preview-root'); const assert = require('node:assert'); const { createAdcpServer: _createAdcpServer, @@ -208,6 +210,72 @@ describe('createAdcpServer', () => { assert.ok(enhancedContexts.every(Object.isFrozen)); }); + it('selects only exact prereleases and never downshifts a stable pin to a preview', () => + withExternalPreviewRoot(async preview => { + const previewWire = toReleasePrecisionVersion(preview); + const otherPreview = preview.replace(/(\d+)$/, (_, n) => String(Number(n) + 1)); + const otherPatch = preview.replace(/\.0-/, '.1-'); + const seen = []; + const server = createAdcpServer({ + name: 'Preview seller', + version: '1.0.0', + adcpVersion: preview, + defaultAdcpVersion: '3.2.1', + capabilities: { supported_versions: ['3.1.18', '3.2.1', preview] }, + mediaBuy: { + getProducts: async (_params, ctx) => { + seen.push(ctx.servedAdcpVersion); + return { products: [], cache_scope: 'public' }; + }, + }, + }); + for (const [pin, expected] of [ + [preview, previewWire], + ['3.3', '3.2'], + ['3.4', '3.2'], + [undefined, '3.2'], + ]) { + const args = pin ? { adcp_version: pin } : {}; + for (const result of [ + await callToolRaw(server, 'get_products', args), + await server.invoke({ toolName: 'get_products', args }), + ]) { + assert.notEqual(result.isError, true, JSON.stringify(result)); + assert.equal(result.structuredContent.adcp_version, expected); + assert.deepEqual(result.structuredContent.products, []); + } + for (const params of [{ adcp_version: pin }, { _meta: { adcp_version: pin } }]) { + const listed = await server.dispatchTestRequest({ method: 'tools/list', params }); + const advertised = expected === '3.2' ? '3.2.1' : preview; + assert.equal(listed._meta.adcp_version, advertised); + assert.equal(listed.tools.find(tool => tool.name === 'get_products')._meta.adcp_version, advertised); + } + } + assert.deepEqual(seen, [previewWire, previewWire, '3.2', '3.2', '3.2', '3.2', '3.2', '3.2']); + for (const pin of [otherPreview, otherPatch]) { + const result = await callToolRaw(server, 'get_products', { adcp_version: pin }); + assert.equal(result.structuredContent.adcp_error.code, 'VERSION_UNSUPPORTED'); + const listed = await server.dispatchTestRequest({ + method: 'tools/list', + params: { _meta: { adcp_version: pin } }, + }); + assert.equal(listed._meta.adcp_version, '3.2.1'); + } + const previewOnly = createAdcpServer({ + name: 'Preview only', + version: '1.0.0', + adcpVersion: preview, + capabilities: { supported_versions: [preview] }, + mediaBuy: { getProducts: async () => ({ products: [] }) }, + }); + const unavailable = await callToolRaw(previewOnly, 'get_products', { adcp_version: '3.4' }); + assert.equal(unavailable.structuredContent.adcp_error.code, 'VERSION_UNSUPPORTED'); + await assert.rejects( + previewOnly.dispatchTestRequest({ method: 'tools/list', params: { _meta: { adcp_version: '3.4' } } }), + /VERSION_UNSUPPORTED/ + ); + })); + it('rejects an unadvertised or newer defaultAdcpVersion at construction', () => { assert.throws( () => diff --git a/test/server-idempotency.test.js b/test/server-idempotency.test.js index c3505e8be..4834ea44d 100644 --- a/test/server-idempotency.test.js +++ b/test/server-idempotency.test.js @@ -1,4 +1,5 @@ const { describe, it, before, after } = require('node:test'); +const { withExternalPreviewRoot } = require('./helpers/external-preview-root'); const assert = require('node:assert/strict'); const { createAdcpServer: _createAdcpServer } = require('../dist/lib/server/create-adcp-server'); @@ -129,6 +130,38 @@ describe('createAdcpServer with idempotency', () => { assert.notEqual(result.replayed, true, 'fresh execution must not set replayed:true'); }); + it('preserves the request hash when a preview ceiling serves a stable pin', () => + withExternalPreviewRoot(async previewVersion => { + const idempotency = createIdempotencyStore({ backend: memoryBackend({ sweepIntervalMs: 0 }), ttlSeconds: 86400 }); + let calls = 0; + const makeVersioned = (ceiling, supported) => + createAdcpServer({ + name: 'Versioned', + version: '1.0.0', + adcpVersion: ceiling, + defaultAdcpVersion: '3.2.1', + capabilities: { supported_versions: supported }, + idempotency, + resolveSessionKey: () => 'tenant_a', + mediaBuy: { + createMediaBuy: async () => { + calls++; + return { media_buy_id: 'mb_1', packages: [] }; + }, + }, + }); + const stable = makeVersioned('3.2.1', ['3.2.1']); + const preview = makeVersioned(previewVersion, ['3.2.1', previewVersion]); + const request = { ...basePayload, adcp_version: '3.4', idempotency_key: 'version_hash_key_12345' }; + const first = await callTool(stable, 'create_media_buy', request); + const retry = await callTool(preview, 'create_media_buy', request); + assert.equal(first.media_buy_id, 'mb_1'); + assert.equal(retry.media_buy_id, 'mb_1'); + assert.equal(retry.replayed, true); + assert.equal(calls, 1); + assert.equal(request.adcp_version, '3.4'); + })); + it('replay with same key + equivalent payload returns cached response with replayed:true', async () => { const { server, calls } = makeServer(); const key = 'replay_key_abcdefghij'; From 49806b708375ee3e4ba628348a48ad37223b0a4a Mon Sep 17 00:00:00 2001 From: Brian O'Kelley Date: Tue, 17 Nov 2026 22:11:44 -0500 Subject: [PATCH 2/2] fix: keep tools/list lenient for unsupported stable pins on SDK 16 The #3707 cherry-pick made tools/list throw VERSION_UNSUPPORTED for every unsupported stable pin, where 16.x listed the default release. That is a behavior change for servers with no preview, so 16.x keeps the old fallback. When the default release is itself a preview, discovery lists the newest stable release instead, as #3707 does for prerelease pins. Co-Authored-By: Claude Opus 5.5 --- .changeset/prerelease-preview-pins-16.md | 2 +- src/lib/server/create-adcp-server.ts | 13 +++++++------ test/server-create-adcp-server.test.js | 17 +++++++++++++++++ 3 files changed, 25 insertions(+), 7 deletions(-) diff --git a/.changeset/prerelease-preview-pins-16.md b/.changeset/prerelease-preview-pins-16.md index a11e34b59..3c8708ca0 100644 --- a/.changeset/prerelease-preview-pins-16.md +++ b/.changeset/prerelease-preview-pins-16.md @@ -2,4 +2,4 @@ '@adcp/sdk': patch --- -Keep stable AdCP pins on stable releases when a server's `adcpVersion` is a prerelease preview registered with `registerExternalSchemaRoot`. A release pin such as `3.3` or `3.4` no longer resolves onto the preview, and a prerelease pin must match an advertised prerelease exactly or get `VERSION_UNSUPPORTED`. MCP tool discovery reports the selected release in each framework tool's `_meta.adcp_version`. Backport of #3707. +Keep stable AdCP pins on stable releases when a server's `adcpVersion` is a prerelease preview registered with `registerExternalSchemaRoot`. A release pin such as `3.3` or `3.4` no longer resolves onto the preview, and a prerelease pin must match an advertised prerelease exactly or get `VERSION_UNSUPPORTED`. MCP tool discovery reports the selected release in each framework tool's `_meta.adcp_version`, and still lists the default release for an unsupported pin rather than failing, without listing a preview for a pin that did not name it. Backport of #3707. diff --git a/src/lib/server/create-adcp-server.ts b/src/lib/server/create-adcp-server.ts index f67eaa5bf..763e493be 100644 --- a/src/lib/server/create-adcp-server.ts +++ b/src/lib/server/create-adcp-server.ts @@ -9835,8 +9835,11 @@ export function createAdcpServer(config: AdcpServerConfig(MEDIA_BUY_MCP_TOOL_PROFILE); - const discoveryFallback = (requestedVersion: unknown): ServedAdcpRelease | undefined => { - if (!parseAdcpRelease(requestedVersion)?.prerelease) return undefined; + // SDK 16 discovery stays lenient for every unsupported pin, as it was before + // prerelease-aware selection: list the default release. When the default is + // a preview, list the newest stable release instead, so discovery never + // moves a caller onto a preview it did not pin. + const discoveryFallback = (): ServedAdcpRelease | undefined => { if (!parseAdcpRelease(selectedDefault.validationVersion)?.prerelease) return selectedDefault; const ceiling = parseAdcpRelease(adcpVersion)!; const stable = selectServedAdcpRelease( @@ -9869,9 +9872,7 @@ export function createAdcpServer(config: AdcpServerConfig(config: AdcpServerConfig { ); })); + it('keeps tools/list lenient for an unsupported stable pin', async () => { + const stableOnly = createAdcpServer({ + name: 'Stable seller', + version: '1.0.0', + adcpVersion: '3.2.1', + capabilities: { supported_versions: ['3.1.18', '3.2.1'] }, + mediaBuy: { getProducts: async () => ({ products: [] }) }, + }); + const call = await callToolRaw(stableOnly, 'get_products', { adcp_version: '3.0' }); + assert.equal(call.structuredContent.adcp_error.code, 'VERSION_UNSUPPORTED'); + for (const params of [{ adcp_version: '3.0' }, { _meta: { adcp_version: '3.0' } }]) { + const listed = await stableOnly.dispatchTestRequest({ method: 'tools/list', params }); + assert.equal(listed._meta.adcp_version, '3.2.1'); + assert.equal(listed.tools.find(tool => tool.name === 'get_products')._meta.adcp_version, '3.2.1'); + } + }); + it('rejects an unadvertised or newer defaultAdcpVersion at construction', () => { assert.throws( () =>