@adcp/sdk 6.19.0 → 7.0.0

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

@@ -29,6 +29,7 @@ const rejection_hints_1 = require("./rejection-hints");
 const shape_drift_hints_1 = require("./shape-drift-hints");
 const strict_validation_hints_1 = require("./strict-validation-hints");
 const validations_1 = require("./validations");
+const parallel_dispatch_1 = require("./parallel-dispatch");
 const path_1 = require("./path");
 const redact_secrets_1 = require("../../utils/redact-secrets");
 const test_controller_1 = require("../test-controller");
@@ -242,6 +243,7 @@ function applyBranchSetGrading(phases, phaseResults, branchSetByPhaseId, contrib
             step.skip_reason = 'peer_branch_taken';
             step.skip = { reason: 'peer_branch_taken', detail };
             delete step.error;
+            delete step.adcp_error;
             skippedDelta++;
             regraded = true;
         }
@@ -698,6 +700,7 @@ const REQUIREMENT_TO_SKIP_REASON = {
     controller: 'missing_test_controller',
     seeded_state: 'requirement_unmet',
     real_wire: 'requirement_unmet',
+    webhook_receiver: 'requirement_unmet',
 };
 /**
  * Build a minimal StoryboardResult for a storyboard skipped because a
@@ -770,6 +773,10 @@ function buildRequirementUnmetResult(agentUrls, storyboard, requirement, detail)
  *   - `real_wire` — always available; the runner is hitting a real wire
  *     by definition. The tag is a no-op gate today, reserved for a
  *     future `--mock-only` mode.
+ *   - `webhook_receiver` — operator supplied `options.webhook_receiver`.
+ *     Autodetected from step `sample_request` token presence (see
+ *     `detectImplicitRequires`); authors don't write this tag manually.
+ *     Spec: adcp-client#1678.
  */
 function checkRequires(requires, options) {
     for (const requirement of requires) {
@@ -799,10 +806,72 @@ function checkRequires(requires, options) {
             case 'real_wire':
                 // Always available — reserved for a future --mock-only mode.
                 break;
+            case 'webhook_receiver': {
+                if (options.webhook_receiver === undefined) {
+                    return {
+                        requirement,
+                        detail: 'Storyboard references `{{runner.webhook_url:…}}` or `{{runner.webhook_base}}` but no ' +
+                            'webhook receiver is configured. Pass `webhook_receiver` in StoryboardRunOptions ' +
+                            '(or `--webhook-receiver` on the CLI) to host a receiver, or omit this storyboard. ' +
+                            'Required by the webhook-emission universal: ' +
+                            'compliance/{version}/universal/webhook-emission.yaml grades not_applicable when ' +
+                            'no receiver is configured (prerequisites section).',
+                    };
+                }
+                break;
+            }
         }
     }
     return null;
 }
+/**
+ * Webhook-token regex used to autodetect the implicit `webhook_receiver`
+ * requirement. Matches `{{runner.webhook_url:<step_id>}}` and the bare
+ * `{{runner.webhook_base}}`. Same shape as the `MUSTACHE_TOKEN_RE` in
+ * context.ts but scoped to the two webhook-bearing tokens — we only care
+ * whether the storyboard needs a receiver, not what substitution it
+ * would produce. Single `[^{}]+` body avoids the polynomial-redos
+ * backtrack pattern flagged by CodeQL alert #49.
+ */
+const WEBHOOK_TOKEN_RE = /\{\{runner\.(?:webhook_url:[A-Za-z0-9_]+|webhook_base)\}\}/;
+/**
+ * Recursively scan a JSON-like value for any webhook receiver token. The
+ * scan only touches strings; objects and arrays are walked structurally
+ * so deeply-nested `push_notification_config.url` entries (or any other
+ * authoring pattern) are discovered without a hard-coded field list.
+ */
+function valueContainsWebhookToken(value) {
+    if (typeof value === 'string') {
+        return WEBHOOK_TOKEN_RE.test(value);
+    }
+    if (Array.isArray(value)) {
+        return value.some(valueContainsWebhookToken);
+    }
+    if (value !== null && typeof value === 'object') {
+        return Object.values(value).some(valueContainsWebhookToken);
+    }
+    return false;
+}
+/**
+ * Return the implicit requirements a storyboard needs based on its
+ * structure (not its declared `requires:` list). Today: only
+ * `'webhook_receiver'`, autodetected from `{{runner.webhook_url:…}}` /
+ * `{{runner.webhook_base}}` token presence inside any step's
+ * `sample_request`. Token presence is the authoring contract — a
+ * storyboard that names the runner's webhook receiver cannot run
+ * without one — so authors don't need to remember to add
+ * `requires: [webhook_receiver]` separately. Spec: adcp-client#1678.
+ */
+function detectImplicitRequires(storyboard) {
+    for (const phase of storyboard.phases) {
+        for (const step of phase.steps) {
+            if (step.sample_request && valueContainsWebhookToken(step.sample_request)) {
+                return ['webhook_receiver'];
+            }
+        }
+    }
+    return [];
+}
 /**
  * Build a hard-failure StoryboardResult for when agent capability
  * discovery (`get_agent_info` / MCP `tools/list`) failed. Surfacing
@@ -1030,8 +1099,20 @@ async function executeStoryboardPass(agentUrls, storyboard, options, dispatchOff
     // Spec: adcp-client#1626. The default (no `requires` field) is
     // `[real_wire]`, which is always available — untagged storyboards
     // run unchanged.
-    if (storyboard.requires?.length) {
-        const unmet = checkRequires(storyboard.requires, options);
+    //
+    // Implicit requirements (adcp-client#1678) are unioned with the
+    // declared list: today this means `'webhook_receiver'` is added when
+    // any step's `sample_request` references `{{runner.webhook_url:…}}`
+    // or `{{runner.webhook_base}}`. Authors do not need to retag those
+    // storyboards — the token presence is the declaration. Without the
+    // implicit gate, storyboards that name the receiver but run without
+    // one would silently ship literal mustache tokens on the wire and
+    // get rejected by 3.0-strict sellers as `INVALID_REQUEST: relative URL`.
+    const declared = storyboard.requires ?? [];
+    const implicit = detectImplicitRequires(storyboard);
+    const allRequires = [...declared, ...implicit.filter(r => !declared.includes(r))];
+    if (allRequires.length) {
+        const unmet = checkRequires(allRequires, options);
         if (unmet) {
             if (!options._client)
                 await (0, protocols_1.closeConnections)(options.protocol);
@@ -1366,6 +1447,15 @@ async function executeStoryboardPass(agentUrls, storyboard, options, dispatchOff
             });
             continue;
         }
+        // Reset alias cache at this phase boundary (#1657). $generate:uuid_v4#alias
+        // is designed to be stable within a scenario — the initial call and its
+        // idempotency replay share the same UUID — but aliases must NOT bleed across
+        // phases. Independent test groups that each start with a "setup" step need
+        // fresh idempotency keys; otherwise the seller's idempotency cache replays
+        // stale state from a prior group into the new one. Creating a new object
+        // identity drops the WeakMap entry without losing any $context.* values
+        // (those ride as plain properties on the spread result).
+        context = { ...context };
         // Seeding-cascade skip: either the pre-flight seed phase failed (setup
         // break) or the agent doesn't advertise `comply_test_controller`
         // (coverage gap). Both paths emit skipped steps; the reasons differ so
@@ -2417,7 +2507,9 @@ client, step, phaseId, context, allSteps, options, state) {
     // match the options. Enforcing this here (after builder + sample_request)
     // prevents session-key divergence across create/get/update/delete steps
     // when individual builders or sample_request YAML omit brand.
-    request = applyBrandInvariant(request, options, effectiveStep.task);
+    // `step.omit_account` suppresses account synthesis for schema_validation
+    // steps that deliberately test the seller's missing-account rejection path.
+    request = applyBrandInvariant(request, options, effectiveStep.task, { omit_account: step.omit_account });
     // Per-run sandbox-bypass hint (#841). When the operator passes
     // `--no-sandbox` (or sets `disable_sandbox: true` programmatically), the
     // runner stamps `ext.adcp.disable_sandbox: true` on every outgoing
@@ -2498,16 +2590,25 @@ client, step, phaseId, context, allSteps, options, state) {
     // and the server never sees a missing-key request. Paired flags so the two
     // layers agree; see `applyIdempotencyInvariant` for the runner-level skip.
     const testsMissingIdempotencyKey = step.omit_idempotency_key === true && (0, idempotency_1.isMutatingTask)(effectiveStep.task);
-    // Defense-in-depth for the missing-key vector: when a mutating step sets
-    // `omit_idempotency_key: true` and `step.auth` is unset, route via
-    // `rawMcpProbe` anyway so no SDK-layer normalization can slip a key onto the
-    // wire. The SDK's `skipIdempotencyAutoInject` plumbing already honors this
-    // flag, but the raw-HTTP path removes the escape hatch entirely. A2A and
-    // oauth stay on the SDK path — their dispatch can't be replicated here
-    // (A2A uses a different envelope; oauth needs refresh semantics).
+    // Analogous to `testsMissingIdempotencyKey`: when a step sets
+    // `omit_account: true` the runner has already suppressed account synthesis
+    // in `applyBrandInvariant` (above — ordering is load-bearing: this must
+    // come after `applyBrandInvariant` so the comment "above" stays accurate
+    // if either block is reordered). Track the flag here so the raw-probe
+    // defense-in-depth path is also triggered and no SDK-layer normalization
+    // can silently re-inject an account before the wire call.
+    const testsMissingAccount = step.omit_account === true && effectiveStep.task === 'create_media_buy';
+    // Defense-in-depth for the missing-field vectors: when a step sets
+    // `omit_idempotency_key: true` or `omit_account: true` and `step.auth` is
+    // unset, route via `rawMcpProbe` anyway so no SDK-layer normalization can
+    // slip the missing field onto the wire. The SDK's `skipIdempotencyAutoInject`
+    // / `skipAccountValidation` plumbing already honors these flags, but the
+    // raw-HTTP path removes the escape hatch entirely. A2A and oauth stay on
+    // the SDK path — their dispatch can't be replicated here (A2A uses a
+    // different envelope; oauth needs refresh semantics).
     const rawProbeHeaders = step.auth !== undefined
         ? authHeadersForStep(step.auth, options)
-        : testsMissingIdempotencyKey && options.protocol !== 'a2a'
+        : (testsMissingIdempotencyKey || testsMissingAccount) && options.protocol !== 'a2a'
             ? defaultAuthHeadersForRawProbe(options)
             : undefined;
     const useRawProbe = rawProbeHeaders !== undefined;
@@ -2516,6 +2617,83 @@ client, step, phaseId, context, allSteps, options, state) {
     let httpResult;
     let responseRecord;
     let a2aEnvelope;
+    let crossResponses;
+    // Parallel-dispatch fan-out: when the storyboard step declares
+    // `parallel_dispatch`, the runner fires N concurrent dispatches against
+    // the same agent with the same idempotency_key (default) and grades the
+    // cross-response set instead of a single response. Gated on the
+    // `parallel_dispatch_runner` test-kit contract — runners (or runs) without
+    // it grade the step `not_applicable` so older runners don't fail on
+    // newer storyboard contracts.
+    if (step.parallel_dispatch && !useRawProbe) {
+        const contractsInScope = new Set(options.contracts ?? []);
+        if (!contractsInScope.has(parallel_dispatch_1.PARALLEL_DISPATCH_CONTRACT)) {
+            const next = getNextStepPreview(step.id, allSteps, context, runState.runnerVars);
+            const detail = `Test-kit contract "${parallel_dispatch_1.PARALLEL_DISPATCH_CONTRACT}" is not configured on this runner; concurrent-retry grading requires it.`;
+            return {
+                step_id: step.id,
+                phase_id: phaseId,
+                title: step.title,
+                task: step.task,
+                passed: true,
+                skipped: true,
+                skip_reason: 'not_applicable',
+                skip: buildSkip('not_applicable', detail),
+                duration_ms: 0,
+                validations: [],
+                context,
+                next,
+                extraction: { path: 'none' },
+            };
+        }
+        const specError = (0, parallel_dispatch_1.validateParallelDispatchSpec)(step.parallel_dispatch);
+        if (specError) {
+            const next = getNextStepPreview(step.id, allSteps, context, runState.runnerVars);
+            return {
+                step_id: step.id,
+                phase_id: phaseId,
+                title: step.title,
+                task: step.task,
+                passed: false,
+                duration_ms: 0,
+                validations: [
+                    {
+                        check: 'parallel_dispatch_misconfigured',
+                        passed: false,
+                        description: specError,
+                        json_pointer: null,
+                        expected: 'a well-formed parallel_dispatch spec',
+                        actual: step.parallel_dispatch,
+                        schema_id: null,
+                        schema_url: null,
+                    },
+                ],
+                context,
+                error: specError,
+                next,
+                extraction: { path: 'none' },
+            };
+        }
+        if (step.parallel_dispatch.mode === 'distributed') {
+            const next = getNextStepPreview(step.id, allSteps, context, runState.runnerVars);
+            const detail = 'parallel_dispatch.mode: distributed is not implemented in @adcp/sdk; use process_local for in-process grading.';
+            return {
+                step_id: step.id,
+                phase_id: phaseId,
+                title: step.title,
+                task: step.task,
+                passed: true,
+                skipped: true,
+                skip_reason: 'not_applicable',
+                skip: buildSkip('not_applicable', detail),
+                duration_ms: 0,
+                validations: [],
+                context,
+                next,
+                extraction: { path: 'none' },
+            };
+        }
+    }
     // Capture the ISO timestamp immediately before the step's AdCP request
     // dispatch. `upstream_traffic` validations use this as the default
     // `since_timestamp` window bound when querying the controller. Recorded
@@ -2574,40 +2752,91 @@ client, step, phaseId, context, allSteps, options, state) {
         // lands, key the capture off the negotiated transport instead.
         const captureA2a = options.protocol === 'a2a';
         let a2aCaptures;
-        const dispatch = () => (0, task_map_1.executeStoryboardTask)(client, effectiveStep.task, request, {
-            skipIdempotencyAutoInject: testsMissingIdempotencyKey,
-        });
-        const run = await (0, client_1.runStep)(step.title, effectiveStep.task, async () => {
-            if (!captureA2a)
-                return dispatch();
-            try {
-                const { result: dispatchResult, captures } = await (0, rawResponseCapture_1.withRawResponseCapture)(dispatch);
-                a2aCaptures = captures;
-                return dispatchResult;
-            }
-            catch (err) {
-                // `withRawResponseCapture` attaches partial captures to the
-                // thrown error so we still get the wire-shape envelope when
-                // the SDK threw mid-parse (e.g. agent emitted malformed JSON).
-                // Bare-throw cases (network errors, no captures attached)
-                // leave `a2aCaptures` undefined and the validator self-skips.
-                const partial = (0, rawResponseCapture_1.getCapturesFromError)(err);
-                if (partial)
-                    a2aCaptures = partial;
-                throw err;
+        if (step.parallel_dispatch) {
+            // Fan out N concurrent dispatches via the SDK client. All dispatches
+            // share the runner-minted idempotency_key (default) so the seller
+            // sees one logical request and resolves the race deterministically.
+            //
+            // Known limitation: `dispatchWithBarrier` uses `Promise.race` against a
+            // timer; when the barrier wins, the underlying SDK request is NOT
+            // aborted — it continues to completion against the seller. The runner
+            // reports the dispatch as `timed_out`, but a late-arriving success
+            // can still land on the seller's idempotency cache. Storyboard
+            // authors writing follow-up steps that observe seller state after a
+            // barrier timeout should account for this race.
+            const started = Date.now();
+            crossResponses = await (0, parallel_dispatch_1.runParallelDispatches)(client, effectiveStep.task, request, {
+                spec: step.parallel_dispatch,
+                keyMinter: idempotency_1.generateIdempotencyKey,
+                correlationPrefix: step.id,
+            });
+            const durationMs = Date.now() - started;
+            // Representative TaskResult is ALWAYS `dispatches[0]` — pinning the
+            // representative to a fixed index keeps the aggregation loop's `i=1`
+            // start aligned (every dispatch graded exactly once). Picking the
+            // "best" resolved arm would double-count whichever dispatch won and
+            // skip dispatches[0] from per-response grading entirely.
+            const firstDispatch = crossResponses.dispatches[0];
+            const allTimedOut = crossResponses.dispatches.every(d => d.timed_out);
+            const barrierTimeoutError = 'parallel_dispatch_barrier_timeout: no dispatch resolved within barrier_timeout_ms';
+            taskResult = firstDispatch?.taskResult ?? {
+                success: false,
+                ...(allTimedOut && { error: barrierTimeoutError }),
+            };
+            // Pass/fail is derived from the cross-response set rather than any
+            // single arm: the step passes when at least one dispatch resolved
+            // (cross-response validations then grade the race outcome). All-
+            // timed-out is a hard failure regardless of validations.
+            stepResult = {
+                duration_ms: durationMs,
+                passed: !allTimedOut && crossResponses.resolved.length > 0,
+                ...(allTimedOut && { error: barrierTimeoutError }),
+            };
+            if (taskResult) {
+                responseRecord = {
+                    transport: options.protocol === 'a2a' ? 'a2a' : 'mcp',
+                    payload: (0, redact_secrets_1.redactSecrets)(taskResult.data ?? taskResult.error ?? null),
+                    duration_ms: durationMs,
+                };
             }
-        });
-        taskResult = run.result;
-        stepResult = run.step;
-        if (captureA2a && a2aCaptures) {
-            a2aEnvelope = parseLastA2aMessageSendCapture(a2aCaptures);
         }
-        if (taskResult) {
-            responseRecord = {
-                transport: options.protocol === 'a2a' ? 'a2a' : 'mcp',
-                payload: (0, redact_secrets_1.redactSecrets)(taskResult.data ?? taskResult.error ?? null),
-                duration_ms: stepResult.duration_ms,
-            };
+        else {
+            const dispatch = () => (0, task_map_1.executeStoryboardTask)(client, effectiveStep.task, request, {
+                skipIdempotencyAutoInject: testsMissingIdempotencyKey,
+                skipAccountValidation: testsMissingAccount,
+            });
+            const run = await (0, client_1.runStep)(step.title, effectiveStep.task, async () => {
+                if (!captureA2a)
+                    return dispatch();
+                try {
+                    const { result: dispatchResult, captures } = await (0, rawResponseCapture_1.withRawResponseCapture)(dispatch);
+                    a2aCaptures = captures;
+                    return dispatchResult;
+                }
+                catch (err) {
+                    // `withRawResponseCapture` attaches partial captures to the
+                    // thrown error so we still get the wire-shape envelope when
+                    // the SDK threw mid-parse (e.g. agent emitted malformed JSON).
+                    // Bare-throw cases (network errors, no captures attached)
+                    // leave `a2aCaptures` undefined and the validator self-skips.
+                    const partial = (0, rawResponseCapture_1.getCapturesFromError)(err);
+                    if (partial)
+                        a2aCaptures = partial;
+                    throw err;
+                }
+            });
+            taskResult = run.result;
+            stepResult = run.step;
+            if (captureA2a && a2aCaptures) {
+                a2aEnvelope = parseLastA2aMessageSendCapture(a2aCaptures);
+            }
+            if (taskResult) {
+                responseRecord = {
+                    transport: options.protocol === 'a2a' ? 'a2a' : 'mcp',
+                    payload: (0, redact_secrets_1.redactSecrets)(taskResult.data ?? taskResult.error ?? null),
+                    duration_ms: stepResult.duration_ms,
+                };
+            }
         }
     }
     const requestRecord = {
@@ -2653,6 +2882,14 @@ client, step, phaseId, context, allSteps, options, state) {
         // Step passes when the task fails (returns an error)
         passed = !taskResult?.success || !!stepResult.error;
     }
+    else if (crossResponses) {
+        // Parallel-dispatch step: pass/fail is driven by the cross-response
+        // set, not the representative arm. The representative is pinned to
+        // `dispatches[0]` (which may itself have failed under the race) so
+        // gating on its `.success` would false-fail steps where later arms
+        // resolved correctly. Validations grade the actual race outcome.
+        passed = stepResult.passed;
+    }
     else {
         passed = stepResult.passed && (taskResult?.success ?? false);
     }
@@ -2692,6 +2929,7 @@ client, step, phaseId, context, allSteps, options, state) {
             ...(a2aEnvelope && { a2aEnvelope }),
             ...(upstreamTraffic && { upstreamTraffic }),
             ...(step.sample_request && { storyboardStep: { sample_request: step.sample_request } }),
+            ...(crossResponses && { crossResponses }),
             ...(() => {
                 // Walk back through the run's captured A2A envelopes and use
                 // the most recent prior step's envelope as the comparison
@@ -2713,6 +2951,43 @@ client, step, phaseId, context, allSteps, options, state) {
             })(),
         };
         validations = (0, validations_1.runValidations)(resolvedValidations, vctx);
+        // Parallel-dispatch aggregation: per-response checks (`response_schema`,
+        // `field_present`, `error_code`, etc.) declared by the storyboard MUST
+        // grade against every dispatch's resolved response, not just the
+        // representative one. Re-run each non-cross-response validation against
+        // each dispatch's TaskResult and append the additional results so the
+        // step's overall pass/fail reflects the full fan-out. The first run
+        // (above) already covers dispatch[0]; this loop covers dispatches[1..N].
+        if (crossResponses && crossResponses.dispatches.length > 1) {
+            const perResponseValidations = resolvedValidations.filter(v => v.check !== 'cross_response_field_equal' && v.check !== 'cross_response_count_distinct');
+            for (let i = 1; i < crossResponses.dispatches.length; i++) {
+                const d = crossResponses.dispatches[i];
+                if (!d || !d.taskResult)
+                    continue;
+                const dispatchCtx = {
+                    ...vctx,
+                    taskResult: d.taskResult,
+                    // Per-dispatch responseRecord stays minimal — the redacted payload
+                    // captures enough for failure attribution without bloating success.
+                    ...(responseRecord && {
+                        response: {
+                            ...responseRecord,
+                            payload: (0, redact_secrets_1.redactSecrets)(d.taskResult.data ?? d.taskResult.error ?? null),
+                            duration_ms: d.duration_ms,
+                        },
+                    }),
+                };
+                // Drop crossResponses on the per-dispatch context so cross-response
+                // checks don't re-fire here (they already ran once above on the
+                // representative dispatch and produced their single result).
+                delete dispatchCtx.crossResponses;
+                const dispatchResults = (0, validations_1.runValidations)(perResponseValidations, dispatchCtx).map(r => ({
+                    ...r,
+                    description: `[dispatch ${d.correlation_id}] ${r.description}`,
+                }));
+                validations.push(...dispatchResults);
+            }
+        }
     }
     // Persist the captured A2A envelope keyed by step id so cross-step
     // validators (`a2a_context_continuity`) on subsequent steps can
@@ -2907,6 +3182,7 @@ client, step, phaseId, context, allSteps, options, state) {
             context_provenance: Object.fromEntries(runState.contextProvenance),
         }),
         error: step.expect_error ? undefined : truncateError(stepResult.error || taskResult?.error),
+        ...(!step.expect_error && taskResult?.adcp_error && { adcp_error: taskResult.adcp_error }),
         next,
         request: requestRecord,
         ...(responseRecord && { response_record: responseRecord }),
@@ -3324,7 +3600,7 @@ function evalContributesIf(expr, priorStepResults) {
  * the function fails open and injects as before. Schema checks use raw JSON
  * reads, not AJV internals.
  */
-function applyBrandInvariant(request, options, taskName) {
+function applyBrandInvariant(request, options, taskName, stepFlags) {
     // Only force the invariant when the caller has actually supplied a brand.
     // Storyboards that don't exercise brand-scoped tools (e.g. security
     // probes) legitimately run without one and should pass through unchanged.
@@ -3340,6 +3616,13 @@ function applyBrandInvariant(request, options, taskName) {
     const result = { ...request };
     if (topBrandOk)
         result.brand = brand;
+    // When a storyboard step sets `omit_account: true` it is deliberately
+    // testing the seller's missing-account rejection path. Skip all account
+    // synthesis — both the natural-key-merge branch (existing account on the
+    // request) and the synthetic-construction branch (no account on the
+    // request) — so the request reaches the wire exactly as authored.
+    if (stepFlags?.omit_account)
+        return result;
     if ('account' in request) {
         // Caller sent an account — merge brand in only when it's a plain object
         // using AccountReference's natural-key variant (`{brand, operator, sandbox?}`).