@adcp/sdk 14.0.0-rc.51 → 14.0.0-rc.53

package/README.md

@@ -7,7 +7,7 @@
 [![API Documentation](https://img.shields.io/badge/API-Documentation-blue.svg)](https://adcontextprotocol.github.io/adcp-client/api/)
 [![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/adcontextprotocol/adcp-client/ci.yml?branch=main)](https://github.com/adcontextprotocol/adcp-client/actions)
 
-Official TypeScript/JavaScript client for the **Ad Context Protocol (AdCP)**. Build distributed advertising operations that work synchronously OR asynchronously with the same code.
+Official TypeScript/JavaScript SDK for the **Ad Context Protocol (AdCP)**. Use its buyer client to call agents, server framework to build them, and conformance tools to test them. The SDK supports MCP and A2A, with both immediate and asynchronous task results.
 
 ## For AI Agents
 

package/dist/lib/registry/types.generated.d.mts

@@ -7877,6 +7877,18 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
+            /** @description Agent does not offer public product browsing (no wholesale buying mode, or a buyer account is required) */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        error: string;
+                        message: string;
+                    };
+                };
+            };
             /** @description Rate limit exceeded */
             429: {
                 headers: {

package/dist/lib/registry/types.generated.d.ts

@@ -7877,6 +7877,18 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
+            /** @description Agent does not offer public product browsing (no wholesale buying mode, or a buyer account is required) */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        error: string;
+                        message: string;
+                    };
+                };
+            };
             /** @description Rate limit exceeded */
             429: {
                 headers: {

package/dist/lib/schemas-data/v2.5/_provenance.json

@@ -4,5 +4,5 @@
   "source_sha": "4e553ad955f83b49c7d221ab5c3ff78237ad02e3",
   "source_tarball_sha256": "580656d6466ef9f0d1119985e6726c2efea718dc671e2ad30957fcb2fd54af0f",
   "upstream_adcp_version": "2.5.3",
-  "synced_at": "2026-09-30T04:42:03.622Z"
+  "synced_at": "2026-09-30T09:55:20.074Z"
 }

package/dist/lib/server/auth-signature.d.mts

@@ -69,8 +69,11 @@ export interface VerifySignatureAsAuthenticatorOptions {
     now?: () => number;
     /**
      * Trusted endpoint release pin used to select the 3.0/3.1 or 3.2 signature
-     * profile. When omitted, verification accepts both encodings for SDK 13
-     * compatibility while digest coverage follows `capability`.
+     * profile. Set it on every endpoint that advertises a 3.2 release: a 3.2
+     * pin rejects Base64URL `Signature` / `Content-Digest` values as
+     * `request_signature_header_malformed` whatever `capability` says. When
+     * omitted, verification accepts both encodings for SDK 13 compatibility
+     * while digest coverage follows `capability`.
      */
     adcpVersion?: string;
     /**

package/dist/lib/server/auth-signature.d.ts

@@ -69,8 +69,11 @@ export interface VerifySignatureAsAuthenticatorOptions {
     now?: () => number;
     /**
      * Trusted endpoint release pin used to select the 3.0/3.1 or 3.2 signature
-     * profile. When omitted, verification accepts both encodings for SDK 13
-     * compatibility while digest coverage follows `capability`.
+     * profile. Set it on every endpoint that advertises a 3.2 release: a 3.2
+     * pin rejects Base64URL `Signature` / `Content-Digest` values as
+     * `request_signature_header_malformed` whatever `capability` says. When
+     * omitted, verification accepts both encodings for SDK 13 compatibility
+     * while digest coverage follows `capability`.
      */
     adcpVersion?: string;
     /**

package/dist/lib/signing/content-digest.d.mts

@@ -8,5 +8,13 @@ export declare function computeContentDigest(body: string | Uint8Array, encoding
  * up the `sha-256` member without requiring any particular position.
  */
 export declare function parseContentDigest(header: string): Buffer | null;
+/** Raw text of the `sha-256` byte-sequence token in a Content-Digest header, if present. */
+export declare function contentDigestSha256Token(header: string): string | undefined;
+/**
+ * True when `encoded` is canonical padded standard Base64 (RFC 4648 §4), the
+ * RFC 8941 `sf-binary` form AdCP 3.2 requires: `+`/`/` alphabet, length a
+ * multiple of four, and only the `=` padding the byte length requires.
+ */
+export declare function isPaddedStandardBase64(encoded: string): boolean;
 export declare function contentDigestUsesEncoding(header: string, encoding: SfBinaryEncoding): boolean;
 export declare function contentDigestMatches(header: string, body: string | Uint8Array): boolean;

package/dist/lib/signing/content-digest.d.ts

@@ -8,5 +8,13 @@ export declare function computeContentDigest(body: string | Uint8Array, encoding
  * up the `sha-256` member without requiring any particular position.
  */
 export declare function parseContentDigest(header: string): Buffer | null;
+/** Raw text of the `sha-256` byte-sequence token in a Content-Digest header, if present. */
+export declare function contentDigestSha256Token(header: string): string | undefined;
+/**
+ * True when `encoded` is canonical padded standard Base64 (RFC 4648 §4), the
+ * RFC 8941 `sf-binary` form AdCP 3.2 requires: `+`/`/` alphabet, length a
+ * multiple of four, and only the `=` padding the byte length requires.
+ */
+export declare function isPaddedStandardBase64(encoded: string): boolean;
 export declare function contentDigestUsesEncoding(header: string, encoding: SfBinaryEncoding): boolean;
 export declare function contentDigestMatches(header: string, body: string | Uint8Array): boolean;

package/dist/lib/signing/content-digest.js

@@ -20,7 +20,9 @@ var content_digest_exports = {};
 __export(content_digest_exports, {
   computeContentDigest: () => computeContentDigest,
   contentDigestMatches: () => contentDigestMatches,
+  contentDigestSha256Token: () => contentDigestSha256Token,
   contentDigestUsesEncoding: () => contentDigestUsesEncoding,
+  isPaddedStandardBase64: () => isPaddedStandardBase64,
   parseContentDigest: () => parseContentDigest,
   requestSigningEncodingForVersion: () => requestSigningEncodingForVersion
 });
@@ -47,12 +49,17 @@ function parseContentDigest(header) {
   const m = header.match(SHA256_MEMBER_RE);
   return m && m[1] ? Buffer.from(m[1], "base64") : null;
 }
+function contentDigestSha256Token(header) {
+  return header.match(/(?:^|[,\s])sha-256=:([^:]+):/)?.[1];
+}
+function isPaddedStandardBase64(encoded) {
+  return encoded.length > 0 && encoded.length % 4 === 0 && /^[A-Za-z0-9+/]+={0,2}$/.test(encoded);
+}
 function contentDigestUsesEncoding(header, encoding) {
-  const match = header.match(/(?:^|[,\s])sha-256=:([^:]+):/);
-  if (!match?.[1]) return false;
-  const encoded = match[1];
+  const encoded = contentDigestSha256Token(header);
+  if (!encoded) return false;
   if (encoding === "legacy-base64url") return /^[A-Za-z0-9_-]+$/.test(encoded);
-  return encoded.length % 4 === 0 && /^[A-Za-z0-9+/]+={1,2}$/.test(encoded);
+  return isPaddedStandardBase64(encoded);
 }
 function contentDigestMatches(header, body) {
   const expected = parseContentDigest(header);
@@ -70,7 +77,9 @@ function toBuffer(body) {
 0 && (module.exports = {
   computeContentDigest,
   contentDigestMatches,
+  contentDigestSha256Token,
   contentDigestUsesEncoding,
+  isPaddedStandardBase64,
   parseContentDigest,
   requestSigningEncodingForVersion
 });

package/dist/lib/signing/content-digest.mjs

@@ -20,12 +20,17 @@ function parseContentDigest(header) {
   const m = header.match(SHA256_MEMBER_RE);
   return m && m[1] ? Buffer.from(m[1], "base64") : null;
 }
+function contentDigestSha256Token(header) {
+  return header.match(/(?:^|[,\s])sha-256=:([^:]+):/)?.[1];
+}
+function isPaddedStandardBase64(encoded) {
+  return encoded.length > 0 && encoded.length % 4 === 0 && /^[A-Za-z0-9+/]+={0,2}$/.test(encoded);
+}
 function contentDigestUsesEncoding(header, encoding) {
-  const match = header.match(/(?:^|[,\s])sha-256=:([^:]+):/);
-  if (!match?.[1]) return false;
-  const encoded = match[1];
+  const encoded = contentDigestSha256Token(header);
+  if (!encoded) return false;
   if (encoding === "legacy-base64url") return /^[A-Za-z0-9_-]+$/.test(encoded);
-  return encoded.length % 4 === 0 && /^[A-Za-z0-9+/]+={1,2}$/.test(encoded);
+  return isPaddedStandardBase64(encoded);
 }
 function contentDigestMatches(header, body) {
   const expected = parseContentDigest(header);
@@ -42,7 +47,9 @@ function toBuffer(body) {
 export {
   computeContentDigest,
   contentDigestMatches,
+  contentDigestSha256Token,
   contentDigestUsesEncoding,
+  isPaddedStandardBase64,
   parseContentDigest,
   requestSigningEncodingForVersion
 };

package/dist/lib/signing/parser.d.mts

@@ -1,4 +1,4 @@
-import type { SfBinaryEncoding } from './content-digest.mjs';
+import { type SfBinaryEncoding } from './content-digest.mjs';
 export interface ParsedSignatureInput {
     label: string;
     components: string[];

package/dist/lib/signing/parser.d.ts

@@ -1,4 +1,4 @@
-import type { SfBinaryEncoding } from './content-digest';
+import { type SfBinaryEncoding } from './content-digest';
 export interface ParsedSignatureInput {
     label: string;
     components: string[];

package/dist/lib/signing/parser.js

@@ -25,6 +25,7 @@ __export(parser_exports, {
 module.exports = __toCommonJS(parser_exports);
 var import_structured_headers = require("structured-headers");
 var import_errors = require('./errors.js');
+var import_content_digest = require('./content-digest.js');
 const STRING_PARAMS = /* @__PURE__ */ new Set(["nonce", "keyid", "alg", "tag"]);
 const INTEGER_PARAMS = /* @__PURE__ */ new Set(["created", "expires"]);
 function malformed(message) {
@@ -79,7 +80,7 @@ function parseSignature(headerValue, expectedLabel, encoding = "legacy-base64url
   const rawBytes = headerValue.match(new RegExp(`(?:^|,\\s*)${escapedLabel}\\s*=\\s*:([^:]+):`))?.[1];
   if (!rawBytes) malformed(`Signature header does not contain a byte sequence for label "${expectedLabel}"`);
   if (encoding === "rfc8941-base64") {
-    if (rawBytes.length % 4 !== 0 || !/^[A-Za-z0-9+/]+={1,2}$/.test(rawBytes)) {
+    if (!(0, import_content_digest.isPaddedStandardBase64)(rawBytes)) {
       malformed("Signature value must use padded standard Base64 for AdCP 3.2+");
     }
   } else if (!/^[A-Za-z0-9_-]+$/.test(rawBytes)) {
@@ -87,7 +88,7 @@ function parseSignature(headerValue, expectedLabel, encoding = "legacy-base64url
   }
   let dict;
   try {
-    dict = (0, import_structured_headers.parseDictionary)(normalizeByteSequenceBase64(headerValue));
+    dict = (0, import_structured_headers.parseDictionary)(encoding === "rfc8941-base64" ? headerValue : normalizeByteSequenceBase64(headerValue));
   } catch (e) {
     if (e instanceof import_structured_headers.ParseError) {
       if (/base64/i.test(e.message)) malformed("Signature value contains non-base64 characters");

package/dist/lib/signing/parser.mjs

@@ -1,5 +1,6 @@
 import { ParseError, parseDictionary, serializeInnerList } from "structured-headers";
 import { RequestSignatureError } from "./errors.mjs";
+import { isPaddedStandardBase64 } from "./content-digest.mjs";
 const STRING_PARAMS = /* @__PURE__ */ new Set(["nonce", "keyid", "alg", "tag"]);
 const INTEGER_PARAMS = /* @__PURE__ */ new Set(["created", "expires"]);
 function malformed(message) {
@@ -54,7 +55,7 @@ function parseSignature(headerValue, expectedLabel, encoding = "legacy-base64url
   const rawBytes = headerValue.match(new RegExp(`(?:^|,\\s*)${escapedLabel}\\s*=\\s*:([^:]+):`))?.[1];
   if (!rawBytes) malformed(`Signature header does not contain a byte sequence for label "${expectedLabel}"`);
   if (encoding === "rfc8941-base64") {
-    if (rawBytes.length % 4 !== 0 || !/^[A-Za-z0-9+/]+={1,2}$/.test(rawBytes)) {
+    if (!isPaddedStandardBase64(rawBytes)) {
       malformed("Signature value must use padded standard Base64 for AdCP 3.2+");
     }
   } else if (!/^[A-Za-z0-9_-]+$/.test(rawBytes)) {
@@ -62,7 +63,7 @@ function parseSignature(headerValue, expectedLabel, encoding = "legacy-base64url
   }
   let dict;
   try {
-    dict = parseDictionary(normalizeByteSequenceBase64(headerValue));
+    dict = parseDictionary(encoding === "rfc8941-base64" ? headerValue : normalizeByteSequenceBase64(headerValue));
   } catch (e) {
     if (e instanceof ParseError) {
       if (/base64/i.test(e.message)) malformed("Signature value contains non-base64 characters");

package/dist/lib/signing/verifier.d.mts

@@ -19,8 +19,12 @@ export interface VerifyRequestOptions {
     operation?: string;
     /**
      * Trusted endpoint release pin; never inferred from request payload data.
-     * When omitted, the verifier accepts both the legacy 3.0/3.1 Base64URL
-     * representation and the 3.2+ RFC 8941 Base64 representation. Digest
+     * A 3.2+ pin parses `Signature` and `Content-Digest` strictly as RFC 8941
+     * padded standard Base64 and rejects Base64URL as
+     * `request_signature_header_malformed`, regardless of
+     * `capability.covers_content_digest`. When omitted, the verifier accepts
+     * both the legacy 3.0/3.1 Base64URL representation and the 3.2+ RFC 8941
+     * Base64 representation, so it cannot grade as a 3.2 verifier. Digest
      * coverage still follows `capability.covers_content_digest`.
      */
     adcpVersion?: string;

package/dist/lib/signing/verifier.d.ts

@@ -19,8 +19,12 @@ export interface VerifyRequestOptions {
     operation?: string;
     /**
      * Trusted endpoint release pin; never inferred from request payload data.
-     * When omitted, the verifier accepts both the legacy 3.0/3.1 Base64URL
-     * representation and the 3.2+ RFC 8941 Base64 representation. Digest
+     * A 3.2+ pin parses `Signature` and `Content-Digest` strictly as RFC 8941
+     * padded standard Base64 and rejects Base64URL as
+     * `request_signature_header_malformed`, regardless of
+     * `capability.covers_content_digest`. When omitted, the verifier accepts
+     * both the legacy 3.0/3.1 Base64URL representation and the 3.2+ RFC 8941
+     * Base64 representation, so it cannot grade as a 3.2 verifier. Digest
      * coverage still follows `capability.covers_content_digest`.
      */
     adcpVersion?: string;

package/dist/lib/signing/verifier.js

@@ -92,7 +92,7 @@ async function verifyRequestSignature(request, options) {
       parsedEncoding = candidate;
       break;
     } catch (error) {
-      parseError ??= error;
+      if (parseError === void 0 || candidate === (pinnedBinaryEncoding ?? "rfc8941-base64")) parseError = error;
     }
   }
   if (!parsedSig) throw parseError;
@@ -192,9 +192,16 @@ async function verifyRequestSignature(request, options) {
   }
   if (parsedInput.components.includes("content-digest")) {
     const digestHeader = (0, import_canonicalize.getHeaderValue)(request.headers, "Content-Digest");
-    const encodingMatches = !!digestHeader && contentDigestEncodingCandidates(pinnedBinaryEncoding, options.capability.covers_content_digest).some(
+    const encodingMatches = !!digestHeader && contentDigestEncodingCandidates(pinnedBinaryEncoding).some(
       (candidate) => (0, import_content_digest.contentDigestUsesEncoding)(digestHeader, candidate)
     );
+    if (digestHeader && !encodingMatches && pinnedBinaryEncoding === "rfc8941-base64" && (0, import_content_digest.contentDigestSha256Token)(digestHeader) !== void 0) {
+      throw new import_errors.RequestSignatureError(
+        "request_signature_header_malformed",
+        11,
+        "Content-Digest sha-256 value must use padded standard Base64 for AdCP 3.2+"
+      );
+    }
     if (!digestHeader || !encodingMatches || !(0, import_content_digest.contentDigestMatches)(digestHeader, request.body ?? "")) {
       throw new import_errors.RequestSignatureError(
         "request_signature_digest_mismatch",
@@ -236,17 +243,14 @@ async function verifyRequestSignature(request, options) {
   return { status: "verified", keyid: jwk.kid, agent_url, verified_at: now };
 }
 function signatureEncodingCandidates(pinned, digestPolicy) {
-  if (!pinned) return ["rfc8941-base64", "legacy-base64url"];
-  if (digestPolicy !== "either") return [pinned];
-  return [pinned, alternateBinaryEncoding(pinned)];
+  if (!pinned) return ["legacy-base64url", "rfc8941-base64"];
+  if (pinned === "rfc8941-base64" || digestPolicy !== "either") return [pinned];
+  return ["legacy-base64url", "rfc8941-base64"];
 }
-function contentDigestEncodingCandidates(pinned, digestPolicy) {
-  if (pinned === "rfc8941-base64" && digestPolicy !== "either") return [pinned];
+function contentDigestEncodingCandidates(pinned) {
+  if (pinned === "rfc8941-base64") return [pinned];
   return ["rfc8941-base64", "legacy-base64url"];
 }
-function alternateBinaryEncoding(encoding) {
-  return encoding === "rfc8941-base64" ? "legacy-base64url" : "rfc8941-base64";
-}
 function jsonRpcProtocolMethods(body) {
   if (!body) return [];
   if (exceedsUnsignedBodyInspectionCap(body)) return [];

package/dist/lib/signing/verifier.mjs

@@ -7,6 +7,7 @@ import {
 } from "./canonicalize.mjs";
 import {
   contentDigestMatches,
+  contentDigestSha256Token,
   contentDigestUsesEncoding,
   requestSigningEncodingForVersion
 } from "./content-digest.mjs";
@@ -84,7 +85,7 @@ async function verifyRequestSignature(request, options) {
       parsedEncoding = candidate;
       break;
     } catch (error) {
-      parseError ??= error;
+      if (parseError === void 0 || candidate === (pinnedBinaryEncoding ?? "rfc8941-base64")) parseError = error;
     }
   }
   if (!parsedSig) throw parseError;
@@ -184,9 +185,16 @@ async function verifyRequestSignature(request, options) {
   }
   if (parsedInput.components.includes("content-digest")) {
     const digestHeader = getHeaderValue(request.headers, "Content-Digest");
-    const encodingMatches = !!digestHeader && contentDigestEncodingCandidates(pinnedBinaryEncoding, options.capability.covers_content_digest).some(
+    const encodingMatches = !!digestHeader && contentDigestEncodingCandidates(pinnedBinaryEncoding).some(
       (candidate) => contentDigestUsesEncoding(digestHeader, candidate)
     );
+    if (digestHeader && !encodingMatches && pinnedBinaryEncoding === "rfc8941-base64" && contentDigestSha256Token(digestHeader) !== void 0) {
+      throw new RequestSignatureError(
+        "request_signature_header_malformed",
+        11,
+        "Content-Digest sha-256 value must use padded standard Base64 for AdCP 3.2+"
+      );
+    }
     if (!digestHeader || !encodingMatches || !contentDigestMatches(digestHeader, request.body ?? "")) {
       throw new RequestSignatureError(
         "request_signature_digest_mismatch",
@@ -228,17 +236,14 @@ async function verifyRequestSignature(request, options) {
   return { status: "verified", keyid: jwk.kid, agent_url, verified_at: now };
 }
 function signatureEncodingCandidates(pinned, digestPolicy) {
-  if (!pinned) return ["rfc8941-base64", "legacy-base64url"];
-  if (digestPolicy !== "either") return [pinned];
-  return [pinned, alternateBinaryEncoding(pinned)];
+  if (!pinned) return ["legacy-base64url", "rfc8941-base64"];
+  if (pinned === "rfc8941-base64" || digestPolicy !== "either") return [pinned];
+  return ["legacy-base64url", "rfc8941-base64"];
 }
-function contentDigestEncodingCandidates(pinned, digestPolicy) {
-  if (pinned === "rfc8941-base64" && digestPolicy !== "either") return [pinned];
+function contentDigestEncodingCandidates(pinned) {
+  if (pinned === "rfc8941-base64") return [pinned];
   return ["rfc8941-base64", "legacy-base64url"];
 }
-function alternateBinaryEncoding(encoding) {
-  return encoding === "rfc8941-base64" ? "legacy-base64url" : "rfc8941-base64";
-}
 function jsonRpcProtocolMethods(body) {
   if (!body) return [];
   if (exceedsUnsignedBodyInspectionCap(body)) return [];

package/dist/lib/testing/compliance/comply.d.mts

@@ -9,7 +9,7 @@
  */
 import type { TestOptions, TestResult, AgentProfile } from '../types.mjs';
 import type { NotApplicableStoryboard, ResolvedBundle } from '../storyboard/compliance.mjs';
-import type { Storyboard, StoryboardResult, StoryboardRunOptions } from '../storyboard/types.mjs';
+import type { AgentEntry, Storyboard, StoryboardContext, StoryboardResult, StoryboardRunOptions } from '../storyboard/types.mjs';
 import type { ComplianceBundleResult, ComplianceTrack, ComplianceFailure, ComplianceResult, ComplianceSummary, AdvisoryObservation, OverallStatus } from './types.mjs';
 import type { VersionEnvelopeMode } from '../../protocols/index.mjs';
 /**
@@ -98,7 +98,113 @@ export interface ComplyOptions extends TestOptions {
     testKitPath?: string;
     /** Scoped hosted stable-line alias for prerelease-backed compliance caches. */
     hostedStableLineAlias?: string;
+    /**
+     * Per-storyboard routing hook. `comply()` grades one agent, so storyboards
+     * that need a second agent (`requires: [multi_agent]`, e.g. the
+     * governance-aware seller scenarios) otherwise skip with
+     * `requirement_unmet`. The hook lets a caller that can supply the other
+     * agents route those storyboards while every other storyboard keeps the
+     * ordinary single-URL run.
+     *
+     * Called once per selected storyboard, after capability discovery,
+     * `required_tools` partitioning and the `timeout_ms` budget check, and
+     * before the storyboard runs. Storyboards whose root capability predicate
+     * (`requires_capability` / `requires_all_capabilities`) the agent under
+     * test does not satisfy are not passed to the hook: they keep their
+     * `not_applicable` verdict. Not consulted in the degraded auth-rejected
+     * path, which runs only storyboards with no `required_tools`. An error the
+     * hook throws propagates out of `comply()`.
+     *
+     * `context.profile` is the agent under test's own `get_adcp_capabilities`
+     * answer: untrusted, agent-controlled input. Do not derive agent URLs or
+     * credentials from it.
+     *
+     * Return:
+     * - `undefined`: run the storyboard as usual against `agentUrl`.
+     * - a {@link ComplyStoryboardRoute}: run it as
+     *   `runStoryboard('', storyboard, { ...runOptions, agents, default_agent, context })`
+     *   and grade the result against the agent under test only (below). The
+     *   result lands in `tracks`, `summary`, `failures`, `storyboards_executed`
+     *   and `bundle_results` like any other run.
+     * - a {@link ComplyStoryboardSkip}: do not run it. `comply()` records the
+     *   same whole-storyboard `requirement_unmet` row the runner emits for an
+     *   unmet `requires:` gate, with `skip.detail` set to the reason (control
+     *   and bidi characters stripped, max 1000 chars) and `skip.requirement:
+     *   'multi_agent'` when the storyboard declares it. Like an unrouted
+     *   `multi_agent` storyboard it is listed in `storyboards_executed` and caps
+     *   its bundle at `partial`.
+     *
+     * Grading of routed results. The agent under test is only credited or
+     * blamed for what it served:
+     * - A failed step served by another routed agent, including that agent's
+     *   discovery failure (routed runs use `discovery_resilient`), becomes a
+     *   `prerequisite_failed` skip: a coverage gap (`partial`), never `failing`.
+     * - If no step served by the agent under test passed, a synthetic
+     *   `agent_under_test_coverage` gap row keeps the bundle from `passing`.
+     * - `failures[].fix_command` for a routed storyboard is a single-URL
+     *   command; re-running it reproduces only the unrouted skip.
+     *
+     * Credential and network isolation, enforced by `comply()`. Caller
+     * configuration errors throw, failing the run:
+     * - `agents[default_agent].url` must be the agent under test (`agentUrl`).
+     * - Every entry that sets `auth` must set a real credential object (a known
+     *   `type` with its secret fields); `null`, `''`, `{}` and the like throw.
+     *   Only an agent-under-test entry may omit `auth`; it then gets the
+     *   run-level `auth` pinned onto it (or the test-kit default if there is
+     *   none). Run-level `auth` is dropped from the routed options, so the
+     *   runner's `entry.auth ?? options.auth` fallback cannot hand it to
+     *   another agent.
+     * - Routing is refused while run-level `headers` are set, because the runner
+     *   sends them to every routed agent.
+     * - A replacement `route.storyboard` must keep the same `id` and grading
+     *   shape (phases, steps, tasks, agent pins, validations, expectations and
+     *   gates); only request payloads and context may change.
+     * - Run-level `transport` (including `trustedFetchFn` / SSRF guards) is
+     *   shared by every routed agent. The hook cannot override it; only `url`,
+     *   `auth` and `transport` (wire protocol) are read from each entry.
+     *
+     * Storyboard content that would forward test-kit credentials is refused as
+     * a skip rather than a throw: `$test_kit.auth` references in storyboard
+     * context, or a step not pinned to an agent-under-test key (unpinned steps
+     * route by protocol) that uses a `from_test_kit` auth directive or a
+     * `$test_kit.auth` reference.
+     *
+     * Known limit: version negotiation (`adcpVersion`, `wireAdcpVersion`,
+     * `versionEnvelope`) is done once against the agent under test and shared
+     * by every routed agent.
+     *
+     * Do not mutate `storyboard`; return a patched copy in `route.storyboard`.
+     */
+    routeStoryboard?: (storyboard: Storyboard, context: ComplyRouteStoryboardContext) => ComplyStoryboardRouting | Promise<ComplyStoryboardRouting>;
+}
+/** Second argument to {@link ComplyOptions.routeStoryboard}. */
+export interface ComplyRouteStoryboardContext {
+    /** The agent under test, as passed to `comply()`. */
+    agent_url: string;
+    /** Capability profile `comply()` discovered for the agent under test. */
+    profile: AgentProfile;
+}
+/** Route one storyboard across several agents. See {@link ComplyOptions.routeStoryboard}. */
+export interface ComplyStoryboardRoute {
+    /** Agents map for `runStoryboard`. `agents[default_agent].url` must be the agent under test. */
+    agents: Record<string, AgentEntry>;
+    /** Key of the agent under test in `agents`. */
+    default_agent: string;
+    /** Initial-context overrides, merged over any run-level context. */
+    context?: StoryboardContext;
+    /**
+     * Storyboard to run in place of the selected one (e.g. a patched copy).
+     * Must keep the same `id` so the result is attributed to the same bundle.
+     */
+    storyboard?: Storyboard;
+}
+/** Record a storyboard as not runnable. See {@link ComplyOptions.routeStoryboard}. */
+export interface ComplyStoryboardSkip {
+    /** Human-readable reason, reported as `skip.detail`. */
+    skip: string;
 }
+/** Return type of {@link ComplyOptions.routeStoryboard}. */
+export type ComplyStoryboardRouting = ComplyStoryboardRoute | ComplyStoryboardSkip | undefined;
 /**
  * Run compliance assessment against an agent.
  *