diff --git a/.changeset/test-agent-3-3-preview-docs.md b/.changeset/test-agent-3-3-preview-docs.md
new file mode 100644
index 00000000000..eb76c547bcc
--- /dev/null
+++ b/.changeset/test-agent-3-3-preview-docs.md
@@ -0,0 +1,5 @@
+---
+"adcontextprotocol": patch
+---
+
+Docs: the 3.3 beta program page explains how to try the public test agent's opt-in `3.3-beta.3` preview. It covers which pins are served the preview, which experimental 3.3 surfaces become reachable, and that the preview is experimental and moves with each beta. The page now also records that `@adcp/sdk` 17.0.0-beta.11 and later bundle `3.3.0-beta.3`. The quickstart points to the preview.
diff --git a/docs/quickstart.mdx b/docs/quickstart.mdx
index af0bcd6aa53..5588c08dbae 100644
--- a/docs/quickstart.mdx
+++ b/docs/quickstart.mdx
@@ -26,6 +26,8 @@ export AGENT_URL="https://test-agent.adcontextprotocol.org/sales/mcp"
The test agent is path-routed: `/sales/mcp` serves media-buy tools (this quickstart's path), and sibling URLs serve the other specialisms — `/signals/mcp`, `/governance/mcp`, `/creative/mcp`, `/creative-builder/mcp`, `/brand/mcp`. Hit [`/.well-known/adagents.json`](https://test-agent.adcontextprotocol.org/.well-known/adagents.json) for the full tenant + tool list.
+The test agent serves AdCP 3.2, 3.1, and 3.0. It also serves the 3.3 beta as an experimental preview, but only to requests that pin `adcp_version: "3.3-beta.3"` exactly. See [Try the preview on the public test agent](/docs/reference/3-3-beta#try-the-preview-on-the-public-test-agent).
+
For your own API key (org-scoped, usage tracking), create one at the [AAO dashboard](https://agenticadvertising.org/dashboard/api-keys).
To test an OAuth connect flow, use `/sales/mcp` and follow its `401`
diff --git a/docs/reference/3-3-beta.mdx b/docs/reference/3-3-beta.mdx
index 1de153d00c8..255e78372ae 100644
--- a/docs/reference/3-3-beta.mdx
+++ b/docs/reference/3-3-beta.mdx
@@ -1,7 +1,7 @@
---
title: AdCP 3.3 beta program
sidebarTitle: 3.3 beta program
-description: "Where the AdCP 3.3 beta stands at beta.3, how to test a beta before SDK support, which SDK versions bundle which beta, and which proposals are still in review for 3.3."
+description: "Where the AdCP 3.3 beta stands at beta.3, how to test a beta before SDK support or against the public test agent's preview, which SDK versions bundle which beta, and which proposals are still in review for 3.3."
"og:title": "AdCP — 3.3 beta program"
---
@@ -24,7 +24,7 @@ The latest checkpoint is **`3.3.0-beta.3`, published 2026-10-31**. Each beta is
| `3.3.0-beta.2` | 2026-10-30 | Account change outcomes, seller offers, measurement provenance, structural capability bounds, the principal clarification, reporting-subscription convergence, and the withdrawal of definition pins, purchase rights, and installment selection | The same teams, against the withdrawn surfaces removed |
| `3.3.0-beta.3` | 2026-10-31 | Live creative updates, the protocol envelope on every task response, money terms on resolved account requests, revocation as no access, and reporting-subscription coverage computable from the wire | The same teams; this is the checkpoint the docs describe |
-Beta.0 did not wait for the SDKs. A checkpoint is SDK-backed only after the matching SDK versions and integration evidence are published, and no published SDK bundles beta.3 yet ([SDK guidance](#sdk-guidance)). Three features that shipped in the betas are [withdrawn after beta.1](#withdrawn-after-beta-1).
+Beta.0 did not wait for the SDKs. A checkpoint is SDK-backed only after the matching SDK versions and integration evidence are published. `@adcp/sdk` 17.0.0-beta.11 is the first published SDK that bundles beta.3 ([SDK guidance](#sdk-guidance)). Three features that shipped in the betas are [withdrawn after beta.1](#withdrawn-after-beta-1).
## Know which version string to use
@@ -68,6 +68,40 @@ Useful tests are:
4. Exercise raw MCP or A2A calls with `adcp_version: "3.3-beta.3"` against a staging peer that advertises the same pin.
5. Run the compliance assets with a source-compatible runner if you maintain one. Do not weaken production authentication to accommodate a beta runner.
+## Try the preview on the public test agent
+
+The public test agent at `https://test-agent.adcontextprotocol.org` serves `3.3.0-beta.3` as an opt-in preview alongside its stable releases. It lists `"3.3-beta.3"` in `adcp.supported_versions` and serves the preview only to a request that pins exactly that value:
+
+| Request | Served |
+|---|---|
+| `adcp_version: "3.3-beta.3"` | The preview. Responses echo `"3.3-beta.3"` and validate against the published `3.3.0-beta.3` schemas. |
+| `adcp_version: "3.2"`, `"3.3"`, or a later release | 3.2. A release pin never resolves onto a prerelease. |
+| Any other 3.3 prerelease, such as `"3.3-beta.2"` | Never the preview. Prerelease pins match exactly. |
+| `adcp_major_version` alone, or no version | The route's stable default, never the preview. |
+
+```bash
+curl -s https://test-agent.adcontextprotocol.org/sales/mcp \
+ -H "Authorization: Bearer $ADCP_AUTH_TOKEN" \
+ -H 'Content-Type: application/json' \
+ -H 'Accept: application/json, text/event-stream' \
+ -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_adcp_capabilities","arguments":{"adcp_version":"3.3-beta.3"}}}'
+```
+
+At the preview pin, `/sales/mcp` serves the experimental 3.3 surfaces the training agent implements:
+
+- account requests (`account.requests`): `request_account`, and `account_requests` on `list_accounts`;
+- the caller's `authorization`, with `authorized_at` and `regranted_at`, and `revision` on each `list_accounts` account;
+- principal-level reporting subscriptions (`media_buy.reporting_subscriptions`): the `reporting_subscriptions` section of `sync_principal` and `get_principal`, and `subscription_coverage` on `get_reporting_status`;
+- the `reporting_subscription_probe` controller scenario, which revokes, reduces, and restores grants and advances a per-caller sandbox clock.
+
+`tools/list` includes `request_account` only when the listing is pinned to the preview (`params._meta.adcp_version`, as `@adcp/sdk` sends it). Hold policy, `extend_hold`, and response collections are not served yet ([#8181](https://github.com/adcontextprotocol/adcp/issues/8181)).
+
+With `@adcp/sdk`, use 17.0.0-beta.11 or later, which negotiates exactly `3.3-beta.3`. Earlier 17.0.0 betas bundle an older beta, so they settle on 3.2 with the test agent.
+
+
+**The preview is experimental and can change without notice.** It follows the latest published beta and moves to the next one when it ships. Once it moves, the old pin is no longer served. AAO can also switch the preview off, after which the agent serves only its stable releases. Use it to try 3.3 surfaces, not as a stable integration target.
+
+
**No 3.3 verification badge is issued from a beta.** A beta bundle is an implementation input, not a certification target, and prerelease grading runs are diagnostic, as they were for 3.2.
@@ -88,7 +122,7 @@ SDK maintainers should report protocol ambiguities against the [AdCP repository]
## SDK guidance
-**TypeScript.** Use `@adcp/sdk` **17.0.0-beta.6 or later** (npm `beta` dist-tag) to test 3.3. The published prereleases bundle a signed AdCP release: 17.0.0-beta.6 bundles `3.3.0-beta.1`, and 17.0.0-beta.10 bundles `3.3.0-beta.2`. No published `@adcp/sdk` bundles `3.3.0-beta.3` yet, so the beta.3 surfaces (live creative updates, the envelope on every response, money terms on resolved account requests, and the reporting-subscription coverage rules) are raw-wire only until an SDK ingests that bundle. Pin the exact SDK version, and send a prerelease `adcp_version` only to a peer that advertises that exact pin. `@adcp/sdk` 17 is a major release; read its [16 to 17 migration guide](https://github.com/adcontextprotocol/adcp-client/blob/main/docs/migration-16-to-17.md) first.
+**TypeScript.** Use `@adcp/sdk` **17.0.0-beta.6 or later** (npm `beta` dist-tag) to test 3.3. The published prereleases bundle a signed AdCP release: 17.0.0-beta.6 bundles `3.3.0-beta.1`, 17.0.0-beta.10 bundles `3.3.0-beta.2`, and 17.0.0-beta.11 and later bundle `3.3.0-beta.3`. Each negotiates only its own beta, so a buyer and seller on different betas settle on a stable release. Pin the exact SDK version, and send a prerelease `adcp_version` only to a peer that advertises that exact pin. `@adcp/sdk` 17 is a major release; read its [16 to 17 migration guide](https://github.com/adcontextprotocol/adcp-client/blob/main/docs/migration-16-to-17.md) first.
**Python.** There is no Python SDK release that bundles a 3.3 beta. Support is pending [adcp-client-python#1560](https://github.com/adcontextprotocol/adcp-client-python/issues/1560), which is open. Until it lands, use the `adcp` 3.2 release for production-line work and validate 3.3 behavior over the raw wire against the signed bundle.
diff --git a/server/src/scripts/verify-training-agent-runtime-assets.ts b/server/src/scripts/verify-training-agent-runtime-assets.ts
index bb00fac3c73..4e0fda136b4 100644
--- a/server/src/scripts/verify-training-agent-runtime-assets.ts
+++ b/server/src/scripts/verify-training-agent-runtime-assets.ts
@@ -11,10 +11,13 @@ import { readFile } from 'node:fs/promises';
import path from 'node:path';
import { resolveAdcpVersion } from '@adcp/sdk';
import {
+ ensurePreviewSchemaBundle,
ensureTrainingAgentSchemaBundle,
+ PREVIEW_SCHEMA_BUNDLE,
resolveRetainedSchemaRoot,
RETAINED_SCHEMA_BUNDLE,
} from '../training-agent/schema-compat.js';
+import { TRAINING_AGENT_HOSTED_PREVIEW } from '../training-agent/candidate-version.js';
import { SELLER_GOVERNANCE_DISCOVERY_ADCP_VERSION } from '../training-agent/types.js';
import { coverageModelHasZone, resolveCoverageModelDir } from '../training-agent/reporting-coverage-model.js';
@@ -44,6 +47,27 @@ console.log(
`Training-agent runtime schema verified: ${resolvedVersion} -> ${schemaRoot}`,
);
+// The hosted 3.3 preview validates against its committed published bundle.
+// Checked even when the kill switch is set, so the image can always serve it.
+const previewRoot = resolveRetainedSchemaRoot(undefined, undefined, TRAINING_AGENT_HOSTED_PREVIEW.bundle);
+const previewIndex = JSON.parse(await readFile(path.join(previewRoot, 'index.json'), 'utf8')) as { adcp_version?: unknown };
+if (previewIndex.adcp_version !== TRAINING_AGENT_HOSTED_PREVIEW.bundle) {
+ throw new Error(
+ `Training-agent preview schema index ${previewRoot} declares ${String(previewIndex.adcp_version)}; ` +
+ `expected ${TRAINING_AGENT_HOSTED_PREVIEW.bundle}`,
+ );
+}
+if (PREVIEW_SCHEMA_BUNDLE) {
+ await ensurePreviewSchemaBundle();
+ const previewResolved = resolveAdcpVersion(TRAINING_AGENT_HOSTED_PREVIEW.wireVersion);
+ if (previewResolved !== TRAINING_AGENT_HOSTED_PREVIEW.wireVersion && previewResolved !== TRAINING_AGENT_HOSTED_PREVIEW.bundle) {
+ throw new Error(
+ `Training-agent preview version ${TRAINING_AGENT_HOSTED_PREVIEW.wireVersion} resolved as ${previewResolved}`,
+ );
+ }
+}
+console.log(`Training-agent preview schema verified: ${TRAINING_AGENT_HOSTED_PREVIEW.wireVersion} -> ${previewRoot}`);
+
// Reporting-subscription coverage runs the spec's reference model at runtime.
const coverageModelDir = resolveCoverageModelDir();
if (!coverageModelHasZone('America/New_York')) {
diff --git a/server/src/training-agent/candidate-version.ts b/server/src/training-agent/candidate-version.ts
index 5dab45db2eb..1f7c2479742 100644
--- a/server/src/training-agent/candidate-version.ts
+++ b/server/src/training-agent/candidate-version.ts
@@ -1,5 +1,6 @@
/** Trusted local storyboard processes may serve their generated source bundle.
- * Production and ordinary training-agent processes retain released contracts.
+ * Production and ordinary training-agent processes serve released contracts
+ * only: the stable lines and, unless disabled, the published preview below.
* This selects a wire release only; it does not enable experimental features. */
export function trainingAgentCandidateVersion(
env: Record = process.env,
@@ -10,3 +11,75 @@ export function trainingAgentCandidateVersion(
}
export const TRAINING_AGENT_CANDIDATE_ADCP_VERSION = trainingAgentCandidateVersion();
+
+/**
+ * The published prerelease the hosted training agent serves as an opt-in
+ * preview (#8181): wire value and the committed, immutable schema bundle
+ * (`dist/schemas/`) its responses validate against.
+ *
+ * It must name the prerelease whose published schemas match what the agent
+ * emits. main's source schemas are structurally identical to 3.3.0-beta.3
+ * (only descriptions changed since), and @adcp/sdk 17.0.0-beta.11 and later
+ * negotiate exactly `3.3-beta.3`. Advance both together with the next 3.3
+ * prerelease cut; tenants/served-release-shape.test.ts grades the agent's
+ * preview responses against this bundle.
+ */
+export const TRAINING_AGENT_HOSTED_PREVIEW = Object.freeze({
+ wireVersion: '3.3-beta.3',
+ bundle: '3.3.0-beta.3',
+} as const);
+
+/** Ops kill switch: set to `1` or `true` to stop advertising and serving the
+ * preview. Read at startup, so it takes effect on the next restart without a
+ * code change. A process with the switch set negotiates exactly as one that
+ * never listed the preview. */
+export const TRAINING_AGENT_PREVIEW_KILL_SWITCH = 'TRAINING_AGENT_DISABLE_ADCP_PREVIEW';
+
+export function trainingAgentPreviewDisabled(
+ env: Record = process.env,
+): boolean {
+ const value = env[TRAINING_AGENT_PREVIEW_KILL_SWITCH]?.trim().toLowerCase();
+ return value === '1' || value === 'true';
+}
+
+/**
+ * The one prerelease this process serves to callers that pin it exactly:
+ * the trusted storyboard candidate when candidate mode is on, otherwise the
+ * hosted preview unless the kill switch is set. Never served to unpinned,
+ * major-only or release-pinned callers (versioning.mdx, "Pre-release pins").
+ */
+export function trainingAgentPreviewVersion(
+ env: Record = process.env,
+): string | undefined {
+ const candidate = trainingAgentCandidateVersion(env);
+ if (candidate) return candidate;
+ return trainingAgentPreviewDisabled(env) ? undefined : TRAINING_AGENT_HOSTED_PREVIEW.wireVersion;
+}
+
+export const TRAINING_AGENT_PREVIEW_ADCP_VERSION = trainingAgentPreviewVersion();
+
+/** Whether this process serves the published hosted preview (as opposed to a
+ * local candidate, or no prerelease at all). */
+export const TRAINING_AGENT_SERVES_HOSTED_PREVIEW = TRAINING_AGENT_PREVIEW_ADCP_VERSION !== undefined
+ && TRAINING_AGENT_PREVIEW_ADCP_VERSION !== TRAINING_AGENT_CANDIDATE_ADCP_VERSION;
+
+/** Whether an MCP request selects this process's preview by an exact pin: a
+ * `tools/call` whose arguments carry it, or a `tools/list` that carries it in
+ * params or `params._meta` (as @adcp/sdk sends it). */
+export function requestPinsPreview(
+ body: unknown,
+ preview: string | undefined = TRAINING_AGENT_PREVIEW_ADCP_VERSION,
+): boolean {
+ if (!preview || !body || typeof body !== 'object') return false;
+ const { method, params } = body as { method?: unknown; params?: Record };
+ if (!params || typeof params !== 'object') return false;
+ if (method === 'tools/call') {
+ const args = params.arguments as { adcp_version?: unknown } | undefined;
+ return args?.adcp_version === preview;
+ }
+ if (method === 'tools/list') {
+ const meta = params._meta as { adcp_version?: unknown } | undefined;
+ return params.adcp_version === preview || meta?.adcp_version === preview;
+ }
+ return false;
+}
diff --git a/server/src/training-agent/index.ts b/server/src/training-agent/index.ts
index f25ecac48c1..58aac862e36 100644
--- a/server/src/training-agent/index.ts
+++ b/server/src/training-agent/index.ts
@@ -62,6 +62,8 @@ import {
import { isWorkOSApiKeyFormat } from '../middleware/api-key-format.js';
import { buildGovernanceAgentCredentialAuthenticator } from './governance-agent-credentials.js';
import { createTrainingBuyerOAuthMiddleware, trainingBuyerOAuthConfig, trainingBuyerMetadata, trainingBuyerDocumentation, TRAINING_BUYER_METADATA_PATH } from './buyer-oauth.js';
+import { requestPinsPreview } from './candidate-version.js';
+import { ensurePreviewSchemaBundle } from './schema-compat.js';
const logger = createLogger('training-agent-routes');
@@ -428,6 +430,8 @@ export function createTrainingAgentRouter(options: {
}
}
+ // Served-release shaping reads the hosted preview's published bundle.
+ if (requestPinsPreview(req.body)) await ensurePreviewSchemaBundle();
const transport = new StreamableHTTPServerTransport({
sessionIdGenerator: undefined,
enableJsonResponse: true,
@@ -515,6 +519,7 @@ export function createTrainingAgentRouter(options: {
}
}
+ if (requestPinsPreview(req.body)) await ensurePreviewSchemaBundle();
const transport = new StreamableHTTPServerTransport({
sessionIdGenerator: undefined,
enableJsonResponse: true,
diff --git a/server/src/training-agent/schema-compat.ts b/server/src/training-agent/schema-compat.ts
index b51ac8f0f7b..df92a40bad2 100644
--- a/server/src/training-agent/schema-compat.ts
+++ b/server/src/training-agent/schema-compat.ts
@@ -6,7 +6,11 @@ import {
SELLER_GOVERNANCE_DISCOVERY_ADCP_VERSION,
TRAINING_AGENT_RETAINED_RC_ADCP_VERSION,
} from './types.js';
-import { TRAINING_AGENT_CANDIDATE_ADCP_VERSION } from './candidate-version.js';
+import {
+ TRAINING_AGENT_CANDIDATE_ADCP_VERSION,
+ TRAINING_AGENT_HOSTED_PREVIEW,
+ TRAINING_AGENT_SERVES_HOSTED_PREVIEW,
+} from './candidate-version.js';
function canonicalSchemaBundleVersion(version: string): string {
const match = version.match(/^(\d+)\.(\d+)(?:\.(\d+))?((?:-(?:beta|rc)\.\d+)?)$/);
@@ -48,6 +52,17 @@ export const CANDIDATE_SCHEMA_BUNDLE = TRAINING_AGENT_CANDIDATE_ADCP_VERSION
: undefined;
const CANDIDATE_SCHEMA_TREE = 'latest';
+/**
+ * The hosted preview's published bundle (candidate-version.ts), registered
+ * from the committed, immutable dist/schemas/ tree under its own
+ * release key, so preview responses are validated against exactly what was
+ * published. The installed @adcp/sdk may package a different 3.3 beta, or
+ * none. Unset when the preview is disabled or a local candidate replaces it.
+ */
+export const PREVIEW_SCHEMA_BUNDLE: string | undefined = TRAINING_AGENT_SERVES_HOSTED_PREVIEW
+ ? TRAINING_AGENT_HOSTED_PREVIEW.bundle
+ : undefined;
+
let registration: Promise | undefined;
export function resolveRetainedSchemaRoot(
@@ -75,7 +90,8 @@ export function resolveRetainedSchemaRoot(
* Register the training agent's retained prerelease checkpoints (beta.6 and
* the last 3.2 RC) with SDK builds that do not package them,
* and, in a trusted candidate process, the built source tree under the
- * candidate's release key (see CANDIDATE_SCHEMA_BUNDLE).
+ * candidate's release key (see CANDIDATE_SCHEMA_BUNDLE). The hosted preview's
+ * bundle is registered separately, on first use (ensurePreviewSchemaBundle).
*
* This is deliberately lazy: @adcp/sdk/testing owns the public external-root
* API, but the rest of that entry point is unnecessary unless the training
@@ -99,11 +115,35 @@ export function ensureTrainingAgentSchemaBundle(): Promise {
// (adcontextprotocol/adcp-client#3519, still so in 17.0.0-beta.6).
// Register there too, or the rule reads the published bundle and drops
// `status`. Remove with #3519's fix.
- const cjsTesting = createRequire(import.meta.url)('@adcp/sdk/testing') as {
- registerExternalSchemaRoot: (version: string, schemaRoot: string) => void;
- };
- cjsTesting.registerExternalSchemaRoot(CANDIDATE_SCHEMA_BUNDLE, root);
+ cjsRegisterExternalSchemaRoot(CANDIDATE_SCHEMA_BUNDLE, root);
}
});
return registration;
}
+
+let previewRegistration: Promise | undefined;
+
+/**
+ * Register the hosted preview's published bundle (PREVIEW_SCHEMA_BUNDLE) with
+ * the SDK. Lazy: registering a full bundle costs seconds, so only the preview
+ * registry and preview-pinned requests on the v5 route pay it. The ESM loader
+ * is enough: the published bundle composes the envelope the way the SDK's
+ * status rule expects, so preview responses keep `status` without the
+ * CommonJS registration the candidate needs (served-release-shape.test.ts
+ * grades it). A no-op when the preview is off.
+ */
+export function ensurePreviewSchemaBundle(): Promise {
+ if (!PREVIEW_SCHEMA_BUNDLE) return Promise.resolve();
+ const bundle = PREVIEW_SCHEMA_BUNDLE;
+ previewRegistration ??= import('@adcp/sdk/testing').then(({ registerExternalSchemaRoot }) => {
+ registerExternalSchemaRoot(bundle, resolveRetainedSchemaRoot(undefined, undefined, bundle));
+ });
+ return previewRegistration;
+}
+
+function cjsRegisterExternalSchemaRoot(version: string, schemaRoot: string): void {
+ const cjsTesting = createRequire(import.meta.url)('@adcp/sdk/testing') as {
+ registerExternalSchemaRoot: (version: string, schemaRoot: string) => void;
+ };
+ cjsTesting.registerExternalSchemaRoot(version, schemaRoot);
+}
diff --git a/server/src/training-agent/task-handlers.ts b/server/src/training-agent/task-handlers.ts
index 381d01973d0..9617d437444 100644
--- a/server/src/training-agent/task-handlers.ts
+++ b/server/src/training-agent/task-handlers.ts
@@ -55,6 +55,7 @@ import { BrandManager } from '../brand-manager.js';
import { isPrivateHostname, normalizeExternalHostname, safeFetch, safeFetchAxiosLike } from '../utils/url-security.js';
import { isSellerOptimizedProposalId, sellerOptimizedDeclarationForVersion, sellerOptimizedFeatureFlags, sellerOptimizedOversubscriptionError, sellerOptimizedProposalForBrief, sellerOptimizedStateError, sellerOptimizedUnsupportedError, type SellerOptimizedState } from './seller-optimized-budget.js';
import { packageReportingOfferingIds } from './package-reporting-offerings.js';
+import { TRAINING_AGENT_PREVIEW_ADCP_VERSION } from './candidate-version.js';
import { parseAdcpReleaseVersion, type ParsedAdcpReleaseVersion, servesReleaseBefore, supportsAccountSurfaces33, supportsBiddingPolicyCapability, TRAINING_BIDDING_POLICY_CAPABILITY, TRAINING_CONVERSION_TRACKING_SUPPORTED_TARGETS, supportsGetProductsRejected, supportsReliableReporting, supportsSalesFixedRate, supportsSellerGovernanceDiscovery, TRAINING_AGENT_CURRENT_ADCP_VERSION, TRAINING_AGENT_DEFAULT_ADCP_VERSION, TRAINING_AGENT_SUPPORTED_RELEASE_VERSIONS, type TrainingContext, type CatalogProduct, type MediaBuyState, type MediaBuyAvailableActionState, type MediaBuyProductAllowedActionState, type PackageState, type SignalActivationState, type CreativeState, type CreativeManifest, type ToolArgs, type ListReference, type PackageTargeting, type AccountRef, type BrandRef, type SessionState, type SeededProductAvailability, type PackageFrequencyCapEligibility, supportsAccountChangeFeed, atLeastAdcpVersion } from './types.js';
import { classifyCreativeChange, decideLiveUpdate, livePackageIds, servingContent, stagedUpdateWire, liveUpdatesCapability, type CreativeChangeKind, type LiveUpdateServingMode, type StagedCreativeContent, type StagedCreativeUpdate } from './live-creative-updates.js';
import {
@@ -3417,11 +3418,16 @@ function parsedSupportedReleaseVersions(supportedVersions: readonly string[]): P
.sort(compareAdcpReleaseVersions);
}
+/** The release a major-only request is served: the highest supported entry
+ * in that major, except the opt-in preview (candidate-version.ts), which is
+ * served only to an exact pin (versioning.mdx, "Pre-release pins"). A
+ * major-only request is never upgraded onto it. */
function highestSupportedRelease(
major?: number,
supportedVersions: readonly string[] = SUPPORTED_RELEASE_VERSIONS,
): string | undefined {
- const parsedVersions = parsedSupportedReleaseVersions(supportedVersions);
+ const parsedVersions = parsedSupportedReleaseVersions(supportedVersions)
+ .filter(version => version.raw !== TRAINING_AGENT_PREVIEW_ADCP_VERSION);
const candidates = major === undefined
? parsedVersions
: parsedVersions.filter(version => version.major === major);
diff --git a/server/src/training-agent/tenants/registry.ts b/server/src/training-agent/tenants/registry.ts
index b5138fd77aa..c86585ff132 100644
--- a/server/src/training-agent/tenants/registry.ts
+++ b/server/src/training-agent/tenants/registry.ts
@@ -52,13 +52,13 @@ import { buildBrandTenantConfig } from './brand.js';
import { buildSiTenantConfig } from './si.js';
import { createLogger } from '../../logger.js';
import { TRAINING_AGENT_CURRENT_ADCP_VERSION, type TrainingContext } from '../types.js';
-import { TRAINING_AGENT_CANDIDATE_ADCP_VERSION } from '../candidate-version.js';
+import { TRAINING_AGENT_CANDIDATE_ADCP_VERSION, TRAINING_AGENT_HOSTED_PREVIEW } from '../candidate-version.js';
import { releaseLineEchoEnhancer } from './release-line-echo.js';
import { getCanonicalBase } from '../canonical-base.js';
import { creativeProjectionAdapters } from '../task-handlers.js';
import { sharedTrainingTaskStore } from '../mcp-task-store.js';
import { taskRegistryNamespaceForTenant } from '../task-registry-scope.js';
-import { ensureTrainingAgentSchemaBundle } from '../schema-compat.js';
+import { ensurePreviewSchemaBundle, ensureTrainingAgentSchemaBundle } from '../schema-compat.js';
export { getCanonicalBase } from '../canonical-base.js';
@@ -197,19 +197,26 @@ function buildDefaultServerOptions(
storyboardCompat: TrainingContext['storyboardCompat'] | undefined,
taskRegistry: TaskRegistry,
identity33?: CreateAdcpServerFromPlatformOptions['identity33'],
+ preview?: boolean,
): CreateAdcpServerFromPlatformOptions {
const projectionAdapters = creativeProjectionAdapters();
return {
name: 'adcp-training-agent',
version: '1.0.0',
// The experimental identity route speaks 3.3: the SDK binds identity33
- // to the 3.3 schemas, and Web Bot Auth is a 3.3 profile.
+ // to the 3.3 schemas, and Web Bot Auth is a 3.3 profile. The hosted
+ // preview registry serves only requests pinned exactly to the preview
+ // (tenants/router.ts routes them); every other request stays on a stable
+ // registry configured as if the preview did not exist, because the SDK
+ // shapes each response down from its configured ceiling.
adcpVersion: identity33
? '3.3'
: storyboardCompat?.version === '3.0'
? '3.0'
- : TRAINING_AGENT_CANDIDATE_ADCP_VERSION ?? TRAINING_AGENT_CURRENT_ADCP_VERSION,
- ...(!identity33 && TRAINING_AGENT_CANDIDATE_ADCP_VERSION && storyboardCompat?.version !== '3.0' && {
+ : preview
+ ? TRAINING_AGENT_HOSTED_PREVIEW.wireVersion
+ : TRAINING_AGENT_CANDIDATE_ADCP_VERSION ?? TRAINING_AGENT_CURRENT_ADCP_VERSION,
+ ...(!identity33 && !preview && TRAINING_AGENT_CANDIDATE_ADCP_VERSION && storyboardCompat?.version !== '3.0' && {
defaultAdcpVersion: TRAINING_AGENT_CURRENT_ADCP_VERSION,
}),
...(identity33 && { identity33 }),
@@ -287,6 +294,9 @@ export function createRegistryHolder(options: {
proposalNegotiationProfile?: TrainingContext['proposalNegotiationProfile'];
/** Experimental 3.3 identity authorization; serves AdCP 3.3. */
identity33?: CreateAdcpServerFromPlatformOptions['identity33'];
+ /** Serve the hosted 3.3 preview (candidate-version.ts). The router sends
+ * this registry only requests pinned exactly to it. */
+ preview?: boolean;
/** Register only these tenants. Defaults to every tenant. */
tenantIds?: readonly string[];
} = {}): RegistryHolder {
@@ -299,13 +309,14 @@ export function createRegistryHolder(options: {
if (pendingInit) return pendingInit;
const promise = (async () => {
await ensureTrainingAgentSchemaBundle();
+ if (options.preview) await ensurePreviewSchemaBundle();
const t0 = Date.now();
logger.info('Tenant registry init starting');
const hostBase = buildHostBaseUrl();
const signalsTaskRegistry = pickTaskRegistry('signals');
const salesTaskRegistry = withSellerManagedTaskReplay(pickTaskRegistry('sales'));
const reg = createTenantRegistry({
- defaultServerOptions: buildDefaultServerOptions(options.storyboardCompat, salesTaskRegistry, options.identity33),
+ defaultServerOptions: buildDefaultServerOptions(options.storyboardCompat, salesTaskRegistry, options.identity33, options.preview),
jwksValidator: noopJwksValidator,
autoValidate: true,
});
diff --git a/server/src/training-agent/tenants/release-line-echo.ts b/server/src/training-agent/tenants/release-line-echo.ts
index f1de3c68e34..ff2a1d09b70 100644
--- a/server/src/training-agent/tenants/release-line-echo.ts
+++ b/server/src/training-agent/tenants/release-line-echo.ts
@@ -5,6 +5,7 @@ import {
TRAINING_AGENT_CURRENT_ADCP_RELEASE,
TRAINING_AGENT_CURRENT_ADCP_VERSION,
} from '../types.js';
+import { TRAINING_AGENT_PREVIEW_ADCP_VERSION } from '../candidate-version.js';
type ResponseEnhancer = NonNullable;
@@ -39,7 +40,8 @@ export function runWithReleaseLineEcho(body: unknown, fn: () => T): T {
* structured result and its JSON text mirror agree with the negotiated
* release. Inert once the current bundle is the release line itself.
*/
-export const releaseLineEchoEnhancer: ResponseEnhancer = (response) => {
+export const releaseLineEchoEnhancer: ResponseEnhancer = (response, context) => {
+ echoPreview(response, context);
if (servingReleaseLine.getStore() !== true) return;
const structured = (response as { structuredContent?: unknown }).structuredContent;
if (!structured || typeof structured !== 'object' || Array.isArray(structured)) return;
@@ -50,3 +52,24 @@ export const releaseLineEchoEnhancer: ResponseEnhancer = (response) => {
record.adcp_version = TRAINING_AGENT_CURRENT_ADCP_RELEASE;
if (textMirrorsStructured && first) first.text = JSON.stringify(record);
};
+
+/**
+ * A response served at the opt-in preview echoes it (versioning.mdx: the echo
+ * names the release served). The SDK stamps the echo on framework tools; the
+ * sales tenant's custom tools (list_accounts, request_account, get_principal,
+ * ...) carry none, so add it there. Stable responses are left as they are.
+ */
+function echoPreview(
+ response: Parameters[0],
+ context: Parameters[1],
+): void {
+ if (!TRAINING_AGENT_PREVIEW_ADCP_VERSION || context?.servedAdcpVersion !== TRAINING_AGENT_PREVIEW_ADCP_VERSION) return;
+ const structured = (response as { structuredContent?: unknown }).structuredContent;
+ if (!structured || typeof structured !== 'object' || Array.isArray(structured)) return;
+ const record = structured as Record;
+ if (record.adcp_version !== undefined) return;
+ const first = Array.isArray(response.content) ? response.content[0] as { type?: unknown; text?: unknown } | undefined : undefined;
+ const textMirrorsStructured = first?.type === 'text' && first.text === JSON.stringify(record);
+ record.adcp_version = TRAINING_AGENT_PREVIEW_ADCP_VERSION;
+ if (textMirrorsStructured && first) first.text = JSON.stringify(record);
+}
diff --git a/server/src/training-agent/tenants/router.ts b/server/src/training-agent/tenants/router.ts
index ff6a8214223..bf8eddd0cb4 100644
--- a/server/src/training-agent/tenants/router.ts
+++ b/server/src/training-agent/tenants/router.ts
@@ -19,6 +19,7 @@ import { createLogger } from '../../logger.js';
import { runWithAccountIdAliasScope, runWithSessionContext, flushDirtySessions } from '../state.js';
import { createRegistryHolder, pickStateStore, resolveTenantHost, type RegistryHolder } from './registry.js';
import { createIdentity33Runtime, type Identity33Runtime } from '../identity33/runtime.js';
+import { requestPinsPreview, TRAINING_AGENT_SERVES_HOSTED_PREVIEW } from '../candidate-version.js';
import { IDENTITY33_ROUTE, PROPOSAL_NEGOTIATION_PROFILE_PATHS } from '../lab-route-paths.js';
import { getReplayStore } from '../request-signing.js';
import { advertiseIdentity33Capabilities, requireIdentity33, signedRequestUrl } from '../identity33/route.js';
@@ -54,7 +55,7 @@ import {
supportedCanonicalFormatsCapability,
} from '../task-handlers.js';
import { sellerOptimizedDeclarationForVersion, sellerOptimizedFeatureFlags } from '../seller-optimized-budget.js';
-import { supportsAccountChangeFeed, supportsAccountSurfaces33, TRAINING_AGENT_REGISTERS_ACCOUNT_SURFACES_33, 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, supportsAccountSurfaces33, TRAINING_AGENT_REGISTERS_ACCOUNT_SURFACES_33, supportsBiddingPolicyCapability, TRAINING_BIDDING_POLICY_CAPABILITY, supportsGetProductsRejected, supportsReliableReporting, supportsReportingStatus, supportsSalesFixedRate, supportsSellerGovernanceDiscovery, TRAINING_AGENT_CURRENT_ADCP_VERSION, TRAINING_AGENT_DEFAULT_ADCP_VERSION, TRAINING_AGENT_STABLE_REGISTRY_VERSIONS, 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';
@@ -368,7 +369,11 @@ function tenantMcpHandler(
tenantId: string,
storyboardCompat?: TrainingContext['storyboardCompat'],
proposalNegotiationProfile?: TrainingContext['proposalNegotiationProfile'],
+ previewHolder?: RegistryHolder,
) {
+ // Releases this route serves: with a preview registry, every advertised
+ // release; otherwise the stable registry's.
+ const routeVersions = previewHolder ? TRAINING_AGENT_SUPPORTED_RELEASE_VERSIONS : TRAINING_AGENT_STABLE_REGISTRY_VERSIONS;
return async (req: Request, res: Response): Promise => {
setCORSHeaders(res);
@@ -379,6 +384,7 @@ function tenantMcpHandler(
tenantId,
storyboardCompat,
proposalNegotiationProfile,
+ routeVersions,
);
// Bridge `res.locals.trainingPrincipal` (set by the upstream
// `requireAuth` middleware) onto `req.auth` so the framework's MCP
@@ -487,7 +493,11 @@ function tenantMcpHandler(
}
const host = resolveTenantHost(req);
- const registry = await holder.get().catch((err: unknown) => {
+ // Only a request pinned exactly to the hosted preview reaches its
+ // registry; every other request is served as if the preview did not
+ // exist (versioning.mdx, "Pre-release pins").
+ const servingHolder = previewHolder && requestPinsPreview(req.body) ? previewHolder : holder;
+ const registry = await servingHolder.get().catch((err: unknown) => {
// Surfacing the rejection here is what makes #3854 / #3869-class
// init bugs visible. Without it the rejection escapes to Express's
// default error handler — the smoke sees an HTML 500 with no JSON
@@ -623,10 +633,10 @@ function tenantMcpHandler(
else delete controllerArgs.ext;
}
- if (await tryHandleLocalComplyScenario(req, res, resolved.tenantId, principal, storyboardCompat)) {
+ if (await tryHandleLocalComplyScenario(req, res, resolved.tenantId, principal, storyboardCompat, routeVersions)) {
return;
}
- if (await tryRefuseByAccountGrant(req, res, principal, storyboardCompat)) {
+ if (await tryRefuseByAccountGrant(req, res, principal, storyboardCompat, routeVersions)) {
return;
}
const transport = new StreamableHTTPServerTransport({
@@ -701,6 +711,7 @@ async function tryRefuseByAccountGrant(
res: Response,
principal: string | undefined,
storyboardCompat: TrainingContext['storyboardCompat'] | undefined,
+ routeVersions: readonly string[],
): Promise {
if (storyboardCompat?.version === '3.0') return false;
if (req.body?.method !== 'tools/call') return false;
@@ -712,7 +723,7 @@ async function tryRefuseByAccountGrant(
if (!accountId) return false;
// Grants change only through the 3.3 controller scenario. A process that
// never serves the 3.3 wire skips the per-call sandbox read.
- const version = resolveServedAdcpVersion(args);
+ const version = resolveServedAdcpVersion(args, routeVersions);
if (!TRAINING_AGENT_REGISTERS_ACCOUNT_SURFACES_33 && !(version.ok && supportsAccountSurfaces33(version.servedVersion))) {
return false;
}
@@ -750,7 +761,8 @@ async function tryHandleLocalComplyScenario(
res: Response,
tenantId: string,
principal: string | undefined,
- storyboardCompat?: TrainingContext['storyboardCompat'],
+ storyboardCompat: TrainingContext['storyboardCompat'] | undefined,
+ routeVersions: readonly string[],
): Promise {
if (req.body?.method !== 'tools/call') return false;
if (req.body?.params?.name !== 'comply_test_controller') return false;
@@ -826,7 +838,7 @@ async function tryHandleLocalComplyScenario(
}
const { context, ...handlerArgs } = rawArgs;
- const versionResolution = resolveServedAdcpVersion(handlerArgs);
+ const versionResolution = resolveServedAdcpVersion(handlerArgs, routeVersions);
if (!versionResolution.ok) {
res.json({
jsonrpc: '2.0',
@@ -892,8 +904,9 @@ function wrapTenantCapabilitiesProjection(
req: Request,
res: Response,
tenantId: string,
- storyboardCompat?: TrainingContext['storyboardCompat'],
- proposalNegotiationProfile?: TrainingContext['proposalNegotiationProfile'],
+ storyboardCompat: TrainingContext['storyboardCompat'] | undefined,
+ proposalNegotiationProfile: TrainingContext['proposalNegotiationProfile'] | undefined,
+ routeVersions: readonly string[],
): void {
if (req.body?.method !== 'tools/call') return;
if (req.body?.params?.name !== 'get_adcp_capabilities') return;
@@ -902,7 +915,7 @@ function wrapTenantCapabilitiesProjection(
const hasVersionSelector = capabilityArgs.adcp_version !== undefined
|| capabilityArgs.adcp_major_version !== undefined;
const requestedVersion = hasVersionSelector
- ? resolveServedAdcpVersion(capabilityArgs)
+ ? resolveServedAdcpVersion(capabilityArgs, routeVersions)
: proposalNegotiationProfile
? { ok: true as const, servedVersion: TRAINING_AGENT_CURRENT_ADCP_VERSION }
: undefined;
@@ -927,6 +940,7 @@ function wrapTenantCapabilitiesProjection(
storyboardCompat,
proposalNegotiationProfile,
requestedVersion?.ok ? requestedVersion.servedVersion : undefined,
+ routeVersions,
);
if (patched !== body && !res.headersSent) {
res.setHeader('content-length', String(patched.length));
@@ -1068,6 +1082,7 @@ function projectTenantCapabilities(
storyboardCompat?: TrainingContext['storyboardCompat'],
proposalNegotiationProfile?: TrainingContext['proposalNegotiationProfile'],
servedVersionOverride?: string,
+ routeVersions: readonly string[] = TRAINING_AGENT_STABLE_REGISTRY_VERSIONS,
): Buffer {
try {
const parsed = JSON.parse(body.toString('utf8')) as {
@@ -1118,9 +1133,11 @@ function projectTenantCapabilities(
: {};
structured.adcp = {
...adcp,
- supported_versions: Array.isArray(adcp.supported_versions)
- ? adcp.supported_versions
- : [...TRAINING_AGENT_SUPPORTED_RELEASE_VERSIONS],
+ // A route with the preview registry advertises the preview with its
+ // stable releases; the stable registry itself never lists it.
+ supported_versions: routeVersions !== TRAINING_AGENT_STABLE_REGISTRY_VERSIONS || !Array.isArray(adcp.supported_versions)
+ ? [...routeVersions]
+ : adcp.supported_versions,
};
const tenantProtocols = TENANT_PROTOCOLS[tenantId];
// Frozen 3.0 capability projection predates the route-specific protocol
@@ -1657,6 +1674,18 @@ export function mountTenantRoutes(
});
}
}
+ // The hosted 3.3 preview (#8181) has its own registry, so stable requests
+ // keep exactly the stable configuration: the SDK shapes every response
+ // down from its configured ceiling. Built on the first preview-pinned
+ // request; production prewarms it once the stable registry is up.
+ const previewHolder = TRAINING_AGENT_SERVES_HOSTED_PREVIEW && middleware.storyboardCompat?.version !== '3.0'
+ ? createRegistryHolder({ storyboardCompat: middleware.storyboardCompat, preview: true, tenantIds })
+ : undefined;
+ if (previewHolder && process.env.NODE_ENV === 'production') {
+ holder.get().then(() => previewHolder.get()).catch(err => {
+ logger.error({ err }, 'Preview tenant registry prewarm failed; the first preview request will retry');
+ });
+ }
const mw: RequestHandler[] = [];
if (middleware.rateLimit) mw.push(middleware.rateLimit);
if (middleware.requireAuth) mw.push(middleware.requireAuth);
@@ -1676,7 +1705,7 @@ export function mountTenantRoutes(
parent.post(
`/${tenantId}/mcp`,
...(tenantId === 'governance' ? governanceMw : tenantId === 'sales' ? salesMw : mw),
- tenantMcpHandler(holder, tenantId, middleware.storyboardCompat),
+ tenantMcpHandler(holder, tenantId, middleware.storyboardCompat, undefined, previewHolder),
);
parent.get(`/${tenantId}/mcp`, (_req, res) => {
setCORSHeaders(res);
@@ -1699,7 +1728,7 @@ export function mountTenantRoutes(
setCORSHeaders(res);
res.status(204).end();
});
- parent.post('/', ...governanceMw, tenantMcpHandler(holder, 'governance', middleware.storyboardCompat));
+ parent.post('/', ...governanceMw, tenantMcpHandler(holder, 'governance', middleware.storyboardCompat, undefined, previewHolder));
}
if (
diff --git a/server/src/training-agent/tenants/sales.ts b/server/src/training-agent/tenants/sales.ts
index 18172c48372..e68b4bbd5c7 100644
--- a/server/src/training-agent/tenants/sales.ts
+++ b/server/src/training-agent/tenants/sales.ts
@@ -232,6 +232,8 @@ export function buildSalesTenantConfig(
proposalNegotiationProfile?: TrainingContext['proposalNegotiationProfile'];
/** Set on the experimental 3.3 identity route's registry holder. */
identity33?: unknown;
+ /** Set on the hosted 3.3 preview's registry holder. */
+ preview?: boolean;
} = {},
taskRegistry?: TaskRegistry,
): {
@@ -243,6 +245,7 @@ export function buildSalesTenantConfig(
options.storyboardCompat,
options.proposalNegotiationProfile ?? 'ask-only',
taskRegistry,
+ options.preview === true,
);
return {
tenantId: TENANT_ID,
@@ -279,9 +282,10 @@ export function buildSalesTenantConfig(
customTools: {
list_accounts: listAccountsTool(options.storyboardCompat),
// Experimental 3.3 account requests: registered where the 3.3 wire
- // is served (the identity route, and storyboard candidate mode).
+ // is served (the identity route, the hosted preview, and storyboard
+ // candidate mode).
...(options.storyboardCompat?.version !== '3.0'
- && (options.identity33 || TRAINING_AGENT_REGISTERS_ACCOUNT_SURFACES_33)
+ && (options.identity33 || options.preview || TRAINING_AGENT_REGISTERS_ACCOUNT_SURFACES_33)
&& { request_account: requestAccountTool() }),
report_usage: reportUsageTool({ creativeBillsThroughAdcp: false }),
...(options.storyboardCompat?.version !== '3.0' && {
diff --git a/server/src/training-agent/tenants/served-release-shape.test.ts b/server/src/training-agent/tenants/served-release-shape.test.ts
index e07cfcae9aa..d41bb479323 100644
--- a/server/src/training-agent/tenants/served-release-shape.test.ts
+++ b/server/src/training-agent/tenants/served-release-shape.test.ts
@@ -18,9 +18,11 @@
* or "Unknown tool" on /mcp) rather than answered with a payload that
* release cannot validate.
*
- * 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.
+ * The same flow runs at the opt-in 3.3 preview (#8181,
+ * candidate-version.ts): an exact `3.3-beta.3` pin is echoed and every
+ * response validates against the published 3.3.0-beta.3 bundle, the release
+ * the preview claims. The local candidate wire contract is covered in
+ * tests/unit/training-agent-candidate-version.test.ts.
*/
import { afterAll, beforeAll, describe, expect, it } from 'vitest';
@@ -30,11 +32,15 @@ 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';
+import { TRAINING_AGENT_HOSTED_PREVIEW, TRAINING_AGENT_PREVIEW_ADCP_VERSION } from '../candidate-version.js';
process.env.PUBLIC_TEST_AGENT_TOKEN = 'served-release-shape-token';
const TOKEN = 'served-release-shape-token';
+/** Stable releases, then the opt-in preview this process serves. */
+const VERSIONS = ['3.2', '3.1', '3.0', TRAINING_AGENT_HOSTED_PREVIEW.wireVersion] as const;
+
/** The source response schema each tool is graded against for `x-added-in`. */
const RESPONSE_SCHEMAS: Record = {
get_adcp_capabilities: 'protocol/get-adcp-capabilities-response.json',
@@ -287,9 +293,13 @@ describe('served-release response shape below 3.3 (#8487)', () => {
await new Promise(resolve => server.close(() => resolve()));
});
+ it('serves the hosted preview in this process', () => {
+ expect(TRAINING_AGENT_PREVIEW_ADCP_VERSION).toBe(TRAINING_AGENT_HOSTED_PREVIEW.wireVersion);
+ });
+
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 () => {
+ it(`serves ${label} callers pinned to 3.2, 3.1, 3.0 and the 3.3 preview their release's shape`, async () => {
const url = `${baseUrl}${route ? `/${route}` : ''}/mcp`;
await rpc(url, 1, 'initialize', {
protocolVersion: '2025-03-26',
@@ -298,7 +308,7 @@ describe('served-release response shape below 3.3 (#8487)', () => {
});
const graded: string[] = [];
const failures: string[] = [];
- for (const version of ['3.2', '3.1', '3.0']) {
+ for (const version of VERSIONS) {
const account = {
brand: { domain: `served-release-${route || 'v5'}.example` },
operator: `served-release-${route || 'v5'}.example`,
@@ -338,6 +348,10 @@ describe('served-release response shape below 3.3 (#8487)', () => {
capture(tool, structured, state);
const served = typeof structured.adcp_version === 'string' ? structured.adcp_version : version;
expect(served.startsWith(version), `${label} ${tool} echoed ${served} for ${version}`).toBe(true);
+ // The preview is only ever served to an exact pin, and says so.
+ if (version === TRAINING_AGENT_HOSTED_PREVIEW.wireVersion && structured.adcp_version !== version) {
+ failures.push(`${label} ${tool} @${version}: echoed ${String(structured.adcp_version)}`);
+ }
const schemaFile = tool === 'list_creative_formats' && route.startsWith('creative')
? 'creative/list-creative-formats-response.json'
@@ -373,8 +387,9 @@ describe('served-release response shape below 3.3 (#8487)', () => {
}
}
expect(failures).toEqual([]);
- // Every listed tool was graded at 3.2.
+ // Every listed tool was graded at 3.2 and at the preview.
expect(graded.filter(entry => entry.endsWith('@3.2')).map(entry => entry.split('@')[0])).toEqual([...tools]);
+ expect(graded.filter(entry => entry.endsWith(`@${TRAINING_AGENT_HOSTED_PREVIEW.wireVersion}`)).map(entry => entry.split('@')[0])).toEqual([...tools]);
}, 180_000);
}
diff --git a/server/src/training-agent/tenants/tenant-smoke.test.ts b/server/src/training-agent/tenants/tenant-smoke.test.ts
index 4f9ffd1b762..7f031ea579c 100644
--- a/server/src/training-agent/tenants/tenant-smoke.test.ts
+++ b/server/src/training-agent/tenants/tenant-smoke.test.ts
@@ -2291,7 +2291,8 @@ describe('tenant routing smoke', () => {
const previewRouteIds = creative?.preview?.routes?.map(route => route.capability_id) ?? [];
expect(body.result?.structuredContent?.adcp_version).toBe('3.2');
expect(body.result?.structuredContent?.adcp?.major_versions).toContain(3);
- expect(body.result?.structuredContent?.adcp?.supported_versions).toEqual(['3.0', '3.1-beta.5', '3.1-beta.7', '3.1-rc.4', '3.1-rc.6', '3.1-rc.7', '3.1-rc.8', '3.1-rc.9', '3.1-rc.10', '3.1-rc.14', '3.1-rc.15', '3.1', '3.2-beta.6', '3.2-rc.0', '3.2-rc.7', '3.2']);
+ // The opt-in 3.3 preview (#8181) is advertised last, served to an exact pin only.
+ expect(body.result?.structuredContent?.adcp?.supported_versions).toEqual(['3.0', '3.1-beta.5', '3.1-beta.7', '3.1-rc.4', '3.1-rc.6', '3.1-rc.7', '3.1-rc.8', '3.1-rc.9', '3.1-rc.10', '3.1-rc.14', '3.1-rc.15', '3.1', '3.2-beta.6', '3.2-rc.0', '3.2-rc.7', '3.2', '3.3-beta.3']);
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');
@@ -3918,7 +3919,7 @@ describe('tenant routing smoke', () => {
field: 'adcp_version',
details: {
adcp_version: '4.0',
- supported_versions: ['3.0', '3.1-beta.5', '3.1-beta.7', '3.1-rc.4', '3.1-rc.6', '3.1-rc.7', '3.1-rc.8', '3.1-rc.9', '3.1-rc.10', '3.1-rc.14', '3.1-rc.15', '3.1', '3.2-beta.6', '3.2-rc.0', '3.2-rc.7', '3.2'],
+ supported_versions: ['3.0', '3.1-beta.5', '3.1-beta.7', '3.1-rc.4', '3.1-rc.6', '3.1-rc.7', '3.1-rc.8', '3.1-rc.9', '3.1-rc.10', '3.1-rc.14', '3.1-rc.15', '3.1', '3.2-beta.6', '3.2-rc.0', '3.2-rc.7', '3.2', '3.3-beta.3'],
},
});
expect(unsupportedBody.result?.structuredContent?.context?.correlation_id).toBe('tenant-local-version-unsupported');
diff --git a/server/src/training-agent/types.ts b/server/src/training-agent/types.ts
index 8feef9a825e..dd912baa005 100644
--- a/server/src/training-agent/types.ts
+++ b/server/src/training-agent/types.ts
@@ -12,7 +12,11 @@ import type {
EventType,
CanonicalProposal,
} from '@adcp/sdk';
-import { TRAINING_AGENT_CANDIDATE_ADCP_VERSION } from './candidate-version.js';
+import {
+ TRAINING_AGENT_CANDIDATE_ADCP_VERSION,
+ TRAINING_AGENT_PREVIEW_ADCP_VERSION,
+ TRAINING_AGENT_SERVES_HOSTED_PREVIEW,
+} from './candidate-version.js';
// SpecialCategory for episodes (e.g., premiere, finale) — not yet in @adcp/sdk types
type SpecialCategory = 'premiere' | 'finale' | 'holiday' | 'awards' | 'reunion' | 'crossover' | 'championship';
@@ -86,10 +90,26 @@ export const TRAINING_AGENT_SUPPORTED_RELEASE_VERSIONS: readonly string[] = Obje
'3.2-rc.0', TRAINING_AGENT_RETAINED_RC_ADCP_VERSION,
TRAINING_AGENT_CURRENT_ADCP_VERSION,
TRAINING_AGENT_CURRENT_ADCP_RELEASE,
- ...(TRAINING_AGENT_CANDIDATE_ADCP_VERSION ? [TRAINING_AGENT_CANDIDATE_ADCP_VERSION] : []),
+ // The opt-in prerelease preview (candidate-version.ts), served only to an
+ // exact pin.
+ ...(TRAINING_AGENT_PREVIEW_ADCP_VERSION ? [TRAINING_AGENT_PREVIEW_ADCP_VERSION] : []),
])]);
export const TRAINING_AGENT_DEFAULT_ADCP_VERSION = '3.0' as const;
+/**
+ * The releases an SDK registry can negotiate below its configured ceiling.
+ * The hosted preview is served by its own registry (tenants/registry.ts), so
+ * the stable registries keep exactly the releases they negotiated before it
+ * existed. In candidate mode the candidate stays in, as one registry serves
+ * it. Equal to TRAINING_AGENT_SUPPORTED_RELEASE_VERSIONS when the preview is
+ * off.
+ */
+export const TRAINING_AGENT_STABLE_REGISTRY_VERSIONS: readonly string[] = Object.freeze(
+ TRAINING_AGENT_SUPPORTED_RELEASE_VERSIONS.filter(version => !(
+ TRAINING_AGENT_SERVES_HOSTED_PREVIEW && version === TRAINING_AGENT_PREVIEW_ADCP_VERSION
+ )),
+);
+
export const PROPOSAL_NEGOTIATION_PROFILES = [
'ask-only',
'typed-negotiation',
@@ -249,8 +269,10 @@ export function supportsAccountSurfaces33(servedVersion: string | undefined): bo
}
/** Whether this process registers the experimental 3.3 account tools on its
- * ordinary routes: only when it can serve the 3.3 wire (the trusted
- * storyboard candidate mode). The 3.3 identity route registers them too. */
+ * ordinary routes and enforces sandbox grants on every account-scoped call:
+ * only when one registry serves the 3.3 wire to every caller (the trusted
+ * storyboard candidate mode). The hosted preview's own registry and the 3.3
+ * identity route register them too. */
export const TRAINING_AGENT_REGISTERS_ACCOUNT_SURFACES_33 = supportsAccountSurfaces33(TRAINING_AGENT_CANDIDATE_ADCP_VERSION);
/** An AdCP release version (`3.2`, `3.1-rc.4`, `3.0.28`), parsed. */
diff --git a/server/src/training-agent/v6-sales-platform.ts b/server/src/training-agent/v6-sales-platform.ts
index c1c870b2e5f..7ee31468b13 100644
--- a/server/src/training-agent/v6-sales-platform.ts
+++ b/server/src/training-agent/v6-sales-platform.ts
@@ -93,7 +93,7 @@ import {
runWithSessionContext,
sessionKeyFromArgs,
} from './state.js';
-import { supportsAccountSurfaces33, supportsReliableReporting, supportsReportingStatus, TRAINING_AGENT_SUPPORTED_RELEASE_VERSIONS, TRAINING_CONVERSION_TRACKING_SUPPORTED_TARGETS, type ToolArgs, type TrainingContext } from './types.js';
+import { supportsAccountSurfaces33, supportsReliableReporting, supportsReportingStatus, TRAINING_AGENT_STABLE_REGISTRY_VERSIONS, TRAINING_AGENT_SUPPORTED_RELEASE_VERSIONS, TRAINING_CONVERSION_TRACKING_SUPPORTED_TARGETS, type ToolArgs, type TrainingContext } from './types.js';
import { canonicalizeAccountRef, syntheticAccountIdFromRef } from './account-scope.js';
import { emitDurableSellerManagedTaskWebhook, maybeEmitCompletionWebhook } from './webhooks.js';
import { validateWebhookUrl } from './webhook-fetch.js';
@@ -1562,6 +1562,8 @@ export class TrainingSalesPlatform
private readonly storyboardCompat?: TrainingContext['storyboardCompat'],
private readonly proposalNegotiationProfile: NonNullable = 'ask-only',
taskRegistry?: TaskRegistry,
+ /** This platform serves the hosted 3.3 preview's registry. */
+ private readonly servesPreview = false,
) {
if (taskRegistry) {
this.sellerManagedControlJobs = new SellerManagedControlJobCoordinator(
@@ -1625,7 +1627,11 @@ export class TrainingSalesPlatform
// no longer derives the retained 3.2-rc.7 checkpoint on its own. Declare
// the served releases explicitly so exact prerelease pins negotiate to
// the checkpoint the agent advertises instead of downshifting to 3.1.
- return { ...TRAINING_SALES_CAPABILITIES, supported_versions: [...TRAINING_AGENT_SUPPORTED_RELEASE_VERSIONS] };
+ // Only the preview's own registry negotiates the hosted preview.
+ return {
+ ...TRAINING_SALES_CAPABILITIES,
+ supported_versions: [...(this.servesPreview ? TRAINING_AGENT_SUPPORTED_RELEASE_VERSIONS : TRAINING_AGENT_STABLE_REGISTRY_VERSIONS)],
+ };
}
async acknowledgeSellerManagedWebhook(taskId: string): Promise {
diff --git a/server/tests/unit/training-agent-preview-kill-switch.test.ts b/server/tests/unit/training-agent-preview-kill-switch.test.ts
new file mode 100644
index 00000000000..d77f3bf4492
--- /dev/null
+++ b/server/tests/unit/training-agent-preview-kill-switch.test.ts
@@ -0,0 +1,93 @@
+/**
+ * #8181: TRAINING_AGENT_DISABLE_ADCP_PREVIEW turns the hosted 3.3 preview off
+ * without a code change. The process then negotiates exactly as one that
+ * never listed the preview: nothing advertises it, an exact pin is refused on
+ * the v5 route and served the stable release on SDK tenant routes (as before
+ * the preview existed), and the experimental tools are not registered.
+ */
+import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
+import express from 'express';
+import http from 'node:http';
+
+vi.hoisted(() => {
+ process.env.TRAINING_AGENT_DISABLE_ADCP_PREVIEW = '1';
+ process.env.PUBLIC_TEST_AGENT_TOKEN = 'preview-kill-switch-token';
+});
+
+import { TRAINING_AGENT_HOSTED_PREVIEW, TRAINING_AGENT_PREVIEW_ADCP_VERSION } from '../../src/training-agent/candidate-version.js';
+import { PREVIEW_SCHEMA_BUNDLE } from '../../src/training-agent/schema-compat.js';
+import { TRAINING_AGENT_SUPPORTED_RELEASE_VERSIONS } from '../../src/training-agent/types.js';
+import { stopSessionCleanup } from '../../src/training-agent/state.js';
+
+const PREVIEW = TRAINING_AGENT_HOSTED_PREVIEW.wireVersion;
+
+describe('hosted 3.3 preview kill switch', () => {
+ let server: http.Server;
+ let baseUrl: string;
+ let rpcId = 0;
+
+ const rpc = async (path: string, method: string, params?: Record) => {
+ rpcId += 1;
+ const response = await fetch(`${baseUrl}${path}`, {
+ method: 'POST',
+ headers: { 'content-type': 'application/json', accept: 'application/json, text/event-stream', authorization: 'Bearer preview-kill-switch-token' },
+ body: JSON.stringify({ jsonrpc: '2.0', id: rpcId, method, ...(params && { params }) }),
+ });
+ return response.json() as Promise>;
+ };
+
+ beforeAll(async () => {
+ const { createTrainingAgentRouter } = await import('../../src/training-agent/index.js');
+ const app = express();
+ app.use(express.json({ verify: (req, _res, body) => {
+ (req as unknown as { rawBody: string }).rawBody = body.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 () => {
+ stopSessionCleanup();
+ if (server) {
+ server.closeAllConnections();
+ await new Promise(resolve => server.close(() => resolve()));
+ }
+ });
+
+ it('removes the preview from the process', () => {
+ expect(TRAINING_AGENT_PREVIEW_ADCP_VERSION).toBeUndefined();
+ expect(PREVIEW_SCHEMA_BUNDLE).toBeUndefined();
+ expect(TRAINING_AGENT_SUPPORTED_RELEASE_VERSIONS.some(version => version.startsWith('3.3'))).toBe(false);
+ });
+
+ it.each(['/mcp', '/sales/mcp', '/signals/mcp'])('neither advertises nor serves the preview on %s', async route => {
+ for (const args of [{}, { adcp_version: '3.2' }]) {
+ const result = (await rpc(route, 'tools/call', { name: 'get_adcp_capabilities', arguments: args })).result?.structuredContent;
+ expect(result.adcp.supported_versions).not.toContain(PREVIEW);
+ expect(result.experimental_features ?? []).not.toContain('account.requests');
+ }
+ const pinned = (await rpc(route, 'tools/call', { name: 'get_adcp_capabilities', arguments: { adcp_version: PREVIEW } })).result?.structuredContent;
+ if (route === '/mcp') {
+ expect(pinned.adcp_error?.code, JSON.stringify(pinned).slice(0, 300)).toBe('VERSION_UNSUPPORTED');
+ expect(pinned.adcp_error.details.supported_versions).not.toContain(PREVIEW);
+ } else {
+ expect(pinned.adcp_version, JSON.stringify(pinned).slice(0, 300)).toBe('3.2');
+ expect(pinned.experimental_features ?? []).not.toContain('account.requests');
+ }
+ }, 60_000);
+
+ it('does not register the experimental account tool', async () => {
+ const list = await rpc('/sales/mcp', 'tools/list', { _meta: { adcp_version: PREVIEW } });
+ expect(list.result.tools.map((tool: { name: string }) => tool.name)).not.toContain('request_account');
+ const called = await rpc('/sales/mcp', 'tools/call', {
+ name: 'request_account',
+ arguments: { adcp_version: PREVIEW, brand: { domain: 'kill-switch.example' }, operator: 'kill-switch.example', idempotency_key: 'preview-kill-switch-request-1' },
+ });
+ expect(called.result?.isError).toBe(true);
+ expect(called.result?.structuredContent?.request).toBeUndefined();
+ }, 60_000);
+});
diff --git a/server/tests/unit/training-agent-preview-version.test.ts b/server/tests/unit/training-agent-preview-version.test.ts
new file mode 100644
index 00000000000..1e1b6f53181
--- /dev/null
+++ b/server/tests/unit/training-agent-preview-version.test.ts
@@ -0,0 +1,272 @@
+/**
+ * #8181: the hosted training agent serves the published AdCP 3.3 beta as an
+ * opt-in preview. Only an exact pin is served the preview; stable, major-only
+ * and unpinned callers negotiate as before (versioning.mdx, "Pre-release
+ * pins"). The kill switch is covered in
+ * training-agent-preview-kill-switch.test.ts, response shapes in
+ * src/training-agent/tenants/served-release-shape.test.ts.
+ */
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import express from 'express';
+import http from 'node:http';
+
+process.env.PUBLIC_TEST_AGENT_TOKEN = 'preview-version-test-token';
+
+import {
+ TRAINING_AGENT_HOSTED_PREVIEW,
+ TRAINING_AGENT_PREVIEW_ADCP_VERSION,
+ TRAINING_AGENT_PREVIEW_KILL_SWITCH,
+ requestPinsPreview,
+ trainingAgentPreviewVersion,
+} from '../../src/training-agent/candidate-version.js';
+import { resolveServedAdcpVersion } from '../../src/training-agent/task-handlers.js';
+import {
+ TRAINING_AGENT_STABLE_REGISTRY_VERSIONS,
+ TRAINING_AGENT_SUPPORTED_RELEASE_VERSIONS,
+} from '../../src/training-agent/types.js';
+import { stopSessionCleanup } from '../../src/training-agent/state.js';
+
+const PREVIEW = TRAINING_AGENT_HOSTED_PREVIEW.wireVersion;
+const TOKEN = 'preview-version-test-token';
+
+type Structured = Record;
+
+describe('hosted 3.3 preview selection', () => {
+ it('serves the published preview by default, in every runtime', () => {
+ expect(PREVIEW).toBe('3.3-beta.3');
+ expect(TRAINING_AGENT_HOSTED_PREVIEW.bundle).toBe('3.3.0-beta.3');
+ expect(TRAINING_AGENT_PREVIEW_ADCP_VERSION).toBe(PREVIEW);
+ for (const NODE_ENV of ['production', 'development', 'test', undefined]) {
+ expect(trainingAgentPreviewVersion({ NODE_ENV })).toBe(PREVIEW);
+ }
+ });
+
+ it('is disabled by the kill switch', () => {
+ expect(TRAINING_AGENT_PREVIEW_KILL_SWITCH).toBe('TRAINING_AGENT_DISABLE_ADCP_PREVIEW');
+ for (const value of ['1', 'true', 'TRUE', ' true ']) {
+ expect(trainingAgentPreviewVersion({ NODE_ENV: 'production', [TRAINING_AGENT_PREVIEW_KILL_SWITCH]: value })).toBeUndefined();
+ }
+ for (const value of ['0', 'false', '']) {
+ expect(trainingAgentPreviewVersion({ NODE_ENV: 'production', [TRAINING_AGENT_PREVIEW_KILL_SWITCH]: value })).toBe(PREVIEW);
+ }
+ });
+
+ it('yields to a trusted storyboard candidate', () => {
+ const candidate = { NODE_ENV: 'test', ADCP_STORYBOARD_CANDIDATE_VERSION_MODE: '1', ADCP_TRAINING_CANDIDATE_VERSION: '3.3-beta.4' };
+ expect(trainingAgentPreviewVersion(candidate)).toBe('3.3-beta.4');
+ // The kill switch governs only the hosted preview.
+ expect(trainingAgentPreviewVersion({ ...candidate, [TRAINING_AGENT_PREVIEW_KILL_SWITCH]: '1' })).toBe('3.3-beta.4');
+ // Candidate mode never applies outside the test runtime.
+ expect(trainingAgentPreviewVersion({ ...candidate, NODE_ENV: 'production' })).toBe(PREVIEW);
+ });
+
+ it('lists the preview once among the supported releases', () => {
+ expect(TRAINING_AGENT_SUPPORTED_RELEASE_VERSIONS.filter(version => version === PREVIEW)).toHaveLength(1);
+ expect(TRAINING_AGENT_SUPPORTED_RELEASE_VERSIONS.filter(version => version.startsWith('3.3'))).toEqual([PREVIEW]);
+ });
+
+ it('serves the preview only to an exact pin on the v5 resolver', () => {
+ expect(resolveServedAdcpVersion({ adcp_version: PREVIEW })).toEqual({ ok: true, servedVersion: PREVIEW });
+ // A major-only request is never upgraded onto a prerelease.
+ expect(resolveServedAdcpVersion({ adcp_major_version: 3 })).toEqual({ ok: true, servedVersion: '3.2' });
+ // A release pin never downshifts onto a prerelease.
+ for (const adcp_version of ['3.3', '3.4', '3.9']) {
+ expect(resolveServedAdcpVersion({ adcp_version })).toEqual({ ok: true, servedVersion: '3.2' });
+ }
+ // Other prereleases of the line are matched exactly, so they are refused.
+ for (const adcp_version of ['3.3-beta.1', '3.3-beta.4', '3.3-rc.1']) {
+ expect(resolveServedAdcpVersion({ adcp_version }).ok).toBe(false);
+ }
+ expect(resolveServedAdcpVersion({}).ok && resolveServedAdcpVersion({}).servedVersion).toBe('3.0');
+ });
+
+ it('sends only exact preview pins to the preview registry', () => {
+ // The stable registries never negotiate the preview.
+ expect(TRAINING_AGENT_STABLE_REGISTRY_VERSIONS).toEqual(
+ TRAINING_AGENT_SUPPORTED_RELEASE_VERSIONS.filter(version => version !== PREVIEW),
+ );
+ const call = (args: Record) => ({ method: 'tools/call', params: { name: 'get_products', arguments: args } });
+ expect(requestPinsPreview(call({ adcp_version: PREVIEW }))).toBe(true);
+ expect(requestPinsPreview({ method: 'tools/list', params: { _meta: { adcp_version: PREVIEW } } })).toBe(true);
+ expect(requestPinsPreview({ method: 'tools/list', params: { adcp_version: PREVIEW } })).toBe(true);
+ for (const args of [{}, { adcp_major_version: 3 }, { adcp_version: '3.2' }, { adcp_version: '3.3' }, { adcp_version: '3.3-beta.1' }, { adcp_version: '3.3.0-beta.3' }]) {
+ expect(requestPinsPreview(call(args)), JSON.stringify(args)).toBe(false);
+ }
+ expect(requestPinsPreview({ method: 'tools/list', params: {} })).toBe(false);
+ expect(requestPinsPreview({ method: 'initialize', params: { adcp_version: PREVIEW } })).toBe(false);
+ });
+});
+
+describe('hosted 3.3 preview negotiation over MCP', () => {
+ let server: http.Server;
+ let baseUrl: string;
+ let rpcId = 0;
+
+ const rpc = async (path: string, method: string, params?: Record) => {
+ rpcId += 1;
+ const response = await fetch(`${baseUrl}${path}`, {
+ method: 'POST',
+ headers: { 'content-type': 'application/json', accept: 'application/json, text/event-stream', authorization: `Bearer ${TOKEN}` },
+ body: JSON.stringify({ jsonrpc: '2.0', id: rpcId, method, ...(params && { params }) }),
+ });
+ return response.json() as Promise>;
+ };
+ const call = async (path: string, name: string, args: Record): Promise => {
+ const envelope = await rpc(path, 'tools/call', { name, arguments: args });
+ return (envelope.result?.structuredContent ?? { __envelope: envelope }) as Structured;
+ };
+
+ beforeAll(async () => {
+ const { createTrainingAgentRouter } = await import('../../src/training-agent/index.js');
+ const app = express();
+ app.use(express.json({ limit: '5mb', verify: (req, _res, body) => {
+ (req as unknown as { rawBody: string }).rawBody = body.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 () => {
+ stopSessionCleanup();
+ if (server) {
+ server.closeAllConnections();
+ await new Promise(resolve => server.close(() => resolve()));
+ }
+ });
+
+ const ROUTES = ['/mcp', '/sales/mcp', '/signals/mcp', '/governance/mcp', '/creative/mcp', '/creative-builder/mcp', '/brand/mcp', '/si/mcp'];
+
+ it.each(ROUTES)('advertises the preview and serves it only to an exact pin on %s', async route => {
+ const cases: Array<[Record, string]> = [
+ [{ adcp_version: PREVIEW }, PREVIEW],
+ // Unpinned callers keep each route's stable default.
+ [{}, route === '/mcp' ? '3.0' : '3.2'],
+ [{ adcp_major_version: 3 }, '3.2'],
+ [{ adcp_version: '3.2' }, '3.2'],
+ [{ adcp_version: '3.3' }, '3.2'],
+ [{ adcp_version: '3.4' }, '3.2'],
+ [{ adcp_version: '3.1' }, '3.1'],
+ [{ adcp_version: '3.0' }, '3.0'],
+ ];
+ for (const [args, expected] of cases) {
+ const result = await call(route, 'get_adcp_capabilities', args);
+ expect(result.adcp_error, `${route} ${JSON.stringify(args)}: ${JSON.stringify(result).slice(0, 300)}`).toBeUndefined();
+ expect(result.adcp_version, `${route} ${JSON.stringify(args)}`).toBe(expected);
+ // Capability discovery advertises the exact preview to every caller
+ // (versioning.mdx: the buyer reads supported_versions, then pins).
+ expect(result.adcp.supported_versions.filter((version: string) => version === PREVIEW)).toHaveLength(1);
+ expect(result.adcp.supported_versions).toContain('3.2');
+ expect(result.adcp.supported_versions).not.toContain('3.3-beta.1');
+ }
+ // A 3.3 prerelease the agent does not list never selects the preview,
+ // nor the SDK's own packaged 3.3 beta.
+ for (const adcp_version of ['3.3-beta.1', '3.3-beta.4']) {
+ const result = await call(route, 'get_adcp_capabilities', { adcp_version });
+ expect(result.adcp_version, `${route} ${adcp_version}: ${JSON.stringify(result).slice(0, 300)}`).not.toBe(PREVIEW);
+ expect(result.adcp_version).not.toBe(adcp_version);
+ }
+ }, 120_000);
+
+ it('reaches the experimental 3.3 sales surfaces at the preview pin only', async () => {
+ const preview = await call('/sales/mcp', 'get_adcp_capabilities', { adcp_version: PREVIEW });
+ expect(preview.experimental_features).toEqual(expect.arrayContaining(['account.requests', 'media_buy.reporting_subscriptions']));
+ expect(preview.account.requests).toBeDefined();
+ expect(preview.adcp.principal.supported_sections).toContain('reporting_subscriptions');
+ expect(preview.compliance_testing.scenarios).toContain('reporting_subscription_probe');
+ for (const args of [{}, { adcp_version: '3.2' }, { adcp_version: '3.3' }]) {
+ const stable = await call('/sales/mcp', 'get_adcp_capabilities', args);
+ expect(stable.experimental_features).not.toContain('account.requests');
+ expect(stable.experimental_features).not.toContain('media_buy.reporting_subscriptions');
+ expect(stable.account.requests).toBeUndefined();
+ expect(stable.adcp.principal.supported_sections).not.toContain('reporting_subscriptions');
+ expect(stable.compliance_testing.scenarios).not.toContain('reporting_subscription_probe');
+ }
+
+ // request_account is discovered and served at the preview only.
+ const pinnedList = await rpc('/sales/mcp', 'tools/list', { _meta: { adcp_version: PREVIEW } });
+ expect(pinnedList.result.tools.map((tool: { name: string }) => tool.name)).toContain('request_account');
+ for (const params of [{}, { _meta: { adcp_version: '3.2' } }, { _meta: { adcp_version: '3.3' } }]) {
+ const stableList = await rpc('/sales/mcp', 'tools/list', params);
+ expect(stableList.result.tools.map((tool: { name: string }) => tool.name)).not.toContain('request_account');
+ // Tools are stamped with the release the listing was served at.
+ expect(new Set(stableList.result.tools.map((tool: { _meta?: { adcp_version?: string } }) => tool._meta?.adcp_version).filter(Boolean))).toEqual(new Set(['3.2']));
+ }
+ const opened = await call('/sales/mcp', 'request_account', {
+ adcp_version: PREVIEW,
+ brand: { domain: 'preview-open.example' },
+ operator: 'preview-open.example',
+ idempotency_key: 'preview-version-request-account-1',
+ });
+ expect(opened.adcp_version).toBe(PREVIEW);
+ expect(opened.request?.resolution, JSON.stringify(opened).slice(0, 300)).toBe('created');
+ // Below the preview the tool does not exist, exactly as before the preview.
+ for (const adcp_version of ['3.2', '3.3']) {
+ const refused = await rpc('/sales/mcp', 'tools/call', {
+ name: 'request_account',
+ arguments: {
+ adcp_version,
+ brand: { domain: 'preview-open.example' },
+ operator: 'preview-open.example',
+ idempotency_key: `preview-version-request-account-${adcp_version}`,
+ },
+ });
+ expect(refused.result?.isError, JSON.stringify(refused).slice(0, 300)).toBe(true);
+ expect(refused.result?.content?.[0]?.text).toContain('Tool request_account not found');
+ }
+
+ // The account carries the caller's 3.3 authorization at the preview only.
+ const previewAccounts = await call('/sales/mcp', 'list_accounts', { adcp_version: PREVIEW });
+ expect(previewAccounts.adcp_version).toBe(PREVIEW);
+ expect(previewAccounts.accounts.length).toBeGreaterThan(0);
+ for (const account of previewAccounts.accounts) {
+ expect(typeof account.authorization?.authorized_at, JSON.stringify(account).slice(0, 300)).toBe('string');
+ }
+ const stableAccounts = await call('/sales/mcp', 'list_accounts', { adcp_version: '3.2' });
+ for (const account of stableAccounts.accounts) {
+ expect(account.authorization?.authorized_at).toBeUndefined();
+ expect(account.revision).toBeUndefined();
+ }
+
+ // The reporting-subscription sandbox clock answers at the preview only.
+ const scenarios = await call('/sales/mcp', 'comply_test_controller', { adcp_version: PREVIEW, scenario: 'list_scenarios' });
+ expect(scenarios.scenarios).toContain('reporting_subscription_probe');
+ const stableScenarios = await call('/sales/mcp', 'comply_test_controller', { adcp_version: '3.2', scenario: 'list_scenarios' });
+ expect(stableScenarios.scenarios).not.toContain('reporting_subscription_probe');
+ }, 120_000);
+
+ it('resolves public sandbox account references at the preview as it does at 3.2', async () => {
+ // AdCP 3.3 routes refuse account references the seller cannot resolve
+ // (@adcp/sdk fail-closed resolution). The training agent's resolver is
+ // reference-aware: a provisioned natural key resolves, an unprovisioned
+ // one on a discovery task is ACCOUNT_NOT_FOUND, at the preview and 3.2.
+ const account = { brand: { domain: 'preview-sandbox.example' }, operator: 'preview-sandbox.example', sandbox: true };
+ for (const adcp_version of [PREVIEW, '3.2']) {
+ const unprovisioned = await call('/sales/mcp', 'get_products', {
+ adcp_version,
+ account: { ...account, brand: { domain: `unprovisioned-${adcp_version}.example` } },
+ buying_mode: 'brief',
+ brief: 'sports',
+ });
+ expect(unprovisioned.adcp_error?.code, `${adcp_version}: ${JSON.stringify(unprovisioned).slice(0, 300)}`).toBe('ACCOUNT_NOT_FOUND');
+ }
+ const synced = await call('/sales/mcp', 'sync_accounts', {
+ adcp_version: PREVIEW,
+ accounts: [{ ...account, billing: 'operator', payment_terms: 'net_30' }],
+ idempotency_key: 'preview-version-sync-accounts-1',
+ });
+ expect(synced.accounts?.[0]?.status, JSON.stringify(synced).slice(0, 300)).toBe('active');
+ for (const adcp_version of [PREVIEW, '3.2']) {
+ const products = await call('/sales/mcp', 'get_products', { adcp_version, account, buying_mode: 'brief', brief: 'sports' });
+ expect(products.adcp_error, `${adcp_version}: ${JSON.stringify(products).slice(0, 300)}`).toBeUndefined();
+ expect(products.adcp_version).toBe(adcp_version);
+ expect(products.products.length).toBeGreaterThan(0);
+ const accountId = synced.accounts[0].account_id;
+ const buys = await call('/sales/mcp', 'get_media_buys', { adcp_version, account: { account_id: accountId } });
+ expect(buys.adcp_error, `${adcp_version}: ${JSON.stringify(buys).slice(0, 300)}`).toBeUndefined();
+ }
+ }, 120_000);
+});
diff --git a/server/tests/unit/training-agent-release-pin.test.ts b/server/tests/unit/training-agent-release-pin.test.ts
index 4e1ecfd8aa2..4f6e24468df 100644
--- a/server/tests/unit/training-agent-release-pin.test.ts
+++ b/server/tests/unit/training-agent-release-pin.test.ts
@@ -14,6 +14,7 @@ import {
TRAINING_AGENT_DEFAULT_ADCP_VERSION,
TRAINING_AGENT_SUPPORTED_RELEASE_VERSIONS,
} from '../../src/training-agent/types.js';
+import { TRAINING_AGENT_PREVIEW_ADCP_VERSION } from '../../src/training-agent/candidate-version.js';
describe('training agent 3.2 release-line pin', () => {
it('derives the release line from the current bundle', () => {
@@ -26,7 +27,12 @@ describe('training agent 3.2 release-line pin', () => {
it('advertises the release line and keeps the exact rc.7 pin, without duplicates', () => {
expect(TRAINING_AGENT_SUPPORTED_RELEASE_VERSIONS).toContain(TRAINING_AGENT_CURRENT_ADCP_VERSION);
expect(TRAINING_AGENT_SUPPORTED_RELEASE_VERSIONS).toContain('3.2-rc.7');
- expect(TRAINING_AGENT_SUPPORTED_RELEASE_VERSIONS.at(-1)).toBe(TRAINING_AGENT_CURRENT_ADCP_RELEASE);
+ // The release line is the newest release; only the opt-in 3.3 preview
+ // (#8181), served to an exact pin alone, is listed after it.
+ expect(TRAINING_AGENT_SUPPORTED_RELEASE_VERSIONS.at(TRAINING_AGENT_PREVIEW_ADCP_VERSION ? -2 : -1)).toBe(TRAINING_AGENT_CURRENT_ADCP_RELEASE);
+ if (TRAINING_AGENT_PREVIEW_ADCP_VERSION) {
+ expect(TRAINING_AGENT_SUPPORTED_RELEASE_VERSIONS.at(-1)).toBe(TRAINING_AGENT_PREVIEW_ADCP_VERSION);
+ }
expect(new Set(TRAINING_AGENT_SUPPORTED_RELEASE_VERSIONS).size).toBe(TRAINING_AGENT_SUPPORTED_RELEASE_VERSIONS.length);
});