@adcp/sdk 15.0.0 → 15.2.0

package/bin/adcp-grade.js

@@ -45,7 +45,25 @@ Options:
                              JSON-RPC tools/call envelope and posts to the
                              agent's MCP mount (see #612); \`raw\` posts to
                              per-operation AdCP endpoints (REST-binding agents);
-                             \`a2a\` signs the official A2A client's request.
+                             \`a2a\` signs the official A2A client's request
+                             and also grades the A2A operation-resolution
+                             vectors (adcp#7945): required_for must be
+                             enforced against the operation named by the
+                             invocation DataPart's \`skill\`, not the JSON-RPC
+                             method. Vector ids are prefixed a2a/. Tiers:
+                             contradiction-resolution (MUST in 3.2) and
+                             hardening (SHOULD in 3.2.x, MUST from 3.3). The
+                             signed create_media_buy vectors need
+                             --allow-live-side-effects (or a sandbox
+                             contract). If the compliance bundle carries no
+                             A2A vectors the run reports them unavailable.
+  --required-for <op[,op...]>
+                             Agent's request_signing.required_for. Skips
+                             vectors that assert an operation the agent does
+                             not require (capability_profile_mismatch).
+  --protocol-methods-required-for <m[,m...]>
+                             Agent's request_signing.protocol_methods_required_for
+                             (e.g. SendMessage). Gates A2A negative/007.
   --timeout <ms>             Per-probe timeout (default 10000)
   --json                     Emit the full GradeReport as JSON
   -h, --help                 Show this help
@@ -54,6 +72,9 @@ Environment:
   ADCP_GRADE_INITIALIZE_AUTHORIZATION
                              Authorization header used only for the MCP
                              initialize lifecycle (kept out of process argv).
+  ADCP_A2A_VECTORS_DIR       Directory with the A2A operation-resolution
+                             vectors (positive/ and negative/), overriding the
+                             compliance bundle. For bundles that predate them.
 
 Exit code:
   0   all graded vectors passed (skipped vectors don't count as failures)
@@ -202,6 +223,12 @@ async function runRequestSigningGrader(args) {
         options.signingProfileVersion = profile;
         break;
       }
+      case '--required-for':
+        options.agentRequiredFor = parseVectorList(args[++i], '--required-for');
+        break;
+      case '--protocol-methods-required-for':
+        options.agentProtocolMethodsRequiredFor = parseVectorList(args[++i], '--protocol-methods-required-for');
+        break;
       case '--allow-live-side-effects':
         options.allowLiveSideEffects = true;
         break;
@@ -470,6 +497,7 @@ function printHumanReport(report, options = {}) {
     `${report.passed_count} passed, ${report.failed_count} failed, ${report.skipped_count} skipped — total ${report.total_duration_ms}ms`
   );
   console.log(`Overall: ${report.passed ? 'PASS' : 'FAIL'}`);
+  printA2aOperationResolutionSummary(report.a2a_operation_resolution);
   // Only hint on an EXPLICIT --transport raw run — mcp is the default now,
   // so an unset transport already grades over MCP and the raw→mcp retry
   // hint would misdirect (if mcp mode fails everywhere, it's a different
@@ -484,6 +512,22 @@ function printHumanReport(report, options = {}) {
   console.log();
 }
 
+function printA2aOperationResolutionSummary(summary) {
+  if (!summary) return;
+  console.log();
+  if (!summary.vectors_available) {
+    console.log(`⚠  A2A operation-resolution: ${summary.message}. required_for over A2A was NOT graded.`);
+    return;
+  }
+  const t = summary.tiers;
+  const line = (label, tier) =>
+    `  ${label}: ${tier.passed} passed, ${tier.failed} failed, ${tier.skipped} skipped` +
+    (tier.failed_vectors.length ? ` (failed: ${tier.failed_vectors.join(', ')})` : '');
+  console.log(`A2A operation-resolution vectors (source: ${summary.source}):`);
+  console.log(line('contradiction-resolution (MUST in 3.2)', t['contradiction-resolution']));
+  console.log(line('hardening (SHOULD in 3.2.x, MUST from 3.3)', t.hardening));
+}
+
 /**
  * Heuristic: if the grader ran in `raw` mode (explicit --transport raw —
  * mcp is the default) and every non-skipped vector
@@ -516,7 +560,7 @@ function formatRow(r) {
     : r.passed
       ? `${r.http_status}${r.actual_error_code ? ` ${r.actual_error_code}` : ''}`
       : (r.diagnostic ?? 'see report');
-  return { id, status, detail };
+  return { id, status, detail: r.tier && !r.skipped ? `[${r.tier}] ${detail}` : detail };
 }
 
 module.exports = { handleGradeCommand };

package/bin/adcp.js

@@ -1966,7 +1966,9 @@ COMMANDS:
   doctor [options]            Check project secrets, SDK drift, and migrations
   storyboard <subcommand>     Test agent flows (run, list, show, step)
   specialism <subcommand>     Inspect a compliance specialism (list, show)
-  grade <subject> <url>       Conformance graders (e.g. request-signing)
+  grade <subject> <url>       Conformance graders (e.g. request-signing; with
+                              --transport a2a it also grades the A2A
+                              operation-resolution vectors)
   fuzz <url>                  Property-based conformance fuzzing against schemas
   resolve <agent-url>         Walk the brand_json_url discovery chain
                               (capabilities -> brand.json -> JWKS) and print
@@ -2191,7 +2193,10 @@ REQUEST-SIGNING VECTOR OPTIONS (signed_requests storyboard):
                                   discovery. Pass raw for agents that
                                   expose AdCP tools as per-operation HTTP
                                   endpoints. Mirrors
-                                  \`adcp grade request-signing --transport\`.
+                                  \`adcp grade request-signing --transport\`,
+                                  which with a2a additionally grades the A2A
+                                  operation-resolution vectors (required_for
+                                  keyed on the DataPart skill, adcp#7945).
   --signing-skip-vectors IDS      Comma-separated vector ids to skip (graded
                                   operator_skip), e.g.
                                   025-jwk-alg-crv-mismatch. Unknown ids are

package/dist/lib/canonical-references/index.d.mts

@@ -5,7 +5,7 @@ export interface CanonicalReference {
 }
 export type CanonicalReferenceKind = 'format_schema' | 'platform_extensions' | 'generic';
 export type CanonicalReferenceStatus = 'resolved' | 'unresolvable' | 'invalid_document' | 'invalid_schema' | 'digest_mismatch' | 'blocked_unsafe_url' | 'invalid_ref';
-export type CanonicalReferenceErrorCode = 'invalid_ref' | 'non_https_url' | 'unsafe_url' | 'redirect_blocked' | 'http_error' | 'network_error' | 'body_too_large' | 'invalid_json' | 'document_too_deep' | 'invalid_json_schema' | 'unsupported_schema_draft' | 'ref_sandbox_violation' | 'external_ref_unpinned' | 'keyword_limit_exceeded' | 'budget_exceeded' | 'digest_mismatch';
+export type CanonicalReferenceErrorCode = 'invalid_ref' | 'non_https_url' | 'unsafe_url' | 'redirect_blocked' | 'http_error' | 'network_error' | 'body_too_large' | 'invalid_json' | 'document_too_deep' | 'invalid_json_schema' | 'unsupported_schema_draft' | 'ref_sandbox_violation' | 'external_ref_unpinned' | 'keyword_limit_exceeded' | 'budget_exceeded' | 'invalid_options' | 'aborted' | 'access_denied' | 'digest_mismatch';
 export interface CanonicalReferenceError {
     code: CanonicalReferenceErrorCode;
     message: string;
@@ -63,7 +63,25 @@ export interface CanonicalReferenceCacheOptions {
     /** Maximum estimated retained bytes. Default 32 MiB. Set to 0 to disable caching. */
     maxBytes?: number;
 }
+/** Host-owned authenticated document transport. It must enforce destination scope before I/O. */
+export interface CanonicalDocumentReader {
+    read(request: {
+        uri: string;
+        maxBytes: number;
+        signal: AbortSignal;
+    }): Promise<{
+        body: Uint8Array;
+        contentType?: string;
+    }>;
+}
+/** Stable, secret-free failure for an authenticated document transport. */
+export declare class CanonicalDocumentReadError extends Error {
+    readonly code: 'access_denied' | 'unsafe_url' | 'body_too_large' | 'network_error' | 'invalid_options' | 'aborted';
+    constructor(code: 'access_denied' | 'unsafe_url' | 'body_too_large' | 'network_error' | 'invalid_options' | 'aborted');
+}
 export interface CanonicalReferenceResolverOptions {
+    /** Private transports bypass all caches so every resolution re-authorizes. No HTTP fallback. */
+    documentReader?: CanonicalDocumentReader;
     /** Caller-owned cache. Defaults to a fresh bounded per-resolver LRU. */
     cache?: CanonicalReferenceCache;
     /** Default 5_000 ms. */

package/dist/lib/canonical-references/index.d.ts

@@ -5,7 +5,7 @@ export interface CanonicalReference {
 }
 export type CanonicalReferenceKind = 'format_schema' | 'platform_extensions' | 'generic';
 export type CanonicalReferenceStatus = 'resolved' | 'unresolvable' | 'invalid_document' | 'invalid_schema' | 'digest_mismatch' | 'blocked_unsafe_url' | 'invalid_ref';
-export type CanonicalReferenceErrorCode = 'invalid_ref' | 'non_https_url' | 'unsafe_url' | 'redirect_blocked' | 'http_error' | 'network_error' | 'body_too_large' | 'invalid_json' | 'document_too_deep' | 'invalid_json_schema' | 'unsupported_schema_draft' | 'ref_sandbox_violation' | 'external_ref_unpinned' | 'keyword_limit_exceeded' | 'budget_exceeded' | 'digest_mismatch';
+export type CanonicalReferenceErrorCode = 'invalid_ref' | 'non_https_url' | 'unsafe_url' | 'redirect_blocked' | 'http_error' | 'network_error' | 'body_too_large' | 'invalid_json' | 'document_too_deep' | 'invalid_json_schema' | 'unsupported_schema_draft' | 'ref_sandbox_violation' | 'external_ref_unpinned' | 'keyword_limit_exceeded' | 'budget_exceeded' | 'invalid_options' | 'aborted' | 'access_denied' | 'digest_mismatch';
 export interface CanonicalReferenceError {
     code: CanonicalReferenceErrorCode;
     message: string;
@@ -63,7 +63,25 @@ export interface CanonicalReferenceCacheOptions {
     /** Maximum estimated retained bytes. Default 32 MiB. Set to 0 to disable caching. */
     maxBytes?: number;
 }
+/** Host-owned authenticated document transport. It must enforce destination scope before I/O. */
+export interface CanonicalDocumentReader {
+    read(request: {
+        uri: string;
+        maxBytes: number;
+        signal: AbortSignal;
+    }): Promise<{
+        body: Uint8Array;
+        contentType?: string;
+    }>;
+}
+/** Stable, secret-free failure for an authenticated document transport. */
+export declare class CanonicalDocumentReadError extends Error {
+    readonly code: 'access_denied' | 'unsafe_url' | 'body_too_large' | 'network_error' | 'invalid_options' | 'aborted';
+    constructor(code: 'access_denied' | 'unsafe_url' | 'body_too_large' | 'network_error' | 'invalid_options' | 'aborted');
+}
 export interface CanonicalReferenceResolverOptions {
+    /** Private transports bypass all caches so every resolution re-authorizes. No HTTP fallback. */
+    documentReader?: CanonicalDocumentReader;
     /** Caller-owned cache. Defaults to a fresh bounded per-resolver LRU. */
     cache?: CanonicalReferenceCache;
     /** Default 5_000 ms. */

package/dist/lib/canonical-references/index.js

@@ -28,6 +28,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var canonical_references_exports = {};
 __export(canonical_references_exports, {
+  CanonicalDocumentReadError: () => CanonicalDocumentReadError,
   canonicalReferenceCacheKey: () => canonicalReferenceCacheKey,
   createCanonicalReferenceCache: () => createCanonicalReferenceCache,
   createCanonicalReferenceResolver: () => createCanonicalReferenceResolver,
@@ -44,6 +45,18 @@ var import_sandbox_refs = require('../v2/format-schema/sandbox-refs.js');
 var import_regex_safety = require('../v2/format-schema/regex-safety.js');
 var import_strict_json = require('../signing/agent-resolver/strict-json.js');
 const Ajv2020 = require("ajv/dist/2020");
+class CanonicalDocumentReadError extends Error {
+  constructor(code) {
+    super(`Canonical document read: ${code}`);
+    this.code = code;
+    this.name = "CanonicalDocumentReadError";
+    Object.defineProperty(this, /* @__PURE__ */ Symbol.for("adcp.canonicalDocumentReadError"), { value: true });
+  }
+  code;
+}
+function isCanonicalDocumentReadError(error) {
+  return !!error && typeof error === "object" && error[/* @__PURE__ */ Symbol.for("adcp.canonicalDocumentReadError")] === true;
+}
 const DEFAULT_TIMEOUT_MS = 5e3;
 const DEFAULT_MAX_BODY_BYTES = 1024 * 1024;
 const DEFAULT_MAX_TOTAL_REF_BYTES = 8 * 1024 * 1024;
@@ -149,10 +162,13 @@ function exceedsJsonDocumentDepth(value) {
   return false;
 }
 function createCanonicalReferenceResolver(defaults = {}) {
+  if (defaults.documentReader && (!Number.isSafeInteger(defaults.timeoutMs ?? DEFAULT_TIMEOUT_MS) || (defaults.timeoutMs ?? DEFAULT_TIMEOUT_MS) < 1 || (defaults.timeoutMs ?? DEFAULT_TIMEOUT_MS) > 6e4 || !Number.isSafeInteger(defaults.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES) || (defaults.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES) < 1 || (defaults.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES) > 8 * 1024 * 1024))
+    throw new RangeError("Private canonical document transport limits are invalid");
   const cache = defaults.cache ?? createCanonicalReferenceCache();
   const merge = (options = {}) => ({
     ...defaults,
     ...options,
+    documentReader: defaults.documentReader ?? options.documentReader,
     cache
   });
   return {
@@ -205,7 +221,7 @@ async function fetchJsonReference(ref, options) {
   const kind = options.kind ?? "generic";
   const valid = validateRef(ref, kind, options);
   if (!valid.ok) return valid.result;
-  const cache = options.cache;
+  const cache = options.documentReader ? void 0 : options.cache;
   const cacheKey = canonicalReferenceCacheKey(ref, options);
   const cached = cache?.get(cacheKey);
   if (cached) {
@@ -223,15 +239,70 @@ async function fetchJsonReference(ref, options) {
   }
   let response;
   try {
-    response = await (0, import_ssrf_fetch.ssrfSafeFetch)(ref.uri, {
-      method: "GET",
-      headers: { accept: "application/json, application/schema+json" },
-      timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
-      maxBodyBytes: options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES,
-      allowPrivateIp: options.allowPrivateNetwork === true,
-      signal: options.signal
-    });
+    if (options.documentReader) {
+      const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+      const maxBytes = options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
+      if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 6e4 || !Number.isSafeInteger(maxBytes) || maxBytes < 1 || maxBytes > 8 * 1024 * 1024)
+        throw new CanonicalDocumentReadError("invalid_options");
+      const controller = new AbortController();
+      const onAbort = () => controller.abort(new CanonicalDocumentReadError("aborted"));
+      options.signal?.addEventListener("abort", onAbort, { once: true });
+      if (options.signal?.aborted) onAbort();
+      let abortListener;
+      const timer = setTimeout(() => controller.abort(new CanonicalDocumentReadError("network_error")), timeoutMs);
+      try {
+        controller.signal.throwIfAborted();
+        const read = await Promise.race([
+          options.documentReader.read({ uri: ref.uri, maxBytes, signal: controller.signal }),
+          new Promise((_, reject) => {
+            abortListener = () => reject(controller.signal.reason);
+            controller.signal.addEventListener("abort", abortListener, { once: true });
+            if (controller.signal.aborted) abortListener();
+          })
+        ]);
+        controller.signal.throwIfAborted();
+        if (!(read?.body instanceof Uint8Array) || read.body.byteLength > maxBytes)
+          throw new CanonicalDocumentReadError("body_too_large");
+        response = {
+          status: 200,
+          body: Uint8Array.from(read.body),
+          headers: { "content-type": read.contentType ?? "" }
+        };
+      } finally {
+        clearTimeout(timer);
+        options.signal?.removeEventListener("abort", onAbort);
+        if (abortListener) controller.signal.removeEventListener("abort", abortListener);
+      }
+    } else {
+      response = await (0, import_ssrf_fetch.ssrfSafeFetch)(ref.uri, {
+        method: "GET",
+        headers: { accept: "application/json, application/schema+json" },
+        timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+        maxBodyBytes: options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES,
+        allowPrivateIp: options.allowPrivateNetwork === true,
+        signal: options.signal
+      });
+    }
   } catch (err) {
+    if (isCanonicalDocumentReadError(err)) {
+      const code = [
+        "access_denied",
+        "unsafe_url",
+        "body_too_large",
+        "network_error",
+        "invalid_options",
+        "aborted"
+      ].includes(err.code) ? err.code : "network_error";
+      return fail(
+        kind,
+        ref,
+        cacheKey,
+        code === "unsafe_url" ? "blocked_unsafe_url" : "unresolvable",
+        code,
+        `Canonical document read failed: ${code}`,
+        { retryable: code === "network_error" }
+      );
+    }
     if (err instanceof import_ssrf_fetch.SsrfRefusedError) {
       if (err.code === "body_exceeds_limit") {
         return fail(
@@ -753,6 +824,7 @@ function countSchemaKeywords(root) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  CanonicalDocumentReadError,
   canonicalReferenceCacheKey,
   createCanonicalReferenceCache,
   createCanonicalReferenceResolver,

package/dist/lib/canonical-references/index.mjs

@@ -18,6 +18,18 @@ import {
 } from "../v2/format-schema/sandbox-refs.mjs";
 import { findUnsafeRegexPattern, unsafeRegexDetails } from "../v2/format-schema/regex-safety.mjs";
 import { rejectDuplicateJsonKeys } from "../signing/agent-resolver/strict-json.mjs";
+class CanonicalDocumentReadError extends Error {
+  constructor(code) {
+    super(`Canonical document read: ${code}`);
+    this.code = code;
+    this.name = "CanonicalDocumentReadError";
+    Object.defineProperty(this, /* @__PURE__ */ Symbol.for("adcp.canonicalDocumentReadError"), { value: true });
+  }
+  code;
+}
+function isCanonicalDocumentReadError(error) {
+  return !!error && typeof error === "object" && error[/* @__PURE__ */ Symbol.for("adcp.canonicalDocumentReadError")] === true;
+}
 const DEFAULT_TIMEOUT_MS = 5e3;
 const DEFAULT_MAX_BODY_BYTES = 1024 * 1024;
 const DEFAULT_MAX_TOTAL_REF_BYTES = 8 * 1024 * 1024;
@@ -123,10 +135,13 @@ function exceedsJsonDocumentDepth(value) {
   return false;
 }
 function createCanonicalReferenceResolver(defaults = {}) {
+  if (defaults.documentReader && (!Number.isSafeInteger(defaults.timeoutMs ?? DEFAULT_TIMEOUT_MS) || (defaults.timeoutMs ?? DEFAULT_TIMEOUT_MS) < 1 || (defaults.timeoutMs ?? DEFAULT_TIMEOUT_MS) > 6e4 || !Number.isSafeInteger(defaults.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES) || (defaults.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES) < 1 || (defaults.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES) > 8 * 1024 * 1024))
+    throw new RangeError("Private canonical document transport limits are invalid");
   const cache = defaults.cache ?? createCanonicalReferenceCache();
   const merge = (options = {}) => ({
     ...defaults,
     ...options,
+    documentReader: defaults.documentReader ?? options.documentReader,
     cache
   });
   return {
@@ -179,7 +194,7 @@ async function fetchJsonReference(ref, options) {
   const kind = options.kind ?? "generic";
   const valid = validateRef(ref, kind, options);
   if (!valid.ok) return valid.result;
-  const cache = options.cache;
+  const cache = options.documentReader ? void 0 : options.cache;
   const cacheKey = canonicalReferenceCacheKey(ref, options);
   const cached = cache?.get(cacheKey);
   if (cached) {
@@ -197,15 +212,70 @@ async function fetchJsonReference(ref, options) {
   }
   let response;
   try {
-    response = await ssrfSafeFetch(ref.uri, {
-      method: "GET",
-      headers: { accept: "application/json, application/schema+json" },
-      timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
-      maxBodyBytes: options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES,
-      allowPrivateIp: options.allowPrivateNetwork === true,
-      signal: options.signal
-    });
+    if (options.documentReader) {
+      const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+      const maxBytes = options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
+      if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 6e4 || !Number.isSafeInteger(maxBytes) || maxBytes < 1 || maxBytes > 8 * 1024 * 1024)
+        throw new CanonicalDocumentReadError("invalid_options");
+      const controller = new AbortController();
+      const onAbort = () => controller.abort(new CanonicalDocumentReadError("aborted"));
+      options.signal?.addEventListener("abort", onAbort, { once: true });
+      if (options.signal?.aborted) onAbort();
+      let abortListener;
+      const timer = setTimeout(() => controller.abort(new CanonicalDocumentReadError("network_error")), timeoutMs);
+      try {
+        controller.signal.throwIfAborted();
+        const read = await Promise.race([
+          options.documentReader.read({ uri: ref.uri, maxBytes, signal: controller.signal }),
+          new Promise((_, reject) => {
+            abortListener = () => reject(controller.signal.reason);
+            controller.signal.addEventListener("abort", abortListener, { once: true });
+            if (controller.signal.aborted) abortListener();
+          })
+        ]);
+        controller.signal.throwIfAborted();
+        if (!(read?.body instanceof Uint8Array) || read.body.byteLength > maxBytes)
+          throw new CanonicalDocumentReadError("body_too_large");
+        response = {
+          status: 200,
+          body: Uint8Array.from(read.body),
+          headers: { "content-type": read.contentType ?? "" }
+        };
+      } finally {
+        clearTimeout(timer);
+        options.signal?.removeEventListener("abort", onAbort);
+        if (abortListener) controller.signal.removeEventListener("abort", abortListener);
+      }
+    } else {
+      response = await ssrfSafeFetch(ref.uri, {
+        method: "GET",
+        headers: { accept: "application/json, application/schema+json" },
+        timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+        maxBodyBytes: options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES,
+        allowPrivateIp: options.allowPrivateNetwork === true,
+        signal: options.signal
+      });
+    }
   } catch (err) {
+    if (isCanonicalDocumentReadError(err)) {
+      const code = [
+        "access_denied",
+        "unsafe_url",
+        "body_too_large",
+        "network_error",
+        "invalid_options",
+        "aborted"
+      ].includes(err.code) ? err.code : "network_error";
+      return fail(
+        kind,
+        ref,
+        cacheKey,
+        code === "unsafe_url" ? "blocked_unsafe_url" : "unresolvable",
+        code,
+        `Canonical document read failed: ${code}`,
+        { retryable: code === "network_error" }
+      );
+    }
     if (err instanceof SsrfRefusedError) {
       if (err.code === "body_exceeds_limit") {
         return fail(
@@ -726,6 +796,7 @@ function countSchemaKeywords(root) {
   return walk(root);
 }
 export {
+  CanonicalDocumentReadError,
   canonicalReferenceCacheKey,
   createCanonicalReferenceCache,
   createCanonicalReferenceResolver,

package/dist/lib/client/core.d.mts

@@ -7,3 +7,4 @@ export { InMemoryWebhookRegistrationStore, type InMemoryWebhookRegistrationStore
 export type { ConversationConfig, ConversationContext, InputHandler, InputHandlerResponse, InputRequest, Message, TaskInfo, TaskOptions, TaskResult, TaskResultCompleted, TaskResultFailure, TaskResultIntermediate, TaskResultMetadata, } from '../core/ConversationTypes.mjs';
 export type { AgentConfig } from '../types/adcp.mjs';
 export type { ResolveAccountOptions, ListedAccount } from '../core/account-resolution.mjs';
+export type { CreativeFormatWireMode } from '../v2/projection/creative-delivery.mjs';

package/dist/lib/client/core.d.ts

@@ -7,3 +7,4 @@ export { InMemoryWebhookRegistrationStore, type InMemoryWebhookRegistrationStore
 export type { ConversationConfig, ConversationContext, InputHandler, InputHandlerResponse, InputRequest, Message, TaskInfo, TaskOptions, TaskResult, TaskResultCompleted, TaskResultFailure, TaskResultIntermediate, TaskResultMetadata, } from '../core/ConversationTypes';
 export type { AgentConfig } from '../types/adcp';
 export type { ResolveAccountOptions, ListedAccount } from '../core/account-resolution';
+export type { CreativeFormatWireMode } from '../v2/projection/creative-delivery';

package/dist/lib/core/AgentClient.d.mts

@@ -14,7 +14,7 @@ import type { MediaBuyLifecycleCoordinator, MediaBuyLifecycleCoordinatorOptions
 import type { ProposalRefinementCapabilities, RefineProposalsInput, RefineProposalsResponse } from '../negotiation/types.mjs';
 import type { LegacyFormatConverter } from '../v2/projection/v1-to-v2.mjs';
 import type { ProjectionCatalogSnapshot } from '../v2/projection/catalog-snapshot.mjs';
-import type { CanonicalCreateMediaBuyInput, CanonicalCreativeResponse, CanonicalGetProductsRequest, CanonicalGetProductsResponse, CanonicalListCreativesRequest, CanonicalListCreativesResponse, CanonicalPreviewCreativeRequest, CanonicalPreviewCreativeResponse, CanonicalSyncCreativesRequest, CanonicalUpdateMediaBuyRequest } from '../v2/projection/creative-delivery.mjs';
+import type { CanonicalCreateMediaBuyInput, CanonicalCreativeResponse, CanonicalGetProductsRequest, CanonicalGetProductsResponse, CanonicalListCreativesRequest, CanonicalListCreativesResponse, CanonicalPreviewCreativeRequest, CanonicalPreviewCreativeResponse, CanonicalSyncCreativesRequest, CanonicalUpdateMediaBuyRequest, CreativeFormatWireMode } from '../v2/projection/creative-delivery.mjs';
 export type { CanonicalGetProductsResponse } from '../v2/projection/creative-delivery.mjs';
 export type CanonicalProjectionTaskOptions = TaskOptions & {
     /** Migration escape hatch for seller-specific legacy refs absent from the bundled registry. */
@@ -533,6 +533,14 @@ export declare class AgentClient {
      * For v2 servers: builds synthetic capabilities from tool list
      */
     getCapabilities(options?: Pick<TaskOptions, 'signal' | 'transport'>): Promise<AdcpCapabilities>;
+    /**
+     * Resolve the creative wire mode used by canonical writes without sending a
+     * mutation. Uses capabilities, this tool's input schema, and the client wire
+     * pin. Older peers with insufficient evidence return `unknown` and require
+     * an unambiguous legacy reference during projection; conflicting evidence
+     * or unproven support with a 3.2+ buyer pin throws `CreativeFormatCapabilityError`.
+     */
+    resolveCreativeFormatWireMode(taskType: 'sync_creatives' | 'create_media_buy' | 'update_media_buy', options?: Pick<TaskOptions, 'signal' | 'transport'>): Promise<CreativeFormatWireMode>;
     /** Scope token for a tenant-bound, application-owned capability preflight. */
     getCapabilityEvidenceScope(): import('./SingleAgentClient.mjs').CapabilityEvidenceScope;
     /** Install fresh capability evidence without making a redundant probe. */

package/dist/lib/core/AgentClient.d.ts

@@ -14,7 +14,7 @@ import type { MediaBuyLifecycleCoordinator, MediaBuyLifecycleCoordinatorOptions
 import type { ProposalRefinementCapabilities, RefineProposalsInput, RefineProposalsResponse } from '../negotiation/types';
 import type { LegacyFormatConverter } from '../v2/projection/v1-to-v2';
 import type { ProjectionCatalogSnapshot } from '../v2/projection/catalog-snapshot';
-import type { CanonicalCreateMediaBuyInput, CanonicalCreativeResponse, CanonicalGetProductsRequest, CanonicalGetProductsResponse, CanonicalListCreativesRequest, CanonicalListCreativesResponse, CanonicalPreviewCreativeRequest, CanonicalPreviewCreativeResponse, CanonicalSyncCreativesRequest, CanonicalUpdateMediaBuyRequest } from '../v2/projection/creative-delivery';
+import type { CanonicalCreateMediaBuyInput, CanonicalCreativeResponse, CanonicalGetProductsRequest, CanonicalGetProductsResponse, CanonicalListCreativesRequest, CanonicalListCreativesResponse, CanonicalPreviewCreativeRequest, CanonicalPreviewCreativeResponse, CanonicalSyncCreativesRequest, CanonicalUpdateMediaBuyRequest, CreativeFormatWireMode } from '../v2/projection/creative-delivery';
 export type { CanonicalGetProductsResponse } from '../v2/projection/creative-delivery';
 export type CanonicalProjectionTaskOptions = TaskOptions & {
     /** Migration escape hatch for seller-specific legacy refs absent from the bundled registry. */
@@ -533,6 +533,14 @@ export declare class AgentClient {
      * For v2 servers: builds synthetic capabilities from tool list
      */
     getCapabilities(options?: Pick<TaskOptions, 'signal' | 'transport'>): Promise<AdcpCapabilities>;
+    /**
+     * Resolve the creative wire mode used by canonical writes without sending a
+     * mutation. Uses capabilities, this tool's input schema, and the client wire
+     * pin. Older peers with insufficient evidence return `unknown` and require
+     * an unambiguous legacy reference during projection; conflicting evidence
+     * or unproven support with a 3.2+ buyer pin throws `CreativeFormatCapabilityError`.
+     */
+    resolveCreativeFormatWireMode(taskType: 'sync_creatives' | 'create_media_buy' | 'update_media_buy', options?: Pick<TaskOptions, 'signal' | 'transport'>): Promise<CreativeFormatWireMode>;
     /** Scope token for a tenant-bound, application-owned capability preflight. */
     getCapabilityEvidenceScope(): import('./SingleAgentClient').CapabilityEvidenceScope;
     /** Install fresh capability evidence without making a redundant probe. */

package/dist/lib/core/AgentClient.js

@@ -791,6 +791,16 @@ class AgentClient {
   async getCapabilities(options) {
     return this.client.getCapabilities(options);
   }
+  /**
+   * Resolve the creative wire mode used by canonical writes without sending a
+   * mutation. Uses capabilities, this tool's input schema, and the client wire
+   * pin. Older peers with insufficient evidence return `unknown` and require
+   * an unambiguous legacy reference during projection; conflicting evidence
+   * or unproven support with a 3.2+ buyer pin throws `CreativeFormatCapabilityError`.
+   */
+  async resolveCreativeFormatWireMode(taskType, options) {
+    return this.client.resolveCreativeFormatWireMode(taskType, options);
+  }
   /** Scope token for a tenant-bound, application-owned capability preflight. */
   getCapabilityEvidenceScope() {
     return this.client.getCapabilityEvidenceScope();

package/dist/lib/core/AgentClient.mjs

@@ -759,6 +759,16 @@ class AgentClient {
   async getCapabilities(options) {
     return this.client.getCapabilities(options);
   }
+  /**
+   * Resolve the creative wire mode used by canonical writes without sending a
+   * mutation. Uses capabilities, this tool's input schema, and the client wire
+   * pin. Older peers with insufficient evidence return `unknown` and require
+   * an unambiguous legacy reference during projection; conflicting evidence
+   * or unproven support with a 3.2+ buyer pin throws `CreativeFormatCapabilityError`.
+   */
+  async resolveCreativeFormatWireMode(taskType, options) {
+    return this.client.resolveCreativeFormatWireMode(taskType, options);
+  }
   /** Scope token for a tenant-bound, application-owned capability preflight. */
   getCapabilityEvidenceScope() {
     return this.client.getCapabilityEvidenceScope();

package/dist/lib/core/SingleAgentClient.d.mts

@@ -19,7 +19,7 @@ import type { ProductCache } from './product-cache.mjs';
 import { type ResolveAccountOptions } from './account-resolution.mjs';
 import { type BuyerPropertyPolicy, type ProductPropertyPolicyMode } from '../media-buy/property-policy.mjs';
 import { type ResolveListOptions } from '../server/targeting-helpers.mjs';
-import { type CanonicalCreateMediaBuyInput, type CanonicalCreativeResponse, type CanonicalGetProductsRequest, type CanonicalGetProductsResponse, type CanonicalListCreativesRequest, type CanonicalListCreativesResponse, type CanonicalPreviewCreativeRequest, type CanonicalPreviewCreativeResponse, type CanonicalSyncCreativesRequest, type CanonicalUpdateMediaBuyRequest, type SyncCreativeFormatProjection } from '../v2/projection/creative-delivery.mjs';
+import { type CanonicalCreateMediaBuyInput, type CanonicalCreativeResponse, type CanonicalGetProductsRequest, type CanonicalGetProductsResponse, type CanonicalListCreativesRequest, type CanonicalListCreativesResponse, type CanonicalPreviewCreativeRequest, type CanonicalPreviewCreativeResponse, type CanonicalSyncCreativesRequest, type CanonicalUpdateMediaBuyRequest, type CreativeFormatWireMode, type SyncCreativeFormatProjection } from '../v2/projection/creative-delivery.mjs';
 import type { LegacyFormatConverter } from '../v2/projection/v1-to-v2.mjs';
 import { type ProjectionCatalogSnapshot } from '../v2/projection/catalog-snapshot.mjs';
 import type { CanonicalFormatLegacyResolver } from '../v2/projection/v2-to-v1.mjs';
@@ -927,7 +927,18 @@ export declare class SingleAgentClient {
      * Projection-only options are ignored because this method preserves the caller's legacy wire payload.
      */
     syncCreativesLegacy(params: MutatingRequestInput<SyncCreativesRequest>, inputHandler?: InputHandler, options?: SyncCreativesTaskOptions): Promise<TaskResult<SyncCreativesResponse>>;
-    private resolveCreativeFormatWireMode;
+    /**
+     * Resolve the creative wire mode used by the canonical write methods without
+     * sending a mutation. Discovers capabilities and the current tool's input
+     * schema, or reuses fresh cached/primed evidence, with this client's wire pin.
+     *
+     * `unknown` preserves the conservative legacy projection for older peers
+     * whose capabilities and schema do not establish support. Projection still
+     * requires an unambiguous legacy reference for each creative in that case.
+     * Conflicting evidence and unproven support with a 3.2+ buyer pin throw
+     * `CreativeFormatCapabilityError`, just as they do during a write.
+     */
+    resolveCreativeFormatWireMode(taskType: 'sync_creatives' | 'create_media_buy' | 'update_media_buy', options?: ReadRequestOptions): Promise<CreativeFormatWireMode>;
     /** Validate malformed creative payloads before capability discovery can perform I/O. */
     private validateBeforeCreativeCapabilityProbe;
     /**

package/dist/lib/core/SingleAgentClient.d.ts

@@ -19,7 +19,7 @@ import type { ProductCache } from './product-cache';
 import { type ResolveAccountOptions } from './account-resolution';
 import { type BuyerPropertyPolicy, type ProductPropertyPolicyMode } from '../media-buy/property-policy';
 import { type ResolveListOptions } from '../server/targeting-helpers';
-import { type CanonicalCreateMediaBuyInput, type CanonicalCreativeResponse, type CanonicalGetProductsRequest, type CanonicalGetProductsResponse, type CanonicalListCreativesRequest, type CanonicalListCreativesResponse, type CanonicalPreviewCreativeRequest, type CanonicalPreviewCreativeResponse, type CanonicalSyncCreativesRequest, type CanonicalUpdateMediaBuyRequest, type SyncCreativeFormatProjection } from '../v2/projection/creative-delivery';
+import { type CanonicalCreateMediaBuyInput, type CanonicalCreativeResponse, type CanonicalGetProductsRequest, type CanonicalGetProductsResponse, type CanonicalListCreativesRequest, type CanonicalListCreativesResponse, type CanonicalPreviewCreativeRequest, type CanonicalPreviewCreativeResponse, type CanonicalSyncCreativesRequest, type CanonicalUpdateMediaBuyRequest, type CreativeFormatWireMode, type SyncCreativeFormatProjection } from '../v2/projection/creative-delivery';
 import type { LegacyFormatConverter } from '../v2/projection/v1-to-v2';
 import { type ProjectionCatalogSnapshot } from '../v2/projection/catalog-snapshot';
 import type { CanonicalFormatLegacyResolver } from '../v2/projection/v2-to-v1';
@@ -927,7 +927,18 @@ export declare class SingleAgentClient {
      * Projection-only options are ignored because this method preserves the caller's legacy wire payload.
      */
     syncCreativesLegacy(params: MutatingRequestInput<SyncCreativesRequest>, inputHandler?: InputHandler, options?: SyncCreativesTaskOptions): Promise<TaskResult<SyncCreativesResponse>>;
-    private resolveCreativeFormatWireMode;
+    /**
+     * Resolve the creative wire mode used by the canonical write methods without
+     * sending a mutation. Discovers capabilities and the current tool's input
+     * schema, or reuses fresh cached/primed evidence, with this client's wire pin.
+     *
+     * `unknown` preserves the conservative legacy projection for older peers
+     * whose capabilities and schema do not establish support. Projection still
+     * requires an unambiguous legacy reference for each creative in that case.
+     * Conflicting evidence and unproven support with a 3.2+ buyer pin throw
+     * `CreativeFormatCapabilityError`, just as they do during a write.
+     */
+    resolveCreativeFormatWireMode(taskType: 'sync_creatives' | 'create_media_buy' | 'update_media_buy', options?: ReadRequestOptions): Promise<CreativeFormatWireMode>;
     /** Validate malformed creative payloads before capability discovery can perform I/O. */
     private validateBeforeCreativeCapabilityProbe;
     /**