@adcp/sdk 17.0.0-beta.0 → 17.0.0-beta.1

package/dist/lib/testing/client.js

@@ -641,23 +641,24 @@ async function discoverAgentProfile(client, signal, schemaAdcpVersion) {
   }
   const failure = describeProfileDiscoveryFailure(profile);
   if (!step.passed || failure) {
-    const evidence = { ...step, ...failure ?? {}, passed: false, duration_ms: step.duration_ms };
-    evidence.error = (0, import_redact_credential_patterns.redactCredentialPatterns)(evidence.error ?? "Agent discovery failed", false).slice(
+    const evidence2 = { ...step, ...failure ?? {}, passed: false, duration_ms: step.duration_ms };
+    evidence2.error = (0, import_redact_credential_patterns.redactCredentialPatterns)(evidence2.error ?? "Agent discovery failed", false).slice(
       0,
       4096
     );
-    profile.capabilities_failure = evidence;
+    profile.capabilities_failure = evidence2;
   }
   if (!step.passed) step.error = (0, import_redact_credential_patterns.redactCredentialPatterns)(step.error ?? "Agent discovery failed", false);
   if (!failure && step.passed && (scopeKey === void 0 || scopeKey === client.getCapabilityEvidenceScope().scopeKey)) {
     seedTestClientSigningCapability(client, profile, schemaAdcpVersion);
   }
+  const evidence = step.passed && !failure ? { ...step } : void 0;
   if (step.passed && !failure) {
     delete step.request;
     delete step.response_record;
     delete step.adcp_error;
   }
-  return { profile, step, ...caughtError !== void 0 && { caughtError } };
+  return { profile, step, ...caughtError !== void 0 && { caughtError }, ...evidence && { evidence } };
 }
 async function discoverAgentCapabilities(client, profile, options) {
   const steps = [];
@@ -876,7 +877,7 @@ function validateResponseSchema(toolName, data, responseAdcpVersion) {
       warnings: [`No Zod schema registered for "${toolName}" \u2014 validation skipped`]
     };
   }
-  const compatData = data && typeof data === "object" && !Array.isArray(data) ? (0, import_envelope_status_compat.injectLegacyEnvelopeStatus)(data, { toolName }) : data;
+  const compatData = data && typeof data === "object" && !Array.isArray(data) ? (0, import_envelope_status_compat.injectLegacyEnvelopeStatus)(data, { toolName, adcpVersion: responseAdcpVersion }) : data;
   const result = schema.safeParse((0, import_response_schemas.prepareResponseForSchemaValidation)(toolName, compatData, responseAdcpVersion));
   if (result.success) {
     return {

package/dist/lib/testing/client.mjs

@@ -599,23 +599,24 @@ async function discoverAgentProfile(client, signal, schemaAdcpVersion) {
   }
   const failure = describeProfileDiscoveryFailure(profile);
   if (!step.passed || failure) {
-    const evidence = { ...step, ...failure ?? {}, passed: false, duration_ms: step.duration_ms };
-    evidence.error = redactCredentialPatterns(evidence.error ?? "Agent discovery failed", false).slice(
+    const evidence2 = { ...step, ...failure ?? {}, passed: false, duration_ms: step.duration_ms };
+    evidence2.error = redactCredentialPatterns(evidence2.error ?? "Agent discovery failed", false).slice(
       0,
       4096
     );
-    profile.capabilities_failure = evidence;
+    profile.capabilities_failure = evidence2;
   }
   if (!step.passed) step.error = redactCredentialPatterns(step.error ?? "Agent discovery failed", false);
   if (!failure && step.passed && (scopeKey === void 0 || scopeKey === client.getCapabilityEvidenceScope().scopeKey)) {
     seedTestClientSigningCapability(client, profile, schemaAdcpVersion);
   }
+  const evidence = step.passed && !failure ? { ...step } : void 0;
   if (step.passed && !failure) {
     delete step.request;
     delete step.response_record;
     delete step.adcp_error;
   }
-  return { profile, step, ...caughtError !== void 0 && { caughtError } };
+  return { profile, step, ...caughtError !== void 0 && { caughtError }, ...evidence && { evidence } };
 }
 async function discoverAgentCapabilities(client, profile, options) {
   const steps = [];
@@ -834,7 +835,7 @@ function validateResponseSchema(toolName, data, responseAdcpVersion) {
       warnings: [`No Zod schema registered for "${toolName}" \u2014 validation skipped`]
     };
   }
-  const compatData = data && typeof data === "object" && !Array.isArray(data) ? injectLegacyEnvelopeStatus(data, { toolName }) : data;
+  const compatData = data && typeof data === "object" && !Array.isArray(data) ? injectLegacyEnvelopeStatus(data, { toolName, adcpVersion: responseAdcpVersion }) : data;
   const result = schema.safeParse(prepareResponseForSchemaValidation(toolName, compatData, responseAdcpVersion));
   if (result.success) {
     return {

package/dist/lib/testing/storyboard/agent-routing.d.mts

@@ -1,5 +1,5 @@
 import type { TestClient } from '../client.mjs';
-import type { AgentProfile } from '../types.mjs';
+import type { AgentProfile, TestStepResult } from '../types.mjs';
 import { type AdcpProtocol } from '../../utils/capabilities.mjs';
 import type { AgentEntry, Storyboard, StoryboardRunOptions, StoryboardStep } from './types.mjs';
 /** Storyboard applicability is any-of; it does not authorize individual steps. */
@@ -18,6 +18,8 @@ export interface AgentRoutingContext {
     clients: Map<string, TestClient>;
     /** Per-agent discovered profile (`get_adcp_capabilities` result). */
     profiles: Map<string, AgentProfile>;
+    /** Actual discovery exchanges, retained separately from compact rollup steps. */
+    discoverySteps?: ReadonlyMap<string, TestStepResult>;
     /** Protocol → keys of agents that claim it. */
     protocolIndex: Map<AdcpProtocol, string[]>;
     /** Resolved (key → URL) for echo on the storyboard result. */
@@ -41,7 +43,8 @@ export declare class DiscoveryFailure extends Error {
     readonly agentKey: string;
     readonly url: string;
     readonly underlying: string;
-    constructor(message: string, agentKey: string, url: string, underlying: string);
+    readonly step?: TestStepResult | undefined;
+    constructor(message: string, agentKey: string, url: string, underlying: string, step?: TestStepResult | undefined);
 }
 /**
  * Discover every agent in the map in parallel and build the routing index.

package/dist/lib/testing/storyboard/agent-routing.d.ts

@@ -1,5 +1,5 @@
 import type { TestClient } from '../client';
-import type { AgentProfile } from '../types';
+import type { AgentProfile, TestStepResult } from '../types';
 import { type AdcpProtocol } from '../../utils/capabilities';
 import type { AgentEntry, Storyboard, StoryboardRunOptions, StoryboardStep } from './types';
 /** Storyboard applicability is any-of; it does not authorize individual steps. */
@@ -18,6 +18,8 @@ export interface AgentRoutingContext {
     clients: Map<string, TestClient>;
     /** Per-agent discovered profile (`get_adcp_capabilities` result). */
     profiles: Map<string, AgentProfile>;
+    /** Actual discovery exchanges, retained separately from compact rollup steps. */
+    discoverySteps?: ReadonlyMap<string, TestStepResult>;
     /** Protocol → keys of agents that claim it. */
     protocolIndex: Map<AdcpProtocol, string[]>;
     /** Resolved (key → URL) for echo on the storyboard result. */
@@ -41,7 +43,8 @@ export declare class DiscoveryFailure extends Error {
     readonly agentKey: string;
     readonly url: string;
     readonly underlying: string;
-    constructor(message: string, agentKey: string, url: string, underlying: string);
+    readonly step?: TestStepResult | undefined;
+    constructor(message: string, agentKey: string, url: string, underlying: string, step?: TestStepResult | undefined);
 }
 /**
  * Discover every agent in the map in parallel and build the routing index.

package/dist/lib/testing/storyboard/agent-routing.js

@@ -127,16 +127,18 @@ class RoutingError extends Error {
   hint;
 }
 class DiscoveryFailure extends Error {
-  constructor(message, agentKey, url, underlying) {
+  constructor(message, agentKey, url, underlying, step) {
     super(message);
     this.agentKey = agentKey;
     this.url = url;
     this.underlying = underlying;
+    this.step = step;
     this.name = "DiscoveryFailure";
   }
   agentKey;
   url;
   underlying;
+  step;
 }
 async function discoverAgentRouting(options) {
   const agents = options.agents;
@@ -150,6 +152,7 @@ async function discoverAgentRouting(options) {
     agentMap[key] = entry.url;
   }
   const profiles = /* @__PURE__ */ new Map();
+  const discoverySteps = /* @__PURE__ */ new Map();
   const discoveryFailures = [];
   if (options._routingProfiles) {
     for (const [key] of entries) {
@@ -162,6 +165,7 @@ async function discoverAgentRouting(options) {
     return {
       clients,
       profiles,
+      discoverySteps,
       protocolIndex: buildProtocolIndex(profiles),
       agentMap,
       discoveryFailures
@@ -171,8 +175,8 @@ async function discoverAgentRouting(options) {
     entries.map(async ([key, entry]) => {
       const perAgentOptions = buildAgentOptions(entry, options);
       try {
-        const { profile, step } = await (0, import_client.getOrDiscoverStoryboardProfile)(clients.get(key), perAgentOptions);
-        return { key, profile, step };
+        const { profile, step, evidence } = await (0, import_client.getOrDiscoverStoryboardProfile)(clients.get(key), perAgentOptions);
+        return { key, profile, step, evidence };
       } catch (err) {
         return {
           key,
@@ -180,6 +184,7 @@ async function discoverAgentRouting(options) {
           step: {
             step: "Discover agent capabilities",
             passed: false,
+            duration_ms: 0,
             error: scrubAuthSecrets(err?.message || String(err))
           }
         };
@@ -187,6 +192,7 @@ async function discoverAgentRouting(options) {
     })
   );
   for (const r of discoveryResults) {
+    discoverySteps.set(r.key, "evidence" in r && r.evidence ? r.evidence : r.step);
     if (!r.profile || r.step.passed === false) {
       const rawDetail = scrubAuthSecrets(r.step.error ?? "Discovery returned no profile.");
       const detail = rawDetail.length > 512 ? `${rawDetail.slice(0, 512)} \u2026(truncated)` : rawDetail;
@@ -194,7 +200,7 @@ async function discoverAgentRouting(options) {
       const message = resilient ? baseMessage : `${baseMessage}
 
 If this is hello-cluster / exploratory CI and you want unrelated storyboards to complete despite this failure, set \`StoryboardRunOptions.discovery_resilient: true\`. Do NOT set it in production \u2014 a topology with a broken tenant is a hard misconfiguration there.`;
-      const failure = new DiscoveryFailure(message, r.key, agents[r.key].url, detail);
+      const failure = new DiscoveryFailure(message, r.key, agents[r.key].url, detail, { ...r.step, error: detail });
       if (!resilient) throw failure;
       discoveryFailures.push(failure);
       continue;
@@ -204,6 +210,7 @@ If this is hello-cluster / exploratory CI and you want unrelated storyboards to
   return {
     clients,
     profiles,
+    discoverySteps,
     protocolIndex: buildProtocolIndex(profiles),
     agentMap,
     discoveryFailures

package/dist/lib/testing/storyboard/agent-routing.mjs

@@ -95,16 +95,18 @@ class RoutingError extends Error {
   hint;
 }
 class DiscoveryFailure extends Error {
-  constructor(message, agentKey, url, underlying) {
+  constructor(message, agentKey, url, underlying, step) {
     super(message);
     this.agentKey = agentKey;
     this.url = url;
     this.underlying = underlying;
+    this.step = step;
     this.name = "DiscoveryFailure";
   }
   agentKey;
   url;
   underlying;
+  step;
 }
 async function discoverAgentRouting(options) {
   const agents = options.agents;
@@ -118,6 +120,7 @@ async function discoverAgentRouting(options) {
     agentMap[key] = entry.url;
   }
   const profiles = /* @__PURE__ */ new Map();
+  const discoverySteps = /* @__PURE__ */ new Map();
   const discoveryFailures = [];
   if (options._routingProfiles) {
     for (const [key] of entries) {
@@ -130,6 +133,7 @@ async function discoverAgentRouting(options) {
     return {
       clients,
       profiles,
+      discoverySteps,
       protocolIndex: buildProtocolIndex(profiles),
       agentMap,
       discoveryFailures
@@ -139,8 +143,8 @@ async function discoverAgentRouting(options) {
     entries.map(async ([key, entry]) => {
       const perAgentOptions = buildAgentOptions(entry, options);
       try {
-        const { profile, step } = await getOrDiscoverStoryboardProfile(clients.get(key), perAgentOptions);
-        return { key, profile, step };
+        const { profile, step, evidence } = await getOrDiscoverStoryboardProfile(clients.get(key), perAgentOptions);
+        return { key, profile, step, evidence };
       } catch (err) {
         return {
           key,
@@ -148,6 +152,7 @@ async function discoverAgentRouting(options) {
           step: {
             step: "Discover agent capabilities",
             passed: false,
+            duration_ms: 0,
             error: scrubAuthSecrets(err?.message || String(err))
           }
         };
@@ -155,6 +160,7 @@ async function discoverAgentRouting(options) {
     })
   );
   for (const r of discoveryResults) {
+    discoverySteps.set(r.key, "evidence" in r && r.evidence ? r.evidence : r.step);
     if (!r.profile || r.step.passed === false) {
       const rawDetail = scrubAuthSecrets(r.step.error ?? "Discovery returned no profile.");
       const detail = rawDetail.length > 512 ? `${rawDetail.slice(0, 512)} \u2026(truncated)` : rawDetail;
@@ -162,7 +168,7 @@ async function discoverAgentRouting(options) {
       const message = resilient ? baseMessage : `${baseMessage}
 
 If this is hello-cluster / exploratory CI and you want unrelated storyboards to complete despite this failure, set \`StoryboardRunOptions.discovery_resilient: true\`. Do NOT set it in production \u2014 a topology with a broken tenant is a hard misconfiguration there.`;
-      const failure = new DiscoveryFailure(message, r.key, agents[r.key].url, detail);
+      const failure = new DiscoveryFailure(message, r.key, agents[r.key].url, detail, { ...r.step, error: detail });
       if (!resilient) throw failure;
       discoveryFailures.push(failure);
       continue;
@@ -172,6 +178,7 @@ If this is hello-cluster / exploratory CI and you want unrelated storyboards to
   return {
     clients,
     profiles,
+    discoverySteps,
     protocolIndex: buildProtocolIndex(profiles),
     agentMap,
     discoveryFailures

package/dist/lib/testing/storyboard/context.d.mts

@@ -10,12 +10,22 @@
  * (context_outputs/context_inputs) while still enabling stateful flows.
  */
 import type { StoryboardContext, ContextOutput, ContextInput, ContextProvenanceEntry } from './types.mjs';
-type ContextExtractor = (data: unknown) => Record<string, unknown>;
+/**
+ * `adcpVersion` is the release the step was requested at. Media-buy mutation
+ * extractors use it to tell a 3.1+ task-envelope `status` from a 3.0
+ * lifecycle `status` when the response does not echo its version.
+ */
+type ContextExtractor = (data: unknown, adcpVersion?: string) => Record<string, unknown>;
 export declare const CONTEXT_EXTRACTORS: Record<string, ContextExtractor>;
 /**
  * Extract context values from a task response.
+ *
+ * @param adcpVersion - Optional AdCP release the request was sent at. Used
+ *   only when the response does not echo `adcp_version`, to read a
+ *   create/update top-level `status` as the 3.1+ task status rather than a
+ *   3.0 media-buy lifecycle.
  */
-export declare function extractContext(taskName: string, data: unknown): Record<string, unknown>;
+export declare function extractContext(taskName: string, data: unknown, adcpVersion?: string): Record<string, unknown>;
 /**
  * Propagate the alias cache from one context to another — call after
  * shallow-cloning context between storyboard steps so replay tests
@@ -132,7 +142,7 @@ export interface ContextWriteResult {
  * tagging it as a convention-based extraction. `response_path` is absent
  * for convention extractors — they're hardcoded functions, not YAML paths.
  */
-export declare function extractContextWithProvenance(taskName: string, data: unknown, stepId: string): ContextWriteResult;
+export declare function extractContextWithProvenance(taskName: string, data: unknown, stepId: string, adcpVersion?: string): ContextWriteResult;
 /**
  * Like `applyContextOutputs`, but also returns provenance for each written
  * key carrying the YAML `response_path` so diagnostics can cite it verbatim.

package/dist/lib/testing/storyboard/context.d.ts

@@ -10,12 +10,22 @@
  * (context_outputs/context_inputs) while still enabling stateful flows.
  */
 import type { StoryboardContext, ContextOutput, ContextInput, ContextProvenanceEntry } from './types';
-type ContextExtractor = (data: unknown) => Record<string, unknown>;
+/**
+ * `adcpVersion` is the release the step was requested at. Media-buy mutation
+ * extractors use it to tell a 3.1+ task-envelope `status` from a 3.0
+ * lifecycle `status` when the response does not echo its version.
+ */
+type ContextExtractor = (data: unknown, adcpVersion?: string) => Record<string, unknown>;
 export declare const CONTEXT_EXTRACTORS: Record<string, ContextExtractor>;
 /**
  * Extract context values from a task response.
+ *
+ * @param adcpVersion - Optional AdCP release the request was sent at. Used
+ *   only when the response does not echo `adcp_version`, to read a
+ *   create/update top-level `status` as the 3.1+ task status rather than a
+ *   3.0 media-buy lifecycle.
  */
-export declare function extractContext(taskName: string, data: unknown): Record<string, unknown>;
+export declare function extractContext(taskName: string, data: unknown, adcpVersion?: string): Record<string, unknown>;
 /**
  * Propagate the alias cache from one context to another — call after
  * shallow-cloning context between storyboard steps so replay tests
@@ -132,7 +142,7 @@ export interface ContextWriteResult {
  * tagging it as a convention-based extraction. `response_path` is absent
  * for convention extractors — they're hardcoded functions, not YAML paths.
  */
-export declare function extractContextWithProvenance(taskName: string, data: unknown, stepId: string): ContextWriteResult;
+export declare function extractContextWithProvenance(taskName: string, data: unknown, stepId: string, adcpVersion?: string): ContextWriteResult;
 /**
  * Like `applyContextOutputs`, but also returns provenance for each written
  * key carrying the YAML `response_path` so diagnostics can cite it verbatim.

package/dist/lib/testing/storyboard/context.js

@@ -59,14 +59,19 @@ function asRecord(value) {
 function readMediaBuyStatus(record) {
   return (0, import_media_buy_status.getAuthoritativeMediaBuyStatus)(record);
 }
-function readMediaBuyFields(data) {
+function readMediaBuyFields(data, adcpVersion) {
   const outer = asRecord(data);
   const nested = asRecord(outer?.media_buy);
   return {
     mediaBuyId: nested?.media_buy_id ?? outer?.media_buy_id,
-    status: readMediaBuyStatus(nested) ?? readMediaBuyStatus(outer)
+    status: readMediaBuyStatus(nested) ?? readMediaBuyStatus(withRequestedVersion(outer, adcpVersion))
   };
 }
+function withRequestedVersion(record, adcpVersion) {
+  if (!record || !adcpVersion) return record;
+  if (typeof record.adcp_version === "string" || typeof record.adcp_major_version === "number") return record;
+  return { ...record, adcp_version: adcpVersion };
+}
 function readProposalFields(proposal) {
   if (!proposal) return {};
   const extracted = {};
@@ -181,15 +186,15 @@ const CONTEXT_EXTRACTORS = {
   control_media_buy(data) {
     return readCompactMediaBuyFields(data);
   },
-  create_media_buy(data) {
-    const { mediaBuyId, status } = readMediaBuyFields(data);
+  create_media_buy(data, adcpVersion) {
+    const { mediaBuyId, status } = readMediaBuyFields(data, adcpVersion);
     const extracted = {};
     if (mediaBuyId) extracted.media_buy_id = mediaBuyId;
     if (status) extracted.media_buy_status = status;
     return extracted;
   },
-  update_media_buy(data) {
-    const { mediaBuyId, status } = readMediaBuyFields(data);
+  update_media_buy(data, adcpVersion) {
+    const { mediaBuyId, status } = readMediaBuyFields(data, adcpVersion);
     const extracted = {};
     if (mediaBuyId) extracted.media_buy_id = mediaBuyId;
     if (status) extracted.media_buy_status = status;
@@ -381,11 +386,11 @@ const CONTEXT_EXTRACTORS = {
     return extracted;
   }
 };
-function extractContext(taskName, data) {
+function extractContext(taskName, data, adcpVersion) {
   const extractor = CONTEXT_EXTRACTORS[taskName];
   if (!extractor) return {};
   try {
-    return extractor(data);
+    return extractor(data, adcpVersion);
   } catch {
     return {};
   }
@@ -482,8 +487,8 @@ function applyContextOutputs(data, outputs) {
   }
   return result;
 }
-function extractContextWithProvenance(taskName, data, stepId) {
-  const values = extractContext(taskName, data);
+function extractContextWithProvenance(taskName, data, stepId, adcpVersion) {
+  const values = extractContext(taskName, data, adcpVersion);
   const clearGroups = (() => {
     const response = asRecord(data);
     switch (taskName) {

package/dist/lib/testing/storyboard/context.mjs

@@ -26,14 +26,19 @@ function asRecord(value) {
 function readMediaBuyStatus(record) {
   return getAuthoritativeMediaBuyStatus(record);
 }
-function readMediaBuyFields(data) {
+function readMediaBuyFields(data, adcpVersion) {
   const outer = asRecord(data);
   const nested = asRecord(outer?.media_buy);
   return {
     mediaBuyId: nested?.media_buy_id ?? outer?.media_buy_id,
-    status: readMediaBuyStatus(nested) ?? readMediaBuyStatus(outer)
+    status: readMediaBuyStatus(nested) ?? readMediaBuyStatus(withRequestedVersion(outer, adcpVersion))
   };
 }
+function withRequestedVersion(record, adcpVersion) {
+  if (!record || !adcpVersion) return record;
+  if (typeof record.adcp_version === "string" || typeof record.adcp_major_version === "number") return record;
+  return { ...record, adcp_version: adcpVersion };
+}
 function readProposalFields(proposal) {
   if (!proposal) return {};
   const extracted = {};
@@ -148,15 +153,15 @@ const CONTEXT_EXTRACTORS = {
   control_media_buy(data) {
     return readCompactMediaBuyFields(data);
   },
-  create_media_buy(data) {
-    const { mediaBuyId, status } = readMediaBuyFields(data);
+  create_media_buy(data, adcpVersion) {
+    const { mediaBuyId, status } = readMediaBuyFields(data, adcpVersion);
     const extracted = {};
     if (mediaBuyId) extracted.media_buy_id = mediaBuyId;
     if (status) extracted.media_buy_status = status;
     return extracted;
   },
-  update_media_buy(data) {
-    const { mediaBuyId, status } = readMediaBuyFields(data);
+  update_media_buy(data, adcpVersion) {
+    const { mediaBuyId, status } = readMediaBuyFields(data, adcpVersion);
     const extracted = {};
     if (mediaBuyId) extracted.media_buy_id = mediaBuyId;
     if (status) extracted.media_buy_status = status;
@@ -348,11 +353,11 @@ const CONTEXT_EXTRACTORS = {
     return extracted;
   }
 };
-function extractContext(taskName, data) {
+function extractContext(taskName, data, adcpVersion) {
   const extractor = CONTEXT_EXTRACTORS[taskName];
   if (!extractor) return {};
   try {
-    return extractor(data);
+    return extractor(data, adcpVersion);
   } catch {
     return {};
   }
@@ -449,8 +454,8 @@ function applyContextOutputs(data, outputs) {
   }
   return result;
 }
-function extractContextWithProvenance(taskName, data, stepId) {
-  const values = extractContext(taskName, data);
+function extractContextWithProvenance(taskName, data, stepId, adcpVersion) {
+  const values = extractContext(taskName, data, adcpVersion);
   const clearGroups = (() => {
     const response = asRecord(data);
     switch (taskName) {