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

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) {

package/dist/lib/testing/storyboard/request-signing/vector-loader.d.mts

@@ -34,6 +34,8 @@ export declare function signingProfileForAdcpVersion(version?: string): '3.2' |
 export declare function loadRequestSigningVectors(options?: LoadVectorsOptions): LoadedVectors;
 /** Load only the shared signing keyset, without requiring the grader vectors. */
 export declare function loadRequestSigningKeys(options?: LoadVectorsOptions): TestKeyset;
+/** Refresh only the signing fixtures belonging to a changed custom compliance root. */
+export declare function invalidateRequestSigningVectorCache(complianceDir: string): void;
 /** Test-only: clear the memoization cache so a fresh cache path is reread. */
 export declare function __resetVectorCache(): void;
 /** Where the A2A operation-resolution vectors came from. */

package/dist/lib/testing/storyboard/request-signing/vector-loader.d.ts

@@ -34,6 +34,8 @@ export declare function signingProfileForAdcpVersion(version?: string): '3.2' |
 export declare function loadRequestSigningVectors(options?: LoadVectorsOptions): LoadedVectors;
 /** Load only the shared signing keyset, without requiring the grader vectors. */
 export declare function loadRequestSigningKeys(options?: LoadVectorsOptions): TestKeyset;
+/** Refresh only the signing fixtures belonging to a changed custom compliance root. */
+export declare function invalidateRequestSigningVectorCache(complianceDir: string): void;
 /** Test-only: clear the memoization cache so a fresh cache path is reread. */
 export declare function __resetVectorCache(): void;
 /** Where the A2A operation-resolution vectors came from. */

package/dist/lib/testing/storyboard/request-signing/vector-loader.js

@@ -22,6 +22,7 @@ __export(vector_loader_exports, {
   A2A_VECTORS_UNAVAILABLE_MESSAGE: () => A2A_VECTORS_UNAVAILABLE_MESSAGE,
   __resetVectorCache: () => __resetVectorCache,
   findKey: () => findKey,
+  invalidateRequestSigningVectorCache: () => invalidateRequestSigningVectorCache,
   loadA2aOperationResolutionVectors: () => loadA2aOperationResolutionVectors,
   loadRequestSigningKeys: () => loadRequestSigningKeys,
   loadRequestSigningVectors: () => loadRequestSigningVectors,
@@ -95,6 +96,15 @@ function loadRequestSigningKeys(options = {}) {
   const cacheDir = (0, import_compliance.getComplianceCacheDir)(options);
   return loadKeys((0, import_path.join)(cacheDir, "test-vectors", "request-signing", "keys.json"));
 }
+function invalidateRequestSigningVectorCache(complianceDir) {
+  const sourceDir = (0, import_path.resolve)(complianceDir, "test-vectors", "request-signing");
+  for (const key of VECTOR_CACHE.keys()) {
+    if ((0, import_path.resolve)(key) === sourceDir) VECTOR_CACHE.delete(key);
+  }
+  for (const key of A2A_VECTOR_CACHE.keys()) {
+    if ((0, import_path.resolve)(key) === (0, import_path.join)(sourceDir, "a2a")) A2A_VECTOR_CACHE.delete(key);
+  }
+}
 function __resetVectorCache() {
   VECTOR_CACHE.clear();
   A2A_VECTOR_CACHE.clear();
@@ -384,6 +394,7 @@ function strArray(v, where) {
   A2A_VECTORS_UNAVAILABLE_MESSAGE,
   __resetVectorCache,
   findKey,
+  invalidateRequestSigningVectorCache,
   loadA2aOperationResolutionVectors,
   loadRequestSigningKeys,
   loadRequestSigningVectors,

package/dist/lib/testing/storyboard/request-signing/vector-loader.mjs

@@ -69,6 +69,15 @@ function loadRequestSigningKeys(options = {}) {
   const cacheDir = getComplianceCacheDir(options);
   return loadKeys(join(cacheDir, "test-vectors", "request-signing", "keys.json"));
 }
+function invalidateRequestSigningVectorCache(complianceDir) {
+  const sourceDir = resolve(complianceDir, "test-vectors", "request-signing");
+  for (const key of VECTOR_CACHE.keys()) {
+    if (resolve(key) === sourceDir) VECTOR_CACHE.delete(key);
+  }
+  for (const key of A2A_VECTOR_CACHE.keys()) {
+    if (resolve(key) === join(sourceDir, "a2a")) A2A_VECTOR_CACHE.delete(key);
+  }
+}
 function __resetVectorCache() {
   VECTOR_CACHE.clear();
   A2A_VECTOR_CACHE.clear();
@@ -357,6 +366,7 @@ export {
   A2A_VECTORS_UNAVAILABLE_MESSAGE,
   __resetVectorCache,
   findKey,
+  invalidateRequestSigningVectorCache,
   loadA2aOperationResolutionVectors,
   loadRequestSigningKeys,
   loadRequestSigningVectors,

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

@@ -684,7 +684,7 @@ function remapTaskCompletionOutputs(outputs) {
     return o;
   });
 }
-async function resolveTaskCompletionOutputs(taskResult, outputs, client, webhookReceiver, originatingTaskName) {
+async function resolveTaskCompletionOutputs(taskResult, outputs, client, webhookReceiver, originatingTaskName, responseAdcpVersion) {
   const hasTaskCompletionPath = outputs.some(
     (o) => typeof o.path === "string" && o.path.startsWith(TASK_COMPLETION_PATH_PREFIX)
   );
@@ -737,7 +737,10 @@ async function resolveTaskCompletionOutputs(taskResult, outputs, client, webhook
     if (winner.kind === "poll") {
       const polled = winner.result;
       if (polled.success === false) return { attempted: true, taskFailed: true };
-      return { attempted: true, data: normalizeTaskCompletionData(polled.data, originatingTaskName) };
+      return {
+        attempted: true,
+        data: normalizeTaskCompletionData(polled.data, originatingTaskName, responseAdcpVersion)
+      };
     }
     const waitResult = winner.result;
     if (waitResult.timed_out) {
@@ -745,7 +748,10 @@ async function resolveTaskCompletionOutputs(taskResult, outputs, client, webhook
     }
     const webhookBody = waitResult.webhook.body;
     if (webhookBody?.status === "completed") {
-      return { attempted: true, data: normalizeTaskCompletionData(webhookBody.result, originatingTaskName) };
+      return {
+        attempted: true,
+        data: normalizeTaskCompletionData(webhookBody.result, originatingTaskName, responseAdcpVersion)
+      };
     }
     return { attempted: true, taskFailed: true };
   } catch {
@@ -754,18 +760,19 @@ async function resolveTaskCompletionOutputs(taskResult, outputs, client, webhook
     if (timer) clearTimeout(timer);
   }
 }
-function normalizeTaskCompletionData(data, taskName) {
+function normalizeTaskCompletionData(data, taskName, adcpVersion) {
   if (data == null || typeof data !== "object" || Array.isArray(data)) return data;
   const original = data;
-  const compat = (0, import_envelope_status_compat.injectLegacyEnvelopeStatus)(original, { toolName: taskName });
+  const compatOptions = { toolName: taskName, adcpVersion };
+  const compat = (0, import_envelope_status_compat.injectLegacyEnvelopeStatus)(original, compatOptions);
   if (!("status" in original) && "status" in compat) {
     const { status: _status, ...rest } = compat;
-    return (0, import_envelope_status_compat.normalizeLegacyMediaBuyStatusForReturn)(rest, { toolName: taskName });
+    return (0, import_envelope_status_compat.normalizeLegacyMediaBuyStatusForReturn)(rest, compatOptions);
   }
   if ((taskName === "create_media_buy" || taskName === "update_media_buy") && typeof original.status === "string" && compat.status === "completed" && typeof compat.media_buy_status === "string") {
-    return (0, import_envelope_status_compat.normalizeLegacyMediaBuyStatusForReturn)({ ...compat, status: original.status }, { toolName: taskName });
+    return (0, import_envelope_status_compat.normalizeLegacyMediaBuyStatusForReturn)({ ...compat, status: original.status }, compatOptions);
   }
-  return (0, import_envelope_status_compat.normalizeLegacyMediaBuyStatusForReturn)(compat, { toolName: taskName });
+  return (0, import_envelope_status_compat.normalizeLegacyMediaBuyStatusForReturn)(compat, compatOptions);
 }
 function readEnvIntOrDefault(value, fallback) {
   if (!value) return fallback;
@@ -1903,9 +1910,10 @@ async function prepareStoryboardFixturesBody(agentUrl, storyboard, options) {
     options = snapshotPreparationOptions(options);
   }
   const callerOwnsClients = (0, import_client.hasTestClientScope)();
-  const preparationOptions = resolvePreparationRouteOptions(agentUrls[0], options);
+  const runOptions = options;
+  const preparationOptions = resolvePreparationRouteOptions(agentUrls[0], runOptions);
   const resolution = (0, import_client.getOrCreateClientResolution)(agentUrls[0], preparationOptions);
-  const client = resolution.client;
+  let client = resolution.client;
   const finishPreparation = (seeding, disposition) => {
     if (!scopeStillMatches()) {
       return refusePreparation(driftRefusal, seeding ?? void 0);
@@ -1915,6 +1923,45 @@ async function prepareStoryboardFixturesBody(agentUrl, storyboard, options) {
   options = preparationOptions;
   try {
     let profile = options._profile;
+    let discoveryStep;
+    let routingContext;
+    const failDiscovery = (step, failedProfile) => {
+      const failed = buildDiscoveryFailedResult(agentUrls, storyboard, step, failedProfile);
+      return finishPreparation(
+        { phase: failed.phases[0], allPassed: false, passedCount: 0, failedCount: 1 },
+        { status: "failed", detail: step.error ?? "agent discovery failed before fixture preparation" }
+      );
+    };
+    if (runOptions.agents && (storyboardCapabilityPredicates(storyboard).length > 0 || storyboard.required_tools?.length || storyboard.required_any_of_tools?.length)) {
+      try {
+        validateAgentsMap(agentUrl, storyboard, runOptions);
+        routingContext = await (0, import_agent_routing.buildRoutingContext)(storyboard, { ...runOptions, discovery_resilient: false });
+      } catch (error) {
+        const failedStep = error instanceof import_agent_routing.DiscoveryFailure ? error.step : void 0;
+        return await failDiscovery({
+          ...failedStep,
+          step: failedStep?.step ?? "Discover preparation topology",
+          passed: false,
+          duration_ms: failedStep?.duration_ms ?? 0,
+          error: (0, import_oauth_metadata_graph.redactOAuthUrlsInText)(
+            error instanceof import_agent_routing.DiscoveryFailure ? `Discovery failed for agent "${error.agentKey}" (${(0, import_oauth_metadata_graph.redactOAuthUrlForOutput)(error.url)}): ${error.underlying}` : error instanceof Error ? error.message : String(error)
+          )
+        });
+      }
+      for (const routeProfile of routingContext.profiles.values()) {
+        const failure = (0, import_client.describeProfileDiscoveryFailure)(
+          routeProfile,
+          runOptions._requireValidCapabilityEvidence === true,
+          runOptions._allowCapabilityDiagnostic === true
+        );
+        if (failure) return await failDiscovery(failure, routeProfile);
+      }
+      const firstKey = Object.keys(runOptions.agents)[0];
+      profile = routingContext.profiles.get(firstKey);
+      client = routingContext.clients.get(firstKey);
+      discoveryStep = routingContext.discoverySteps?.get(firstKey);
+      options = { ...options, _profile: profile, agentTools: (0, import_agent_routing.normalizeAgentToolNames)(profile.tools) };
+    }
     const suppliedFailure = profile && (0, import_client.describeProfileDiscoveryFailure)(
       profile,
       options._requireValidCapabilityEvidence === true,
@@ -1927,8 +1974,9 @@ async function prepareStoryboardFixturesBody(agentUrl, storyboard, options) {
         { status: "failed", detail: suppliedFailure.error ?? "agent discovery failed" }
       );
     }
-    if (!profile && !resolution.reusedShared) {
+    if (!profile) {
       const discovered = await (0, import_client.getOrDiscoverStoryboardProfile)(client, options);
+      discoveryStep = discovered.evidence ?? discovered.step;
       if (discovered.step.passed === false) {
         const failed = buildDiscoveryFailedResult(agentUrls, storyboard, discovered.step, discovered.profile);
         return await finishPreparation(
@@ -1949,6 +1997,80 @@ async function prepareStoryboardFixturesBody(agentUrl, storyboard, options) {
       };
     }
     if (!scopeStillMatches()) return await refusePreparation(driftRefusal);
+    let capabilityUnmet;
+    const applicabilityTools = routingContext ? [...new Set([...routingContext.profiles.values()].flatMap((p) => (0, import_agent_routing.normalizeAgentToolNames)(p.tools) ?? []))] : options.agentTools;
+    try {
+      if (routingContext && runOptions.agents) {
+        const dispatch = createRoutingDispatcher(routingContext, runOptions, runOptions.agents);
+        const defaultProfile = runOptions.default_agent ? routingContext.profiles.get(runOptions.default_agent) : void 0;
+        const rootDetails = storyboard.phases.flatMap(
+          (phase) => phase.steps.filter((step) => step.task !== import_loader.VALIDATION_ONLY_TASK).map((step) => {
+            const selected = dispatch.nextFor(step);
+            const owner = runOptions.default_agent ? defaultProfile : selected.profile;
+            return evaluateStoryboardCapabilityGates(
+              storyboard,
+              owner,
+              (0, import_agent_routing.normalizeAgentToolNames)(owner?.tools),
+              runOptions.adcpVersion
+            );
+          })
+        );
+        capabilityUnmet = rootDetails.length > 0 && rootDetails.every((detail) => detail !== null) ? rootDetails[0] : null;
+      } else {
+        capabilityUnmet = evaluateStoryboardCapabilityGates(
+          storyboard,
+          profile,
+          options.agentTools,
+          options.adcpVersion
+        );
+      }
+    } catch (error) {
+      return await failDiscovery({
+        step: "Resolve preparation routes",
+        passed: false,
+        duration_ms: 0,
+        error: (0, import_oauth_metadata_graph.redactOAuthUrlsInText)(error instanceof Error ? error.message : String(error))
+      });
+    }
+    const missingFamily = applicabilityTools && storyboard.required_any_of_tools?.find((family) => !(0, import_agent_routing.hasAnyRequiredTool)(family.tools, applicabilityTools));
+    const unmetDetail = capabilityUnmet ?? (missingFamily ? `missing_required_tool_family: needs ${missingFamily.tools.join(" or ")}` + (missingFamily.rationale ? ` (${missingFamily.rationale})` : "") : null) ?? (storyboard.required_tools?.length && applicabilityTools && !(0, import_agent_routing.hasAnyRequiredTool)(storyboard.required_tools, applicabilityTools) ? `agent does not advertise any of [${storyboard.required_tools.join(", ")}]` : null);
+    if (unmetDetail !== null) {
+      const observations = routingContext && runOptions.agents ? Object.entries(runOptions.agents).map(([key, entry]) => ({
+        key,
+        url: entry.url,
+        step: routingContext.discoverySteps?.get(key)
+      })) : [{ key: "discovery", url: agentUrls[0], step: discoveryStep }];
+      const steps = observations.map(({ key, url, step }) => ({
+        storyboard_id: storyboard.id,
+        phase_id: "discovery",
+        step_id: key,
+        title: step ? "Agent capability discovery" : "Supplied agent capability profile",
+        task: step?.task ?? "",
+        passed: true,
+        duration_ms: step?.duration_ms ?? 0,
+        validations: [],
+        context: {},
+        ...routingContext && { agent_url: (0, import_oauth_metadata_graph.redactOAuthUrlForOutput)(url) },
+        extraction: step?.extraction ?? { path: "none" },
+        ...step?.request && { request: step.request },
+        ...step?.response_record && { response_record: step.response_record }
+      }));
+      return await finishPreparation(
+        {
+          phase: {
+            phase_id: "discovery",
+            phase_title: "Agent capability discovery",
+            passed: true,
+            duration_ms: steps.reduce((total, step) => total + step.duration_ms, 0),
+            steps
+          },
+          allPassed: true,
+          passedCount: steps.length,
+          failedCount: 0
+        },
+        { status: "unsupported", reason: "not_applicable", detail: unmetDetail }
+      );
+    }
     const context = createRunContext(storyboard, options).context;
     const seeding = await (0, import_seeding.runControllerSeeding)(client, storyboard, options, context);
     if (!seeding) {
@@ -5841,7 +5963,12 @@ async function executeStep(client, step, storyboardId, phaseId, context, allStep
   };
   const hasData = taskResult?.data !== void 0 && taskResult?.data !== null;
   if (passed && hasData && taskResult && !(effectiveStep.task === "sync_accounts" && request.dry_run === true)) {
-    const extracted = (0, import_context.extractContextWithProvenance)(effectiveStep.task, taskResult.data, step.id);
+    const extracted = (0, import_context.extractContextWithProvenance)(
+      effectiveStep.task,
+      taskResult.data,
+      step.id,
+      options._serverAdcpVersion ?? options.adcpVersion
+    );
     const conventionUnset = [];
     for (const group of extracted.clearGroups ?? []) {
       if (group.when && !group.when.values.includes(updatedContext[group.when.key])) continue;
@@ -5872,7 +5999,8 @@ async function executeStep(client, step, storyboardId, phaseId, context, allStep
       step.context_outputs,
       client,
       runState.webhookReceiver,
-      effectiveStep.task
+      effectiveStep.task,
+      options._serverAdcpVersion ?? options.adcpVersion
     );
     const extractionData = "data" in taskCompletionResolution ? taskCompletionResolution.data : hasData && taskResult ? taskResult.data : void 0;
     const remappedOutputs = remapTaskCompletionOutputs(step.context_outputs);