@adcp/sdk 8.1.0-beta.1 → 8.1.0-beta.10

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

@@ -7,6 +7,8 @@
  * - runStoryboardStep(): run a single step (stateless, LLM-friendly)
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyStoryboardVersionOptions = applyStoryboardVersionOptions;
+exports.applyAdcpVersionRunOptions = applyAdcpVersionRunOptions;
 exports.resolveCapabilityPath = resolveCapabilityPath;
 exports.evaluateCapabilityPredicate = evaluateCapabilityPredicate;
 exports.__redactSecretsForTest = __redactSecretsForTest;
@@ -39,7 +41,9 @@ const request_builder_1 = require("./request-builder");
 const client_2 = require("../client");
 const idempotency_1 = require("../../utils/idempotency");
 const schema_loader_1 = require("../../validation/schema-loader");
+const version_1 = require("../../version");
 const probes_1 = require("./probes");
+const capabilities_types_1 = require("../../signing/agent-resolver/capabilities-types");
 const test_kit_1 = require("./test-kit");
 const loader_1 = require("./loader");
 const probe_dispatch_1 = require("./request-signing/probe-dispatch");
@@ -65,6 +69,26 @@ const SKIP_DETAILS = {
 };
 const CONTROLLER_SEEDING_FAILED_DETAIL = 'Skipped: pre-flight comply_test_controller seeding failed; the agent was not populated with the storyboard fixtures the remaining phases depend on.';
 const OAUTH_NOT_ADVERTISED_DETAIL = 'Skipped: agent does not advertise OAuth — /.well-known/oauth-protected-resource returned 404 (RFC 9728 §3). API-key path must carry auth_mechanism_verified for this storyboard to pass.';
+function applyStoryboardVersionOptions(storyboard, options) {
+    return applyAdcpVersionRunOptions(storyboard.adcp_version, options);
+}
+function applyAdcpVersionRunOptions(defaultAdcpVersion, options) {
+    const adcpVersion = options.adcpVersion ?? defaultAdcpVersion;
+    if (adcpVersion === undefined)
+        return options;
+    const versionEnvelope = options.versionEnvelope ?? storyboardVersionEnvelopeMode(adcpVersion);
+    if (options.adcpVersion === adcpVersion && options.versionEnvelope === versionEnvelope) {
+        return options;
+    }
+    return { ...options, adcpVersion, versionEnvelope };
+}
+function storyboardVersionEnvelopeMode(adcpVersion) {
+    const bundleKey = (0, schema_loader_1.resolveBundleKey)(adcpVersion);
+    const major = (0, version_1.parseAdcpMajorVersion)(bundleKey);
+    if (Number.isFinite(major) && major < 3)
+        return 'none';
+    return 'auto';
+}
 /**
  * Suffix appended to the skip detail when the sole-stateful-step exemption
  * fires (`not_applicable` / `missing_tool` / `missing_test_controller` on
@@ -179,6 +203,107 @@ function evaluateCapabilityPredicate(predicate, actual) {
 function buildSkip(reason, detail) {
     return { reason, detail: detail ?? SKIP_DETAILS[reason] };
 }
+function detectResponseDerivedNotApplicable(step, request, response, runState, allSteps) {
+    if (response === undefined || response === null)
+        return null;
+    const gates = [
+        ...normalizeResponseNotApplicableGates(step.not_applicable_if),
+        ...inferImplicitResponseNotApplicableGates(step, request, runState, allSteps),
+    ];
+    for (const gate of gates) {
+        if (gate.kind !== 'terminal_page')
+            continue;
+        if (!terminalPageGateMatches(gate, request, response))
+            continue;
+        const detail = gate.detail ??
+            `${gate.reason ?? 'single_page_result'}: ${step.task} response is terminal; cursor-walk not applicable`;
+        return {
+            detail,
+            contextKeys: responseNotApplicableContextKeys(step, gate),
+        };
+    }
+    return null;
+}
+function normalizeResponseNotApplicableGates(gates) {
+    if (!gates)
+        return [];
+    return Array.isArray(gates) ? gates : [gates];
+}
+function inferImplicitResponseNotApplicableGates(step, request, runState, allSteps) {
+    // Back-compat for the already-published pagination_integrity_list_accounts
+    // storyboard: it expresses the continuation requirement as validations
+    // rather than a dedicated response-derived gate. Keep this narrowly scoped
+    // to list_accounts so other seeded pagination storyboards do not silently
+    // waive fixture/setup mistakes.
+    if (step.task !== 'list_accounts')
+        return [];
+    const expectsContinuation = step.validations?.some(v => v.check === 'field_value' && v.path === 'pagination.has_more' && v.value === true);
+    const capturesCursor = step.context_outputs?.some(o => o.path === 'pagination.cursor');
+    const validatesCursor = step.validations?.some(v => v.check === 'field_present' && v.path === 'pagination.cursor');
+    if (!expectsContinuation || (!capturesCursor && !validatesCursor))
+        return [];
+    const maxResults = (0, path_1.resolvePath)(request, 'pagination.max_results');
+    if (typeof maxResults === 'number' &&
+        Number.isFinite(maxResults) &&
+        hasUnrunAccountSeedExceedingPageSize(allSteps, runState, maxResults)) {
+        return [];
+    }
+    const setupAccounts = (0, path_1.resolvePath)(runState?.priorStepResults.get('sync_three_accounts')?.response, 'accounts');
+    if (typeof maxResults === 'number' &&
+        Number.isFinite(maxResults) &&
+        Array.isArray(setupAccounts) &&
+        setupAccounts.length > maxResults) {
+        return [];
+    }
+    return [{ kind: 'terminal_page', items_path: 'accounts', reason: 'single_page_result' }];
+}
+function hasUnrunAccountSeedExceedingPageSize(allSteps, runState, maxResults) {
+    return (allSteps?.some(({ step }) => {
+        if (runState?.priorStepResults.has(step.id))
+            return false;
+        if (step.task !== 'sync_accounts')
+            return false;
+        const accounts = (0, path_1.resolvePath)(step.sample_request, 'accounts');
+        return Array.isArray(accounts) && accounts.length > maxResults;
+    }) ?? false);
+}
+function terminalPageGateMatches(gate, request, response) {
+    const maxResults = (0, path_1.resolvePath)(request, gate.request_max_results_path ?? 'pagination.max_results');
+    if (typeof maxResults !== 'number' || !Number.isFinite(maxResults) || maxResults <= 0)
+        return false;
+    const items = (0, path_1.resolvePath)(response, gate.items_path);
+    if (!Array.isArray(items))
+        return false;
+    const pagination = (0, path_1.resolvePath)(response, 'pagination');
+    if (pagination === undefined || pagination === null)
+        return items.length < maxResults;
+    if (typeof pagination !== 'object' || Array.isArray(pagination))
+        return false;
+    const p = pagination;
+    if (p.has_more === true)
+        return false;
+    if (p.has_more !== false)
+        return false;
+    if (typeof p.total_count === 'number' && p.total_count > items.length)
+        return false;
+    if (items.length < maxResults)
+        return true;
+    return typeof p.total_count === 'number' && p.total_count <= items.length;
+}
+function responseNotApplicableContextKeys(step, gate) {
+    if (gate.context_keys?.length)
+        return gate.context_keys;
+    return (step.context_outputs ?? [])
+        .filter(o => o.path === 'pagination.cursor')
+        .map(o => o.key)
+        .filter((key) => typeof key === 'string' && key.length > 0);
+}
+function responseDerivedContextResult(runState) {
+    const entries = runState.responseDerivedNotApplicableContextKeys;
+    return entries && entries.size > 0
+        ? { response_derived_not_applicable_context_keys: Object.fromEntries(entries) }
+        : {};
+}
 /**
  * True for skip reasons that imply state genuinely never materialized
  * — no other code path could have established it. The runner trips
@@ -571,6 +696,7 @@ function filterResponseHeaders(headers) {
  * empty on instance B.
  */
 async function runStoryboard(agentUrlOrUrls, storyboard, options = {}) {
+    options = applyStoryboardVersionOptions(storyboard, options);
     (0, test_kit_1.validateTestKit)(options.test_kit);
     // Enforce authoring-time branch_set invariants regardless of how the
     // storyboard reached us. YAML callers already ran these rules in
@@ -1211,6 +1337,7 @@ async function executeStoryboardPass(agentUrls, storyboard, options, dispatchOff
     let clients;
     let routingContext;
     let profile;
+    let callerOwnsClients = false;
     if (useRouting) {
         try {
             routingContext = await (0, agent_routing_1.buildRoutingContext)(storyboard, options);
@@ -1225,8 +1352,7 @@ async function executeStoryboardPass(agentUrls, storyboard, options, dispatchOff
                 duration_ms: 0,
                 error: detail,
             };
-            if (!options._client)
-                await (0, protocols_1.closeConnections)(options.protocol);
+            await (0, protocols_1.closeConnections)(options.protocol);
             return buildDiscoveryFailedResult(agentUrls, storyboard, failedStep);
         }
         clients = [...routingContext.clients.values()];
@@ -1258,7 +1384,9 @@ async function executeStoryboardPass(agentUrls, storyboard, options, dispatchOff
     else {
         // Build one client per URL. In single-URL mode `_client` (from comply()) is
         // honored so the shared MCP transport is reused across storyboards.
-        clients = agentUrls.map(url => (0, client_1.getOrCreateClient)(url, options));
+        const clientResolutions = agentUrls.map(url => (0, client_1.getOrCreateClientResolution)(url, options));
+        clients = clientResolutions.map(r => r.client);
+        callerOwnsClients = clientResolutions.some(r => r.reusedShared);
         // Drop any retained A2A session ids before this storyboard's first call.
         // `comply()` shares one client across N storyboards for transport reuse;
         // AgentClient.retainSession holds onto `pendingTaskId` from non-terminal
@@ -1273,7 +1401,7 @@ async function executeStoryboardPass(agentUrls, storyboard, options, dispatchOff
         // expected to run the same code behind a shared state store, so one probe
         // is sufficient. For multi-instance runs, skipping N-1 redundant
         // get_agent_info calls also keeps CI output clean.
-        if (!options._client) {
+        if (!callerOwnsClients) {
             const discovered = await (0, client_1.getOrDiscoverProfile)(clients[0], options);
             // Discovery failure must surface as a HARD STORYBOARD FAILURE, not a
             // silent empty `agentTools: []` that lets every step skip with
@@ -1282,8 +1410,7 @@ async function executeStoryboardPass(agentUrls, storyboard, options, dispatchOff
             // (auth misconfig, MCP transport-fallback bugs, network policy, etc.).
             // See: https://github.com/adcontextprotocol/adcp-client/issues/...
             if (discovered.step.passed === false) {
-                if (!options._client)
-                    await (0, protocols_1.closeConnections)(options.protocol);
+                await (0, protocols_1.closeConnections)(options.protocol);
                 return buildDiscoveryFailedResult(agentUrls, storyboard, discovered.step);
             }
             profile = discovered.profile;
@@ -1329,7 +1456,7 @@ async function executeStoryboardPass(agentUrls, storyboard, options, dispatchOff
     if (allRequires.length) {
         const unmet = checkRequires(allRequires, options, profile);
         if (unmet) {
-            if (!options._client)
+            if (!callerOwnsClients)
                 await (0, protocols_1.closeConnections)(options.protocol);
             return {
                 ...buildRequirementUnmetResult(agentUrls, storyboard, unmet.requirement, unmet.detail),
@@ -1348,7 +1475,7 @@ async function executeStoryboardPass(agentUrls, storyboard, options, dispatchOff
             const actual = resolveCapabilityPath(rawCaps, cap.path);
             const unmetDetail = evaluateCapabilityPredicate(cap, actual);
             if (unmetDetail !== null) {
-                if (!options._client)
+                if (!callerOwnsClients)
                     await (0, protocols_1.closeConnections)(options.protocol);
                 return {
                     ...buildCapabilityUnsupportedResult(agentUrls, storyboard, unmetDetail),
@@ -1371,7 +1498,7 @@ async function executeStoryboardPass(agentUrls, storyboard, options, dispatchOff
     if (storyboard.required_tools?.length && options.agentTools) {
         const hasAnyRequired = storyboard.required_tools.some(t => options.agentTools.includes(t));
         if (!hasAnyRequired) {
-            if (!options._client)
+            if (!callerOwnsClients)
                 await (0, protocols_1.closeConnections)(options.protocol);
             return {
                 ...buildRequiredToolsMissingResult(agentUrls, storyboard, `agent does not advertise any of [${storyboard.required_tools.join(', ')}]`),
@@ -1394,6 +1521,7 @@ async function executeStoryboardPass(agentUrls, storyboard, options, dispatchOff
     const contextProvenance = new Map();
     const priorA2aEnvelopes = new Map();
     const stepRequestStarts = new Map();
+    const responseDerivedNotApplicableContextKeys = new Map();
     const phaseResults = [];
     let passedCount = 0;
     let failedCount = 0;
@@ -1863,6 +1991,7 @@ async function executeStoryboardPass(agentUrls, storyboard, options, dispatchOff
                 contextProvenance,
                 priorA2aEnvelopes,
                 stepRequestStarts,
+                responseDerivedNotApplicableContextKeys,
                 agentLibraryVersion: profile?.library_version,
             });
             const result = { ...rawResult, storyboard_id: storyboard.id };
@@ -2323,7 +2452,7 @@ async function executeStoryboardPass(agentUrls, storyboard, options, dispatchOff
     // Close protocol connections when the runner created its own client. The
     // connection pool is keyed by URL+auth, so a single closeConnections() call
     // evicts every instance's transport regardless of how many URLs we used.
-    if (!options._client) {
+    if (!callerOwnsClients) {
         await (0, protocols_1.closeConnections)(options.protocol);
     }
     if (webhookReceiver)
@@ -2361,7 +2490,7 @@ async function runMultiPass(agentUrls, storyboard, options) {
     // only the first pass attaches the synthetic `__controller_seeding__`
     // phase to its `phaseResults`, so the aggregated top-level counts reflect
     // a single seeding pass across the whole run.
-    const preSeedClients = agentUrls.map(url => (0, client_1.getOrCreateClient)(url, options));
+    const preSeedClients = agentUrls.map(url => (0, client_1.getOrCreateClientResolution)(url, options).client);
     const preSeedContext = { ...options.context };
     const preSeededResult = await (0, seeding_1.runControllerSeeding)(preSeedClients[0], storyboard, options, preSeedContext);
     const passes = [];
@@ -2558,15 +2687,17 @@ function summarizeStrictValidation(phases) {
  * Context is passed in and returned, enabling step-by-step orchestration.
  */
 async function runStoryboardStep(agentUrl, storyboard, stepId, options = {}) {
+    options = applyStoryboardVersionOptions(storyboard, options);
     (0, test_kit_1.validateTestKit)(options.test_kit);
-    const client = (0, client_1.getOrCreateClient)(agentUrl, options);
+    const clientResolution = (0, client_1.getOrCreateClientResolution)(agentUrl, options);
+    const client = clientResolution.client;
     // Discover agent profile for standalone step execution. Captured so the
     // executeStep call below can thread `library_version` through to
     // shape-drift hint detection (issue #850). Also threads _profile into
     // options so capability-based skip gates in executeStep (e.g. account-mode
     // branching) can read raw_capabilities, mirroring executeStoryboardPass.
     let profile;
-    if (!options._client) {
+    if (!clientResolution.reusedShared) {
         const discovered = await (0, client_1.getOrDiscoverProfile)(client, options);
         profile = discovered.profile;
         if (profile && !options._profile) {
@@ -2612,6 +2743,7 @@ async function runStoryboardStep(agentUrl, storyboard, stepId, options = {}) {
     // previous step's result). Storyboard-level runs build this internally;
     // here the caller owns accumulation across stateless invocations.
     const contextProvenance = new Map(Object.entries(options.context_provenance ?? {}));
+    const responseDerivedNotApplicableContextKeys = new Map(Object.entries(options.response_derived_not_applicable_context_keys ?? {}));
     const result = await executeStep(client, found.step, found.phaseId, context, allSteps, options, {
         contributions: new Set(),
         priorStepResults: new Map(),
@@ -2622,9 +2754,10 @@ async function runStoryboardStep(agentUrl, storyboard, stepId, options = {}) {
         contextProvenance,
         priorA2aEnvelopes: new Map(),
         stepRequestStarts: new Map(),
+        responseDerivedNotApplicableContextKeys,
         agentLibraryVersion: profile?.library_version,
     });
-    if (!options._client) {
+    if (!clientResolution.reusedShared) {
         await (0, protocols_1.closeConnections)(options.protocol);
     }
     if (ownsWebhookReceiver && webhookReceiver)
@@ -2642,6 +2775,7 @@ client, step, phaseId, context, allSteps, options, state) {
         agentUrl: '',
         contextProvenance: new Map(),
         stepRequestStarts: new Map(),
+        responseDerivedNotApplicableContextKeys: new Map(),
     };
     // HTTP probe tasks bypass the MCP client entirely.
     if (probes_1.PROBE_TASKS.has(step.task)) {
@@ -2810,45 +2944,50 @@ client, step, phaseId, context, allSteps, options, state) {
     const unresolvedVars = findUnresolvedContextVars(request);
     if (unresolvedVars.length > 0 && !step.expect_error) {
         const next = getNextStepPreview(step.id, allSteps, context, runState.runnerVars);
-        const detail = `Skipped: unresolved context variables from prior steps: ${unresolvedVars.map(v => v.key).join(', ')}.`;
-        // Per runner-output-contract.yaml v2.0.0, a skipped consumer step MUST
-        // carry an `unresolved_substitution` validation result for each missing
-        // token — `expected` is the token string, `actual` / `json_pointer` /
-        // `request` / `response` are null (pre-wire failure; no response payload
-        // exists). Surfacing this as a validation rather than only a skip detail
-        // keeps the runner-output contract's "failed/skipped steps include at
-        // least one validation result" invariant intact and lets dashboards
-        // attribute the cascade origin without parsing the skip message.
-        const seenTokens = new Set();
+        const responseDerivedDetails = unresolvedVars
+            .map(v => runState.responseDerivedNotApplicableContextKeys?.get(v.key))
+            .filter((d) => typeof d === 'string');
+        const allResponseDerived = responseDerivedDetails.length === unresolvedVars.length && responseDerivedDetails.length > 0;
+        const detail = allResponseDerived
+            ? [...new Set(responseDerivedDetails)].join('; ')
+            : `Skipped: unresolved context variables from prior steps: ${unresolvedVars.map(v => v.key).join(', ')}.`;
+        // Normal unresolved substitutions carry one validation result per missing
+        // token. Response-derived terminal-page skips are already successful
+        // not_applicable rows, so their downstream cursor consumers stay validation
+        // empty to avoid inventing a failing-looking check for an expected skip.
         const synthesized = [];
-        for (const v of unresolvedVars) {
-            if (seenTokens.has(v.token))
-                continue;
-            seenTokens.add(v.token);
-            synthesized.push({
-                check: 'unresolved_substitution',
-                passed: false,
-                description: `request token "${v.token}" did not resolve — prior step did not populate context.${v.key}`,
-                json_pointer: null,
-                expected: v.token,
-                actual: null,
-                schema_id: null,
-                schema_url: null,
-            });
+        if (!allResponseDerived) {
+            const seenTokens = new Set();
+            for (const v of unresolvedVars) {
+                if (seenTokens.has(v.token))
+                    continue;
+                seenTokens.add(v.token);
+                synthesized.push({
+                    check: 'unresolved_substitution',
+                    passed: false,
+                    description: `request token "${v.token}" did not resolve — prior step did not populate context.${v.key}`,
+                    json_pointer: null,
+                    expected: v.token,
+                    actual: null,
+                    schema_id: null,
+                    schema_url: null,
+                });
+            }
         }
         return {
             step_id: step.id,
             phase_id: phaseId,
             title: step.title,
             task: step.task,
-            passed: false,
+            passed: allResponseDerived,
             skipped: true,
-            skip_reason: 'prerequisite_failed',
-            skip: buildSkip('prerequisite_failed', detail),
+            skip_reason: allResponseDerived ? 'not_applicable' : 'prerequisite_failed',
+            skip: buildSkip(allResponseDerived ? 'not_applicable' : 'prerequisite_failed', detail),
             duration_ms: 0,
             validations: synthesized,
             context,
-            error: detail,
+            ...responseDerivedContextResult(runState),
+            ...(!allResponseDerived && { error: detail }),
             next,
             extraction: { path: 'none' },
         };
@@ -3203,6 +3342,32 @@ client, step, phaseId, context, allSteps, options, state) {
     if (step.expect_error && !taskResult?.data && taskResult?.error) {
         taskResult = { ...taskResult, data: { error: taskResult.error } };
     }
+    const responseDerivedSkip = detectResponseDerivedNotApplicable(effectiveStep, request, taskResult?.data, runState, allSteps);
+    if (responseDerivedSkip && !step.expect_error) {
+        for (const key of responseDerivedSkip.contextKeys) {
+            runState.responseDerivedNotApplicableContextKeys?.set(key, responseDerivedSkip.detail);
+        }
+        const next = getNextStepPreview(step.id, allSteps, context, runState.runnerVars);
+        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', responseDerivedSkip.detail),
+            duration_ms: stepResult.duration_ms,
+            validations: [],
+            context,
+            ...responseDerivedContextResult(runState),
+            response: (0, redact_secrets_1.redactSecrets)(taskResult?.data),
+            next,
+            request: requestRecord,
+            ...(responseRecord && { response_record: responseRecord }),
+            extraction: extractionFromTaskResult(taskResult),
+        };
+    }
     // Determine pass/fail — inverted when expect_error is set
     let passed;
     if (step.expect_error) {
@@ -3370,6 +3535,9 @@ client, step, phaseId, context, allSteps, options, state) {
     if (passed && hasData && taskResult) {
         const extracted = (0, context_1.extractContextWithProvenance)(effectiveStep.task, taskResult.data, step.id);
         Object.assign(updatedContext, extracted.values);
+        for (const key of Object.keys(extracted.values)) {
+            runState.responseDerivedNotApplicableContextKeys?.delete(key);
+        }
         if (runState.contextProvenance) {
             for (const [key, entry] of Object.entries(extracted.provenance)) {
                 runState.contextProvenance.set(key, entry);
@@ -3387,6 +3555,10 @@ client, step, phaseId, context, allSteps, options, state) {
     // ensures the minted value from any same-step $generate:…#<key> inline
     // substitution is visible here.
     if (step.context_outputs?.length) {
+        for (const output of step.context_outputs) {
+            if (output.key)
+                runState.responseDerivedNotApplicableContextKeys?.delete(output.key);
+        }
         // Resolve `task_completion.<path>` outputs against the eventual task
         // artifact rather than the immediate response. When the immediate
         // response is a submitted-arm envelope (HITL / async-signed-IO flows),
@@ -3413,6 +3585,9 @@ client, step, phaseId, context, allSteps, options, state) {
         const remappedOutputs = remapTaskCompletionOutputs(step.context_outputs);
         const explicit = (0, context_1.applyContextOutputsWithProvenance)(extractionData, remappedOutputs, step.id, effectiveStep.task, updatedContext);
         Object.assign(updatedContext, explicit.values);
+        for (const key of Object.keys(explicit.values)) {
+            runState.responseDerivedNotApplicableContextKeys?.delete(key);
+        }
         if (runState.contextProvenance) {
             for (const [key, entry] of Object.entries(explicit.provenance)) {
                 runState.contextProvenance.set(key, entry);
@@ -3543,6 +3718,7 @@ client, step, phaseId, context, allSteps, options, state) {
             runState.contextProvenance.size > 0 && {
             context_provenance: Object.fromEntries(runState.contextProvenance),
         }),
+        ...responseDerivedContextResult(runState),
         error: step.expect_error ? undefined : truncateError(stepResult.error || taskResult?.error),
         ...(!step.expect_error && taskResult?.adcp_error && { adcp_error: taskResult.adcp_error }),
         next,
@@ -3559,7 +3735,24 @@ async function executeProbeStep(step, phaseId, context, allSteps, options, runSt
     const start = Date.now();
     let httpResult;
     const probeOpts = { allowPrivateIp: options.allow_http === true };
-    if (step.task === 'protected_resource_metadata') {
+    if (step.requires_contract) {
+        const contracts = new Set(options.contracts ?? []);
+        if (!contracts.has(step.requires_contract)) {
+            httpResult = {
+                url: runState.agentUrl,
+                status: 0,
+                headers: {},
+                body: null,
+                skipped: true,
+                skip_reason: 'missing_test_kit_contract',
+                error: `Test-kit contract "${step.requires_contract}" is not configured on this runner.`,
+            };
+        }
+    }
+    if (httpResult) {
+        // Contract-gated synthetic probes self-skip before doing any network work.
+    }
+    else if (step.task === 'protected_resource_metadata') {
         httpResult = await (0, probes_1.probeProtectedResourceMetadata)(runState.agentUrl, probeOpts);
         // RFC 9728 presence semantics (adcp-client#677): a 404 means the agent is
         // honestly not advertising OAuth. Convert to a clean step skip so the
@@ -3585,6 +3778,21 @@ async function executeProbeStep(step, phaseId, context, allSteps, options, runSt
     else if (step.task === 'request_signing_probe') {
         httpResult = await (0, probe_dispatch_1.probeRequestSigningVector)(step.id, runState.agentUrl, options);
     }
+    else if (step.task === 'fetch_brand_jwks') {
+        httpResult = await probeBrandJwks(options._profile?.raw_capabilities, probeOpts);
+    }
+    else if (step.task === 'assert_jwks_purpose') {
+        httpResult = assertJwksPurpose(runState.priorProbes.get('fetch_brand_jwks'), 'webhook-signing');
+    }
+    else if (step.task === 'expect_rate_limit_not_replayed') {
+        httpResult = {
+            url: runState.agentUrl,
+            status: 0,
+            headers: {},
+            body: null,
+            error: 'rate_limit_trip_runner contract is configured, but this SDK runner does not yet implement live rate-limit trip/replay probing.',
+        };
+    }
     if (httpResult)
         runState.priorProbes.set(step.task, httpResult);
     const duration = Date.now() - start;
@@ -3670,6 +3878,90 @@ async function executeProbeStep(step, phaseId, context, allSteps, options, runSt
         extraction,
     };
 }
+async function probeBrandJwks(rawCapabilities, options) {
+    const brandJsonUrl = (0, capabilities_types_1.readBrandJsonUrl)(rawCapabilities);
+    if (!brandJsonUrl) {
+        return {
+            url: '',
+            status: 0,
+            headers: {},
+            body: null,
+            error: 'identity.brand_json_url missing from get_adcp_capabilities; cannot fetch brand JWKS',
+        };
+    }
+    const brand = await (0, probes_1.fetchProbe)(brandJsonUrl, options);
+    if (brand.error || brand.status < 200 || brand.status >= 300) {
+        return {
+            ...brand,
+            error: brand.error ?? `brand.json fetch returned HTTP ${brand.status}`,
+        };
+    }
+    const agents = brand.body && typeof brand.body === 'object' ? brand.body.agents : undefined;
+    const jwksUri = Array.isArray(agents)
+        ? agents
+            .map(agent => (agent && typeof agent === 'object' ? agent.jwks_uri : undefined))
+            .find((uri) => typeof uri === 'string' && uri.length > 0)
+        : undefined;
+    if (!jwksUri) {
+        return {
+            url: brandJsonUrl,
+            status: 0,
+            headers: {},
+            body: brand.body,
+            error: 'brand.json agents[] did not contain a jwks_uri',
+        };
+    }
+    const jwks = await (0, probes_1.fetchProbe)(jwksUri, options);
+    if (jwks.error || jwks.status < 200 || jwks.status >= 300) {
+        return {
+            ...jwks,
+            error: jwks.error ?? `JWKS fetch returned HTTP ${jwks.status}`,
+        };
+    }
+    return jwks;
+}
+function assertJwksPurpose(prior, purpose) {
+    if (!prior || prior.error) {
+        return {
+            url: prior?.url ?? '',
+            status: prior?.status ?? 0,
+            headers: prior?.headers ?? {},
+            body: prior?.body ?? null,
+            error: prior?.error ?? 'fetch_brand_jwks step missing; cannot assert JWKS purpose',
+        };
+    }
+    const keys = prior.body && typeof prior.body === 'object' ? prior.body.keys : undefined;
+    if (!Array.isArray(keys)) {
+        return {
+            url: prior.url,
+            status: 0,
+            headers: {},
+            body: prior.body,
+            error: 'JWKS body does not contain keys[]',
+        };
+    }
+    const matching = keys.filter(key => {
+        if (!key || typeof key !== 'object')
+            return false;
+        const rec = key;
+        return rec.adcp_use === purpose && rec.status !== 'revoked' && rec.revoked !== true;
+    });
+    if (matching.length === 0) {
+        return {
+            url: prior.url,
+            status: 0,
+            headers: {},
+            body: prior.body,
+            error: `JWKS contains no active key with adcp_use="${purpose}"`,
+        };
+    }
+    return {
+        url: prior.url,
+        status: 200,
+        headers: prior.headers,
+        body: { purpose, matching_key_count: matching.length },
+    };
+}
 function findPriorProbe(priorStepResults) {
     // Fallback for runStoryboardStep where priorProbes isn't populated — reach
     // into the step result's response, which we set to the HttpProbeResult above.