@adcp/sdk 6.19.1 → 7.1.0

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

@@ -29,8 +29,10 @@ 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 response_unwrapper_1 = require("../../utils/response-unwrapper");
 const test_controller_1 = require("../test-controller");
 const request_builder_1 = require("./request-builder");
 const client_2 = require("../client");
@@ -242,6 +244,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;
         }
@@ -679,6 +682,7 @@ function buildCapabilityUnsupportedResult(agentUrls, storyboard, detail) {
             strict_only_failures: 0,
             lenient_also_failed: 0,
         },
+        notices: [],
     };
 }
 /**
@@ -698,6 +702,8 @@ const REQUIREMENT_TO_SKIP_REASON = {
     controller: 'missing_test_controller',
     seeded_state: 'requirement_unmet',
     real_wire: 'requirement_unmet',
+    webhook_receiver: 'requirement_unmet',
+    request_signer: 'not_applicable',
 };
 /**
  * Build a minimal StoryboardResult for a storyboard skipped because a
@@ -753,6 +759,7 @@ function buildRequirementUnmetResult(agentUrls, storyboard, requirement, detail)
             strict_only_failures: 0,
             lenient_also_failed: 0,
         },
+        notices: [],
     };
 }
 /**
@@ -770,8 +777,25 @@ 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.
+ *   - `request_signer` — agent advertises `request_signing.supported: true`
+ *     in `get_adcp_capabilities`. Autodetected for any storyboard whose
+ *     id is `'signed_requests'` or that contains a `request_signing_probe`
+ *     step (see `detectImplicitRequires`); authors don't write this tag
+ *     manually. Absence-skip semantics are INVERTED from the general
+ *     `requires_capability` rule: the signed-requests universal
+ *     storyboard's own gating spec (signed-requests.yaml prerequisites)
+ *     declares "agents that do not advertise support are not tested
+ *     against this storyboard — absence of advertisement is not a
+ *     failure". When the runner can't read capabilities (no profile
+ *     threaded through), the gate is a no-op — the caller accepted
+ *     responsibility for capability compatibility by reusing an external
+ *     client. Spec: adcp-client#1702.
  */
-function checkRequires(requires, options) {
+function checkRequires(requires, options, profile) {
     for (const requirement of requires) {
         switch (requirement) {
             case 'controller': {
@@ -799,10 +823,119 @@ 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;
+            }
+            case 'request_signer': {
+                // Gate is a no-op when no profile is threaded through (external
+                // `_client` mode). The caller has accepted responsibility for
+                // capability compatibility; failing the gate here would surprise
+                // them with a skip they can't explain from CLI options alone.
+                if (!profile?.raw_capabilities)
+                    break;
+                const supported = resolveCapabilityPath(profile.raw_capabilities, 'request_signing.supported');
+                if (supported === true)
+                    break;
+                return {
+                    requirement,
+                    detail: 'Storyboard requires `request_signing.supported: true` in `get_adcp_capabilities`; ' +
+                        `agent declared ${supported === undefined ? 'no request_signing block' : JSON.stringify(supported)}. ` +
+                        'Per compliance/{version}/universal/signed-requests.yaml: "Agents that do not advertise ' +
+                        'support are not tested against this storyboard — absence of advertisement is not a ' +
+                        'failure, it is a declaration that the agent does not offer verified signed requests." ' +
+                        'To opt in, advertise `request_signing.supported: true` and pre-register the runner ' +
+                        'compliance test keypair per test-kits/signed-requests-runner.yaml. ' +
+                        'Forward-readiness: optional in AdCP 3.0; the schema (request_signing block description) ' +
+                        'declares request signing required for spend-committing operations in AdCP 4.0. Sellers ' +
+                        'that intend to support spend-committing tools SHOULD advertise the capability and ' +
+                        'register the test keypair before the 4.0 cut to avoid a hard compliance failure then.',
+                };
+            }
         }
     }
     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:
+ *   - `'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.
+ *   - `'request_signer'`, autodetected from `storyboard.id ===
+ *     'signed_requests'` or any step using the synthesized
+ *     `request_signing_probe` task. The signed-requests universal
+ *     storyboard's own prerequisites section declares the
+ *     `request_signing.supported: true` capability gate; the runner
+ *     enforces it here so adopters don't see false-negative vector
+ *     failures on bearer-only agents that never claimed signing.
+ *     Spec: adcp-client#1702.
+ */
+function detectImplicitRequires(storyboard) {
+    const requires = [];
+    let needsWebhook = false;
+    let needsSigner = storyboard.id === 'signed_requests';
+    for (const phase of storyboard.phases) {
+        for (const step of phase.steps) {
+            if (!needsWebhook && step.sample_request && valueContainsWebhookToken(step.sample_request)) {
+                needsWebhook = true;
+            }
+            if (!needsSigner && step.task === 'request_signing_probe') {
+                needsSigner = true;
+            }
+            if (needsWebhook && needsSigner)
+                break;
+        }
+        if (needsWebhook && needsSigner)
+            break;
+    }
+    if (needsWebhook)
+        requires.push('webhook_receiver');
+    if (needsSigner)
+        requires.push('request_signer');
+    return requires;
+}
 /**
  * Build a hard-failure StoryboardResult for when agent capability
  * discovery (`get_agent_info` / MCP `tools/list`) failed. Surfacing
@@ -858,6 +991,7 @@ function buildDiscoveryFailedResult(agentUrls, storyboard, discoveryStep) {
             strict_only_failures: 0,
             lenient_also_failed: 0,
         },
+        notices: [],
     };
 }
 /**
@@ -915,8 +1049,85 @@ function buildRequiredToolsMissingResult(agentUrls, storyboard, detail) {
             strict_only_failures: 0,
             lenient_also_failed: 0,
         },
+        notices: [],
     };
 }
+/**
+ * Collect protocol-compliance notices for a storyboard run based on the
+ * agent's declared capabilities. Returns an empty array when rawCaps is
+ * absent (standalone runner without pre-fetched profile).
+ *
+ * Currently emits two spec-grounded notices (adcp-client#1704):
+ *
+ * - `request_signing.required`: `request_signing.supported` is absent or
+ *   false on the signed_requests storyboard. Signing becomes required for
+ *   spend-committing operations in `effective_version: '4.0'`.
+ *
+ * - `webhook_signing.legacy_hmac_fallback.removed`: agent claims
+ *   `webhook_signing.legacy_hmac_fallback: true`, which is removed in
+ *   `effective_version: '4.0'`.
+ *
+ * Note: a third notice (`signed_requests_specialism_deprecated`) is deferred
+ * pending upstream deprecation of the `'signed-requests'` specialism value in
+ * adcontextprotocol/adcp#4418 — the value is still active in the spec.
+ */
+function collectCapabilityNotices(storyboard, rawCaps) {
+    const notices = [];
+    if (!rawCaps || typeof rawCaps !== 'object')
+        return notices;
+    const caps = rawCaps;
+    // Notice: request_signing required in AdCP 4.0.
+    // Fired when this is the signed_requests storyboard and the agent hasn't
+    // declared request_signing support. The storyboard is identified by id OR
+    // by the presence of a request_signing_probe step (mirrors the implicit-
+    // require detection in detectImplicitRequires for PR #1703's gate).
+    const isSignedRequestsStoryboard = storyboard.id === 'signed_requests' ||
+        storyboard.phases.some(p => p.steps.some(s => s.task === 'request_signing_probe'));
+    if (isSignedRequestsStoryboard) {
+        const requestSigning = caps['request_signing'];
+        if (requestSigning?.['supported'] !== true) {
+            notices.push({
+                severity: 'future_required',
+                code: 'request_signing.required',
+                message: 'RFC 9421 request signing (`request_signing.supported: true`) is not advertised. ' +
+                    'Required for spend-committing operations in AdCP 4.0 — 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',
+                docs_url: 'https://adcontextprotocol.org/docs/building/implementation/security#signed-requests-transport-layer',
+                storyboard_ids: [storyboard.id],
+            });
+        }
+    }
+    // Notice: legacy_hmac_fallback removed in AdCP 4.0.
+    // Scoped via the WEBHOOK_STEP_TASKS step-task set rather than an id-regex.
+    // Step-task presence is the authoring contract — a storyboard that asserts
+    // webhook delivery uses one of these tasks. A storyboard id alone (e.g. a
+    // hypothetical `webhook_authoring_guide`) shouldn't trigger the notice
+    // unless it actually exercises the delivery path.
+    const WEBHOOK_STEP_TASKS = new Set([
+        'expect_webhook',
+        'expect_webhook_retry_keys_stable',
+        'expect_webhook_signature_valid',
+    ]);
+    const isWebhookRelatedStoryboard = storyboard.phases.some(p => p.steps.some(s => WEBHOOK_STEP_TASKS.has(s.task)));
+    if (isWebhookRelatedStoryboard) {
+        const webhookSigning = caps['webhook_signing'];
+        if (webhookSigning?.['legacy_hmac_fallback'] === true) {
+            notices.push({
+                severity: 'deprecation',
+                code: 'webhook_signing.legacy_hmac_fallback.removed',
+                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',
+                docs_url: 'https://adcontextprotocol.org/docs/building/implementation/webhooks',
+                storyboard_ids: [storyboard.id],
+            });
+        }
+    }
+    return notices;
+}
 /**
  * Execute a single pass of the storyboard against the supplied replica URLs
  * using round-robin dispatch starting at `dispatchOffset`. Called directly
@@ -1030,12 +1241,33 @@ 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`.
+    // Pre-flight notice collection. Uses options._profile (set by the comply()
+    // pipeline before calling runStoryboard) so the notices are available on
+    // early-return results (requirement-unmet, capability-unsupported). In the
+    // standalone runner path options._profile may be undefined; notices will be
+    // collected again from the fully-fetched profile at result-build time.
+    const preflightNotices = collectCapabilityNotices(storyboard, options._profile?.raw_capabilities);
+    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, profile);
         if (unmet) {
             if (!options._client)
                 await (0, protocols_1.closeConnections)(options.protocol);
-            return buildRequirementUnmetResult(agentUrls, storyboard, unmet.requirement, unmet.detail);
+            return {
+                ...buildRequirementUnmetResult(agentUrls, storyboard, unmet.requirement, unmet.detail),
+                notices: preflightNotices,
+            };
         }
     }
     // Evaluate requires_capability predicate before any phase setup.
@@ -1061,7 +1293,7 @@ async function executeStoryboardPass(agentUrls, storyboard, options, dispatchOff
                     `agent declared ${JSON.stringify(actual)}.`;
                 if (!options._client)
                     await (0, protocols_1.closeConnections)(options.protocol);
-                return buildCapabilityUnsupportedResult(agentUrls, storyboard, detail);
+                return { ...buildCapabilityUnsupportedResult(agentUrls, storyboard, detail), notices: preflightNotices };
             }
         }
     }
@@ -1081,7 +1313,10 @@ async function executeStoryboardPass(agentUrls, storyboard, options, dispatchOff
         if (!hasAnyRequired) {
             if (!options._client)
                 await (0, protocols_1.closeConnections)(options.protocol);
-            return buildRequiredToolsMissingResult(agentUrls, storyboard, `agent does not advertise any of [${storyboard.required_tools.join(', ')}]`);
+            return {
+                ...buildRequiredToolsMissingResult(agentUrls, storyboard, `agent does not advertise any of [${storyboard.required_tools.join(', ')}]`),
+                notices: preflightNotices,
+            };
         }
     }
     let context = { ...options.context };
@@ -1366,6 +1601,18 @@ async function executeStoryboardPass(agentUrls, storyboard, options, dispatchOff
             });
             continue;
         }
+        // Pre-empt OAuth-metadata probes when the agent's capabilities never
+        // advertised OAuth at all (adcp-client#1702). Without this, an
+        // API-key-only agent (e.g. Wonderstruck) has its PRM endpoint
+        // probed; if the well-known path returns anything other than 404
+        // (the existing reactive cascade trigger in `executeProbeStep`),
+        // validations fail and `oauth_discovery` produces 5 false-negative
+        // step failures even though the phase is `optional: true`. The skip
+        // is phase-level — not storyboard-level — so the universal
+        // `unauth_rejection` and `mechanism_required` phases still run.
+        if (!phaseAbsent && phaseContainsOauthMetadataProbe(phase) && !agentAdvertisesOauth(profile)) {
+            phaseAbsent = true;
+        }
         // 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
@@ -1569,6 +1816,20 @@ async function executeStoryboardPass(agentUrls, storyboard, options, dispatchOff
             }
             stepResults.push(result);
             priorStepResults.set(step.id, result);
+            // Schema-validation short-circuit (adcp-client#1709). When the
+            // response unwrapper rejected the agent's response against the SDK's
+            // Zod schema, the step-execution path synthesized a failing
+            // `response_schema` ValidationResult on `result.validations`.
+            // Running step-scope invariants against a response the SDK has
+            // already declared malformed produces noise — the invariants
+            // can't meaningfully grade a payload that didn't parse. Worse,
+            // before #1709 the invariants' failure entries crowded out the
+            // schema-validation entry in `extractFailures`, masking the root
+            // cause across BidMachine's 10+ deploys (see adcp#4419). Skip the
+            // invariant pass entirely on this step and emit a single skipped
+            // `assertion` entry per invariant so consumers can still see WHICH
+            // invariants were skipped and why.
+            const schemaInvalidResponse = result.validations.some(v => v.check === 'response_schema' && !v.passed);
             // Fire per-step assertions. Each result is appended to the step's
             // `validations[]` under `check: "assertion"` so existing UI renders
             // them alongside inline checks, and mirrored into `assertionResults`
@@ -1583,6 +1844,18 @@ async function executeStoryboardPass(agentUrls, storyboard, options, dispatchOff
                 // behavior the invariant would flag (validated at runner start).
                 if ((0, assertions_1.stepDisablesAssertion)(step.invariants, spec.id))
                     continue;
+                if (schemaInvalidResponse) {
+                    // Emit a skipped marker so the report shows the invariant was
+                    // intentionally bypassed (not silently dropped). `passed: true`
+                    // keeps it from flipping `result.passed` — the schema-validation
+                    // failure already did that.
+                    result.validations.push({
+                        check: 'assertion',
+                        passed: true,
+                        description: `${spec.id}: skipped — response failed schema validation (adcp-client#1709)`,
+                    });
+                    continue;
+                }
                 const raw = await spec.onStep(assertionContexts.get(spec.id), result);
                 for (const r of raw) {
                     const full = { ...r, assertion_id: spec.id, scope: 'step', step_id: step.id };
@@ -1944,6 +2217,10 @@ async function executeStoryboardPass(agentUrls, storyboard, options, dispatchOff
     const schemasUsed = collectSchemasUsed(phaseResults);
     const strictSummary = summarizeStrictValidation(phaseResults);
     const validationsNotApplicable = countValidationsNotApplicable(phaseResults);
+    // Use the fully-fetched profile for notice detection; fall back to pre-flight
+    // notices (which used options._profile) when profile was not re-fetched in
+    // this pass (standalone runner with options._profile pre-set skips the fetch).
+    const notices = collectCapabilityNotices(storyboard, profile?.raw_capabilities ?? options._profile?.raw_capabilities);
     const result = {
         storyboard_id: storyboard.id,
         storyboard_title: storyboard.title,
@@ -1966,6 +2243,7 @@ async function executeStoryboardPass(agentUrls, storyboard, options, dispatchOff
         ...(schemasUsed.length > 0 ? { schemas_used: schemasUsed } : {}),
         ...(assertionResults.length > 0 ? { assertions: assertionResults } : {}),
         strict_validation_summary: strictSummary,
+        notices,
     };
     // Close protocol connections when the runner created its own client. The
     // connection pool is keyed by URL+auth, so a single closeConnections() call
@@ -2042,6 +2320,8 @@ async function runMultiPass(agentUrls, storyboard, options) {
     // readers see a per-pass timeline; de-duplicating would hide a real
     // "passed on pass 1, failed on pass 2" divergence.
     const assertionsAgg = passResults.flatMap(r => r.assertions ?? []);
+    // Notices are identical across passes (same agent, same capabilities); deduplicate by code.
+    const noticesDedup = [...new Map(passResults.flatMap(r => r.notices).map(n => [n.code, n])).values()];
     return {
         storyboard_id: storyboard.id,
         storyboard_title: storyboard.title,
@@ -2060,6 +2340,7 @@ async function runMultiPass(agentUrls, storyboard, options) {
         tested_at: new Date().toISOString(),
         ...(schemasDedup.length > 0 ? { schemas_used: schemasDedup } : {}),
         ...(assertionsAgg.length > 0 ? { assertions: assertionsAgg } : {}),
+        notices: noticesDedup,
     };
 }
 /**
@@ -2426,7 +2707,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
@@ -2507,24 +2790,115 @@ 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;
     let taskResult;
     let stepResult;
+    // Raw caught error from the dispatch fn — preserved as `unknown` so the
+    // schema-validation attribution path below can `instanceof` it against
+    // `ResponseSchemaValidationError`. Undefined when the step succeeded or
+    // failed for a non-typed reason. Spec: adcp-client#1709.
+    let caughtError;
     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
@@ -2583,40 +2957,92 @@ 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;
+            caughtError = run.caughtError;
+            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 = {
@@ -2662,13 +3088,21 @@ 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);
     }
+    let validations = [];
     // Run validations. Resolve `$context.<key>` placeholders in `value` and
     // `allowed_values` fields so expected values can reference prior steps
     // (e.g., replay tests assert `media_buy_id === $context.initial_media_buy_id`).
-    let validations = [];
     if (step.validations?.length && (taskResult || httpResult)) {
         const resolvedValidations = step.validations.map(v => {
             const resolved = { ...v };
@@ -2701,6 +3135,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
@@ -2722,6 +3157,78 @@ 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);
+            }
+        }
+    }
+    // Schema-validation attribution (adcp-client#1709). When the response
+    // unwrapper rejected the agent's response against the SDK's Zod schema
+    // for the tool, it threw a typed `ResponseSchemaValidationError` that
+    // surfaced on `caughtError`. Without this attribution, the rejection
+    // would silently propagate into whichever step-scope invariant (e.g.
+    // `context.no_secret_echo`) happened to fire next — the BidMachine
+    // misdiagnosis trace from adcp-client#1709 / adcp#4419 ate 10+ deploys
+    // chasing the wrong cause.
+    //
+    // Synthesize a canonical `response_schema` ValidationResult and prepend
+    // it so `extractFailures.find(v => !v.passed)` resolves it before any
+    // invariant entry. Step-scope invariants downstream of this point will
+    // short-circuit on the schema-invalid response (see the invariant
+    // dispatch loop in `executeStoryboardPass`).
+    if (caughtError instanceof response_unwrapper_1.ResponseSchemaValidationError) {
+        const issues = caughtError.issues
+            .slice(0, 5)
+            .map(i => `${i.path.join('.') || '(root)'}: ${i.message}`)
+            .join('; ');
+        const firstIssue = caughtError.issues[0];
+        const jsonPointer = firstIssue ? '/' + firstIssue.path.map(s => String(s)).join('/') : null;
+        const synthSchemaResult = {
+            check: 'response_schema',
+            passed: false,
+            description: `Response schema validation for ${caughtError.toolName}`,
+            error: issues,
+            json_pointer: jsonPointer,
+            expected: `response schema for ${caughtError.toolName}`,
+            actual: caughtError.issues,
+        };
+        // Prepend so extractFailures picks it up before any inline validation
+        // entry that may also be failing (e.g. `field_present` checks that
+        // legitimately can't observe their target against an unparsed payload).
+        validations = [synthSchemaResult, ...validations];
     }
     // Persist the captured A2A envelope keyed by step id so cross-step
     // validators (`a2a_context_continuity`) on subsequent steps can
@@ -2916,6 +3423,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 }),
@@ -3151,6 +3659,33 @@ function isTaskShape(result) {
 // ────────────────────────────────────────────────────────────
 // Phase / step skip predicates
 // ────────────────────────────────────────────────────────────
+/**
+ * True when the phase contains an OAuth-metadata probe step
+ * (`protected_resource_metadata` or `oauth_auth_server_metadata`). Used
+ * to pre-emptively trigger the existing `phaseAbsent` cascade when the
+ * agent's capabilities never advertised OAuth in the first place, so we
+ * don't burn step failures probing a well-known path the agent doesn't
+ * claim. Spec: adcp-client#1702.
+ */
+function phaseContainsOauthMetadataProbe(phase) {
+    return phase.steps.some(s => s.task === 'protected_resource_metadata' || s.task === 'oauth_auth_server_metadata');
+}
+/**
+ * True when the agent's `get_adcp_capabilities` response declares an
+ * OAuth issuer (today: `account.authorization_endpoint`). When the
+ * profile or its capabilities aren't available — e.g. external
+ * `_client` mode — we conservatively return `true` so the runner falls
+ * through to the existing reactive cascade (`phaseAbsent` flips on a
+ * 404 from the PRM probe). That keeps backward compatibility for
+ * callers that haven't threaded a profile through. Spec: adcp-client#1702.
+ */
+function agentAdvertisesOauth(profile) {
+    const rawCaps = profile?.raw_capabilities;
+    if (rawCaps === undefined)
+        return true;
+    const endpoint = resolveCapabilityPath(rawCaps, 'account.authorization_endpoint');
+    return typeof endpoint === 'string' && endpoint.length > 0;
+}
 /**
  * Evaluate a phase's `skip_if` expression against the runtime options. Only
  * a tiny grammar is supported today; unknown expressions fail closed (phase runs).
@@ -3333,7 +3868,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.
@@ -3349,6 +3884,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?}`).