diff --git a/.changeset/prerelease-preview-pins-16.md b/.changeset/prerelease-preview-pins-16.md new file mode 100644 index 000000000..3c8708ca0 --- /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`, 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 fa273738a..763e493be 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,21 @@ export function createAdcpServer(config: AdcpServerConfig(MEDIA_BUY_MCP_TOOL_PROFILE); + // 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( + { 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 +9872,14 @@ 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 +10045,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..73a6af04a 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,89 @@ 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('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( () => 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';