From 917906f6124d1ca3855321bfed03380671bfa3df Mon Sep 17 00:00:00 2001 From: Brian O'Kelley Date: Mon, 26 Oct 2026 04:14:54 +0000 Subject: [PATCH] fix(training-agent): withhold 3.3 fields from callers pinned below 3.3 The public training agent served AdCP 3.3 fields to callers pinned to 3.2 and below, so stable SDKs (16.x, validating against 3.2.7) logged schema warnings (#8487). The agent is a 3.2 seller in production; it serves 3.3 only through the local candidate wire contract. It gated some newer fields by served version, but nothing kept fields added after the served release out of a response in general. Fields leaked to 3.2 / 3.1 / 3.0 callers: - list_products: installments on core/canonical-product.json (closed in 3.2, so every stable SDK reports the products invalid). Sales tenant and the v5 /mcp route. - get_adcp_capabilities, every tenant: account.stable_account_id. - get_adcp_capabilities, sales and /mcp: media_buy.features .supports_property_breakdown and .supports_installment_property_breakdown, media_buy.vendor_metric_optimization.supported_metrics. - get_adcp_capabilities, governance: governance.supports_budget_periods. - sync_audiences and sync_event_sources: platform_id. - get_adcp_capabilities on sales at 3.1: the 3.2 sales-dooh specialism (closed enum). - get_adcp_capabilities on /mcp at 3.1 and 3.0: the 3.2 media_buy.anonymous_discovery, availability_horizon, outcome_target and signals.anonymous_discovery. The agent emits none of the experimental 3.3 hold or collection surfaces (hold_policy, hold_placed_at, hold ranking, holds[], collections[], include_collections, list_collections, follower counts). Fix: served-release-fields.ts walks a response alongside the source schema and withholds every property whose declaration carries an x-added-in newer than the served release line. Composition is walked as a union, so a field some branch already had in the served release is kept. It is the final gate on get_adcp_capabilities (tenant router and v5 handler), on list_products canonical products, and on sync_audiences and sync_event_sources. Specialisms are filtered by the served release's own enums/specialism.json, replacing the one-off sales-fixed-rate check. A prerelease pin the SDK ships no bundle for reads its release line. Tests: - tenants/served-release-shape.test.ts: on every tenant route and /mcp, callers pinned to 3.2, 3.1 and 3.0 get no field added after their release, and responses validate against the served bundle (all graded tools at 3.2, capabilities at every pin). Fails on main for installments and every leak above. - training-agent-candidate-version.test.ts: a 3.3 caller still gets installments, stable_account_id, the breakdown flags, supported_metrics, supports_budget_periods and platform_id; a 3.2 pin does not. - list_products canonical, creator and seller-managed event source suites now call as a 3.3 caller; a new case validates every 3.2 list_products page against the 3.2 bundle. Co-Authored-By: Claude Opus 5.5 (1M context) --- .../src/training-agent/audience-handlers.ts | 13 +- .../training-agent/catalog-event-handlers.ts | 14 +- .../training-agent/served-release-fields.ts | 273 ++++++++++++++++++ server/src/training-agent/source-schema.ts | 6 + server/src/training-agent/task-handlers.ts | 49 +++- server/src/training-agent/tenants/router.ts | 27 +- .../tenants/served-release-shape.test.ts | 223 ++++++++++++++ .../tenants/tenant-smoke.test.ts | 7 +- server/src/training-agent/types.ts | 29 +- ...raining-agent-availability-windows.test.ts | 3 +- .../training-agent-candidate-version.test.ts | 83 ++++++ .../unit/training-agent-creators.test.ts | 12 +- ...ning-agent-list-products-canonical.test.ts | 59 +++- .../training-agent-outcome-target.test.ts | 3 +- ...agent-seller-managed-event-sources.test.ts | 12 +- ...aining-agent-served-release-fields.test.ts | 65 +++++ .../training-agent-stable-account-id.test.ts | 16 +- server/tests/unit/training-agent.test.ts | 37 +-- 18 files changed, 850 insertions(+), 81 deletions(-) create mode 100644 server/src/training-agent/served-release-fields.ts create mode 100644 server/src/training-agent/tenants/served-release-shape.test.ts create mode 100644 server/tests/unit/training-agent-served-release-fields.test.ts diff --git a/server/src/training-agent/audience-handlers.ts b/server/src/training-agent/audience-handlers.ts index 5b66c8abcd2..f11f8c8b1cf 100644 --- a/server/src/training-agent/audience-handlers.ts +++ b/server/src/training-agent/audience-handlers.ts @@ -12,7 +12,8 @@ */ import { randomUUID } from 'node:crypto'; -import { atLeastAdcpVersion, type TrainingContext, type ToolArgs } from './types.js'; +import { atLeastAdcpVersion, TRAINING_AGENT_CURRENT_ADCP_VERSION, type TrainingContext, type ToolArgs } from './types.js'; +import { omitFieldsAddedAfterRelease } from './served-release-fields.js'; import { sessionKeyFromArgs } from './state.js'; import { TRAINING_AUDIENCE_ACTIVATION_METHODS } from './product-factory.js'; @@ -471,7 +472,17 @@ function sourceResponse( // ── Handler implementation ────────────────────────────────────── +/** sync_audiences shaped to the served release: the 3.3 `platform_id` (and + * any other field added after it) stays off a response served below 3.3. */ export async function handleSyncAudiences(args: ToolArgs, ctx: TrainingContext) { + return omitFieldsAddedAfterRelease( + await syncAudiences(args, ctx), + 'media-buy/sync-audiences-response.json', + ctx.servedAdcpVersion ?? TRAINING_AGENT_CURRENT_ADCP_VERSION, + ); +} + +async function syncAudiences(args: ToolArgs, ctx: TrainingContext) { const req = args as unknown as SyncAudiencesInput; if (!req.account) { diff --git a/server/src/training-agent/catalog-event-handlers.ts b/server/src/training-agent/catalog-event-handlers.ts index 00dcebc7628..4c0a5fc3666 100644 --- a/server/src/training-agent/catalog-event-handlers.ts +++ b/server/src/training-agent/catalog-event-handlers.ts @@ -6,7 +6,8 @@ */ import { createHash, randomUUID } from 'node:crypto'; -import type { TrainingContext, ToolArgs, AccountRef } from './types.js'; +import { TRAINING_AGENT_CURRENT_ADCP_VERSION, type TrainingContext, type ToolArgs, type AccountRef } from './types.js'; +import { omitFieldsAddedAfterRelease } from './served-release-fields.js'; import { getSession, sessionKeyFromArgs, findMediaBuyAcrossSessions } from './state.js'; // ── Types ──────────────────────────────────────────────────────── @@ -735,7 +736,18 @@ export async function handleSyncCatalogs(args: ToolArgs, ctx: TrainingContext) { }; } +/** sync_event_sources shaped to the served release: the 3.3 `platform_id` + * (and any other field added after it) stays off a response served below + * 3.3. */ export async function handleSyncEventSources(args: ToolArgs, ctx: TrainingContext) { + return omitFieldsAddedAfterRelease( + await syncEventSources(args, ctx), + 'media-buy/sync-event-sources-response.json', + ctx.servedAdcpVersion ?? TRAINING_AGENT_CURRENT_ADCP_VERSION, + ); +} + +async function syncEventSources(args: ToolArgs, ctx: TrainingContext) { const req = args as unknown as SyncEventSourcesInput; if (!req.account) { diff --git a/server/src/training-agent/served-release-fields.ts b/server/src/training-agent/served-release-fields.ts new file mode 100644 index 00000000000..217d5edd367 --- /dev/null +++ b/server/src/training-agent/served-release-fields.ts @@ -0,0 +1,273 @@ +import { getSchemaDocumentByRef } from '@adcp/sdk/schemas'; +import { sourceSchemaDocument } from './source-schema.js'; + +/** + * Fields a response must not carry because the source schemas mark them as + * added after the release it is served at. + * + * versioning.mdx ("Server shapes to the served release"): a response echoing + * release R validates against R's schema, and the seller omits what R does + * not define. A field added in 3.3 breaks a 3.2 consumer outright when 3.2 + * closes the object (`core/canonical-product.json` and `installments`, #8487) + * and is still a claim 3.2 never defined when the object is open (a 3.2 + * `media_buy.features` map accepts any boolean). + * + * `x-added-in` is the machine-readable "new in this release" marker the + * schemas carry for SDK generators (tests/x-added-in-3-3-sweep.test.cjs pins + * it on the 3.3 additions). Reading it from the source schema keeps this gate + * in step with the fields a later release adds, with no hand-kept list. + * + * The walk follows the source schema alongside the value. Composition + * (`allOf`/`oneOf`/`anyOf`, `if`/`then`/`else`) is walked as a union: a + * property is withheld only when every declaration of it the walk reaches is + * newer than the served release, so a name some branch already had in that + * release is always kept. Undeclared keys under an open object, `ext` and + * `context` included, are left alone. + * + * The marker describes the declaration, not always the wire: a release can + * require a key it never declared (3.2 `validate_input` warnings require an + * undeclared `field`, which 3.3 declares with `x-added-in`). Gate a response + * only where the served release's own bundle agrees; + * tenants/served-release-shape.test.ts grades each gated response against it. + */ + +type Schema = Readonly>; + +interface Located { + node: Schema; + file: string; +} + +function isRecord(value: unknown): value is Record { + return typeof value === 'object' && value !== null && !Array.isArray(value); +} + +function pointerTarget(document: Schema, fragment: string): unknown { + if (!fragment) return document; + return fragment.slice(1).split('/') + .map(segment => segment.replaceAll('~1', '/').replaceAll('~0', '~')) + .reduce((node, segment) => (isRecord(node) ? node[segment] : undefined), document); +} + +/** Follow a `$ref` chain to the schema node it names. */ +function dereference(node: unknown, file: string, seen = new Set()): Located | undefined { + if (!isRecord(node)) return undefined; + const ref = node.$ref; + if (typeof ref !== 'string') return { node, file }; + const hash = ref.indexOf('#'); + const target = hash === -1 ? ref : ref.slice(0, hash); + const fragment = hash === -1 ? '' : ref.slice(hash + 1); + const targetFile = target ? target.replace(/^\/schemas\//, '') : file; + const key = `${targetFile}#${fragment}`; + if (seen.has(key)) return undefined; + seen.add(key); + return dereference(pointerTarget(sourceSchemaDocument(targetFile), fragment), targetFile, seen); +} + +const alternativesCache = new WeakMap>(); + +/** Every schema a value at this node may satisfy, composition flattened. */ +function alternatives(node: unknown, file: string): Located[] { + if (!isRecord(node)) return []; + let byFile = alternativesCache.get(node); + const cached = byFile?.get(file); + if (cached) return cached; + const out: Located[] = []; + const visited = new Set(); + const visit = (candidate: unknown, candidateFile: string) => { + const located = dereference(candidate, candidateFile); + if (!located || visited.has(located.node)) return; + visited.add(located.node); + out.push(located); + for (const keyword of ['allOf', 'oneOf', 'anyOf'] as const) { + const branches = located.node[keyword]; + if (Array.isArray(branches)) for (const branch of branches) visit(branch, located.file); + } + for (const keyword of ['then', 'else'] as const) { + if (located.node[keyword] !== undefined) visit(located.node[keyword], located.file); + } + }; + visit(node, file); + if (!byFile) { + byFile = new Map(); + alternativesCache.set(node, byFile); + } + byFile.set(file, out); + return out; +} + +function releaseLine(version: string): [number, number] | undefined { + const match = /^(\d+)\.(\d+)/.exec(version); + return match ? [Number(match[1]), Number(match[2])] : undefined; +} + +function addedAfter(addedIn: unknown, servedLine: [number, number]): boolean { + if (typeof addedIn !== 'string') return false; + const added = releaseLine(addedIn); + if (!added) return false; + return added[0] > servedLine[0] || (added[0] === servedLine[0] && added[1] > servedLine[1]); +} + +/** A property declaration is newer when it, or the whole schema file it + * points at (`"hold_policy": { "$ref": "/schemas/core/hold-policy.json" }`), + * carries a newer `x-added-in`. */ +function declaredAfter(declaration: Located, servedLine: [number, number]): boolean { + if (addedAfter(declaration.node['x-added-in'], servedLine)) return true; + const target = dereference(declaration.node, declaration.file); + return target !== undefined && addedAfter(target.node['x-added-in'], servedLine); +} + +/** Union of the alternatives of several schemas, each node once. Shared + * `$ref` targets would otherwise repeat once per branch and compound at every + * level of a deep value. */ +function alternativesOf(schemas: readonly Located[]): Located[] { + const seen = new Set(); + const out: Located[] = []; + for (const { node, file } of schemas) { + for (const located of alternatives(node, file)) { + if (seen.has(located.node)) continue; + seen.add(located.node); + out.push(located); + } + } + return out; +} + +function collect( + value: unknown, + schemas: readonly Located[], + servedLine: [number, number], + path: string[], + found: string[][], +): void { + if (schemas.length === 0) return; + if (Array.isArray(value)) { + const items = alternativesOf(schemas + .filter(({ node }) => node.items !== undefined) + .map(({ node, file }) => ({ node: node.items as Schema, file }))); + value.forEach((item, index) => collect(item, items, servedLine, [...path, String(index)], found)); + return; + } + if (!isRecord(value)) return; + for (const [key, child] of Object.entries(value)) { + const declarations: Located[] = []; + for (const { node, file } of schemas) { + const properties = node.properties; + if (isRecord(properties) && properties[key] !== undefined) { + declarations.push({ node: properties[key] as Schema, file }); + } else if (isRecord(node.additionalProperties)) { + declarations.push({ node: node.additionalProperties, file }); + } + } + if (declarations.length === 0) continue; + const current = declarations.filter(declaration => !declaredAfter(declaration, servedLine)); + if (current.length === 0) { + found.push([...path, key]); + continue; + } + collect(child, alternativesOf(current), servedLine, [...path, key], found); + } +} + +function fieldPaths(value: unknown, schemaFile: string, servedVersion: string): string[][] { + const servedLine = releaseLine(servedVersion); + if (!servedLine) return []; + const found: string[][] = []; + collect(value, alternatives(sourceSchemaDocument(schemaFile), schemaFile), servedLine, [], found); + return found; +} + +/** + * Top-level properties of `schemaFile` that are added after + * `servedVersion`'s release line, e.g. `installments` on + * `core/canonical-product.json` for a 3.2 response. + */ +const addedProperties = new Map>(); + +export function propertiesAddedAfterRelease(schemaFile: string, servedVersion: string): ReadonlySet { + const servedLine = releaseLine(servedVersion); + if (!servedLine) return new Set(); + const key = `${schemaFile}\0${servedLine.join('.')}`; + const cached = addedProperties.get(key); + if (cached) return cached; + const declarations = new Map(); + for (const { node, file } of alternatives(sourceSchemaDocument(schemaFile), schemaFile)) { + if (!isRecord(node.properties)) continue; + for (const [name, declaration] of Object.entries(node.properties)) { + declarations.set(name, [...(declarations.get(name) ?? []), { node: declaration as Schema, file }]); + } + } + const added = new Set([...declarations] + .filter(([, located]) => located.every(declaration => declaredAfter(declaration, servedLine))) + .map(([name]) => name)); + addedProperties.set(key, added); + return added; +} + +/** + * JSON pointers of the fields in `value` that `schemaFile` (relative to + * static/schemas/source, e.g. `core/canonical-product.json`) marks as added + * after `servedVersion`'s release line. + */ +export function fieldsAddedAfterRelease(value: unknown, schemaFile: string, servedVersion: string): string[] { + return fieldPaths(value, schemaFile, servedVersion) + .map(path => `/${path.map(segment => segment.replaceAll('~', '~0').replaceAll('/', '~1')).join('/')}`); +} + +/** + * `value` without the fields `schemaFile` marks as added after + * `servedVersion`'s release line. Returns `value` itself when nothing is + * withheld, otherwise a copy; the input is never mutated. + */ +export function omitFieldsAddedAfterRelease(value: T, schemaFile: string, servedVersion: string): T { + const paths = fieldPaths(value, schemaFile, servedVersion); + if (paths.length === 0) return value; + const copy = structuredClone(value); + for (const path of paths) { + const parent = path.slice(0, -1).reduce( + (node, segment) => (isRecord(node) || Array.isArray(node) ? (node as Record)[segment] : undefined), + copy, + ); + if (isRecord(parent)) delete parent[path[path.length - 1]]; + } + return copy; +} + +const servedEnums = new Map | null>(); + +function enumValues(schemaRef: string, version: string): unknown { + return (getSchemaDocumentByRef(schemaRef, version)?.schema as { enum?: unknown } | undefined)?.enum; +} + +/** + * Values the served release's own enum schema (`enums/specialism.json`) + * allows. Unlike a field, an enum value carries no `x-added-in`, so the + * served bundle is the source. A prerelease pin whose bundle the SDK does not + * ship (`3.1-rc.15`, `3.2-rc.0`) is read from its release line's bundle, which + * still rejects every value a later line adds. Null only when neither bundle + * is available, in which case callers leave their list as is (the + * compliance-scenarios precedent). + */ +export function servedReleaseEnum(schemaRef: string, servedVersion: string): ReadonlySet | null { + const key = `${servedVersion}\0${schemaRef}`; + const cached = servedEnums.get(key); + if (cached !== undefined) return cached; + let values: unknown; + try { + values = enumValues(schemaRef, servedVersion); + } catch { + const line = /^(\d+\.\d+)-/.exec(servedVersion)?.[1]; + try { + if (!line) return null; + values = enumValues(schemaRef, line); + } catch { + // Retry on the next call: the bundle may be registered later. + return null; + } + } + const allowed = Array.isArray(values) + ? new Set(values.filter((value): value is string => typeof value === 'string')) + : null; + servedEnums.set(key, allowed); + return allowed; +} diff --git a/server/src/training-agent/source-schema.ts b/server/src/training-agent/source-schema.ts index 0de56145635..a935cf4a345 100644 --- a/server/src/training-agent/source-schema.ts +++ b/server/src/training-agent/source-schema.ts @@ -214,6 +214,12 @@ export function loadSourceSchema(relativePath: string): JsonSchema { return structuredClone(readSchema(relativePath)); } +/** The shared parsed source schema, for read-only walks. Callers must not + * mutate it; loadSourceSchema returns a private copy. */ +export function sourceSchemaDocument(relativePath: string): Readonly { + return readSchema(relativePath); +} + function schemaFiles(directory: string): string[] { return readdirSync(directory, { withFileTypes: true }).flatMap(entry => { const path = join(directory, entry.name); diff --git a/server/src/training-agent/task-handlers.ts b/server/src/training-agent/task-handlers.ts index 41c6dd45a91..cabb9a79660 100644 --- a/server/src/training-agent/task-handlers.ts +++ b/server/src/training-agent/task-handlers.ts @@ -75,6 +75,7 @@ import { resolveReportingAccountDurably, } from './reporting-reliability.js'; import { loadSourceSchema, validateSourceSchema } from './source-schema.js'; +import { omitFieldsAddedAfterRelease, propertiesAddedAfterRelease } from './served-release-fields.js'; import { TRAINING_AGGREGATE_FREQUENCY_CAPPING, TRAINING_PACKAGE_FREQUENCY_CAPPING, @@ -7767,6 +7768,8 @@ function compactCanonicalProduct(product: Record): Record, fields: ReadonlySet< } /** Project the additive 3.x get_products representation into the closed - * canonical offer shape used by list_products. */ + * canonical offer shape used by list_products. With a served release, fields + * the source schema adds after it (for 3.2, the 3.3 `installments`) are + * withheld; without one the projection follows the source schema. */ export function compactLifecycleProduct( product: Record, requestedFields?: ReadonlySet, requiredFields: ReadonlySet = new Set(), + servedAdcpVersion?: string, ): Record { - const selectedFields = requestedFields - ? new Set(['product_id', 'name', ...requestedFields, ...requiredFields]) - : COMPACT_PRODUCT_FIELDS; + const withheldFields = servedAdcpVersion === undefined + ? new Set() + : propertiesAddedAfterRelease(CANONICAL_PRODUCT_SCHEMA, servedAdcpVersion); + const selectedFields = new Set([...(requestedFields + ? ['product_id', 'name', ...requestedFields, ...requiredFields] + : COMPACT_PRODUCT_FIELDS)].filter(field => !withheldFields.has(field))); const projected = pickCompactFields(product, selectedFields); // A returned overlay_support.collection_list is only schema-valid alongside // collection_targeting_allowed: true, so it overrides a narrower projection. @@ -7958,7 +7967,9 @@ export function compactLifecycleProduct( compactReportingCapabilityFields(), ); } - return projected; + return servedAdcpVersion === undefined + ? projected + : omitFieldsAddedAfterRelease(projected, CANONICAL_PRODUCT_SCHEMA, servedAdcpVersion); } /** Match a buyer's future targeting requirement against a Product's binding @@ -10030,6 +10041,7 @@ export function projectProductDiscoveryResult( toolName: string, result: Record, originalArgs: Record, + servedAdcpVersion: string, ): Record { if (!isProductDiscoveryTool(toolName) || toolName === 'get_products') return result; if (Array.isArray(result.errors) && result.errors.length > 0 && !Array.isArray(result.products)) return result; @@ -10110,7 +10122,12 @@ export function projectProductDiscoveryResult( } return { outcome: 'listed', - products: products.map(product => compactLifecycleProduct(product, requestedFields, requiredProductFields)), + products: products.map(product => compactLifecycleProduct( + product, + requestedFields, + requiredProductFields, + servedAdcpVersion, + )), ...(pagination && typeof pagination.cursor === 'string' && { next_cursor: pagination.cursor }), ...(typeof result.wholesale_feed_version === 'string' && { feed_version: result.wholesale_feed_version }), ...(typeof result.pricing_version === 'string' && { pricing_version: result.pricing_version }), @@ -20446,7 +20463,7 @@ export async function handleGetAdcpCapabilities(args: ToolArgs, ctx: TrainingCon const supportedCreativeFormats = includeThreeOneFields(ctx) ? supportedCanonicalFormatsCapability() : undefined; - return { + const capabilities = { adcp_version: DEFAULT_ADCP_VERSION, adcp: { major_versions: [...SUPPORTED_MAJOR_VERSIONS], @@ -20673,6 +20690,13 @@ export async function handleGetAdcpCapabilities(args: ToolArgs, ctx: TrainingCon description: 'Training agent for AdCP protocol testing and certification', }, }; + // Withhold fields added after the served release, such as the 3.3 + // property-breakdown feature flags on a 3.2 response. + return omitFieldsAddedAfterRelease( + capabilities, + 'protocol/get-adcp-capabilities-response.json', + isThreeZeroResponse ? '3.0' : servedAdcpVersion, + ); } // ── Signal task handlers ────────────────────────────────────────── @@ -23096,13 +23120,14 @@ export async function executeProductDiscoveryPlatformTool( return proposalArgs; })() : normalizeProductDiscoveryArgs(toolName, args); + const servedAdcpVersion = ctx.servedAdcpVersion ?? CURRENT_ADCP_VERSION; const result = await Promise.resolve(handler(normalized as ToolArgs, { ...ctx, - servedAdcpVersion: ctx.servedAdcpVersion ?? CURRENT_ADCP_VERSION, + servedAdcpVersion, })); await flushDirtySessions(); if (typedRefinement) return result as Record; - return projectProductDiscoveryResult(toolName, result as Record, args); + return projectProductDiscoveryResult(toolName, result as Record, args, servedAdcpVersion); } function legacyPackagesFromPurchases( @@ -24627,6 +24652,7 @@ async function executeTrainingAgentToolInContext( toolName, outcome.response as Record, initialHandlerArgs, + versionResolution.servedVersion, ); return { success: true, @@ -24664,6 +24690,7 @@ async function executeTrainingAgentToolInContext( toolName, result as Record, initialHandlerArgs, + versionResolution.servedVersion, ); const response = addServedAdcpVersion(projectedResponse, versionResolution.servedVersion, callerContext) as Record; if (claim && typeof idempotencyKey === 'string') { @@ -25011,6 +25038,7 @@ export function createTrainingAgentServer(ctx: TrainingContext): Server { name, outcome.response as Record, initialHandlerArgs, + servedAdcpVersion, ); const body: Record = { ...replayBody, replayed: true }; if (!isTaskRequest && body.status === undefined) body.status = 'completed'; @@ -25211,7 +25239,7 @@ export function createTrainingAgentServer(ctx: TrainingContext): Server { // `completed` on synchronous success — handlers that emit a different // TaskStatus (e.g., `submitted` for async-task envelopes) set it on // `inner` and we honor that value. - const outwardInner = projectProductDiscoveryResult(name, inner, initialHandlerArgs); + const outwardInner = projectProductDiscoveryResult(name, inner, initialHandlerArgs, servedAdcpVersion); const response: Record = { ...outwardInner }; if (response.status === undefined) response.status = 'completed'; response.adcp_version = servedAdcpVersion; @@ -25300,6 +25328,7 @@ export function createTrainingAgentServer(ctx: TrainingContext): Server { name, cachableResponse, initialHandlerArgs, + servedAdcpVersion, ); maybeEmitCompletionWebhook({ toolName: name, diff --git a/server/src/training-agent/tenants/router.ts b/server/src/training-agent/tenants/router.ts index 44b8a032e41..82a8e985761 100644 --- a/server/src/training-agent/tenants/router.ts +++ b/server/src/training-agent/tenants/router.ts @@ -52,9 +52,10 @@ import { supportedCanonicalFormatsCapability, } from '../task-handlers.js'; import { sellerOptimizedDeclarationForVersion, sellerOptimizedFeatureFlags } from '../seller-optimized-budget.js'; -import { advertisesSalesFixedRateSpecialism, supportsAccountChangeFeed, supportsBiddingPolicyCapability, TRAINING_BIDDING_POLICY_CAPABILITY, supportsGetProductsRejected, supportsReliableReporting, supportsReportingStatus, supportsSalesFixedRate, supportsSellerGovernanceDiscovery, TRAINING_AGENT_CURRENT_ADCP_VERSION, TRAINING_AGENT_DEFAULT_ADCP_VERSION, TRAINING_AGENT_SUPPORTED_RELEASE_VERSIONS, type TrainingContext } from '../types.js'; +import { supportsAccountChangeFeed, supportsBiddingPolicyCapability, TRAINING_BIDDING_POLICY_CAPABILITY, supportsGetProductsRejected, supportsReliableReporting, supportsReportingStatus, supportsSalesFixedRate, supportsSellerGovernanceDiscovery, TRAINING_AGENT_CURRENT_ADCP_VERSION, TRAINING_AGENT_DEFAULT_ADCP_VERSION, TRAINING_AGENT_SUPPORTED_RELEASE_VERSIONS, type TrainingContext } from '../types.js'; import { getIdentityBaseUrl } from '../config.js'; import { complianceScenariosForServedVersion } from '../compliance-scenarios.js'; +import { omitFieldsAddedAfterRelease, servedReleaseEnum } from '../served-release-fields.js'; import { runWithReleaseLineEcho } from './release-line-echo.js'; import { redactConflictEnvelopeInBody } from '../conflict-envelope.js'; import { proposalCapabilitiesForProfile } from '../proposal-negotiation-profiles.js'; @@ -1017,11 +1018,16 @@ function projectTenantCapabilities( ? structured.adcp_version : TRAINING_AGENT_DEFAULT_ADCP_VERSION); structured.adcp_version = servedVersion; - // `sales-fixed-rate` is a 3.3 enum value. Consumers served 3.2 or below - // validate `specialisms` against a closed enum that predates it, so the - // id is withdrawn from their capability response (DR-0024). - if (Array.isArray(structured.specialisms) && !advertisesSalesFixedRateSpecialism(servedVersion)) { - structured.specialisms = structured.specialisms.filter(id => id !== 'sales-fixed-rate'); + // `specialisms` is a closed enum in every release, so a consumer served an + // older release never sees an id added after it (DR-0024): the 3.3 + // `sales-fixed-rate` below 3.3, the 3.2 `sales-dooh` below 3.2. + const allowedSpecialisms = Array.isArray(structured.specialisms) + ? servedReleaseEnum('enums/specialism.json', storyboardCompat?.version === '3.0' ? '3.0' : servedVersion) + : null; + if (allowedSpecialisms && Array.isArray(structured.specialisms)) { + structured.specialisms = structured.specialisms.filter( + (id): id is string => typeof id === 'string' && allowedSpecialisms.has(id), + ); } const adcp = structured.adcp && typeof structured.adcp === 'object' ? structured.adcp @@ -1336,6 +1342,15 @@ function projectTenantCapabilities( } } projectWholesaleCapabilities(structured, tenantId, storyboardCompat); + // Every tenant, last: withhold fields added after the served release + // (3.3 account.stable_account_id, governance.supports_budget_periods, + // the property-breakdown feature flags, ...), whichever projection above + // or SDK derivation contributed them. + parsed.result!.structuredContent = omitFieldsAddedAfterRelease( + structured, + 'protocol/get-adcp-capabilities-response.json', + storyboardCompat?.version === '3.0' ? '3.0' : servedVersion, + ); const firstText = parsed.result?.content?.[0]; if (firstText?.type === 'text') { firstText.text = 'Capabilities retrieved successfully.'; diff --git a/server/src/training-agent/tenants/served-release-shape.test.ts b/server/src/training-agent/tenants/served-release-shape.test.ts new file mode 100644 index 00000000000..c7f5a1fff9e --- /dev/null +++ b/server/src/training-agent/tenants/served-release-shape.test.ts @@ -0,0 +1,223 @@ +/** + * #8487: a caller pinned below 3.3 gets the shape of the release the response + * echoes. versioning.mdx ("Server shapes to the served release"): the + * response validates against that release's schema and omits what the + * release does not define. + * + * Two checks on every route: + * + * - No field the source schemas mark as added after the served release + * (`x-added-in`). This catches a 3.3 field under an object 3.2 leaves open, + * which the 3.2 schema cannot catch. + * - The response validates against the served release's own bundle, as + * stable SDKs validate it (16.x against 3.2.7). This catches anything new + * under an object the release closes, annotated or not. + * + * The 3.3 side (the same fields still reach a 3.3 caller) is covered in + * tests/unit/training-agent-candidate-version.test.ts, since the training + * agent serves 3.3 only through the local candidate wire contract. + */ + +import { afterAll, beforeAll, describe, expect, it } from 'vitest'; +import express from 'express'; +import http from 'node:http'; +import { getCanonicalToolValidator } from '@adcp/sdk/schemas'; +import { fieldsAddedAfterRelease } from '../served-release-fields.js'; +import { clearSessions, stopSessionCleanup } from '../state.js'; +import { clearAccountStore } from '../account-handlers.js'; + +process.env.PUBLIC_TEST_AGENT_TOKEN = 'served-release-shape-token'; + +const TOKEN = 'served-release-shape-token'; + +/** Read tools each route answers without prior state, and the source + * response schema each is graded against. */ +const RESPONSE_SCHEMAS: Record = { + get_adcp_capabilities: 'protocol/get-adcp-capabilities-response.json', + get_products: 'media-buy/get-products-response.json', + list_products: 'media-buy/list-products-response.json', + get_media_buys: 'media-buy/get-media-buys-response.json', + list_creative_formats: 'media-buy/list-creative-formats-response.json', + list_creatives: 'creative/list-creatives-response.json', + get_signals: 'signals/get-signals-response.json', + list_property_lists: 'property/list-property-lists-response.json', + list_collection_lists: 'collection/list-collection-lists-response.json', + list_content_standards: 'content-standards/list-content-standards-response.json', + get_rights: 'brand/get-rights-response.json', + list_tasks: 'core/tasks-list-response.json', + sync_audiences: 'media-buy/sync-audiences-response.json', + sync_event_sources: 'media-buy/sync-event-sources-response.json', +}; + +const ROUTES: Record = { + sales: ['get_adcp_capabilities', 'get_products', 'list_products', 'get_media_buys', 'list_creative_formats', 'list_creatives', 'list_tasks', 'sync_audiences', 'sync_event_sources'], + signals: ['get_adcp_capabilities', 'get_signals', 'list_tasks'], + governance: ['get_adcp_capabilities', 'list_property_lists', 'list_collection_lists', 'list_content_standards', 'list_tasks'], + creative: ['get_adcp_capabilities', 'list_creative_formats', 'list_creatives', 'list_tasks'], + 'creative-builder': ['get_adcp_capabilities', 'list_creative_formats', 'list_tasks'], + brand: ['get_adcp_capabilities', 'get_rights', 'list_tasks'], + si: ['get_adcp_capabilities', 'list_tasks'], + // The v5 route the SDK's `test-mcp` alias and the public examples call. + '': ['get_adcp_capabilities', 'get_products', 'list_products', 'get_media_buys', 'list_creative_formats', 'list_creatives', 'get_signals', 'list_property_lists', 'list_collection_lists', 'list_content_standards', 'get_rights', 'sync_audiences', 'sync_event_sources'], +}; + +/** + * Responses whose whole shape is graded against the served bundle below 3.2. + * Older releases also predate shapes the agent still projects on other tools + * (outside #8487), so those are held to the `x-added-in` check only. + */ +const GRADED_BELOW_THREE_TWO = new Set(['get_adcp_capabilities']); + +/** + * Root envelope keys a release's closed task root may not list: the + * `adcp_version` echo every response carries (versioning.mdx; the 3.2 + * list_products root omits it, 3.3 adds it) and the envelope `status` the v5 + * route stamps. SDK clients relax the response root for both. + */ +const ROOT_ENVELOPE_KEYS = new Set(['adcp_version', 'status']); + +interface Called { + structured: Record | undefined; + raw: unknown; +} + +async function rpc(url: string, id: number, method: string, params?: Record): Promise> { + const response = await fetch(url, { + method: 'POST', + headers: { + 'content-type': 'application/json', + accept: 'application/json', + authorization: `Bearer ${TOKEN}`, + }, + body: JSON.stringify({ jsonrpc: '2.0', id, method, ...(params && { params }) }), + }); + return response.json() as Promise>; +} + +describe('served-release response shape below 3.3 (#8487)', () => { + let server: http.Server; + let baseUrl: string; + let rpcId = 1; + + const call = async (url: string, name: string, args: Record): Promise => { + rpcId += 1; + const raw = await rpc(url, rpcId, 'tools/call', { name, arguments: args }); + const result = raw.result as { structuredContent?: Record } | undefined; + return { structured: result?.structuredContent, raw }; + }; + + beforeAll(async () => { + clearSessions(); + clearAccountStore(); + const { createTrainingAgentRouter } = await import('../index.js'); + const app = express(); + app.use(express.json({ + limit: '5mb', + verify: (req, _res, buf) => { + (req as unknown as { rawBody: string }).rawBody = buf.toString('utf8'); + }, + })); + app.use('/api/training-agent', createTrainingAgentRouter({ disableRateLimit: true })); + server = http.createServer(app); + await new Promise(resolve => server.listen(0, '127.0.0.1', resolve)); + const address = server.address(); + if (!address || typeof address === 'string') throw new Error('Missing test server address'); + baseUrl = `http://127.0.0.1:${address.port}/api/training-agent`; + }, 60_000); + + afterAll(async () => { + clearSessions(); + clearAccountStore(); + stopSessionCleanup(); + server.closeAllConnections(); + await new Promise(resolve => server.close(() => resolve())); + }); + + for (const [route, tools] of Object.entries(ROUTES)) { + const label = route ? `/${route}/mcp` : '/mcp'; + it(`serves ${label} callers pinned to 3.2, 3.1 and 3.0 their release's shape`, async () => { + const url = `${baseUrl}${route ? `/${route}` : ''}/mcp`; + await rpc(url, 1, 'initialize', { + protocolVersion: '2025-03-26', + clientInfo: { name: 'served-release-shape', version: '1' }, + capabilities: {}, + }); + const graded: string[] = []; + const failures: string[] = []; + for (const version of ['3.2', '3.1', '3.0']) { + const account = { + brand: { domain: `served-release-${route || 'v5'}.example` }, + operator: `served-release-${route || 'v5'}.example`, + sandbox: true, + }; + await call(url, 'sync_accounts', { + adcp_version: version, + accounts: [{ ...account, billing: 'operator', payment_terms: 'net_30' }], + idempotency_key: `served-release-${route || 'v5'}-${version}-provision`, + }); + for (const tool of tools) { + const args: Record = { adcp_version: version, account }; + if (tool === 'get_products') args.buying_mode = 'wholesale'; + if (tool === 'get_signals') { + args.signal_spec = 'sports fans'; + args.deliver_to = { deployments: [{ type: 'platform', platform: 'the-trade-desk' }], countries: ['US'] }; + } + if (tool === 'sync_audiences') { + args.idempotency_key = `served-release-${route || 'v5'}-${version}-audiences`; + args.audiences = [{ + audience_id: 'served_release_loyalty', name: 'Served release loyalty', audience_type: 'crm', + add: [{ external_id: 'member_1', hashed_email: 'a'.repeat(64) }], + }]; + } + if (tool === 'sync_event_sources') { + args.idempotency_key = `served-release-${route || 'v5'}-${version}-sources`; + args.event_sources = [{ event_source_id: 'served_release_pixel', name: 'Served release pixel', event_types: ['purchase'] }]; + } + const { structured, raw } = await call(url, tool, args); + const adcpError = structured?.adcp_error as { code?: string; message?: string } | undefined; + const error = adcpError?.code; + // Compact-lifecycle tools start at 3.2 and list_tasks at 3.1; older + // pins answer VERSION_UNSUPPORTED, or "Unknown tool" on /mcp. + const absentFromRelease = error === 'VERSION_UNSUPPORTED' + || (error === 'INVALID_REQUEST' && adcpError?.message === `Unknown tool: ${tool}`); + if (absentFromRelease && version !== '3.2') continue; + if (!structured || error) { + failures.push(`${label} ${tool} @${version}: no result ${JSON.stringify(raw).slice(0, 300)}`); + continue; + } + const served = typeof structured.adcp_version === 'string' ? structured.adcp_version : version; + expect(served.startsWith(version), `${label} ${tool} echoed ${served} for ${version}`).toBe(true); + + const schemaFile = tool === 'list_creative_formats' && route.startsWith('creative') + ? 'creative/list-creative-formats-response.json' + : RESPONSE_SCHEMAS[tool]; + const newer = fieldsAddedAfterRelease(structured, schemaFile, served) + .filter(pointer => pointer !== '/adcp_version'); + if (newer.length > 0) failures.push(`${label} ${tool} @${served}: fields added after ${served}: ${newer.join(', ')}`); + + if (version !== '3.2' && !GRADED_BELOW_THREE_TWO.has(tool)) continue; + const validate = getCanonicalToolValidator(tool, 'sync', { adcpVersion: served }); + if (!validate) { + failures.push(`${label} ${tool} @${served}: no ${served} response schema`); + continue; + } + validate(structured); + const errors = (validate.errors ?? []).filter(entry => !( + entry.instancePath === '' + && entry.keyword === 'additionalProperties' + && ROOT_ENVELOPE_KEYS.has(String((entry.params as { additionalProperty?: unknown }).additionalProperty)) + )); + if (errors.length > 0) { + failures.push(`${label} ${tool} @${served}: ${JSON.stringify(errors.slice(0, 5).map(entry => ( + `${entry.instancePath} ${entry.message} ${JSON.stringify(entry.params)}` + )))}`); + } + graded.push(`${tool}@${served}`); + } + } + expect(failures).toEqual([]); + // Every listed tool was graded at 3.2. + expect(graded.filter(entry => entry.endsWith('@3.2')).map(entry => entry.split('@')[0])).toEqual([...tools]); + }, 60_000); + } +}); diff --git a/server/src/training-agent/tenants/tenant-smoke.test.ts b/server/src/training-agent/tenants/tenant-smoke.test.ts index 3f0b027018e..292184b4292 100644 --- a/server/src/training-agent/tenants/tenant-smoke.test.ts +++ b/server/src/training-agent/tenants/tenant-smoke.test.ts @@ -2243,9 +2243,10 @@ describe('tenant routing smoke', () => { expect(mediaBuy?.features?.inline_creative_management).toBe(true); expect(mediaBuy?.supported_optimization_metrics).toContain('clicks'); expect(mediaBuy?.vendor_metric_optimization?.supported_targets).toContain('threshold_rate'); - expect(mediaBuy?.vendor_metric_optimization?.supported_metrics).toContainEqual( - expect.objectContaining({ vendor: { domain: 'attentionvendor.example' }, metric_id: 'attention_score' }), - ); + // The supported_metrics rollup is a 3.3 field (#8070), withheld from + // this 3.2 response (#8487); training-agent-candidate-version.test.ts + // covers it on 3.3. + expect(mediaBuy?.vendor_metric_optimization).not.toHaveProperty('supported_metrics'); expect(mediaBuy?.conversion_tracking?.supported_targets).toEqual(['cost_per']); expect(previewCapabilityIds.length).toBeGreaterThan(0); expect(previewRouteIds).toEqual(previewCapabilityIds); diff --git a/server/src/training-agent/types.ts b/server/src/training-agent/types.ts index 5d3c7791c13..ee137e32767 100644 --- a/server/src/training-agent/types.ts +++ b/server/src/training-agent/types.ts @@ -140,9 +140,10 @@ export function supportsSellerGovernanceDiscovery(servedVersion: string | undefi * * This gate now covers only the `force_media_buy_confirmation` hold scenario, * which stays exercisable on the 3.2 wire. The `sales-fixed-rate` specialism - * id itself is a 3.3 enum value and is gated separately by - * `advertisesSalesFixedRateSpecialism` (3.3.0-beta.0 release verification - * validates 3.2 responses against the published 3.2 schema). + * id itself is a 3.3 enum value; the tenant capability projection lists only + * the ids the served release's `enums/specialism.json` allows (3.3.0-beta.0 + * release verification validates 3.2 responses against the published 3.2 + * schema). */ export const SALES_FIXED_RATE_ADCP_LINE = '3.2' as const; @@ -161,28 +162,6 @@ export function supportsSalesFixedRate(servedVersion: string | undefined): boole return major > gateMajor || (major === gateMajor && minor >= gateMinor); } -/** - * First wire line whose `specialisms` enum carries `sales-fixed-rate`. The id - * is a 3.3 enum value (#7963), so a response served at 3.2 or below must not - * list it (DR-0024). The hold controller scenario stays on the - * `supportsSalesFixedRate` gate: `compliance_testing.scenarios` is not a - * closed enum, and the scenario remains exercisable on the 3.2 wire. - */ -export const SALES_FIXED_RATE_SPECIALISM_ADCP_LINE = '3.3' as const; - -/** Whether a capability response served at this wire version may list the - * `sales-fixed-rate` specialism id. */ -export function advertisesSalesFixedRateSpecialism(servedVersion: string | undefined): boolean { - const match = (servedVersion ?? TRAINING_AGENT_CURRENT_ADCP_VERSION).match(/^(\d+)\.(\d+)/); - const gate = SALES_FIXED_RATE_SPECIALISM_ADCP_LINE.match(/^(\d+)\.(\d+)/)!; - if (!match) return false; - const major = Number.parseInt(match[1], 10); - const minor = Number.parseInt(match[2], 10); - const gateMajor = Number.parseInt(gate[1], 10); - const gateMinor = Number.parseInt(gate[2], 10); - return major > gateMajor || (major === gateMajor && minor >= gateMinor); -} - /** First served checkpoint whose media-buy features carry the structured * bidding_policy capability object (older bundles only allow booleans). */ export const BIDDING_POLICY_CAPABILITY_ADCP_VERSION = '3.2-beta.6' as const; diff --git a/server/tests/unit/training-agent-availability-windows.test.ts b/server/tests/unit/training-agent-availability-windows.test.ts index 455f2ea5dbb..4bb483599d2 100644 --- a/server/tests/unit/training-agent-availability-windows.test.ts +++ b/server/tests/unit/training-agent-availability-windows.test.ts @@ -95,7 +95,8 @@ describe('flexible-window availability discovery (training agent)', () => { describe('get_adcp_capabilities', () => { it('declares media_buy.availability_horizon: true', async () => { - const caps = await callTool(server, 'get_adcp_capabilities', {}); + // A 3.2 field: an unpinned (3.0) caller does not get it (#8487). + const caps = await callTool(server, 'get_adcp_capabilities', { adcp_version: '3.2' }); expect((caps as { media_buy: { availability_horizon?: boolean } }).media_buy.availability_horizon).toBe(true); }); }); diff --git a/server/tests/unit/training-agent-candidate-version.test.ts b/server/tests/unit/training-agent-candidate-version.test.ts index 080b28301f3..d8dbf1289c7 100644 --- a/server/tests/unit/training-agent-candidate-version.test.ts +++ b/server/tests/unit/training-agent-candidate-version.test.ts @@ -108,6 +108,20 @@ describe('local candidate wire contract', () => { await preview.close(); }); + it('keeps account.stable_account_id off the v5 monolith even for the candidate', async () => { + // The v5 route neither aliases nor rehydrates account_id (#8487 gates the + // declaration to 3.3; this keeps it off the route that cannot honor it). + const response = await fetch(`${baseUrl}/mcp`, { + method: 'POST', + headers: { 'content-type': 'application/json', accept: 'application/json, text/event-stream', authorization: 'Bearer candidate-version-test-token' }, + body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'tools/call', params: { name: 'get_adcp_capabilities', arguments: { adcp_version: '3.3-beta.0' } } }), + }); + const result = (await response.json()).result?.structuredContent; + expect(result?.adcp_version, JSON.stringify(result).slice(0, 300)).toBe('3.3-beta.0'); + expect(result.account).toBeDefined(); + expect(result.account).not.toHaveProperty('stable_account_id'); + }); + it('keeps legacy signing routes from advertising or accepting the candidate contract', async () => { const legacy = createTrainingAgentServer({ mode: 'open', strict: true, legacySigningProfile: true }); const handler = (legacy as unknown as { _requestHandlers: Map })._requestHandlers.get('tools/call')!; @@ -141,4 +155,73 @@ describe('local candidate wire contract', () => { expect(blocking.passed).toBe(false); expect(storyboardStepStatus(blocking)).toBe('failed'); }, 60_000); + + // #8487: the agent withholds 3.3 fields from a 3.2 caller + // (tenants/served-release-shape.test.ts); a 3.3 caller still gets them. + it('serves 3.3 fields to the candidate and withholds them from an explicit 3.2 pin', async () => { + let id = 100; + const call = async (tenant: string, name: string, args: Record) => { + id += 1; + const response = await fetch(`${baseUrl}/${tenant}/mcp`, { + method: 'POST', + headers: { 'content-type': 'application/json', accept: 'application/json, text/event-stream', authorization: 'Bearer candidate-version-test-token' }, + body: JSON.stringify({ jsonrpc: '2.0', id, method: 'tools/call', params: { name, arguments: args } }), + }); + const envelope = await response.json(); + const result = envelope.result?.structuredContent; + expect(result?.adcp_error, JSON.stringify(envelope).slice(0, 500)).toBeUndefined(); + return result; + }; + const account = { brand: { domain: 'candidate-three-three.example' }, operator: 'candidate-three-three.example', sandbox: true }; + for (const adcp_version of ['3.3-beta.0', '3.2']) { + const current = adcp_version === '3.3-beta.0'; + const sales = await call('sales', 'get_adcp_capabilities', { adcp_version }); + expect(sales.account.stable_account_id).toBe(current ? true : undefined); + expect(sales.media_buy.features.supports_property_breakdown).toBe(current ? true : undefined); + expect(sales.media_buy.features.supports_installment_property_breakdown).toBe(current ? true : undefined); + if (current) { + expect(sales.media_buy.vendor_metric_optimization.supported_metrics).toContainEqual( + expect.objectContaining({ vendor: { domain: 'attentionvendor.example' }, metric_id: 'attention_score' }), + ); + } else { + expect(sales.media_buy.vendor_metric_optimization).not.toHaveProperty('supported_metrics'); + } + const governance = await call('governance', 'get_adcp_capabilities', { adcp_version }); + expect(governance.governance.supports_budget_periods).toBe(current ? true : undefined); + for (const tenant of ['signals', 'creative']) { + const caps = await call(tenant, 'get_adcp_capabilities', { adcp_version }); + expect(caps.account.stable_account_id, tenant).toBe(current ? true : undefined); + } + + await call('sales', 'sync_accounts', { + adcp_version, + accounts: [{ ...account, billing: 'operator', payment_terms: 'net_30' }], + idempotency_key: `candidate-three-three-provision-${adcp_version}`, + }); + const listed = await call('sales', 'list_products', { adcp_version, account, max_results: 50 }); + expect(listed.adcp_version).toBe(adcp_version); + const withInstallments = (listed.products as Array>) + .filter(product => Array.isArray(product.installments)); + if (current) expect(withInstallments.length).toBeGreaterThan(0); + else expect(withInstallments).toEqual([]); + + const audiences = await call('sales', 'sync_audiences', { + adcp_version, account, + idempotency_key: `candidate-three-three-audiences-${adcp_version}`, + audiences: [{ + audience_id: 'candidate_loyalty', name: 'Candidate loyalty', audience_type: 'crm', + add: [{ external_id: 'member_1', hashed_email: 'a'.repeat(64) }], + }], + }); + const sources = await call('sales', 'sync_event_sources', { + adcp_version, account, + idempotency_key: `candidate-three-three-sources-${adcp_version}`, + event_sources: [{ event_source_id: 'candidate_pixel', name: 'Candidate pixel', event_types: ['purchase'] }], + }); + for (const row of [...audiences.audiences, ...sources.event_sources] as Array>) { + expect(typeof row.seller_id).toBe('string'); + expect(row.platform_id).toBe(current ? row.seller_id : undefined); + } + } + }, 60_000); }); diff --git a/server/tests/unit/training-agent-creators.test.ts b/server/tests/unit/training-agent-creators.test.ts index 02889f36b3f..fd5e95474bb 100644 --- a/server/tests/unit/training-agent-creators.test.ts +++ b/server/tests/unit/training-agent-creators.test.ts @@ -1,6 +1,14 @@ import { createHash } from 'node:crypto'; import canonicalize from 'canonicalize'; -import { beforeEach, describe, expect, it } from 'vitest'; +import { beforeEach, describe, expect, it, vi } from 'vitest'; + +// Installments are a 3.3 canonical-product field, so the compact lifecycle +// cases below list products as a 3.3 caller, through the trusted local +// candidate wire contract. +vi.hoisted(() => { + process.env.ADCP_STORYBOARD_CANDIDATE_VERSION_MODE = '1'; + process.env.ADCP_TRAINING_CANDIDATE_VERSION = '3.3-beta.0'; +}); import type { CanonicalProposal } from '@adcp/sdk'; import { CREATOR_PUBLISHER } from '../../src/training-agent/creators.js'; import { PUBLISHERS } from '../../src/training-agent/publishers.js'; @@ -183,6 +191,7 @@ describe('CreatorLoop compact lifecycle', () => { // material deadlines at all — the slot only existed on get_products. it('surfaces slot dates and material deadlines on the canonical product, not only on get_products', async () => { const result = await executeTrainingAgentTool('list_products', { + adcp_version: '3.3-beta.0', account: { brand: { domain: 'buyer.example' }, operator: 'buyer.example' }, criteria: { product_ids: creatorProducts().map(product => product.product_id as string) }, }, context); @@ -212,6 +221,7 @@ describe('CreatorLoop compact lifecycle', () => { it('keeps the legacy and canonical slot sets identical apart from the dropped shorthand', async () => { const legacy = creatorProducts(); const result = await executeTrainingAgentTool('list_products', { + adcp_version: '3.3-beta.0', account: { brand: { domain: 'buyer.example' }, operator: 'buyer.example' }, criteria: { product_ids: legacy.map(product => product.product_id as string) }, }, context); diff --git a/server/tests/unit/training-agent-list-products-canonical.test.ts b/server/tests/unit/training-agent-list-products-canonical.test.ts index af77505276f..a0f20c8a806 100644 --- a/server/tests/unit/training-agent-list-products-canonical.test.ts +++ b/server/tests/unit/training-agent-list-products-canonical.test.ts @@ -1,4 +1,13 @@ -import { describe, it, expect, beforeEach } from 'vitest'; +import { describe, it, expect, beforeEach, vi } from 'vitest'; + +// Installments are a 3.3 canonical-product field, so the canonical shape this +// suite grades is served to a 3.3 caller. The trusted local candidate wire +// contract is the only way the training agent serves 3.3. +vi.hoisted(() => { + process.env.ADCP_STORYBOARD_CANDIDATE_VERSION_MODE = '1'; + process.env.ADCP_TRAINING_CANDIDATE_VERSION = '3.3-beta.0'; +}); + import { createTrainingAgentServer, invalidateCache, @@ -8,6 +17,7 @@ import { import { clearSessions } from '../../src/training-agent/state.js'; import { clearIdempotencyCache } from '../../src/training-agent/idempotency.js'; import { validateSourceSchema } from '../../src/training-agent/source-schema.js'; +import { getCanonicalToolValidator } from '@adcp/sdk/schemas'; import { TRAINING_AGENT_CURRENT_ADCP_VERSION, type TrainingContext } from '../../src/training-agent/types.js'; // list_products returns the closed core/canonical-product.json shape. The @@ -19,6 +29,7 @@ import { TRAINING_AGENT_CURRENT_ADCP_VERSION, type TrainingContext } from '../.. // project onto core/canonical-installment.json, which drops the legacy // deprecated collection_id shorthand and requires collection_ref. +const THREE_THREE_VERSION = '3.3-beta.0'; const DEFAULT_CTX: TrainingContext = { mode: 'open' }; const ACCOUNT = { brand: { domain: 'acmeoutdoor.example' }, operator: 'pinnacle-agency.example', sandbox: true }; @@ -28,13 +39,14 @@ async function callTool( server: ReturnType, toolName: string, args: Record, + adcpVersion: string = THREE_THREE_VERSION, ): Promise> { const requestHandlers = (server as unknown as { _requestHandlers: Map })._requestHandlers; const handler = requestHandlers.get('tools/call')!; const response = await handler( { method: 'tools/call', - params: { name: toolName, arguments: { adcp_version: TRAINING_AGENT_CURRENT_ADCP_VERSION, ...args } }, + params: { name: toolName, arguments: { adcp_version: adcpVersion, ...args } }, }, {}, ); @@ -47,6 +59,7 @@ async function callTool( async function listAllProducts( server: ReturnType, args: Record = {}, + adcpVersion: string = THREE_THREE_VERSION, ): Promise { const products: Product[] = []; let cursor: string | undefined; @@ -56,7 +69,7 @@ async function listAllProducts( max_results: 10, ...args, ...(cursor && { cursor }), - }); + }, adcpVersion); expect(result.outcome, JSON.stringify(result).slice(0, 500)).toBe('listed'); products.push(...(result.products as Product[])); cursor = typeof result.next_cursor === 'string' ? result.next_cursor : undefined; @@ -226,6 +239,46 @@ describe('list_products canonical product projection', () => { } }); + // #8487: the closed 3.2 core/canonical-product.json has no installments, so + // a 3.2 caller gets the products without them, and a narrow projection that + // asks for them gets neither installments nor the collections they pull in. + it('withholds the 3.3 installments from a 3.2 caller', async () => { + const validateThreeTwo = getCanonicalToolValidator('list_products', 'sync', { adcpVersion: '3.2' }); + expect(validateThreeTwo).toBeDefined(); + const threeTwo: Product[] = []; + let cursor: string | undefined; + do { + const page = await callTool(server, 'list_products', { + account: ACCOUNT, max_results: 10, ...(cursor && { cursor }), + }, TRAINING_AGENT_CURRENT_ADCP_VERSION); + // Root envelope keys are out of scope here: the adcp_version echo is + // required on every response (versioning.mdx) although the closed 3.2 + // list_products root omits it (3.3 adds it), and this in-process + // dispatcher stamps envelope status. SDK clients relax the response + // root for both. + const { adcp_version: echoed, status: _status, ...body } = page; + expect(echoed).toBe(TRAINING_AGENT_CURRENT_ADCP_VERSION); + expect(validateThreeTwo!(body), JSON.stringify(validateThreeTwo!.errors)).toBe(true); + threeTwo.push(...(page.products as Product[])); + cursor = typeof page.next_cursor === 'string' ? page.next_cursor : undefined; + } while (cursor); + const threeThree = byId(await listAllProducts(server)); + expect(threeTwo.length).toBe(threeThree.size); + expect(threeTwo.filter(product => product.installments !== undefined)).toEqual([]); + expect([...threeThree.values()].some(product => Array.isArray(product.installments))).toBe(true); + for (const product of threeTwo) { + const { installments: _installments, ...rest } = threeThree.get(product.product_id)!; + expect(product).toEqual(rest); + } + + const slotProduct = [...threeThree.values()].find(product => Array.isArray(product.installments)); + const [narrow] = await listAllProducts(server, { + criteria: { product_ids: [slotProduct!.product_id] }, + fields: ['installments'], + }, TRAINING_AGENT_CURRENT_ADCP_VERSION); + expect(narrow).toEqual({ product_id: slotProduct!.product_id, name: slotProduct!.name }); + }); + it('keeps collection_targeting_allowed and offering ids under a fields projection that needs them', async () => { const legacyResult = await callTool(server, 'get_products', { account: ACCOUNT, buying_mode: 'wholesale' }); const collectionProduct = (legacyResult.products as Product[]).find(product => ( diff --git a/server/tests/unit/training-agent-outcome-target.test.ts b/server/tests/unit/training-agent-outcome-target.test.ts index 75db8ac9da1..41da7d3fd06 100644 --- a/server/tests/unit/training-agent-outcome-target.test.ts +++ b/server/tests/unit/training-agent-outcome-target.test.ts @@ -183,7 +183,8 @@ describe('reverse-forecast outcome_target planning (training agent)', () => { describe('get_adcp_capabilities', () => { it('declares media_buy.outcome_target: true', async () => { - const caps = await callTool(server, 'get_adcp_capabilities', {}); + // A 3.2 field: an unpinned (3.0) caller does not get it (#8487). + const caps = await callTool(server, 'get_adcp_capabilities', { adcp_version: '3.2' }); expect((caps as { media_buy: { outcome_target?: boolean } }).media_buy.outcome_target).toBe(true); }); }); diff --git a/server/tests/unit/training-agent-seller-managed-event-sources.test.ts b/server/tests/unit/training-agent-seller-managed-event-sources.test.ts index 5f1c138633b..054dc0c5b76 100644 --- a/server/tests/unit/training-agent-seller-managed-event-sources.test.ts +++ b/server/tests/unit/training-agent-seller-managed-event-sources.test.ts @@ -1,5 +1,13 @@ -import { describe, it, expect, beforeEach } from 'vitest'; +import { describe, it, expect, beforeEach, vi } from 'vitest'; import crypto from 'node:crypto'; + +// `platform_id` is the 3.3 name for an event source's seller-assigned id, so +// this suite calls as a 3.3 caller through the trusted local candidate wire +// contract. A 3.2 caller gets `seller_id` alone (#8487). +vi.hoisted(() => { + process.env.ADCP_STORYBOARD_CANDIDATE_VERSION_MODE = '1'; + process.env.ADCP_TRAINING_CANDIDATE_VERSION = '3.3-beta.0'; +}); import { createTrainingAgentServer, invalidateCache, @@ -37,7 +45,7 @@ async function callTool( const handler = requestHandlers.get('tools/call'); if (!handler) throw new Error('CallTool handler not found'); const response = await handler( - { method: 'tools/call', params: { name: toolName, arguments: withIdempotencyKey(toolName, args) } }, + { method: 'tools/call', params: { name: toolName, arguments: withIdempotencyKey(toolName, { adcp_version: '3.3-beta.0', ...args }) } }, {}, ); const text = response.content?.[0]?.text; diff --git a/server/tests/unit/training-agent-served-release-fields.test.ts b/server/tests/unit/training-agent-served-release-fields.test.ts new file mode 100644 index 00000000000..528e41afa54 --- /dev/null +++ b/server/tests/unit/training-agent-served-release-fields.test.ts @@ -0,0 +1,65 @@ +import { describe, expect, it } from 'vitest'; +import { getSchemaDocumentByRef } from '@adcp/sdk/schemas'; +import { + fieldsAddedAfterRelease, + omitFieldsAddedAfterRelease, + propertiesAddedAfterRelease, + servedReleaseEnum, +} from '../../src/training-agent/served-release-fields.js'; + +const CAPABILITIES = 'protocol/get-adcp-capabilities-response.json'; + +describe('served-release field gate (#8487)', () => { + it('withholds the 3.3 canonical-product fields from 3.2, and only fields 3.2 lacks', () => { + const withheld = propertiesAddedAfterRelease('core/canonical-product.json', '3.2'); + expect(withheld).toContain('installments'); + const threeTwo = getSchemaDocumentByRef('core/canonical-product.json', '3.2')?.schema as + { properties?: Record; additionalProperties?: unknown } | undefined; + expect(threeTwo?.additionalProperties).toBe(false); + for (const field of withheld) expect(threeTwo?.properties, field).not.toHaveProperty(field); + expect(propertiesAddedAfterRelease('core/canonical-product.json', '3.3-beta.0')).toEqual(new Set()); + }); + + it('finds 3.3 fields under objects 3.2 leaves open, and leaves undeclared keys alone', () => { + const capabilities = { + adcp_version: '3.2', + account: { sandbox: true, stable_account_id: true }, + media_buy: { + features: { inline_creative_management: true, supports_property_breakdown: true }, + vendor_metric_optimization: { supported_targets: ['cost_per'], supported_metrics: [] }, + }, + ext: { stable_account_id: true }, + }; + expect(fieldsAddedAfterRelease(capabilities, CAPABILITIES, '3.2')).toEqual([ + '/account/stable_account_id', + '/media_buy/features/supports_property_breakdown', + '/media_buy/vendor_metric_optimization/supported_metrics', + ]); + // Same release line, whatever the prerelease checkpoint. + expect(fieldsAddedAfterRelease(capabilities, CAPABILITIES, '3.3-beta.0')).toEqual([]); + // A 3.2 field is newer than 3.1. + expect(fieldsAddedAfterRelease({ media_buy: { anonymous_discovery: true } }, CAPABILITIES, '3.1')) + .toEqual(['/media_buy/anonymous_discovery']); + expect(fieldsAddedAfterRelease({ media_buy: { anonymous_discovery: true } }, CAPABILITIES, '3.2')).toEqual([]); + }); + + it('copies only when it withholds something', () => { + const current = { account: { sandbox: true } }; + expect(omitFieldsAddedAfterRelease(current, CAPABILITIES, '3.2')).toBe(current); + const leaking = { account: { sandbox: true, stable_account_id: true } }; + expect(omitFieldsAddedAfterRelease(leaking, CAPABILITIES, '3.2')).toEqual({ account: { sandbox: true } }); + expect(leaking.account.stable_account_id).toBe(true); + }); + + it("reads a closed enum from the served release's bundle", () => { + expect(servedReleaseEnum('enums/specialism.json', '3.1')).not.toContain('sales-dooh'); + expect(servedReleaseEnum('enums/specialism.json', '3.2')).toContain('sales-dooh'); + expect(servedReleaseEnum('enums/specialism.json', '3.2')).not.toContain('sales-fixed-rate'); + expect(servedReleaseEnum('enums/specialism.json', '3.3-beta.0')).toContain('sales-fixed-rate'); + // A prerelease pin the SDK ships no bundle for reads its release line. + expect(servedReleaseEnum('enums/specialism.json', '3.1-rc.15')).toEqual(servedReleaseEnum('enums/specialism.json', '3.1')); + expect(servedReleaseEnum('enums/specialism.json', '3.2-rc.0')).not.toContain('sales-fixed-rate'); + // No bundle at all leaves the caller's list as is. + expect(servedReleaseEnum('enums/specialism.json', '4.0')).toBeNull(); + }); +}); diff --git a/server/tests/unit/training-agent-stable-account-id.test.ts b/server/tests/unit/training-agent-stable-account-id.test.ts index 0ed512f63dd..f371f33b66d 100644 --- a/server/tests/unit/training-agent-stable-account-id.test.ts +++ b/server/tests/unit/training-agent-stable-account-id.test.ts @@ -165,15 +165,13 @@ describe('training agent: account.stable_account_id', () => { stopSessionCleanup(); }); - it('declares the capability only on the current v6 tenant routes', async () => { - for (const path of ['sales/mcp', 'signals/mcp', 'creative/mcp']) { - const url = `${server.baseUrl}/${path}`; - await initialize(url); - const caps = await callTool(url, 'get_adcp_capabilities', { adcp_version: '3.2' }); - expect(caps?.account?.stable_account_id, path).toBe(true); - } - // The v5 monolith neither aliases nor rehydrates, so it must not declare. - for (const path of ['mcp', 'sales/mcp-strict']) { + // account.stable_account_id is a 3.3 field, so no route declares it to a + // 3.2 caller (#8487); the v6 tenant routes still alias and rehydrate the + // account_id, as the cases below show. The 3.3 declaration, and its absence + // from the v5 monolith, are covered in + // training-agent-candidate-version.test.ts. + it('withholds the 3.3 capability from 3.2 callers on every route', async () => { + for (const path of ['sales/mcp', 'signals/mcp', 'creative/mcp', 'mcp', 'sales/mcp-strict']) { const url = `${server.baseUrl}/${path}`; await initialize(url); const caps = await callTool(url, 'get_adcp_capabilities', { adcp_version: '3.2' }); diff --git a/server/tests/unit/training-agent.test.ts b/server/tests/unit/training-agent.test.ts index 22d9543d7aa..161b0d7c7ba 100644 --- a/server/tests/unit/training-agent.test.ts +++ b/server/tests/unit/training-agent.test.ts @@ -1774,15 +1774,10 @@ describe('createTrainingAgentServer', () => { // Removed seller-level reporting (product-level is source of truth) expect(mediaBuy).not.toHaveProperty('reporting'); + // The supported_metrics rollup is a 3.3 field (#8070), withheld from this + // unpinned (3.0) response (#8487). expect(mediaBuy.vendor_metric_optimization).toEqual({ supported_targets: ['threshold_rate'], - supported_metrics: [ - { - vendor: { domain: 'attentionvendor.example' }, - metric_id: 'attention_score', - supported_targets: ['threshold_rate'], - }, - ], }); expect(mediaBuy.performance_feedback).toEqual({ reports_application_status: true, @@ -1837,8 +1832,8 @@ describe('createTrainingAgentServer', () => { }); it('keeps the seller-level vendor_metric_optimization.supported_metrics rollup consistent with the catalog', async () => { - const server = createTrainingAgentServer(DEFAULT_CTX); - const { result } = await simulateCallTool(server, 'get_adcp_capabilities', {}); + // The rollup is a 3.3 field (#8070), served only on a 3.3 response (#8487). + const result = await handleGetAdcpCapabilities({}, { ...DEFAULT_CTX, servedAdcpVersion: '3.3-beta.0' }); const rollup = ((result as Record).media_buy.vendor_metric_optimization.supported_metrics) as Array<{ vendor: { domain: string; brand_id?: string }; metric_id: string; @@ -8213,7 +8208,10 @@ describe('create_media_buy handler', () => { expect(typeof result.media_buy_id).toBe('string'); }); - it('returns stable audience platform IDs and matching legacy aliases on sync and discovery', async () => { + // platform_id is the 3.3 name for the seller-assigned id; a 3.2 caller gets + // the seller_id it defines alone (#8487). The 3.3 side is covered in + // training-agent-candidate-version.test.ts. + it('returns stable audience seller IDs, without the 3.3 platform_id, on 3.2 sync and discovery', async () => { const account = { brand: { domain: 'nova-platform-ids.example' }, operator: 'pinnacle-agency.example' }; const server = createTrainingAgentServer(DEFAULT_CTX); const audience = { @@ -8228,8 +8226,8 @@ describe('create_media_buy handler', () => { }); const created = (synced.audiences as Array>)[0]!; expect(created.action).toBe('created'); - expect(typeof created.platform_id).toBe('string'); - expect(created.seller_id).toBe(created.platform_id); + expect(typeof created.seller_id).toBe('string'); + expect(created).not.toHaveProperty('platform_id'); const { result: updated } = await simulateCallTool(server, 'sync_audiences', { account, @@ -8240,9 +8238,9 @@ describe('create_media_buy handler', () => { expect(result.audiences).toEqual([expect.objectContaining({ audience_id: 'nova_loyalty', action, - platform_id: created.platform_id, - seller_id: created.platform_id, + seller_id: created.seller_id, })]); + expect((result.audiences as Array>)[0]).not.toHaveProperty('platform_id'); } }); @@ -17924,11 +17922,14 @@ describe('get_adcp_capabilities handler', () => { }); it('advertises anonymous product and signal discovery without claiming catalog completeness', async () => { - const [sales, signals] = await Promise.all([ - handleGetAdcpCapabilities({}, { ...DEFAULT_CTX, tenantId: 'sales' }), - handleGetAdcpCapabilities({}, { ...DEFAULT_CTX, tenantId: 'signals' }), + // anonymous_discovery is a 3.2 field, withheld from a 3.0 response (#8487). + const [sales, signals, threeZero] = await Promise.all([ + handleGetAdcpCapabilities({}, { ...DEFAULT_CTX, tenantId: 'sales', servedAdcpVersion: CURRENT_ADCP_VERSION }), + handleGetAdcpCapabilities({}, { ...DEFAULT_CTX, tenantId: 'signals', servedAdcpVersion: CURRENT_ADCP_VERSION }), + handleGetAdcpCapabilities({}, { ...DEFAULT_CTX, tenantId: 'sales', servedAdcpVersion: '3.0' }), ]); + expect(threeZero.media_buy).not.toHaveProperty('anonymous_discovery'); expect(sales.media_buy).toMatchObject({ anonymous_discovery: true }); expect(signals.signals).toMatchObject({ anonymous_discovery: true }); }); @@ -21336,7 +21337,7 @@ describe('proposal lifecycle', () => { const projected = projectProductDiscoveryResult('request_proposals', { products: [{ product_id: 'brief-only-native', name: 'Brief-only native product' }], proposals: [], - }, {}); + }, {}, TRAINING_AGENT_CURRENT_ADCP_VERSION); expect(projected).toEqual({ outcome: 'rejected',