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

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

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

@@ -726,7 +726,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)
   );
@@ -779,7 +779,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) {
@@ -787,7 +790,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 {
@@ -796,18 +802,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 = injectLegacyEnvelopeStatus(original, { toolName: taskName });
+  const compatOptions = { toolName: taskName, adcpVersion };
+  const compat = injectLegacyEnvelopeStatus(original, compatOptions);
   if (!("status" in original) && "status" in compat) {
     const { status: _status, ...rest } = compat;
-    return normalizeLegacyMediaBuyStatusForReturn(rest, { toolName: taskName });
+    return 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 normalizeLegacyMediaBuyStatusForReturn({ ...compat, status: original.status }, { toolName: taskName });
+    return normalizeLegacyMediaBuyStatusForReturn({ ...compat, status: original.status }, compatOptions);
   }
-  return normalizeLegacyMediaBuyStatusForReturn(compat, { toolName: taskName });
+  return normalizeLegacyMediaBuyStatusForReturn(compat, compatOptions);
 }
 function readEnvIntOrDefault(value, fallback) {
   if (!value) return fallback;
@@ -1945,9 +1952,10 @@ async function prepareStoryboardFixturesBody(agentUrl, storyboard, options) {
     options = snapshotPreparationOptions(options);
   }
   const callerOwnsClients = hasTestClientScope();
-  const preparationOptions = resolvePreparationRouteOptions(agentUrls[0], options);
+  const runOptions = options;
+  const preparationOptions = resolvePreparationRouteOptions(agentUrls[0], runOptions);
   const resolution = getOrCreateClientResolution(agentUrls[0], preparationOptions);
-  const client = resolution.client;
+  let client = resolution.client;
   const finishPreparation = (seeding, disposition) => {
     if (!scopeStillMatches()) {
       return refusePreparation(driftRefusal, seeding ?? void 0);
@@ -1957,6 +1965,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 buildRoutingContext(storyboard, { ...runOptions, discovery_resilient: false });
+      } catch (error) {
+        const failedStep = error instanceof DiscoveryFailure ? error.step : void 0;
+        return await failDiscovery({
+          ...failedStep,
+          step: failedStep?.step ?? "Discover preparation topology",
+          passed: false,
+          duration_ms: failedStep?.duration_ms ?? 0,
+          error: redactOAuthUrlsInText(
+            error instanceof DiscoveryFailure ? `Discovery failed for agent "${error.agentKey}" (${redactOAuthUrlForOutput(error.url)}): ${error.underlying}` : error instanceof Error ? error.message : String(error)
+          )
+        });
+      }
+      for (const routeProfile of routingContext.profiles.values()) {
+        const failure = 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: normalizeAgentToolNames(profile.tools) };
+    }
     const suppliedFailure = profile && describeProfileDiscoveryFailure(
       profile,
       options._requireValidCapabilityEvidence === true,
@@ -1969,8 +2016,9 @@ async function prepareStoryboardFixturesBody(agentUrl, storyboard, options) {
         { status: "failed", detail: suppliedFailure.error ?? "agent discovery failed" }
       );
     }
-    if (!profile && !resolution.reusedShared) {
+    if (!profile) {
       const discovered = await 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(
@@ -1991,6 +2039,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) => 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 !== VALIDATION_ONLY_TASK).map((step) => {
+            const selected = dispatch.nextFor(step);
+            const owner = runOptions.default_agent ? defaultProfile : selected.profile;
+            return evaluateStoryboardCapabilityGates(
+              storyboard,
+              owner,
+              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: redactOAuthUrlsInText(error instanceof Error ? error.message : String(error))
+      });
+    }
+    const missingFamily = applicabilityTools && storyboard.required_any_of_tools?.find((family) => !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 && !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: 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 runControllerSeeding(client, storyboard, options, context);
     if (!seeding) {
@@ -5883,7 +6005,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 = extractContextWithProvenance(effectiveStep.task, taskResult.data, step.id);
+    const extracted = 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;
@@ -5914,7 +6041,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);

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

@@ -197,7 +197,7 @@ export interface UpstreamTrafficQueryResult {
  */
 export declare function runValidations(validations: StoryboardValidation[], context: ValidationContext): ValidationResult[];
 /** Capability semver emitted in run summaries and used for advisory expiry. */
-export declare const RUNNER_CAPABILITY_VERSION = "17.0.0-beta.0";
+export declare const RUNNER_CAPABILITY_VERSION = "17.0.0-beta.1";
 /** True when a failed validation contributes to the owning step's grade. */
 export declare function validationFailsStep(result: ValidationResult): boolean;
 /**

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

@@ -197,7 +197,7 @@ export interface UpstreamTrafficQueryResult {
  */
 export declare function runValidations(validations: StoryboardValidation[], context: ValidationContext): ValidationResult[];
 /** Capability semver emitted in run summaries and used for advisory expiry. */
-export declare const RUNNER_CAPABILITY_VERSION = "17.0.0-beta.0";
+export declare const RUNNER_CAPABILITY_VERSION = "17.0.0-beta.1";
 /** True when a failed validation contributes to the owning step's grade. */
 export declare function validationFailsStep(result: ValidationResult): boolean;
 /**

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

@@ -295,8 +295,11 @@ function validateResponseSchemaForVersion(validation, ctx, taskResult) {
     return rest;
   })();
   const schema = import_response_schemas.TOOL_RESPONSE_SCHEMAS[taskName];
-  const dataForValidation = Array.isArray(dataWithoutMessage) ? dataWithoutMessage : (0, import_envelope_status_compat.injectLegacyEnvelopeStatus)(dataWithoutMessage, { toolName: taskName });
   const responseAdcpVersion = ctx.responseAdcpVersion ?? ctx.adcpVersion;
+  const dataForValidation = Array.isArray(dataWithoutMessage) ? dataWithoutMessage : (0, import_envelope_status_compat.injectLegacyEnvelopeStatus)(dataWithoutMessage, {
+    toolName: taskName,
+    adcpVersion: responseAdcpVersion
+  });
   const parseResult = schema?.safeParse(
     (0, import_response_schemas.prepareResponseForSchemaValidation)(taskName, dataForValidation, responseAdcpVersion)
   );

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

@@ -276,8 +276,11 @@ function validateResponseSchemaForVersion(validation, ctx, taskResult) {
     return rest;
   })();
   const schema = TOOL_RESPONSE_SCHEMAS[taskName];
-  const dataForValidation = Array.isArray(dataWithoutMessage) ? dataWithoutMessage : injectLegacyEnvelopeStatus(dataWithoutMessage, { toolName: taskName });
   const responseAdcpVersion = ctx.responseAdcpVersion ?? ctx.adcpVersion;
+  const dataForValidation = Array.isArray(dataWithoutMessage) ? dataWithoutMessage : injectLegacyEnvelopeStatus(dataWithoutMessage, {
+    toolName: taskName,
+    adcpVersion: responseAdcpVersion
+  });
   const parseResult = schema?.safeParse(
     prepareResponseForSchemaValidation(taskName, dataForValidation, responseAdcpVersion)
   );

package/dist/lib/testing/test-controller.js

@@ -31,6 +31,7 @@ __export(test_controller_exports, {
 });
 module.exports = __toCommonJS(test_controller_exports);
 var import_client = require('./client.js');
+var import_errors = require('../errors/index.js');
 const TOOL_NAME = "comply_test_controller";
 const DEFAULT_SANDBOX_ACCOUNT = { brand: { domain: "test.example" }, operator: "test.example", sandbox: true };
 function buildAccount(options) {
@@ -84,6 +85,8 @@ async function detectController(client, profile, options) {
     }
     return { detected: false };
   } catch (error) {
+    if (error instanceof import_errors.ProtocolFeatureUnsupportedError && error.adcpError.details?.feature === "adcp_version")
+      throw error;
     (0, import_client.getLogger)().warn(
       { tool: TOOL_NAME, error: error instanceof Error ? error.message : String(error) },
       "comply_test_controller list_scenarios failed \u2014 treating as unavailable"

package/dist/lib/testing/test-controller.mjs

@@ -1,4 +1,5 @@
 import { getLogger, resolveAccount } from "./client.mjs";
+import { ProtocolFeatureUnsupportedError } from "../errors/index.mjs";
 const TOOL_NAME = "comply_test_controller";
 const DEFAULT_SANDBOX_ACCOUNT = { brand: { domain: "test.example" }, operator: "test.example", sandbox: true };
 function buildAccount(options) {
@@ -52,6 +53,8 @@ async function detectController(client, profile, options) {
     }
     return { detected: false };
   } catch (error) {
+    if (error instanceof ProtocolFeatureUnsupportedError && error.adcpError.details?.feature === "adcp_version")
+      throw error;
     getLogger().warn(
       { tool: TOOL_NAME, error: error instanceof Error ? error.message : String(error) },
       "comply_test_controller list_scenarios failed \u2014 treating as unavailable"

package/dist/lib/utils/envelope-status-compat.d.mts

@@ -14,7 +14,10 @@
  * enum during validation. The same translation applies to the documented 3.1
  * deprecation window for top-level `status: MediaBuyStatus`. Other 3.1+
  * responses are returned unchanged so the strict validator still rejects a
- * peer that omits or misuses `status`.
+ * peer that omits or misuses `status`. A bare `completed` / `rejected` /
+ * `canceled` is never treated as a lifecycle when the payload, or failing
+ * that the caller's requested release (`options.adcpVersion`), is 3.1+:
+ * there it is the task envelope status.
  *
  * The leniency is a back-compat affordance, not a permanent loosening.
  */
@@ -26,6 +29,20 @@ export interface LegacyEnvelopeStatusOptions {
      * the protocol task envelope.
      */
     toolName?: string;
+    /**
+     * AdCP release the caller requested or negotiated for this exchange (for
+     * example the client's `adcpVersion` pin, or the release negotiated down
+     * from it). The response `adcp_version` echo is optional, so a seller on
+     * 3.1+ may answer a create with only `{ status: 'completed', media_buy_id }`.
+     * `completed`, `rejected` and `canceled` are valid both as TaskStatus and as
+     * MediaBuyStatus. When the payload carries no version echo, this release
+     * decides which one a bare top-level `status` is: on 3.1+ it is the task
+     * envelope status and is never copied into `media_buy_status`. An explicit
+     * `adcp_version` / `adcp_major_version` on the payload always wins. When
+     * neither the payload nor the caller knows the release, the legacy 3.0
+     * reading still applies.
+     */
+    adcpVersion?: string;
 }
 /** 3.2 synchronous response arms that intentionally forbid task-envelope status. */
 export declare const STATUS_FREE_SYNC_RESPONSE_TOOLS: ReadonlySet<string>;

package/dist/lib/utils/envelope-status-compat.d.ts

@@ -14,7 +14,10 @@
  * enum during validation. The same translation applies to the documented 3.1
  * deprecation window for top-level `status: MediaBuyStatus`. Other 3.1+
  * responses are returned unchanged so the strict validator still rejects a
- * peer that omits or misuses `status`.
+ * peer that omits or misuses `status`. A bare `completed` / `rejected` /
+ * `canceled` is never treated as a lifecycle when the payload, or failing
+ * that the caller's requested release (`options.adcpVersion`), is 3.1+:
+ * there it is the task envelope status.
  *
  * The leniency is a back-compat affordance, not a permanent loosening.
  */
@@ -26,6 +29,20 @@ export interface LegacyEnvelopeStatusOptions {
      * the protocol task envelope.
      */
     toolName?: string;
+    /**
+     * AdCP release the caller requested or negotiated for this exchange (for
+     * example the client's `adcpVersion` pin, or the release negotiated down
+     * from it). The response `adcp_version` echo is optional, so a seller on
+     * 3.1+ may answer a create with only `{ status: 'completed', media_buy_id }`.
+     * `completed`, `rejected` and `canceled` are valid both as TaskStatus and as
+     * MediaBuyStatus. When the payload carries no version echo, this release
+     * decides which one a bare top-level `status` is: on 3.1+ it is the task
+     * envelope status and is never copied into `media_buy_status`. An explicit
+     * `adcp_version` / `adcp_major_version` on the payload always wins. When
+     * neither the payload nor the caller knows the release, the legacy 3.0
+     * reading still applies.
+     */
+    adcpVersion?: string;
 }
 /** 3.2 synchronous response arms that intentionally forbid task-envelope status. */
 export declare const STATUS_FREE_SYNC_RESPONSE_TOOLS: ReadonlySet<string>;

package/dist/lib/utils/envelope-status-compat.js

@@ -51,7 +51,7 @@ function injectLegacyEnvelopeStatus(response, options) {
     return response;
   }
   if (options?.toolName && STATUS_FREE_SYNC_RESPONSE_TOOLS.has(options.toolName)) return response;
-  if (options?.toolName && MEDIA_BUY_STATUS_RESPONSE_TOOLS.has(options.toolName) && allowsDeprecatedMediaBuyStatus(response) && isMediaBuySuccessStatusForCompat(response)) {
+  if (options?.toolName && MEDIA_BUY_STATUS_RESPONSE_TOOLS.has(options.toolName) && allowsDeprecatedMediaBuyStatus(response) && isMediaBuySuccessStatusForCompat(response, options)) {
     const mediaBuyStatus = response.status;
     return {
       ...response,
@@ -76,16 +76,16 @@ function normalizeLegacyMediaBuyStatusForReturn(response, options) {
   if (!response || typeof response !== "object" || Array.isArray(response)) {
     return response;
   }
-  if (!options?.toolName || !MEDIA_BUY_STATUS_RESPONSE_TOOLS.has(options.toolName) || !allowsDeprecatedMediaBuyStatus(response) || !isMediaBuySuccessStatusForCompat(response)) {
+  if (!options?.toolName || !MEDIA_BUY_STATUS_RESPONSE_TOOLS.has(options.toolName) || !allowsDeprecatedMediaBuyStatus(response) || !isMediaBuySuccessStatusForCompat(response, options)) {
     return response;
   }
-  const status = (0, import_media_buy_status.getAuthoritativeMediaBuyStatus)(response);
+  const status = (0, import_media_buy_status.getAuthoritativeMediaBuyStatus)(withRequestedVersion(response, options));
   if (!status || response.media_buy_status === status) return response;
   return { ...response, media_buy_status: status };
 }
-function isMediaBuySuccessStatusForCompat(response) {
+function isMediaBuySuccessStatusForCompat(response, options) {
   const status = response.status;
-  if ((0, import_media_buy_status.getAuthoritativeMediaBuyStatus)(response) !== status) return false;
+  if ((0, import_media_buy_status.getAuthoritativeMediaBuyStatus)(withRequestedVersion(response, options)) !== status) return false;
   if (typeof response.media_buy_status === "string" && response.media_buy_status !== status) {
     return false;
   }
@@ -100,6 +100,12 @@ function allowsDeprecatedMediaBuyStatus(payload) {
   if (typeof major === "number") return major === 3;
   return true;
 }
+function withRequestedVersion(payload, options) {
+  const requested = options?.adcpVersion;
+  if (typeof requested !== "string" || requested.length === 0) return payload;
+  if (typeof payload.adcp_version === "string" || typeof payload.adcp_major_version === "number") return payload;
+  return { ...payload, adcp_version: requested };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   STATUS_FREE_SYNC_RESPONSE_TOOLS,