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',