@adcp/sdk 6.5.0 → 6.7.0

package/dist/lib/upstream-recorder/types.d.ts

@@ -0,0 +1,365 @@
+/**
+ * Public types for `@adcp/sdk/upstream-recorder`.
+ *
+ * Producer-side companion to the runner-output-contract v2.0.0
+ * `upstream_traffic` storyboard check (spec PR adcontextprotocol/adcp#3816).
+ * The recorder captures outbound HTTP calls an adapter makes during a
+ * sandbox session and surfaces them to the adopter's
+ * `comply_test_controller` `query_upstream_traffic` handler so storyboard
+ * runners can verify side-effects against the adopter's real upstream
+ * platform (the load-bearing anti-façade contract).
+ *
+ * Adopter-facing API. The recorder itself is sandbox-only — `enabled: false`
+ * short-circuits every wrapping adapter to a pass-through.
+ */
+/**
+ * Single recorded outbound HTTP call. Mirrors
+ * `comply-test-controller-response.json > UpstreamTrafficSuccess.recorded_calls[]`
+ * so adopter handlers can return query results verbatim.
+ *
+ * Redaction is applied at recording time, not query time, so the in-memory
+ * buffer never holds plaintext secrets even briefly.
+ */
+export interface RecordedCall {
+    method: string;
+    /** Composed `<METHOD> <URL>` for `endpoint_pattern` matching. */
+    endpoint: string;
+    url: string;
+    host: string;
+    path: string;
+    /**
+     * Media type of the recorded `payload`, mirroring the adapter's outbound
+     * `Content-Type` header. Required by the contract — runners use this to
+     * pick the right matcher (JSONPath for JSON-shaped, substring fallback
+     * for other types).
+     */
+    content_type: string;
+    /** Decoded JSON object when content_type is JSON-shaped; raw string otherwise. */
+    payload: unknown;
+    timestamp: string;
+    status_code?: number;
+    /**
+     * Optional classifier — set when the `purpose` callback was supplied.
+     * Mirrors adcp#3830 item 3 (purpose tagging) so storyboards can scope
+     * `endpoint_pattern` matching to platform-primary calls vs. measurement
+     * vendors when the spec adopts that field.
+     */
+    purpose?: string;
+}
+/**
+ * Optional classifier callback. Invoked at recording time on each call so
+ * the recorder can stamp a `purpose` tag without the adopter wiring it
+ * through their HTTP layer manually. Returning `undefined` leaves the
+ * `purpose` field unset on the resulting `RecordedCall`.
+ */
+export type PurposeClassifier = (input: {
+    method: string;
+    url: string;
+    host: string;
+    path: string;
+    /** Outbound headers (lowercased keys), with secrets already redacted. */
+    headers: Record<string, string>;
+}) => string | undefined;
+/**
+ * Configuration for `createUpstreamRecorder`. Every field is optional;
+ * the defaults match the spec's recommended conformance posture.
+ */
+export interface UpstreamRecorderOptions {
+    /**
+     * Master switch. Defaults to `true`. Adopters MUST gate this against
+     * their sandbox / non-production environment (e.g.
+     * `enabled: process.env.NODE_ENV !== 'production'`). When `false`, the
+     * factory returns a no-op recorder — `wrapFetch` returns the input fetch
+     * unchanged, `record` is a no-op, `query` always returns empty results.
+     * Zero overhead in production.
+     */
+    enabled?: boolean;
+    /**
+     * Override the canonical secret-key redaction pattern. Adopters MAY
+     * extend the contract floor with internal vendor-specific keys. Adopters
+     * MUST NOT narrow it — passing a pattern that omits a contract-required
+     * key is a security regression.
+     */
+    redactPattern?: RegExp;
+    /**
+     * Maximum recorded calls retained in the buffer (across all principals).
+     * Defaults to 1000. When the buffer is full, the oldest entry is evicted
+     * before recording the new call. Storyboards generally exercise tens of
+     * calls per assertion window — 1000 is a safe upper bound for a single
+     * sandbox session.
+     */
+    bufferSize?: number;
+    /**
+     * Time-to-live for recorded calls, in milliseconds. Defaults to 1 hour.
+     * Calls older than `ttlMs` at query time are excluded from results AND
+     * pruned eagerly on the next record. Bounds the buffer's exposure
+     * window — a stale recorder shouldn't surface yesterday's traffic on
+     * today's compliance run.
+     */
+    ttlMs?: number;
+    /**
+     * Optional classifier — see `PurposeClassifier`. Invoked on every record
+     * with the redacted-headers view of the outbound call.
+     */
+    purpose?: PurposeClassifier;
+    /**
+     * When `true`, calling `record()` or invoking the wrapped fetch outside a
+     * `runWithPrincipal(p, fn)` scope throws an `UpstreamRecorderScopeError`
+     * instead of silently dropping the call. Default `false` — silent drop
+     * matches the recorder's "don't break the adapter" posture in production.
+     * Adopters writing or debugging integration tests SHOULD enable this so
+     * forgotten scope wrappers surface as a stack trace pointing at the
+     * unwrapped call site, not as mysterious "controller present, observed
+     * nothing" storyboard failures.
+     */
+    strict?: boolean;
+    /**
+     * Maximum bytes retained in `RecordedCall.payload` per entry. Adopter
+     * payloads exceeding this limit are replaced with the marker string
+     * `'[truncated <n> bytes]'` so the buffer ceiling stays bounded even
+     * when an adopter records bulk uploads. Default 65 536 (64 KiB —
+     * mirrors the spec's `recorded_calls[].payload` `maxLength`).
+     * Set to 0 to disable truncation.
+     */
+    maxPayloadBytes?: number;
+    /**
+     * Optional observability hook. Invoked when the recorder swallows an
+     * error that would otherwise be invisible (purpose classifier throw,
+     * URL parse failure, payload-build throw on a hostile getter, record
+     * outside scope when `strict: false`). Adopters wire this to their
+     * logger so silent failures surface in dev sessions. Throwing inside
+     * `onError` is itself swallowed — the hook MUST NOT crash the recorder.
+     */
+    onError?: (event: UpstreamRecorderErrorEvent) => void;
+}
+/**
+ * Surfaced through `UpstreamRecorderOptions.onError` for adopter
+ * observability. Each kind names a specific swallow site in the recorder.
+ */
+export type UpstreamRecorderErrorEvent = {
+    kind: 'classifier_threw';
+    err: unknown;
+} | {
+    kind: 'url_parse_failed';
+    url: string;
+} | {
+    kind: 'payload_build_failed';
+    err: unknown;
+} | {
+    kind: 'unscoped_record';
+    method: string;
+    url: string;
+};
+/**
+ * Thrown by `record()` and the wrapped fetch when invoked outside a
+ * `runWithPrincipal` scope and `strict: true` is set. Subclasses `Error`
+ * so adopter test runners surface the stack trace.
+ */
+export declare class UpstreamRecorderScopeError extends Error {
+    constructor(message: string);
+}
+/**
+ * Parameters accepted by `recorder.query`. Mirrors the
+ * `query_upstream_traffic` controller scenario shape so the adopter can
+ * pass-through their controller request directly.
+ */
+export interface UpstreamRecorderQueryParams {
+    /**
+     * Caller principal — REQUIRED. Cross-principal isolation is the spec's
+     * security HIGH requirement: a controller call from principal A MUST NOT
+     * surface principal B's traffic. Adopters resolve this from their auth
+     * context (e.g., the `account` block on the controller request, or the
+     * adopter's session principal).
+     */
+    principal: string;
+    /**
+     * ISO 8601 timestamp lower bound. Only calls recorded at or after this
+     * time are returned. The runner subtracts a 250 ms clock-skew tolerance
+     * before sending the bound — adopter MAY also widen the window if it
+     * knows its own clock drifts.
+     */
+    sinceTimestamp?: string;
+    /**
+     * Glob pattern matched against `<METHOD> <URL>` (i.e. `endpoint`). `*`
+     * matches zero-or-more characters of any kind including `/`; all other
+     * characters are literal. Adopter-side filter — equivalent to filtering
+     * on the runner side after the response, but reduces response size.
+     */
+    endpointPattern?: string;
+    /**
+     * Maximum recorded calls to return. Defaults to 100, capped at the
+     * buffer size. When the un-capped result would have exceeded `limit`,
+     * `truncated: true` is set on the response so the runner can detect
+     * overflow.
+     */
+    limit?: number;
+}
+/**
+ * Result of `recorder.query`. Adopter-side ergonomic shape (camelCase
+ * field names, `items` not `recorded_calls`). Use
+ * `toQueryUpstreamTrafficResponse(result)` to project this onto the
+ * spec's `UpstreamTrafficSuccess` controller-response wire shape rather
+ * than reinventing the field renames in every adopter's handler.
+ */
+export interface UpstreamRecorderQueryResult {
+    /** Calls matching all filters, ordered by `timestamp` ascending. */
+    items: RecordedCall[];
+    /**
+     * Total count BEFORE `limit` truncation. `items.length` may be smaller
+     * when limit clipped the result.
+     */
+    total: number;
+    /** True when `total > items.length`. */
+    truncated: boolean;
+    /**
+     * Echo of the requested `sinceTimestamp` (or the recorder-substituted
+     * default — the earliest record retained in the buffer when no
+     * `sinceTimestamp` was passed). Lets the runner verify the controller
+     * honored the bound.
+     */
+    since_timestamp: string;
+}
+/**
+ * Wire shape returned by the `comply_test_controller`'s
+ * `query_upstream_traffic` scenario, mirroring `UpstreamTrafficSuccess`
+ * in `comply-test-controller-response.json` (spec PR
+ * adcontextprotocol/adcp#3816). Adopter handlers can `return
+ * toQueryUpstreamTrafficResponse(recorder.query(...))` directly.
+ */
+export interface QueryUpstreamTrafficResponse {
+    success: true;
+    recorded_calls: RecordedCall[];
+    total_count: number;
+    truncated: boolean;
+    since_timestamp: string;
+}
+/**
+ * Public recorder surface. Adopters get one of these from
+ * `createUpstreamRecorder(options)`.
+ */
+export interface UpstreamRecorder {
+    /**
+     * Run `fn` with `principal` bound as the active recording principal.
+     * Every wrapped HTTP call inside `fn` (including async tasks awaited
+     * inside) records under that principal. Implemented via
+     * AsyncLocalStorage — context propagates across `await` boundaries the
+     * same way Node's stack trace does, so most adopters won't need to
+     * thread the principal through their HTTP call sites manually.
+     *
+     * Re-entrant — nested `runWithPrincipal` calls override the parent's
+     * principal for their inner scope only.
+     */
+    /**
+     * The same string MUST be passed at record-time and query-time — record
+     * happens inside `runWithPrincipal(p, fn)`, query is invoked from the
+     * adopter's `comply_test_controller` handler with the principal it
+     * receives in its auth context. The two ends MUST agree:
+     *
+     *   - **OAuth client_credentials sellers**: pass the resolved `client_id`.
+     *   - **Session-token sellers**: pass the `account.id` (or whatever
+     *     stable per-adopter-account identifier the auth layer materializes).
+     *   - **Anonymous / public-sandbox sellers**: pass a stable per-session
+     *     identifier; literal-anonymous strings collide across tenants and
+     *     defeat isolation.
+     *
+     * Mismatch between record-time and query-time principal returns zero
+     * results. That's the spec's security floor (cross-principal leakage
+     * MUST NOT happen), not a bug — but it means a typo shows up as
+     * "controller present, observed nothing" in storyboard output.
+     */
+    runWithPrincipal<T>(principal: string, fn: () => T | Promise<T>): Promise<T>;
+    /**
+     * Wrap a fetch implementation so calls inside `runWithPrincipal` flow
+     * through this recorder. Returns a fetch with the same signature; the
+     * wrapper is a pass-through when the recorder is `enabled: false` or
+     * when no principal is active. Drop the wrapped fetch into your HTTP
+     * layer (e.g. `globalThis.fetch = recorder.wrapFetch(globalThis.fetch)`)
+     * or pass it explicitly to your HTTP client constructor.
+     */
+    wrapFetch(fetch: typeof globalThis.fetch): typeof globalThis.fetch;
+    /**
+     * Manually record a call. Escape hatch for adopters with custom
+     * transports the recorder doesn't ship a wrapper for. The principal
+     * is read from the active `runWithPrincipal` scope unless explicitly
+     * passed. Redaction + timestamp + purpose tagging still apply.
+     */
+    record(call: RecordInput, principal?: string): void;
+    /**
+     * Return recorded calls scoped to the requesting principal, filtered by
+     * `sinceTimestamp` and `endpointPattern`, and truncated to `limit`.
+     * Adopters typically pass the result verbatim into their
+     * `comply_test_controller`'s `query_upstream_traffic` response.
+     */
+    query(params: UpstreamRecorderQueryParams): UpstreamRecorderQueryResult;
+    /**
+     * Drop every recorded call. Test cleanup helper — production code
+     * should rely on TTL eviction instead.
+     */
+    clear(): void;
+    /** Reflect the configured `enabled` flag — useful for adopter assertions. */
+    readonly enabled: boolean;
+    /**
+     * Introspection helper for adopters debugging "my storyboard says zero
+     * calls but I see them in the logs". Returns the recorder's current
+     * state — buffer size, total entries, distinct principals, the
+     * timestamp of the most recent record, and the active principal in the
+     * caller's scope (when invoked from inside `runWithPrincipal`).
+     * Diagnostic only; not a public conformance surface.
+     */
+    debug(): UpstreamRecorderDebugInfo;
+}
+/**
+ * Snapshot returned by `recorder.debug()`. The shape is informational —
+ * adopters are expected to log it, not match against it.
+ */
+export interface UpstreamRecorderDebugInfo {
+    enabled: boolean;
+    bufferSize: number;
+    bufferedEntries: number;
+    /** Distinct principals with at least one buffered entry. */
+    principals: string[];
+    /** ISO timestamp of the most recent record, or `null` if buffer is empty. */
+    lastRecordedAt: string | null;
+    /**
+     * The principal active in the caller's `runWithPrincipal` scope at the
+     * moment `debug()` was invoked. `null` when called outside any scope.
+     */
+    activePrincipal: string | null;
+    /** Echo of the configured `strict` flag. */
+    strict: boolean;
+}
+/**
+ * Input shape for `recorder.record` / the wrapped fetch's internal call.
+ * The recorder fills in `timestamp` and (optionally) `purpose` itself; the
+ * caller supplies the wire-shape facts.
+ */
+export interface RecordInput {
+    method: string;
+    url: string;
+    /**
+     * Outbound `Content-Type` header value, mirrored verbatim onto
+     * `RecordedCall.content_type`. Required because the runner's matcher
+     * choice depends on it.
+     */
+    content_type: string;
+    /**
+     * Outbound headers — used by the redactor and the purpose classifier.
+     * Keys are normalized to lowercase before redaction; values pass
+     * through if not on a secret-shaped key.
+     */
+    headers?: Record<string, string>;
+    /**
+     * Outbound request body. Object when JSON-decodable (recorder will
+     * apply per-key redaction); string for non-JSON (recorder applies
+     * length-cap only). Pass `undefined` for GET / HEAD / DELETE without
+     * a body.
+     */
+    payload?: unknown;
+    /**
+     * HTTP status code of the upstream response, when known. Adapters
+     * MAY omit this for fire-and-forget calls instrumented before the
+     * response arrives.
+     */
+    status_code?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/lib/upstream-recorder/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/lib/upstream-recorder/types.ts"],"names":[],"mappings":"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"}

package/dist/lib/upstream-recorder/types.js

@@ -0,0 +1,30 @@
+"use strict";
+/**
+ * Public types for `@adcp/sdk/upstream-recorder`.
+ *
+ * Producer-side companion to the runner-output-contract v2.0.0
+ * `upstream_traffic` storyboard check (spec PR adcontextprotocol/adcp#3816).
+ * The recorder captures outbound HTTP calls an adapter makes during a
+ * sandbox session and surfaces them to the adopter's
+ * `comply_test_controller` `query_upstream_traffic` handler so storyboard
+ * runners can verify side-effects against the adopter's real upstream
+ * platform (the load-bearing anti-façade contract).
+ *
+ * Adopter-facing API. The recorder itself is sandbox-only — `enabled: false`
+ * short-circuits every wrapping adapter to a pass-through.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UpstreamRecorderScopeError = void 0;
+/**
+ * Thrown by `record()` and the wrapped fetch when invoked outside a
+ * `runWithPrincipal` scope and `strict: true` is set. Subclasses `Error`
+ * so adopter test runners surface the stack trace.
+ */
+class UpstreamRecorderScopeError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'UpstreamRecorderScopeError';
+    }
+}
+exports.UpstreamRecorderScopeError = UpstreamRecorderScopeError;
+//# sourceMappingURL=types.js.map

package/dist/lib/upstream-recorder/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/lib/upstream-recorder/types.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;GAaG;;;AAuIH;;;;GAIG;AACH,MAAa,0BAA2B,SAAQ,KAAK;IACnD,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,4BAA4B,CAAC;IAC3C,CAAC;CACF;AALD,gEAKC"}

package/dist/lib/utils/capabilities.d.ts

@@ -166,8 +166,24 @@ export interface ToolInfo {
  * These map to task names in the AdCP schema index (kebab-case -> snake_case).
  *
  * Note: Some tools appear in multiple arrays (e.g., list_creative_formats is in
- * both MEDIA_BUY_TOOLS and CREATIVE_TOOLS). This is intentional - these tools
- * serve multiple domains, and their presence should activate all relevant protocols.
+ * both MEDIA_BUY_TOOLS and CREATIVE_TOOLS). This is intentional — these tools
+ * serve multiple domains, and their presence should activate all relevant
+ * protocols when `detectProtocols()` runs.
+ *
+ * **Why these aren't manifest-derived (#1192).** The AdCP manifest
+ * (`schemas/cache/{version}/manifest.json`) carries a single primary `protocol`
+ * per tool — `list_creative_formats` is `media-buy` there, never `creative`.
+ * That's an authoring convenience (where does the tool's spec page live), not
+ * a capability-declaration semantic. The cross-listing here captures
+ * operator reality: a CMP that exposes only `build_creative` /
+ * `list_creative_formats` / `sync_creatives` IS a creative agent, and a buyer
+ * discovering it via `tools/list` should see the `creative` protocol family.
+ * Migrating to manifest-primary would silently flip `detectProtocols()`
+ * results for cross-listed tools and break CMP↔DSP discovery flows. The
+ * drift guard at `test/lib/capabilities-tools-drift.test.js` keeps the arrays
+ * locked to recognized manifest tools (catches typos and removed-upstream
+ * tools) without forcing the arrays to match the manifest's single-valued
+ * view. See PR #1298 for the design rationale.
  */
 export declare const MEDIA_BUY_TOOLS: readonly ["get_products", "list_creative_formats", "create_media_buy", "update_media_buy", "sync_creatives", "list_creatives", "get_media_buy_delivery", "provide_performance_feedback", "sync_audiences"];
 export declare const SIGNALS_TOOLS: readonly ["get_signals", "activate_signal"];
@@ -176,7 +192,7 @@ export declare const CREATIVE_TOOLS: readonly ["build_creative", "list_creative_
 export declare const SPONSORED_INTELLIGENCE_TOOLS: readonly ["si_get_offering", "si_initiate_session", "si_send_message", "si_terminate_session"];
 export declare const TRUSTED_MATCH_TOOLS: readonly ["context_match", "identity_match"];
 export declare const COMPLIANCE_TOOLS: readonly ["comply_test_controller"];
-export declare const BRAND_RIGHTS_TOOLS: readonly ["get_brand_identity", "get_rights", "acquire_rights"];
+export declare const BRAND_RIGHTS_TOOLS: readonly ["get_brand_identity", "get_rights", "acquire_rights", "update_rights"];
 export declare const EVENT_TRACKING_TOOLS: readonly ["sync_event_sources", "log_event"];
 export declare const ACCOUNT_TOOLS: readonly ["list_accounts", "sync_accounts"];
 export declare const PROTOCOL_TOOLS: readonly ["get_adcp_capabilities"];
@@ -197,6 +213,53 @@ export declare const PROTOCOL_TOOLS: readonly ["get_adcp_capabilities"];
  */
 export declare function augmentCapabilitiesFromTools(capabilities: AdcpCapabilities, tools: ToolInfo[]): AdcpCapabilities;
 export declare function buildSyntheticCapabilities(tools: ToolInfo[]): AdcpCapabilities;
+/**
+ * Build synthetic v3 capabilities when the agent advertises
+ * `get_adcp_capabilities` (a v3-only tool) but the call itself failed —
+ * either the executor threw, or the response was non-success with no
+ * structurally v3-shaped data (the case `looksLikeV3Capabilities` would
+ * have caught).
+ *
+ * The agent is verifiably v3 because the v3-only discovery tool is
+ * present in `tools/list`. Falling back to v2 synthetic in this case
+ * triggers v2.5-schema lookups that have nothing to do with the original
+ * failure, cascading "AdCP schema data for version v2.5 not found"
+ * across every subsequent step. Treating as v3 (synthetic) lets the
+ * caller continue against the right adapter set; the underlying
+ * `get_adcp_capabilities` failure still surfaces in logs at the
+ * call site.
+ *
+ * Sets `_synthetic: true` so version-compat checks know detail-level
+ * fields (idempotency TTL, supportedVersions) are unknown — callers
+ * skip those checks rather than throw `VersionUnsupportedError` on a
+ * verifiably-v3 agent.
+ *
+ * Refs: #1217 (carve-out from #1197/closed), #1189 / #1201 (the v3-shape
+ * heuristic this complements).
+ */
+export declare function buildSyntheticV3Capabilities(tools: ToolInfo[]): AdcpCapabilities;
+/**
+ * Heuristic: does this `get_adcp_capabilities` response look v3-shaped?
+ *
+ * Used by callers (e.g. SingleAgentClient.getCapabilities) when the response
+ * fails strict schema validation but is structurally non-empty. The question
+ * the heuristic answers is "is this a v3 agent with a wire-shape bug, or a
+ * v2 agent that happens to advertise the tool?". Falling back to v2 in the
+ * former case masks the original bug behind cascading v2.5-schema-not-found
+ * errors; treating it as v3 surfaces the wire-shape bug at its source.
+ *
+ * Affirmative v3 signals (any one is enough):
+ *   - `adcp` block (only v3 servers carry the `{ major_versions, idempotency, ... }` envelope)
+ *   - `supported_protocols` array (v3-only top-level field)
+ *   - any v3 protocol-level capability block (`media_buy`, `signals`, `creative`, `brand`,
+ *     `governance`, `sponsored_intelligence`, `compliance_testing`, `account`)
+ *
+ * v2 servers don't expose `get_adcp_capabilities` at all (the tool itself is
+ * a v3-only addition), so reaching this function with a non-empty payload
+ * already strongly implies v3 — but we belt-and-suspenders the structural
+ * check to avoid mis-promoting genuinely empty / null responses.
+ */
+export declare function looksLikeV3Capabilities(data: unknown): boolean;
 /**
  * Parse a get_adcp_capabilities response into normalized form
  */

package/dist/lib/utils/capabilities.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../../../src/lib/utils/capabilities.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../../../src/lib/utils/capabilities.ts"],"names":[],"mappings":"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"}

package/dist/lib/utils/capabilities.js

@@ -10,6 +10,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.TASK_FEATURE_MAP = exports.PROTOCOL_TOOLS = exports.ACCOUNT_TOOLS = exports.EVENT_TRACKING_TOOLS = exports.BRAND_RIGHTS_TOOLS = exports.COMPLIANCE_TOOLS = exports.TRUSTED_MATCH_TOOLS = exports.SPONSORED_INTELLIGENCE_TOOLS = exports.CREATIVE_TOOLS = exports.GOVERNANCE_TOOLS = exports.SIGNALS_TOOLS = exports.MEDIA_BUY_TOOLS = void 0;
 exports.augmentCapabilitiesFromTools = augmentCapabilitiesFromTools;
 exports.buildSyntheticCapabilities = buildSyntheticCapabilities;
+exports.buildSyntheticV3Capabilities = buildSyntheticV3Capabilities;
+exports.looksLikeV3Capabilities = looksLikeV3Capabilities;
 exports.parseCapabilitiesResponse = parseCapabilitiesResponse;
 exports.supportsV3 = supportsV3;
 exports.supportsProtocol = supportsProtocol;
@@ -38,8 +40,24 @@ function getRawNested(obj, ...keys) {
  * These map to task names in the AdCP schema index (kebab-case -> snake_case).
  *
  * Note: Some tools appear in multiple arrays (e.g., list_creative_formats is in
- * both MEDIA_BUY_TOOLS and CREATIVE_TOOLS). This is intentional - these tools
- * serve multiple domains, and their presence should activate all relevant protocols.
+ * both MEDIA_BUY_TOOLS and CREATIVE_TOOLS). This is intentional — these tools
+ * serve multiple domains, and their presence should activate all relevant
+ * protocols when `detectProtocols()` runs.
+ *
+ * **Why these aren't manifest-derived (#1192).** The AdCP manifest
+ * (`schemas/cache/{version}/manifest.json`) carries a single primary `protocol`
+ * per tool — `list_creative_formats` is `media-buy` there, never `creative`.
+ * That's an authoring convenience (where does the tool's spec page live), not
+ * a capability-declaration semantic. The cross-listing here captures
+ * operator reality: a CMP that exposes only `build_creative` /
+ * `list_creative_formats` / `sync_creatives` IS a creative agent, and a buyer
+ * discovering it via `tools/list` should see the `creative` protocol family.
+ * Migrating to manifest-primary would silently flip `detectProtocols()`
+ * results for cross-listed tools and break CMP↔DSP discovery flows. The
+ * drift guard at `test/lib/capabilities-tools-drift.test.js` keeps the arrays
+ * locked to recognized manifest tools (catches typos and removed-upstream
+ * tools) without forcing the arrays to match the manifest's single-valued
+ * view. See PR #1298 for the design rationale.
  */
 exports.MEDIA_BUY_TOOLS = [
     'get_products',
@@ -97,7 +115,11 @@ exports.SPONSORED_INTELLIGENCE_TOOLS = [
 ];
 exports.TRUSTED_MATCH_TOOLS = ['context_match', 'identity_match'];
 exports.COMPLIANCE_TOOLS = ['comply_test_controller'];
-exports.BRAND_RIGHTS_TOOLS = ['get_brand_identity', 'get_rights', 'acquire_rights'];
+// `creative_approval` is intentionally absent — it's webhook-only (the buyer
+// POSTs to the `approval_webhook` URL returned by `acquire_rights`), not an
+// MCP/A2A tool the seller exposes. Adopters wire it via their HTTP server
+// using `BrandRightsPlatform.reviewCreativeApproval`.
+exports.BRAND_RIGHTS_TOOLS = ['get_brand_identity', 'get_rights', 'acquire_rights', 'update_rights'];
 exports.EVENT_TRACKING_TOOLS = ['sync_event_sources', 'log_event'];
 exports.ACCOUNT_TOOLS = ['list_accounts', 'sync_accounts'];
 exports.PROTOCOL_TOOLS = ['get_adcp_capabilities'];
@@ -184,6 +206,92 @@ function buildSyntheticCapabilities(tools) {
         _synthetic: true,
     };
 }
+/**
+ * Build synthetic v3 capabilities when the agent advertises
+ * `get_adcp_capabilities` (a v3-only tool) but the call itself failed —
+ * either the executor threw, or the response was non-success with no
+ * structurally v3-shaped data (the case `looksLikeV3Capabilities` would
+ * have caught).
+ *
+ * The agent is verifiably v3 because the v3-only discovery tool is
+ * present in `tools/list`. Falling back to v2 synthetic in this case
+ * triggers v2.5-schema lookups that have nothing to do with the original
+ * failure, cascading "AdCP schema data for version v2.5 not found"
+ * across every subsequent step. Treating as v3 (synthetic) lets the
+ * caller continue against the right adapter set; the underlying
+ * `get_adcp_capabilities` failure still surfaces in logs at the
+ * call site.
+ *
+ * Sets `_synthetic: true` so version-compat checks know detail-level
+ * fields (idempotency TTL, supportedVersions) are unknown — callers
+ * skip those checks rather than throw `VersionUnsupportedError` on a
+ * verifiably-v3 agent.
+ *
+ * Refs: #1217 (carve-out from #1197/closed), #1189 / #1201 (the v3-shape
+ * heuristic this complements).
+ */
+function buildSyntheticV3Capabilities(tools) {
+    const toolNames = new Set(tools.map(t => t.name));
+    const protocols = detectProtocolsFromTools(toolNames);
+    const features = {
+        inlineCreativeManagement: toolNames.has('sync_creatives'),
+        propertyListFiltering: false,
+        contentStandards: false,
+        conversionTracking: exports.EVENT_TRACKING_TOOLS.some(t => toolNames.has(t)),
+        audienceTargeting: toolNames.has('sync_audiences'),
+    };
+    return {
+        version: 'v3',
+        majorVersions: [3],
+        protocols,
+        features,
+        extensions: [],
+        _synthetic: true,
+    };
+}
+/**
+ * Heuristic: does this `get_adcp_capabilities` response look v3-shaped?
+ *
+ * Used by callers (e.g. SingleAgentClient.getCapabilities) when the response
+ * fails strict schema validation but is structurally non-empty. The question
+ * the heuristic answers is "is this a v3 agent with a wire-shape bug, or a
+ * v2 agent that happens to advertise the tool?". Falling back to v2 in the
+ * former case masks the original bug behind cascading v2.5-schema-not-found
+ * errors; treating it as v3 surfaces the wire-shape bug at its source.
+ *
+ * Affirmative v3 signals (any one is enough):
+ *   - `adcp` block (only v3 servers carry the `{ major_versions, idempotency, ... }` envelope)
+ *   - `supported_protocols` array (v3-only top-level field)
+ *   - any v3 protocol-level capability block (`media_buy`, `signals`, `creative`, `brand`,
+ *     `governance`, `sponsored_intelligence`, `compliance_testing`, `account`)
+ *
+ * v2 servers don't expose `get_adcp_capabilities` at all (the tool itself is
+ * a v3-only addition), so reaching this function with a non-empty payload
+ * already strongly implies v3 — but we belt-and-suspenders the structural
+ * check to avoid mis-promoting genuinely empty / null responses.
+ */
+function looksLikeV3Capabilities(data) {
+    if (!isPlainObject(data))
+        return false;
+    if (isPlainObject(data.adcp))
+        return true;
+    if (Array.isArray(data.supported_protocols))
+        return true;
+    const v3Blocks = [
+        'account',
+        'media_buy',
+        'signals',
+        'creative',
+        'brand',
+        'governance',
+        'sponsored_intelligence',
+        'compliance_testing',
+    ];
+    return v3Blocks.some(block => isPlainObject(data[block]));
+}
+function isPlainObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
 /**
  * Parse a get_adcp_capabilities response into normalized form
  */