@adcp/sdk 16.0.0-beta.8 → 16.0.0

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

@@ -62,6 +62,7 @@ var import_node_crypto = require("node:crypto");
 var import_node_fs = require("node:fs");
 var import_node_path = require("node:path");
 var import_account_policy = require('./account-policy.js');
+var import_creative_build_probe = require('./creative-build-probe.js');
 var import_client = require('../client.js');
 var import_protocols = require('../../protocols/index.js');
 var import_rawResponseCapture = require('../../protocols/rawResponseCapture.js');
@@ -76,6 +77,7 @@ var import_parallel_dispatch = require('./parallel-dispatch.js');
 var import_path = require('./path.js');
 var import_rate_limit_trip = require('./rate-limit-trip.js');
 var import_redact_secrets = require('../../utils/redact-secrets.js');
+var import_property_list_reference = require('./property-list-reference.js');
 var import_response_unwrapper = require('../../utils/response-unwrapper.js');
 var import_envelope_status_compat = require('../../utils/envelope-status-compat.js');
 var import_test_controller = require('../test-controller.js');
@@ -761,38 +763,48 @@ function filterResponseHeaders(headers) {
 async function runStoryboard(agentUrlOrUrls, storyboard, options = {}) {
   options = applyReusableProfileOptions(options);
   if ((0, import_client.hasTestClientScope)() && !options._discoveryPass) options = { ...options, _discoveryPass: {} };
-  return (0, import_protocols.withMCPConnectionScope)(
-    async () => {
-      options = applyStoryboardVersionOptions(storyboard, options);
-      options = (0, import_functional_dispatch.applyFunctionalRequestSigning)(options, {
-        ...options.complianceDir && { complianceDir: options.complianceDir },
-        ...options.adcpVersion && { version: options.adcpVersion }
-      });
-      options = (0, import_test_kit.resolveDeclaredTestKit)(storyboard, options);
-      options = (0, import_native_a2a_compliance.applyNativeA2AComplianceTransportOptions)(options);
-      if ((0, import_client.hasTestClientScope)() && options._client && !options.agents) {
-        const resolution = (0, import_client.getOrCreateClientResolution)(
-          typeof agentUrlOrUrls === "string" ? agentUrlOrUrls : agentUrlOrUrls[0],
-          options
+  return (0, import_property_list_reference.withPropertyListCredentialRedaction)(
+    () => (0, import_protocols.withMCPConnectionScope)(
+      async () => {
+        options = applyStoryboardVersionOptions(storyboard, options);
+        options = (0, import_functional_dispatch.applyFunctionalRequestSigning)(options, {
+          ...options.complianceDir && { complianceDir: options.complianceDir },
+          ...options.adcpVersion && { version: options.adcpVersion }
+        });
+        options = (0, import_test_kit.resolveDeclaredTestKit)(storyboard, options);
+        options = (0, import_native_a2a_compliance.applyNativeA2AComplianceTransportOptions)(options);
+        if (storyboard.requires?.[0] === "property_list_reference_runner" && storyboardCapabilityPredicates(storyboard).length === 0 && propertyListReferenceNeedsMcp(options)) {
+          return buildRequirementUnmetResult(
+            Array.isArray(agentUrlOrUrls) ? agentUrlOrUrls : [agentUrlOrUrls],
+            storyboard,
+            "property_list_reference_runner",
+            "Credential-isolated property-list references currently require MCP; A2A probe coverage is unavailable."
+          );
+        }
+        if ((0, import_client.hasTestClientScope)() && options._client && !options.agents) {
+          const resolution = (0, import_client.getOrCreateClientResolution)(
+            typeof agentUrlOrUrls === "string" ? agentUrlOrUrls : agentUrlOrUrls[0],
+            options
+          );
+          const discovered = await (0, import_client.getOrDiscoverProfile)(resolution.client, options);
+          options = {
+            ...options,
+            _profile: discovered.step.passed ? discovered.profile : void 0,
+            agentTools: discovered.step.passed ? discovered.profile.tools : void 0
+          };
+        }
+        const schemaRoot = getRunSchemaRoot(options);
+        const runBody = () => (0, import_schema_loader.withServedReleaseSchemaRoots)(
+          options.servedReleaseSchemaRoots,
+          () => runStoryboardBody(agentUrlOrUrls, storyboard, options)
         );
-        const discovered = await (0, import_client.getOrDiscoverProfile)(resolution.client, options);
-        options = {
-          ...options,
-          _profile: discovered.step.passed ? discovered.profile : void 0,
-          agentTools: discovered.step.passed ? discovered.profile.tools : void 0
-        };
-      }
-      const schemaRoot = getRunSchemaRoot(options);
-      const runBody = () => (0, import_schema_loader.withServedReleaseSchemaRoots)(
-        options.servedReleaseSchemaRoots,
-        () => runStoryboardBody(agentUrlOrUrls, storyboard, options)
-      );
-      if (schemaRoot) {
-        return await (0, import_schema_loader.withExternalSchemaRoot)(schemaRoot.adcpVersion, schemaRoot.schemaRoot, runBody);
-      }
-      return await runBody();
-    },
-    { isolate: !(0, import_client.hasTestClientScope)() }
+        if (schemaRoot) {
+          return await (0, import_schema_loader.withExternalSchemaRoot)(schemaRoot.adcpVersion, schemaRoot.schemaRoot, runBody);
+        }
+        return await runBody();
+      },
+      { isolate: !(0, import_client.hasTestClientScope)() }
+    )
   );
 }
 async function runStoryboardBody(agentUrlOrUrls, storyboard, options) {
@@ -872,6 +884,7 @@ async function runStoryboardBody(agentUrlOrUrls, storyboard, options) {
         'runStoryboard: webhook_receiver is incompatible with multi_instance_strategy: "multi-pass". Each pass would bind a fresh receiver URL, so agents caching the pass-1 URL would deliver to a dead port in pass 2. Use round-robin when the storyboard needs a webhook receiver, or run multi-pass on a storyboard without webhook observation.'
       );
     }
+    if (storyboard.creative_build_probe) return executeStoryboardPass(agentUrls, storyboard, options, 0);
     return runMultiPass(agentUrls, storyboard, options);
   }
   if (options.agents) {
@@ -1024,6 +1037,7 @@ const REQUIREMENT_TO_SKIP_REASON = {
   webhook_replay_receiver: "not_applicable",
   trusted_match_context_router_runner: "not_applicable",
   trusted_match_publisher_auth_runner: "requirement_unmet",
+  property_list_reference_runner: "requirement_unmet",
   request_signer: "not_applicable",
   multi_agent: "requirement_unmet"
 };
@@ -1130,6 +1144,9 @@ function buildRequiredAnyOfToolsMissingResult(agentUrls, storyboard, detail) {
     notices: []
   };
 }
+function propertyListReferenceNeedsMcp(options) {
+  return options.agents ? Object.values(options.agents).some((agent) => (agent.transport ?? options.protocol) === "a2a") : options.protocol === "a2a";
+}
 async function checkRequires(requires, storyboard, options, profile, precomputed) {
   let preparedPublisherAuthProbes = getPreparedTrustedMatchPublisherAuth(options);
   for (const requirement of requires) {
@@ -1168,6 +1185,15 @@ async function checkRequires(requires, storyboard, options, profile, precomputed
       }
       case "real_wire":
         break;
+      case "property_list_reference_runner": {
+        if (propertyListReferenceNeedsMcp(options)) {
+          return {
+            requirement,
+            detail: "Credential-isolated property-list references currently require MCP; A2A probe coverage is unavailable."
+          };
+        }
+        break;
+      }
       case "webhook_receiver": {
         if (options.webhook_receiver === void 0) {
           return {
@@ -1457,7 +1483,7 @@ function collectCapabilityNotices(storyboard, profile) {
     if (requestSigning?.["supported"] !== true) {
       notices.push({
         severity: "future_required",
-        code: "request_signing.required",
+        code: "request_signing_required_in_4_0",
         message: "RFC 9421 request signing (`request_signing.supported: true`) is not advertised. Required for spend-committing operations in AdCP 4.0 \u2014 declare the capability and pre-register the runner compliance test keypair before the 4.0 cut.",
         effective_version: "4.0",
         capability_path: "request_signing.supported",
@@ -1478,7 +1504,7 @@ function collectCapabilityNotices(storyboard, profile) {
     if (webhookSigning?.["legacy_hmac_fallback"] === true) {
       notices.push({
         severity: "deprecation",
-        code: "webhook_signing.legacy_hmac_fallback.removed",
+        code: "legacy_hmac_fallback_removed_in_4_0",
         message: "`webhook_signing.legacy_hmac_fallback: true` is deprecated and removed in AdCP 4.0. Migrate webhook signature verification to RFC 9421 before the 4.0 cut.",
         effective_version: "4.0",
         capability_path: "webhook_signing.legacy_hmac_fallback",
@@ -1998,16 +2024,118 @@ async function executeStoryboardPass(agentUrls, storyboard, options, dispatchOff
   }
   let seedingPhaseResult = null;
   let seedingFailed = false;
+  let creativeBuildCatalogFailed = false;
   let seedingMissingController = false;
   let seedingUnsupported = false;
   let fixtureUnsatisfied = false;
   let fixtureBindings;
   let fixtureResolutionRecords;
   let fixtureCoverageGap;
+  if (storyboard.creative_build_probe && !skipControllerSeedingForPhaseGates) {
+    let resolution;
+    try {
+      resolution = routingContext || isMultiInstance ? {
+        status: "unsatisfied",
+        detail: `fixture_unsatisfied: creative_format:${storyboard.creative_build_probe.context_prefix}: resolve an independent fixture for each routed or replicated agent in a single-agent run`
+      } : (0, import_creative_build_probe.prepareCreativeBuildProbe)(
+        profile?.raw_capabilities,
+        storyboard.creative_build_probe,
+        options.test_kit,
+        options.adcpVersion
+      );
+    } catch (error) {
+      await Promise.allSettled([
+        ...webhookReceiver ? [webhookReceiver.close()] : [],
+        ...!callerOwnsClients ? [(0, import_protocols.closeScopedConnections)(options.protocol)] : []
+      ]);
+      throw error;
+    }
+    const handle = storyboard.creative_build_probe.context_prefix;
+    fixtureResolutionRecords = [
+      {
+        fixture_type: "creative_format",
+        handle,
+        requirements: resolution.status === "resolved" ? resolution.requirements : [],
+        status: resolution.status,
+        ...resolution.status === "resolved" ? {
+          seller_ids: resolution.capabilityId !== void 0 ? { capability_id: resolution.capabilityId } : { format_id: resolution.formatId }
+        } : {},
+        strategy: "discover",
+        strategies_attempted: [
+          {
+            strategy: "discover",
+            disposition: resolution.status === "unsatisfied" ? "unavailable" : resolution.status,
+            detail: resolution.status === "resolved" ? `Bound build route using ${resolution.source} input` : resolution.detail
+          }
+        ]
+      }
+    ];
+    if (resolution.status !== "resolved") {
+      const noPhasesIndex = phaseResults.findIndex((phase) => phase.phase_id === "no_phases");
+      if (noPhasesIndex >= 0) {
+        skippedCount -= phaseResults[noPhasesIndex].steps.filter((step) => step.skipped).length;
+        phaseResults.splice(noPhasesIndex, 1);
+      }
+    }
+    if (resolution.status === "failed") {
+      seedingFailed = true;
+      creativeBuildCatalogFailed = true;
+      failedCount += 1;
+      seedingPhaseResult = {
+        phase_id: "fixture_resolution",
+        phase_title: "Creative build fixture resolution",
+        passed: false,
+        duration_ms: 0,
+        steps: [
+          {
+            storyboard_id: storyboard.id,
+            phase_id: "fixture_resolution",
+            step_id: "creative_build_catalog",
+            title: "Validate advertised creative build catalog",
+            task: "get_adcp_capabilities",
+            passed: false,
+            duration_ms: 0,
+            context: {},
+            extraction: { path: "none" },
+            validations: [
+              {
+                check: "creative_build_probe_catalog",
+                passed: false,
+                description: "Advertised creative catalog satisfies its format and routing contract",
+                error: resolution.detail
+              }
+            ]
+          }
+        ]
+      };
+    } else if (resolution.status === "resolved") {
+      for (const key of [
+        "capability_id",
+        "target_format_id",
+        "message",
+        "creative_manifest",
+        "creative_id",
+        "transformer_id",
+        "config"
+      ]) {
+        delete context[`${handle}_${key}`];
+      }
+      Object.assign(context, resolution.context);
+      options = { ...options, contracts: [.../* @__PURE__ */ new Set([...options.contracts ?? [], "creative_build_probe_runner"])] };
+    } else {
+      fixtureUnsatisfied = true;
+      if (preSeeded === void 0 || preSeeded.attach) skippedCount += 1;
+      fixtureCoverageGap = {
+        reason: "fixture_unsatisfied",
+        detail: resolution.detail,
+        fixtures: [{ fixture_type: "creative_format", handle, requirements: [] }]
+      };
+    }
+  }
   {
     let seeding;
     try {
-      seeding = creativeAssetFixtureGap || skipControllerSeedingForPhaseGates ? null : preSeeded !== void 0 ? preSeeded.result : await (0, import_seeding.runControllerSeeding)(
+      seeding = creativeAssetFixtureGap || fixtureUnsatisfied || seedingFailed || skipControllerSeedingForPhaseGates ? null : preSeeded !== void 0 ? preSeeded.result : await (0, import_seeding.runControllerSeeding)(
         clients[0],
         storyboard,
         options,
@@ -2068,7 +2196,7 @@ async function executeStoryboardPass(agentUrls, storyboard, options, dispatchOff
         }
       }
       fixtureBindings = seeding.bindings;
-      fixtureResolutionRecords = seeding.resolutionRecords;
+      fixtureResolutionRecords = fixtureResolutionRecords ? [...fixtureResolutionRecords, ...seeding.resolutionRecords ?? []] : seeding.resolutionRecords;
       fixtureUnsatisfied = seeding.fixtureUnsatisfied === true && seeding.failedCount === 0;
       if (fixtureUnsatisfied) {
         const noPhasesIndex = phaseResults.findIndex((phase) => phase.phase_id === "no_phases");
@@ -2310,6 +2438,12 @@ async function executeStoryboardPass(agentUrls, storyboard, options, dispatchOff
       } : seedingUnsupported ? {
         skip_reason: "fixture_seed_unsupported",
         skip: { reason: "not_applicable", detail: FIXTURE_SEED_UNSUPPORTED_DETAIL }
+      } : creativeBuildCatalogFailed ? {
+        skip_reason: "prerequisite_failed",
+        skip: {
+          reason: "prerequisite_failed",
+          detail: "Creative build catalog validation failed in fixture_resolution.creative_build_catalog."
+        }
       } : seedingFailed ? {
         skip_reason: "controller_seeding_failed",
         skip: { reason: "prerequisite_failed", detail: CONTROLLER_SEEDING_FAILED_DETAIL }
@@ -3105,32 +3239,57 @@ function summarizeStrictValidation(phases) {
 }
 async function runStoryboardStep(agentUrl, storyboard, stepId, options = {}) {
   options = applyReusableProfileOptions(options);
-  return (0, import_protocols.withMCPConnectionScope)(
-    async () => {
-      storyboard = (0, import_loader.normalizeValidationOnlyTasks)(storyboard);
-      (0, import_loader.validateStoryboardShape)(storyboard);
-      options = applyStoryboardVersionOptions(storyboard, options);
-      options = (0, import_functional_dispatch.applyFunctionalRequestSigning)(options, {
-        ...options.complianceDir && { complianceDir: options.complianceDir },
-        ...options.adcpVersion && { version: options.adcpVersion }
-      });
-      options = (0, import_test_kit.resolveDeclaredTestKit)(storyboard, options);
-      options = (0, import_native_a2a_compliance.applyNativeA2AComplianceTransportOptions)(options);
-      const schemaRoot = getRunSchemaRoot(options);
-      const runBody = () => (0, import_schema_loader.withServedReleaseSchemaRoots)(
-        options.servedReleaseSchemaRoots,
-        () => runStoryboardStepBody(agentUrl, storyboard, stepId, options)
-      );
-      if (schemaRoot) {
-        return await (0, import_schema_loader.withExternalSchemaRoot)(schemaRoot.adcpVersion, schemaRoot.schemaRoot, runBody);
-      }
-      return await runBody();
-    },
-    { isolate: !(0, import_client.hasTestClientScope)() }
+  return (0, import_property_list_reference.withPropertyListCredentialRedaction)(
+    () => (0, import_protocols.withMCPConnectionScope)(
+      async () => {
+        storyboard = (0, import_loader.normalizeValidationOnlyTasks)(storyboard);
+        (0, import_loader.validateStoryboardShape)(storyboard);
+        options = applyStoryboardVersionOptions(storyboard, options);
+        options = (0, import_functional_dispatch.applyFunctionalRequestSigning)(options, {
+          ...options.complianceDir && { complianceDir: options.complianceDir },
+          ...options.adcpVersion && { version: options.adcpVersion }
+        });
+        options = (0, import_test_kit.resolveDeclaredTestKit)(storyboard, options);
+        options = (0, import_native_a2a_compliance.applyNativeA2AComplianceTransportOptions)(options);
+        const schemaRoot = getRunSchemaRoot(options);
+        const runBody = () => (0, import_schema_loader.withServedReleaseSchemaRoots)(
+          options.servedReleaseSchemaRoots,
+          () => runStoryboardStepBody(agentUrl, storyboard, stepId, options)
+        );
+        if (schemaRoot) {
+          return await (0, import_schema_loader.withExternalSchemaRoot)(schemaRoot.adcpVersion, schemaRoot.schemaRoot, runBody);
+        }
+        return await runBody();
+      },
+      { isolate: !(0, import_client.hasTestClientScope)() }
+    )
   );
 }
 async function runStoryboardStepBody(agentUrl, storyboard, stepId, options) {
   (0, import_test_kit.validateTestKit)(options.test_kit);
+  if (storyboard.requires?.[0] === "property_list_reference_runner" && storyboardCapabilityPredicates(storyboard).length === 0 && propertyListReferenceNeedsMcp(options)) {
+    const found2 = flattenSteps(storyboard).find((entry) => entry.step.id === stepId);
+    if (!found2) throw new Error(`Step "${stepId}" not found in storyboard "${storyboard.id}".`);
+    return {
+      storyboard_id: storyboard.id,
+      step_id: stepId,
+      phase_id: found2.phaseId,
+      title: found2.step.title,
+      task: found2.step.task,
+      passed: true,
+      skipped: true,
+      skip_reason: "requirement_unmet",
+      skip: {
+        reason: "requirement_unmet",
+        requirement: "property_list_reference_runner",
+        detail: "Credential-isolated property-list references currently require MCP; A2A probe coverage is unavailable."
+      },
+      duration_ms: 0,
+      validations: [],
+      context: { ...storyboard.context, ...options.context },
+      extraction: { path: "none" }
+    };
+  }
   const clientResolution = (0, import_client.getOrCreateClientResolution)(agentUrl, options);
   const client = clientResolution.client;
   let profile;
@@ -3181,6 +3340,77 @@ async function runStoryboardStepBody(agentUrl, storyboard, stepId, options) {
       return result;
     }
   }
+  if (storyboard.creative_build_probe) {
+    let resolution;
+    try {
+      resolution = (0, import_creative_build_probe.prepareCreativeBuildProbe)(
+        profile?.raw_capabilities,
+        storyboard.creative_build_probe,
+        options.test_kit,
+        options.adcpVersion
+      );
+    } catch (error) {
+      if (!clientResolution.reusedShared) {
+        await Promise.allSettled([(0, import_protocols.closeScopedConnections)(options.protocol)]);
+      }
+      throw error;
+    }
+    if (resolution.status === "failed") {
+      if (!clientResolution.reusedShared) await (0, import_protocols.closeScopedConnections)(options.protocol);
+      return {
+        storyboard_id: storyboard.id,
+        step_id: found.step.id,
+        phase_id: found.phaseId,
+        title: found.step.title,
+        task: found.step.task,
+        passed: false,
+        duration_ms: 0,
+        validations: [
+          {
+            check: "creative_build_probe_catalog",
+            passed: false,
+            description: "Advertised creative catalog satisfies its format and routing contract",
+            error: resolution.detail
+          }
+        ],
+        context,
+        extraction: { path: "none" },
+        contributions: Array.from(options.contributions ?? [])
+      };
+    }
+    if (resolution.status === "unsatisfied") {
+      if (!clientResolution.reusedShared) await (0, import_protocols.closeScopedConnections)(options.protocol);
+      return {
+        storyboard_id: storyboard.id,
+        step_id: found.step.id,
+        phase_id: found.phaseId,
+        title: found.step.title,
+        task: found.step.task,
+        passed: true,
+        skipped: true,
+        skip_reason: "fixture_unsatisfied",
+        skip: { reason: "not_applicable", detail: resolution.detail },
+        duration_ms: 0,
+        validations: [],
+        context,
+        extraction: { path: "none" },
+        contributions: Array.from(options.contributions ?? [])
+      };
+    }
+    for (const key of [
+      "capability_id",
+      "target_format_id",
+      "message",
+      "creative_manifest",
+      "creative_id",
+      "transformer_id",
+      "config"
+    ]) {
+      delete context[`${storyboard.creative_build_probe.context_prefix}_${key}`];
+    }
+    Object.assign(context, resolution.context);
+    options = { ...options, contracts: [.../* @__PURE__ */ new Set([...options.contracts ?? [], "creative_build_probe_runner"])] };
+  }
   const injectedReceiver = options._webhookReceiver;
   const webhookReceiver = injectedReceiver ?? (options.webhook_receiver ? await (0, import_webhook_receiver.createWebhookReceiver)({
     ...options.webhook_receiver.mode && { mode: options.webhook_receiver.mode },
@@ -3962,6 +4192,10 @@ async function executeStep(client, step, storyboardId, phaseId, context, allStep
     }
   }
   const effectiveRequestUrl = requestUrl ?? runState.agentUrl;
+  (0, import_property_list_reference.rememberPropertyListCredentials)(
+    taskResult?.data ?? (caughtError instanceof import_response_unwrapper.ResponseSchemaValidationError ? caughtError.data : void 0),
+    (step.validations ?? []).flatMap((validation) => validation.auth_token_path ? [validation.auth_token_path] : [])
+  );
   const requestRecord = {
     transport: options.protocol === "a2a" ? "a2a" : "mcp",
     operation: effectiveStep.task,
@@ -4148,6 +4382,9 @@ async function executeStep(client, step, storyboardId, phaseId, context, allStep
           (av) => (0, import_context.injectContext)({ __v: av }, context, runState.runnerVars).__v
         );
       }
+      if (resolved.denied_list_id !== void 0) {
+        resolved.denied_list_id = (0, import_context.injectContext)({ value: resolved.denied_list_id }, context, runState.runnerVars).value;
+      }
       return resolved;
     });
     const upstreamTraffic = await prefetchUpstreamTraffic(
@@ -4192,7 +4429,30 @@ async function executeStep(client, step, storyboardId, phaseId, context, allStep
         };
       })()
     };
-    validations = (0, import_validations.runValidations)(resolvedValidations, vctx);
+    validations = (0, import_validations.runValidations)(
+      resolvedValidations.filter((validation) => validation.check !== "property_list_reference"),
+      vctx
+    );
+    for (const validation of resolvedValidations.filter((validation2) => validation2.check === "property_list_reference")) {
+      const result = effectiveStep.task !== "create_property_list" || !validationTaskResult?.success ? {
+        check: validation.check,
+        passed: false,
+        description: validation.description,
+        error: "property_list_reference requires a successful create_property_list response."
+      } : options.protocol === "a2a" ? {
+        check: validation.check,
+        passed: false,
+        description: validation.description,
+        error: "Credential-isolated reference resolution requires MCP."
+      } : await (0, import_property_list_reference.verifyPropertyListReference)(validation, validationTaskResult.data, {
+        agentUrl: client.getDiscoveredMcpEndpoint?.() ?? runState.agentUrl,
+        version: options.adcpVersion ?? options._serverAdcpVersion,
+        signal: options.signal,
+        allowHttp: options.allow_http,
+        redactValues: runCredentialValues(options)
+      });
+      validations.push((0, import_validations.decorateValidationResult)(result, vctx, validation));
+    }
     if (crossResponses && crossResponses.dispatches.length > 1) {
       const perResponseValidations = resolvedValidations.filter(
         (v) => v.check !== "cross_response_field_equal" && v.check !== "cross_response_count_distinct"