Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/capabilities-compliance-testing-cross-check.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
'@adcp/sdk': patch
---

The `testCapabilityDiscovery` protocol/tool cross-check now keys `comply_test_controller` under `compliance_testing`, the protocol the capabilities parser reports for the `compliance_testing` block (#3279). It used `compliance`, so every agent that correctly declared the block failed with "Tools suggest unreported protocols: compliance (has: [comply_test_controller])". An agent that declares a `compliance_testing` block but does not expose `comply_test_controller` now fails the cross-check ("Protocol 'compliance_testing' reported but no matching tools found"), since the block declares the controller. The table's keys are now type-checked against `AdcpProtocol`.
5 changes: 5 additions & 0 deletions .changeset/capabilities-served-release-validation.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
'@adcp/sdk': patch
---

Capability discovery now validates `get_adcp_capabilities` against the release the seller served instead of the caller's pin (#3278). A 3.0 pin cannot carry `adcp_version`, so the SDK sends only `adcp_major_version: 3`. The seller then serves its highest 3.x release and echoes it in `adcp_version`, and the versioning spec says buyers validate against that echo. `discoverAgentProfile` (used by `testCapabilityDiscovery`, `comply()` and the storyboard runner) and `TaskExecutor` validated a 3.2 response strictly against 3.0. A conformant agent got false `capabilities_schema_issues` (for example `media_buy.features.bidding_policy must be boolean`, or the closed 3.0 `compliance_testing.scenarios` enum), and `getAdcpCapabilities()` failed in strict mode. Both now use the echoed release when it is in the pin's major and the SDK bundles its schema. They fall back to the pin when the echo is missing, from another major, or not bundled. Validation stays strict, and an external `schemaRoot` bound to the pin still takes precedence.
12 changes: 11 additions & 1 deletion src/lib/core/TaskExecutor.ts
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,7 @@ import {
type ValidationMode,
} from '../validation/client-hooks';
import { formatIssues } from '../validation/schema-validator';
import { resolveServedValidationVersion } from '../validation/schema-loader';
import { ADCP_VERSION } from '../version';
import { unwrapProtocolResponse, isAdcpOperationSuccess } from '../utils/response-unwrapper';
import { extractAdcpErrorInfo, extractCorrelationId } from '../utils/error-extraction';
Expand Down Expand Up @@ -6124,10 +6125,19 @@ export class TaskExecutor {
// Normal dispatch uses lastKnownServerVersion; restart recovery passes
// the persisted continuation version explicitly so concurrent or fresh
// executors cannot validate the seller's response against another wire.
const validationVersion =
let validationVersion =
(serverVersion ?? this.lastKnownServerVersion) === 'v2'
? 'v2.5'
: (this.responseAdcpVersionForValidation() ?? this.config.adcpVersion ?? ADCP_VERSION);
// Capabilities are negotiated before any pin applies: a 3.0 pin (or a
// major-only envelope) is served the seller's highest release in the
// major, echoed in `adcp_version`. Validate against that release, as the
// versioning spec requires ("Server echoes"), falling back to the pin
// when there is no usable echo. Only the validator's version changes;
// the unwrapper keeps `effectiveResponseAdcpVersion()`.
if (taskName === 'get_adcp_capabilities' && validationVersion !== 'v2.5') {
validationVersion = resolveServedValidationVersion(response, validationVersion);
}
const normalizedResponse = this.normalizeResponseForValidation(response, taskName, validationVersion === 'v2.5');
// TaskExecutor owns the user-facing log entry below. Passing debugLogs
// into the lower-level hook would emit a second, unversioned duplicate.
Expand Down
7 changes: 6 additions & 1 deletion src/lib/testing/client.ts
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,7 @@ import type { AgentRequestSigningConfig } from '../types/adcp';
import { createHmac, hkdfSync, randomBytes } from 'node:crypto';
import { AsyncLocalStorage } from 'node:async_hooks';
import { validateIncomingResponse } from '../validation/client-hooks';
import { resolveServedValidationVersion } from '../validation/schema-loader';
import { extractVersionUnsupportedDetails } from '../utils/error-extraction';
import { buildAgentSigningContext } from '../signing/client';
import type { VerifierCapability } from '../signing/types';
Expand Down Expand Up @@ -844,12 +845,16 @@ export async function discoverAgentProfile(
step.error = versionUnsupported;
} else if (caps?.data) {
profile.raw_capabilities = caps.data;
// Validate against the release the seller served (its echoed
// `adcp_version`), not the pin. A 3.0 pin negotiates major-only, so
// the seller serves its highest 3.x release (versioning spec,
// "Server echoes"). Falls back to the pin when there is no usable echo.
const validation = validateIncomingResponse(
'get_adcp_capabilities',
caps.data,
'strict',
undefined,
schemaAdcpVersion ?? client.getAdcpVersion()
resolveServedValidationVersion(caps.data, schemaAdcpVersion ?? client.getAdcpVersion())
);
if (!validation.valid) {
profile.capabilities_schema_issues = validation.issues.map(issue => ({
Expand Down
9 changes: 6 additions & 3 deletions src/lib/testing/scenarios/capabilities.ts
Original file line number Diff line number Diff line change
Expand Up @@ -311,15 +311,18 @@ function crossValidateProtocolsAndTools(capabilities: AdcpCapabilities, tools: s
const issues: string[] = [];
const warnings: string[] = [];

const protocolToolMap: Record<string, readonly string[]> = {
// Keys must be `AdcpProtocol` values as reported by `parseCapabilitiesResponse`
// (`satisfies` rejects any other key at compile time). `compliance_testing`
// is promoted from the top-level capability block, not `supported_protocols`.
const protocolToolMap: Readonly<Record<string, readonly string[]>> = {
media_buy: MEDIA_BUY_TOOLS,
signals: SIGNALS_TOOLS,
governance: GOVERNANCE_TOOLS,
creative: CREATIVE_TOOLS,
sponsored_intelligence: SPONSORED_INTELLIGENCE_TOOLS,
trusted_match: TRUSTED_MATCH_TOOLS,
compliance: COMPLIANCE_TOOLS,
};
compliance_testing: COMPLIANCE_TOOLS,
} satisfies Partial<Record<AdcpProtocol, readonly string[]>>;

// Check each reported protocol has at least one corresponding tool
const perProtocolDiffs: Record<string, { expected: string[]; found: string[]; missing: string[] }> = {};
Expand Down
66 changes: 66 additions & 0 deletions src/lib/validation/schema-loader.ts
Original file line number Diff line number Diff line change
Expand Up @@ -1280,6 +1280,72 @@ export function hasSchemaBundle(version: string): boolean {
}
}

/** Major of an echoed release-precision `adcp_version` (`core/version-envelope.json` wire pattern). */
const SERVED_RELEASE_MAJOR = /^(\d+)\.\d+(?:-[a-zA-Z0-9.-]+)?$/;
/** Major of a numeric pin: `'3.0'`, `'3.0.25'`, `'3.1-beta'`, `'3.1.0-beta.1'`. */
const NUMERIC_PIN_MAJOR = /^(\d+)\.\d+/;

/**
* Select the AdCP release a seller response is validated against.
*
* The versioning spec (`docs/reference/versioning.mdx`, "Server echoes") says
* the seller echoes the release it actually served in `adcp_version`, and
* buyers SHOULD validate against that release's schema, not their pin; with
* no echo, against the pin. This matters most for `get_adcp_capabilities`
* under a 3.0 pin: the 3.0 bundle has no `adcp_version` request field, so the
* SDK sends only `adcp_major_version: 3` and the seller serves (and echoes)
* its highest 3.x release.
*
* Returns the version to validate `response` against: the echoed
* `adcp_version` when it is a usable release, otherwise `pinnedVersion`.
*
* The echo is used only when it is a release-precision string in the same
* major as the pin and the SDK has a schema bundle for it. Validation stays
* strict either way: an echo from another major, a malformed echo, or one the
* SDK cannot validate falls back to the pin rather than skipping validation.
* When the echo names the pinned release itself, the exact pin is returned so
* a patch-precise pin (and any external schema root bound to it) still
* applies. `supported_versions` is deliberately not consulted: with no echo
* the spec says to validate against the pin.
*
* Two deliberate consequences:
* - An external schema root the caller bound to the pin (`schemaRoot`,
* `withExternalSchemaRoot`) wins over the echo, matching the storyboard
* runner's `response_schema` precedence: the caller chose that protocol
* source explicitly.
* - An echo older than the pin (pin 3.2, served 3.0) is validated against the
* older release. That is the spec's downshift rule, not a loosening bug.
*
* @internal — not part of the public API surface; may change without a major bump.
*/
export function resolveServedValidationVersion(response: unknown, pinnedVersion: string): string {
const pinMajor = NUMERIC_PIN_MAJOR.exec(pinnedVersion)?.[1];
// Legacy aliases ('v2.5', 'v3') have their own adapter paths; leave them alone.
if (pinMajor === undefined) return pinnedVersion;
try {
if (isExternalSchemaRootActive(pinnedVersion)) return pinnedVersion;
} catch {
return pinnedVersion;
}

const echoed =
response !== null && typeof response === 'object'
? (response as { adcp_version?: unknown }).adcp_version
: undefined;
if (typeof echoed !== 'string') return pinnedVersion;
const echoMajor = SERVED_RELEASE_MAJOR.exec(echoed)?.[1];
if (echoMajor === undefined || echoMajor !== pinMajor) return pinnedVersion;

let pinnedRelease: string;
try {
pinnedRelease = toReleasePrecisionWire(pinnedVersion);
} catch {
return pinnedVersion;
}
if (echoed === pinnedRelease) return pinnedVersion;
return hasSchemaBundle(echoed) ? echoed : pinnedVersion;
}

const mcpToolSchemaCache = new Map<string, Readonly<Record<string, unknown>> | null>();
const mcpToolSummaryCache = new Map<string, string | null>();

Expand Down
Loading
Loading