@adcp/sdk 14.0.0-rc.37 → 14.0.0-rc.39

package/dist/lib/testing/index.js

@@ -26,6 +26,7 @@ __export(testing_exports, {
   DISCOVERY_ARM_SCENARIOS: () => import_test_controller.DISCOVERY_ARM_SCENARIOS,
   FixtureBindingRegistry: () => import_storyboard.FixtureBindingRegistry,
   GovernanceAgentStub: () => import_stubs.GovernanceAgentStub,
+  MCP_SESSION_PROBE_TASK: () => import_storyboard.MCP_SESSION_PROBE_TASK,
   RATE_LIMIT_TRIP_CONTRACT: () => import_storyboard.RATE_LIMIT_TRIP_CONTRACT,
   RATE_LIMIT_TRIP_DEFAULT_REPLAY_MAX_WAIT_SECONDS: () => import_storyboard.RATE_LIMIT_TRIP_DEFAULT_REPLAY_MAX_WAIT_SECONDS,
   RATE_LIMIT_TRIP_MAX_ATTEMPTS_MAX: () => import_storyboard.RATE_LIMIT_TRIP_MAX_ATTEMPTS_MAX,
@@ -215,6 +216,7 @@ var import_storyboard = require('./storyboard/index.js');
   DISCOVERY_ARM_SCENARIOS,
   FixtureBindingRegistry,
   GovernanceAgentStub,
+  MCP_SESSION_PROBE_TASK,
   RATE_LIMIT_TRIP_CONTRACT,
   RATE_LIMIT_TRIP_DEFAULT_REPLAY_MAX_WAIT_SECONDS,
   RATE_LIMIT_TRIP_MAX_ATTEMPTS_MAX,

package/dist/lib/testing/index.mjs

@@ -180,7 +180,8 @@ import {
   normalizeOAuthResourceForComparison,
   redactOAuthUrlForOutput,
   BrandJsonSchema,
-  AdagentsJsonSchema
+  AdagentsJsonSchema,
+  MCP_SESSION_PROBE_TASK
 } from "./storyboard/index.mjs";
 export {
   AdagentsJsonSchema,
@@ -191,6 +192,7 @@ export {
   DISCOVERY_ARM_SCENARIOS,
   FixtureBindingRegistry,
   GovernanceAgentStub,
+  MCP_SESSION_PROBE_TASK,
   RATE_LIMIT_TRIP_CONTRACT,
   RATE_LIMIT_TRIP_DEFAULT_REPLAY_MAX_WAIT_SECONDS,
   RATE_LIMIT_TRIP_MAX_ATTEMPTS_MAX,

package/dist/lib/testing/storyboard/agent-routing.d.mts

@@ -1,49 +1,18 @@
-/**
- * Per-specialism agent routing for the storyboard runner (#1066).
- *
- * Resolves each step's `task` to one of N agents in
- * `StoryboardRunOptions.agents` so storyboards that span specialisms
- * (e.g., a `signal_marketplace/governance_denied` flow that calls
- * `sync_governance` then `activate_signal`) can hit the tenant that
- * actually owns each tool.
- *
- * Resolution order per step:
- *   1. Explicit `step.agent` (escape hatch for cross-domain tools)
- *   2. `TASK_FEATURE_MAP` → first protocol → unique claimant in the agents map
- *   3. `options.default_agent`
- *   4. Throw `RoutingError`
- *
- * Multi-claim conflicts (two agents claim the same protocol AND a step
- * relying on that protocol lacks an explicit `agent:` override) fail-fast
- * at routing-context build time, BEFORE any non-discovery network calls.
- *
- * ## Webhook receiver topology in routed mode
- *
- * When `StoryboardRunOptions.webhook_receiver` is set alongside `agents`,
- * the receiver is **shared** across all tenants — one HTTP server, one base
- * URL. The runner does not create per-tenant receivers and does not need to:
- * delivery correlation is by **step-keyed URL** (`/step/<step_id>/<op_id>`),
- * not by source agent. If both a governance tenant and a signals tenant
- * emit webhooks during the same run, the assertion harness matches each
- * delivery to its `expect_webhook*` step by URL path, regardless of which
- * tenant posted it. This means:
- *
- *   - `{{runner.webhook_base}}` substitutes the same URL for every step
- *     across all agents — no per-agent variable needed.
- *   - `{{runner.webhook_url:<step_id>}}` is always sufficient to pin a
- *     delivery to the step that requested it, even when multiple tenants
- *     emit concurrently.
- *   - Per-tenant receivers are not supported; if a future storyboard needs
- *     delivery-source disambiguation, use distinct step IDs (they already
- *     produce distinct URL paths).
- *
- * See `StoryboardRunOptions.webhook_receiver` JSDoc and `webhook-receiver.ts`
- * for implementation details.
- */
 import type { TestClient } from '../client.mjs';
 import type { AgentProfile } from '../types.mjs';
 import { type AdcpProtocol } from '../../utils/capabilities.mjs';
-import type { Storyboard, StoryboardRunOptions, StoryboardStep } from './types.mjs';
+import type { AgentEntry, Storyboard, StoryboardRunOptions, StoryboardStep } from './types.mjs';
+/** Storyboard applicability is any-of; it does not authorize individual steps. */
+export declare function hasAnyRequiredTool(required: readonly string[] | undefined, tools: readonly string[]): boolean;
+/** Normalize legacy discovery entries, retaining the single-agent empty-list fallback. */
+export declare function normalizeAgentToolNames(tools: unknown): string[] | undefined;
+/**
+ * Resolve a `$test_kit.<path>` task reference against the runtime options.
+ * Falls back to `step.task_default`. Returns undefined when neither yields a string.
+ */
+export declare function resolveTaskName(step: StoryboardStep, options: StoryboardRunOptions): string | undefined;
+/** Bind execution gates and transport observations to the same agent as dispatch. */
+export declare function routedAgentOptions(entry: AgentEntry, options: StoryboardRunOptions, profile: AgentProfile): StoryboardRunOptions;
 export interface AgentRoutingContext {
     /** Per-agent transport client. Lifecycle owned by the runner. */
     clients: Map<string, TestClient>;

package/dist/lib/testing/storyboard/agent-routing.d.ts

@@ -1,49 +1,18 @@
-/**
- * Per-specialism agent routing for the storyboard runner (#1066).
- *
- * Resolves each step's `task` to one of N agents in
- * `StoryboardRunOptions.agents` so storyboards that span specialisms
- * (e.g., a `signal_marketplace/governance_denied` flow that calls
- * `sync_governance` then `activate_signal`) can hit the tenant that
- * actually owns each tool.
- *
- * Resolution order per step:
- *   1. Explicit `step.agent` (escape hatch for cross-domain tools)
- *   2. `TASK_FEATURE_MAP` → first protocol → unique claimant in the agents map
- *   3. `options.default_agent`
- *   4. Throw `RoutingError`
- *
- * Multi-claim conflicts (two agents claim the same protocol AND a step
- * relying on that protocol lacks an explicit `agent:` override) fail-fast
- * at routing-context build time, BEFORE any non-discovery network calls.
- *
- * ## Webhook receiver topology in routed mode
- *
- * When `StoryboardRunOptions.webhook_receiver` is set alongside `agents`,
- * the receiver is **shared** across all tenants — one HTTP server, one base
- * URL. The runner does not create per-tenant receivers and does not need to:
- * delivery correlation is by **step-keyed URL** (`/step/<step_id>/<op_id>`),
- * not by source agent. If both a governance tenant and a signals tenant
- * emit webhooks during the same run, the assertion harness matches each
- * delivery to its `expect_webhook*` step by URL path, regardless of which
- * tenant posted it. This means:
- *
- *   - `{{runner.webhook_base}}` substitutes the same URL for every step
- *     across all agents — no per-agent variable needed.
- *   - `{{runner.webhook_url:<step_id>}}` is always sufficient to pin a
- *     delivery to the step that requested it, even when multiple tenants
- *     emit concurrently.
- *   - Per-tenant receivers are not supported; if a future storyboard needs
- *     delivery-source disambiguation, use distinct step IDs (they already
- *     produce distinct URL paths).
- *
- * See `StoryboardRunOptions.webhook_receiver` JSDoc and `webhook-receiver.ts`
- * for implementation details.
- */
 import type { TestClient } from '../client';
 import type { AgentProfile } from '../types';
 import { type AdcpProtocol } from '../../utils/capabilities';
-import type { Storyboard, StoryboardRunOptions, StoryboardStep } from './types';
+import type { AgentEntry, Storyboard, StoryboardRunOptions, StoryboardStep } from './types';
+/** Storyboard applicability is any-of; it does not authorize individual steps. */
+export declare function hasAnyRequiredTool(required: readonly string[] | undefined, tools: readonly string[]): boolean;
+/** Normalize legacy discovery entries, retaining the single-agent empty-list fallback. */
+export declare function normalizeAgentToolNames(tools: unknown): string[] | undefined;
+/**
+ * Resolve a `$test_kit.<path>` task reference against the runtime options.
+ * Falls back to `step.task_default`. Returns undefined when neither yields a string.
+ */
+export declare function resolveTaskName(step: StoryboardStep, options: StoryboardRunOptions): string | undefined;
+/** Bind execution gates and transport observations to the same agent as dispatch. */
+export declare function routedAgentOptions(entry: AgentEntry, options: StoryboardRunOptions, profile: AgentProfile): StoryboardRunOptions;
 export interface AgentRoutingContext {
     /** Per-agent transport client. Lifecycle owned by the runner. */
     clients: Map<string, TestClient>;

package/dist/lib/testing/storyboard/agent-routing.js

@@ -22,11 +22,46 @@ __export(agent_routing_exports, {
   RoutingError: () => RoutingError,
   buildRoutingContext: () => buildRoutingContext,
   buildRoutingContextFromProfiles: () => buildRoutingContextFromProfiles,
-  resolveAgentForStep: () => resolveAgentForStep
+  hasAnyRequiredTool: () => hasAnyRequiredTool,
+  normalizeAgentToolNames: () => normalizeAgentToolNames,
+  resolveAgentForStep: () => resolveAgentForStep,
+  resolveTaskName: () => resolveTaskName,
+  routedAgentOptions: () => routedAgentOptions
 });
 module.exports = __toCommonJS(agent_routing_exports);
+var import_oauth_metadata_graph = require('./oauth-metadata-graph/index.js');
+var import_test_kit = require('./test-kit.js');
 var import_client = require('../client.js');
 var import_capabilities = require('../../utils/capabilities.js');
+function hasAnyRequiredTool(required, tools) {
+  return !required?.length || required.some((tool) => tools.includes(tool));
+}
+function normalizeAgentToolNames(tools) {
+  if (!Array.isArray(tools)) return void 0;
+  const names = tools.flatMap((tool) => {
+    if (typeof tool === "string") return [tool];
+    if (tool && typeof tool === "object" && typeof tool.name === "string") return [tool.name];
+    return [];
+  });
+  return names.length > 0 ? names : void 0;
+}
+function resolveTaskName(step, options) {
+  if (!step.task.startsWith("$test_kit.")) return step.task;
+  const path = step.task.slice("$test_kit.".length).split(".");
+  let value = options.test_kit;
+  for (const segment of path) {
+    if (value == null || typeof value !== "object") {
+      value = void 0;
+      break;
+    }
+    value = value[segment];
+  }
+  const configured = typeof value === "string" && value.length > 0 ? value : step.task_default;
+  if (step.task === "$test_kit.auth.probe_task") {
+    return (0, import_test_kit.selectProbeTask)(configured, options.agentTools, { protocol: options.protocol });
+  }
+  return configured;
+}
 const KNOWN_PROTOCOLS = /* @__PURE__ */ new Set([
   "media_buy",
   "signals",
@@ -38,7 +73,7 @@ const KNOWN_PROTOCOLS = /* @__PURE__ */ new Set([
   "brand"
 ]);
 function scrubAuthSecrets(text) {
-  return text.replace(/(authorization\s*:\s*bearer\s+)[A-Za-z0-9._~+/=-]+/gi, "$1[REDACTED]").replace(/\bbearer\s+[A-Za-z0-9._~+/=-]+/gi, "Bearer [REDACTED]").replace(/([?&]token=)[A-Za-z0-9._~+/=-]+/gi, "$1[REDACTED]");
+  return (0, import_oauth_metadata_graph.redactOAuthUrlsInText)(text).replace(/(authorization\s*:\s*bearer\s+)[A-Za-z0-9._~+/=-]+/gi, "$1[REDACTED]").replace(/\bbearer\s+[A-Za-z0-9._~+/=-]+/gi, "Bearer [REDACTED]").replace(/([?&]token=)[A-Za-z0-9._~+/=-]+/gi, "$1[REDACTED]");
 }
 function buildAgentOptions(entry, options) {
   return {
@@ -55,10 +90,30 @@ function buildAgentOptions(entry, options) {
     // depends on.
     _client: void 0,
     _profile: void 0,
+    profile: void 0,
+    _controllerCapabilities: void 0,
     agents: void 0,
     agentTools: void 0
   };
 }
+function routedAgentOptions(entry, options, profile) {
+  const tools = normalizeAgentToolNames(profile.tools) ?? [];
+  const raw = profile.raw_capabilities;
+  const compliance = raw && typeof raw === "object" && "compliance_testing" in raw ? raw.compliance_testing : void 0;
+  const scenarios = compliance && typeof compliance === "object" && "scenarios" in compliance ? compliance.scenarios : void 0;
+  return {
+    ...buildAgentOptions(entry, options),
+    // Scenario opt-in must be the selected agent's declaration too; a
+    // comply() caller's controller cache belongs to its single agent.
+    _controllerCapabilities: Array.isArray(scenarios) && scenarios.length > 0 && scenarios.every((s) => typeof s === "string") && tools.includes("comply_test_controller") ? {
+      detected: true,
+      scenarios
+    } : { detected: false },
+    profile,
+    _profile: profile,
+    agentTools: tools
+  };
+}
 class RoutingError extends Error {
   constructor(message, task, hint) {
     super(message);
@@ -117,7 +172,7 @@ async function buildRoutingContext(storyboard, options) {
     if (!r.profile || r.step.passed === false) {
       const rawDetail = scrubAuthSecrets(r.step.error ?? "Discovery returned no profile.");
       const detail = rawDetail.length > 512 ? `${rawDetail.slice(0, 512)} \u2026(truncated)` : rawDetail;
-      const baseMessage = `Discovery failed for agent "${r.key}" (${agents[r.key].url}): ${detail}`;
+      const baseMessage = `Discovery failed for agent "${r.key}" (${(0, import_oauth_metadata_graph.redactOAuthUrlForOutput)(agents[r.key].url)}): ${detail}`;
       const message = resilient ? baseMessage : `${baseMessage}
 
 If this is hello-cluster / exploratory CI and you want unrelated storyboards to complete despite this failure, set \`StoryboardRunOptions.discovery_resilient: true\`. Do NOT set it in production \u2014 a topology with a broken tenant is a hard misconfiguration there.`;
@@ -129,7 +184,7 @@ If this is hello-cluster / exploratory CI and you want unrelated storyboards to
     profiles.set(r.key, r.profile);
   }
   const protocolIndex = buildProtocolIndex(profiles);
-  detectMultiClaimConflicts(storyboard, protocolIndex);
+  detectMultiClaimConflicts(storyboard, protocolIndex, options);
   return { clients, profiles, protocolIndex, agentMap, discoveryFailures };
 }
 function buildRoutingContextFromProfiles(storyboard, options, profiles) {
@@ -139,7 +194,7 @@ function buildRoutingContextFromProfiles(storyboard, options, profiles) {
     agentMap[key] = entry.url;
   }
   const protocolIndex = buildProtocolIndex(profiles);
-  detectMultiClaimConflicts(storyboard, protocolIndex);
+  detectMultiClaimConflicts(storyboard, protocolIndex, options);
   return { clients: /* @__PURE__ */ new Map(), profiles, protocolIndex, agentMap, discoveryFailures: [] };
 }
 function buildProtocolIndex(profiles) {
@@ -157,21 +212,22 @@ function buildProtocolIndex(profiles) {
   for (const list of index.values()) list.sort();
   return index;
 }
-function detectMultiClaimConflicts(storyboard, protocolIndex) {
+function detectMultiClaimConflicts(storyboard, protocolIndex, options) {
   const conflicts = [];
   for (const phase of storyboard.phases ?? []) {
     for (const step of phase.steps ?? []) {
       if (step.agent !== void 0) continue;
-      const protocol = primaryProtocolFor(step.task);
+      const task = resolveTaskName(step, { ...options, agentTools: void 0 }) ?? step.task;
+      const protocol = primaryProtocolFor(task);
       if (!protocol) continue;
       const candidates = protocolIndex.get(protocol);
       if (!candidates || candidates.length < 2) continue;
-      const existing = conflicts.find((c) => c.task === step.task && c.protocol === protocol);
+      const existing = conflicts.find((c) => c.task === task && c.protocol === protocol);
       if (existing) {
         existing.stepIds.push(step.id);
       } else {
         conflicts.push({
-          task: step.task,
+          task,
           protocol,
           agents: candidates,
           stepIds: [step.id]
@@ -204,7 +260,7 @@ function resolveAgentForStep(step, options, ctx) {
     const failed = ctx.discoveryFailures.find((f) => f.agentKey === step.agent);
     if (failed) {
       throw new RoutingError(
-        `Step "${step.id}" targets agent "${step.agent}" via \`step.agent\` override, but that agent's discovery failed: ${failed.underlying} (${failed.url}). Either remove the override, fix the agent, or route the step to a healthy agent.`,
+        `Step "${step.id}" targets agent "${step.agent}" via \`step.agent\` override, but that agent's discovery failed: ${failed.underlying} (${(0, import_oauth_metadata_graph.redactOAuthUrlForOutput)(failed.url)}). Either remove the override, fix the agent, or route the step to a healthy agent.`,
         step.task,
         `agent "${step.agent}" failed discovery`
       );
@@ -223,9 +279,11 @@ function resolveAgentForStep(step, options, ctx) {
       );
     }
     if (options.default_agent) return options.default_agent;
-    const failedHint = ctx.discoveryFailures.length > 0 ? ` Discovery failed for: ${ctx.discoveryFailures.map((f) => `${f.agentKey} (${f.url})`).join(", ")}.` : "";
+    const failedHint = ctx.discoveryFailures.length > 0 ? ` Discovery failed for: ${ctx.discoveryFailures.map((f) => `${f.agentKey} (${(0, import_oauth_metadata_graph.redactOAuthUrlForOutput)(f.url)})`).join(", ")}.` : "";
+    const toolAdvertisedBy = [...ctx.profiles].filter(([, profile]) => (normalizeAgentToolNames(profile.tools) ?? []).includes(step.task)).map(([key]) => key);
+    const advertisedHint = toolAdvertisedBy.length ? ` Agent(s) [${toolAdvertisedBy.join(", ")}] advertise "${step.task}" but do not declare "${protocol}" in supported_protocols \u2014 fix that declaration, or pin the step with \`agent:\`.` : "";
     throw new RoutingError(
-      `No agent in the map claims protocol "${protocol}" required by tool "${step.task}" (step "${step.id}"). Available agents: ${[...ctx.profiles.keys()].join(", ") || "(none \u2014 every agent failed discovery)"}.${failedHint} Add an agent that supports ${protocol}, or set \`default_agent\` to fall back.`,
+      `No agent in the map claims protocol "${protocol}" required by tool "${step.task}" (step "${step.id}"). Available agents: ${[...ctx.profiles.keys()].join(", ") || "(none \u2014 every agent failed discovery)"}.${failedHint} Add an agent that supports ${protocol}, or set \`default_agent\` to fall back.${advertisedHint}`,
       step.task,
       `protocol ${protocol} unclaimed`
     );
@@ -243,5 +301,9 @@ function resolveAgentForStep(step, options, ctx) {
   RoutingError,
   buildRoutingContext,
   buildRoutingContextFromProfiles,
-  resolveAgentForStep
+  hasAnyRequiredTool,
+  normalizeAgentToolNames,
+  resolveAgentForStep,
+  resolveTaskName,
+  routedAgentOptions
 });

package/dist/lib/testing/storyboard/agent-routing.mjs

@@ -1,5 +1,36 @@
+import { redactOAuthUrlForOutput, redactOAuthUrlsInText } from "./oauth-metadata-graph/index.mjs";
+import { selectProbeTask } from "./test-kit.mjs";
 import { getOrCreateClient, getOrDiscoverProfile } from "../client.mjs";
 import { TASK_FEATURE_MAP } from "../../utils/capabilities.mjs";
+function hasAnyRequiredTool(required, tools) {
+  return !required?.length || required.some((tool) => tools.includes(tool));
+}
+function normalizeAgentToolNames(tools) {
+  if (!Array.isArray(tools)) return void 0;
+  const names = tools.flatMap((tool) => {
+    if (typeof tool === "string") return [tool];
+    if (tool && typeof tool === "object" && typeof tool.name === "string") return [tool.name];
+    return [];
+  });
+  return names.length > 0 ? names : void 0;
+}
+function resolveTaskName(step, options) {
+  if (!step.task.startsWith("$test_kit.")) return step.task;
+  const path = step.task.slice("$test_kit.".length).split(".");
+  let value = options.test_kit;
+  for (const segment of path) {
+    if (value == null || typeof value !== "object") {
+      value = void 0;
+      break;
+    }
+    value = value[segment];
+  }
+  const configured = typeof value === "string" && value.length > 0 ? value : step.task_default;
+  if (step.task === "$test_kit.auth.probe_task") {
+    return selectProbeTask(configured, options.agentTools, { protocol: options.protocol });
+  }
+  return configured;
+}
 const KNOWN_PROTOCOLS = /* @__PURE__ */ new Set([
   "media_buy",
   "signals",
@@ -11,7 +42,7 @@ const KNOWN_PROTOCOLS = /* @__PURE__ */ new Set([
   "brand"
 ]);
 function scrubAuthSecrets(text) {
-  return text.replace(/(authorization\s*:\s*bearer\s+)[A-Za-z0-9._~+/=-]+/gi, "$1[REDACTED]").replace(/\bbearer\s+[A-Za-z0-9._~+/=-]+/gi, "Bearer [REDACTED]").replace(/([?&]token=)[A-Za-z0-9._~+/=-]+/gi, "$1[REDACTED]");
+  return redactOAuthUrlsInText(text).replace(/(authorization\s*:\s*bearer\s+)[A-Za-z0-9._~+/=-]+/gi, "$1[REDACTED]").replace(/\bbearer\s+[A-Za-z0-9._~+/=-]+/gi, "Bearer [REDACTED]").replace(/([?&]token=)[A-Za-z0-9._~+/=-]+/gi, "$1[REDACTED]");
 }
 function buildAgentOptions(entry, options) {
   return {
@@ -28,10 +59,30 @@ function buildAgentOptions(entry, options) {
     // depends on.
     _client: void 0,
     _profile: void 0,
+    profile: void 0,
+    _controllerCapabilities: void 0,
     agents: void 0,
     agentTools: void 0
   };
 }
+function routedAgentOptions(entry, options, profile) {
+  const tools = normalizeAgentToolNames(profile.tools) ?? [];
+  const raw = profile.raw_capabilities;
+  const compliance = raw && typeof raw === "object" && "compliance_testing" in raw ? raw.compliance_testing : void 0;
+  const scenarios = compliance && typeof compliance === "object" && "scenarios" in compliance ? compliance.scenarios : void 0;
+  return {
+    ...buildAgentOptions(entry, options),
+    // Scenario opt-in must be the selected agent's declaration too; a
+    // comply() caller's controller cache belongs to its single agent.
+    _controllerCapabilities: Array.isArray(scenarios) && scenarios.length > 0 && scenarios.every((s) => typeof s === "string") && tools.includes("comply_test_controller") ? {
+      detected: true,
+      scenarios
+    } : { detected: false },
+    profile,
+    _profile: profile,
+    agentTools: tools
+  };
+}
 class RoutingError extends Error {
   constructor(message, task, hint) {
     super(message);
@@ -90,7 +141,7 @@ async function buildRoutingContext(storyboard, options) {
     if (!r.profile || r.step.passed === false) {
       const rawDetail = scrubAuthSecrets(r.step.error ?? "Discovery returned no profile.");
       const detail = rawDetail.length > 512 ? `${rawDetail.slice(0, 512)} \u2026(truncated)` : rawDetail;
-      const baseMessage = `Discovery failed for agent "${r.key}" (${agents[r.key].url}): ${detail}`;
+      const baseMessage = `Discovery failed for agent "${r.key}" (${redactOAuthUrlForOutput(agents[r.key].url)}): ${detail}`;
       const message = resilient ? baseMessage : `${baseMessage}
 
 If this is hello-cluster / exploratory CI and you want unrelated storyboards to complete despite this failure, set \`StoryboardRunOptions.discovery_resilient: true\`. Do NOT set it in production \u2014 a topology with a broken tenant is a hard misconfiguration there.`;
@@ -102,7 +153,7 @@ If this is hello-cluster / exploratory CI and you want unrelated storyboards to
     profiles.set(r.key, r.profile);
   }
   const protocolIndex = buildProtocolIndex(profiles);
-  detectMultiClaimConflicts(storyboard, protocolIndex);
+  detectMultiClaimConflicts(storyboard, protocolIndex, options);
   return { clients, profiles, protocolIndex, agentMap, discoveryFailures };
 }
 function buildRoutingContextFromProfiles(storyboard, options, profiles) {
@@ -112,7 +163,7 @@ function buildRoutingContextFromProfiles(storyboard, options, profiles) {
     agentMap[key] = entry.url;
   }
   const protocolIndex = buildProtocolIndex(profiles);
-  detectMultiClaimConflicts(storyboard, protocolIndex);
+  detectMultiClaimConflicts(storyboard, protocolIndex, options);
   return { clients: /* @__PURE__ */ new Map(), profiles, protocolIndex, agentMap, discoveryFailures: [] };
 }
 function buildProtocolIndex(profiles) {
@@ -130,21 +181,22 @@ function buildProtocolIndex(profiles) {
   for (const list of index.values()) list.sort();
   return index;
 }
-function detectMultiClaimConflicts(storyboard, protocolIndex) {
+function detectMultiClaimConflicts(storyboard, protocolIndex, options) {
   const conflicts = [];
   for (const phase of storyboard.phases ?? []) {
     for (const step of phase.steps ?? []) {
       if (step.agent !== void 0) continue;
-      const protocol = primaryProtocolFor(step.task);
+      const task = resolveTaskName(step, { ...options, agentTools: void 0 }) ?? step.task;
+      const protocol = primaryProtocolFor(task);
       if (!protocol) continue;
       const candidates = protocolIndex.get(protocol);
       if (!candidates || candidates.length < 2) continue;
-      const existing = conflicts.find((c) => c.task === step.task && c.protocol === protocol);
+      const existing = conflicts.find((c) => c.task === task && c.protocol === protocol);
       if (existing) {
         existing.stepIds.push(step.id);
       } else {
         conflicts.push({
-          task: step.task,
+          task,
           protocol,
           agents: candidates,
           stepIds: [step.id]
@@ -177,7 +229,7 @@ function resolveAgentForStep(step, options, ctx) {
     const failed = ctx.discoveryFailures.find((f) => f.agentKey === step.agent);
     if (failed) {
       throw new RoutingError(
-        `Step "${step.id}" targets agent "${step.agent}" via \`step.agent\` override, but that agent's discovery failed: ${failed.underlying} (${failed.url}). Either remove the override, fix the agent, or route the step to a healthy agent.`,
+        `Step "${step.id}" targets agent "${step.agent}" via \`step.agent\` override, but that agent's discovery failed: ${failed.underlying} (${redactOAuthUrlForOutput(failed.url)}). Either remove the override, fix the agent, or route the step to a healthy agent.`,
         step.task,
         `agent "${step.agent}" failed discovery`
       );
@@ -196,9 +248,11 @@ function resolveAgentForStep(step, options, ctx) {
       );
     }
     if (options.default_agent) return options.default_agent;
-    const failedHint = ctx.discoveryFailures.length > 0 ? ` Discovery failed for: ${ctx.discoveryFailures.map((f) => `${f.agentKey} (${f.url})`).join(", ")}.` : "";
+    const failedHint = ctx.discoveryFailures.length > 0 ? ` Discovery failed for: ${ctx.discoveryFailures.map((f) => `${f.agentKey} (${redactOAuthUrlForOutput(f.url)})`).join(", ")}.` : "";
+    const toolAdvertisedBy = [...ctx.profiles].filter(([, profile]) => (normalizeAgentToolNames(profile.tools) ?? []).includes(step.task)).map(([key]) => key);
+    const advertisedHint = toolAdvertisedBy.length ? ` Agent(s) [${toolAdvertisedBy.join(", ")}] advertise "${step.task}" but do not declare "${protocol}" in supported_protocols \u2014 fix that declaration, or pin the step with \`agent:\`.` : "";
     throw new RoutingError(
-      `No agent in the map claims protocol "${protocol}" required by tool "${step.task}" (step "${step.id}"). Available agents: ${[...ctx.profiles.keys()].join(", ") || "(none \u2014 every agent failed discovery)"}.${failedHint} Add an agent that supports ${protocol}, or set \`default_agent\` to fall back.`,
+      `No agent in the map claims protocol "${protocol}" required by tool "${step.task}" (step "${step.id}"). Available agents: ${[...ctx.profiles.keys()].join(", ") || "(none \u2014 every agent failed discovery)"}.${failedHint} Add an agent that supports ${protocol}, or set \`default_agent\` to fall back.${advertisedHint}`,
       step.task,
       `protocol ${protocol} unclaimed`
     );
@@ -215,5 +269,9 @@ export {
   RoutingError,
   buildRoutingContext,
   buildRoutingContextFromProfiles,
-  resolveAgentForStep
+  hasAnyRequiredTool,
+  normalizeAgentToolNames,
+  resolveAgentForStep,
+  resolveTaskName,
+  routedAgentOptions
 };

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

@@ -8,6 +8,7 @@
  */
 export type { A2ATaskEnvelope, AgentEntry, Storyboard, StoryboardFixtureResolution, FixtureResolutionStrategy, FixtureMatchOperator, FixtureMatchClause, FixtureResolutionDeclaration, ProductFixtureResolutionDeclaration, PricingOptionFixtureResolutionDeclaration, FixtureResolutionStatus, FixtureResolutionRecord, FixtureResolutionAttempt, FixtureResolutionEvidence, FixtureResolutionCoverageGap, StoryboardInvariants, StoryboardInvariantsObject, StepInvariantsObject, StoryboardPhase, StoryboardStep, RateLimitTripSpec, StoryboardValidation, StoryboardValidationCheck, WebhookFilterSpec, WebhookRetryTriggerSpec, WebhookAssertionErrorCode, ContextOutput, ContextInput, ContextProvenanceEntry, ContextValueRejectedHint, ShapeDriftHint, MissingRequiredFieldHint, FormatMismatchHint, MonotonicViolationHint, ImpairmentCoherenceHint, ImpairmentCoherenceNotApplicableHint, StoryboardContext, StoryboardRunOptions, TrustedMatchContextProviderEndpoint, TrustedMatchContextRegistrationContext, TrustedMatchContextRouterRunnerOptions, TrustedMatchPublisherAuthOperation, TrustedMatchPublisherCredentialState, TrustedMatchPublisherAuthTls, TrustedMatchPublisherAuthProbeConfiguration, TrustedMatchPublisherAuthRunner, ValidationResult, StoryboardStepPreview, StoryboardStepResult, StoryboardStepHint, StoryboardStepHintBase, StoryboardPhaseResult, StoryboardResult, AssertionResult, StrictValidationSummary, StrictValidationVerdict, UpstreamTrafficPayloadMatch, RunnerNotice, NoticeCode, NoticeSeverity, } from './types.mjs';
 export { WEBHOOK_IDEMPOTENCY_KEY_PATTERN } from './types.mjs';
+export { MCP_SESSION_PROBE_TASK } from './types.mjs';
 export { registerAssertion, getAssertion, listAssertions, listDefaultAssertions, clearAssertionRegistry, resolveAssertions, } from './assertions.mjs';
 export type { AssertionSpec, AssertionContext, RegisterAssertionOptions } from './assertions.mjs';
 export { createWebhookReceiver } from './webhook-receiver.mjs';

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

@@ -8,6 +8,7 @@
  */
 export type { A2ATaskEnvelope, AgentEntry, Storyboard, StoryboardFixtureResolution, FixtureResolutionStrategy, FixtureMatchOperator, FixtureMatchClause, FixtureResolutionDeclaration, ProductFixtureResolutionDeclaration, PricingOptionFixtureResolutionDeclaration, FixtureResolutionStatus, FixtureResolutionRecord, FixtureResolutionAttempt, FixtureResolutionEvidence, FixtureResolutionCoverageGap, StoryboardInvariants, StoryboardInvariantsObject, StepInvariantsObject, StoryboardPhase, StoryboardStep, RateLimitTripSpec, StoryboardValidation, StoryboardValidationCheck, WebhookFilterSpec, WebhookRetryTriggerSpec, WebhookAssertionErrorCode, ContextOutput, ContextInput, ContextProvenanceEntry, ContextValueRejectedHint, ShapeDriftHint, MissingRequiredFieldHint, FormatMismatchHint, MonotonicViolationHint, ImpairmentCoherenceHint, ImpairmentCoherenceNotApplicableHint, StoryboardContext, StoryboardRunOptions, TrustedMatchContextProviderEndpoint, TrustedMatchContextRegistrationContext, TrustedMatchContextRouterRunnerOptions, TrustedMatchPublisherAuthOperation, TrustedMatchPublisherCredentialState, TrustedMatchPublisherAuthTls, TrustedMatchPublisherAuthProbeConfiguration, TrustedMatchPublisherAuthRunner, ValidationResult, StoryboardStepPreview, StoryboardStepResult, StoryboardStepHint, StoryboardStepHintBase, StoryboardPhaseResult, StoryboardResult, AssertionResult, StrictValidationSummary, StrictValidationVerdict, UpstreamTrafficPayloadMatch, RunnerNotice, NoticeCode, NoticeSeverity, } from './types';
 export { WEBHOOK_IDEMPOTENCY_KEY_PATTERN } from './types';
+export { MCP_SESSION_PROBE_TASK } from './types';
 export { registerAssertion, getAssertion, listAssertions, listDefaultAssertions, clearAssertionRegistry, resolveAssertions, } from './assertions';
 export type { AssertionSpec, AssertionContext, RegisterAssertionOptions } from './assertions';
 export { createWebhookReceiver } from './webhook-receiver';

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

@@ -23,6 +23,7 @@ __export(storyboard_exports, {
   CONTEXT_EXTRACTORS: () => import_context2.CONTEXT_EXTRACTORS,
   CapabilityResolutionError: () => import_compliance.CapabilityResolutionError,
   FixtureBindingRegistry: () => import_fixture_resolution.FixtureBindingRegistry,
+  MCP_SESSION_PROBE_TASK: () => import_types2.MCP_SESSION_PROBE_TASK,
   PROBE_TASK_ALLOWLIST: () => import_test_kit.PROBE_TASK_ALLOWLIST,
   PROTOCOL_TO_PATH: () => import_compliance.PROTOCOL_TO_PATH,
   RATE_LIMIT_TRIP_CONTRACT: () => import_rate_limit_trip.RATE_LIMIT_TRIP_CONTRACT,
@@ -111,6 +112,7 @@ __export(storyboard_exports, {
 module.exports = __toCommonJS(storyboard_exports);
 var import_default_invariants = require('./default-invariants.js');
 var import_types = require('./types.js');
+var import_types2 = require('./types.js');
 var import_assertions = require('./assertions.js');
 var import_webhook_receiver = require('./webhook-receiver.js');
 var import_context = require('./context.js');
@@ -139,6 +141,7 @@ var import_sandbox_entities = require('./sandbox-entities.js');
   CONTEXT_EXTRACTORS,
   CapabilityResolutionError,
   FixtureBindingRegistry,
+  MCP_SESSION_PROBE_TASK,
   PROBE_TASK_ALLOWLIST,
   PROTOCOL_TO_PATH,
   RATE_LIMIT_TRIP_CONTRACT,

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

@@ -1,6 +1,7 @@
 import { registerDefaultInvariants } from "./default-invariants.mjs";
 registerDefaultInvariants();
 import { WEBHOOK_IDEMPOTENCY_KEY_PATTERN } from "./types.mjs";
+import { MCP_SESSION_PROBE_TASK } from "./types.mjs";
 import {
   registerAssertion,
   getAssertion,
@@ -100,6 +101,7 @@ export {
   CONTEXT_EXTRACTORS,
   CapabilityResolutionError,
   FixtureBindingRegistry,
+  MCP_SESSION_PROBE_TASK,
   PROBE_TASK_ALLOWLIST,
   PROTOCOL_TO_PATH,
   RATE_LIMIT_TRIP_CONTRACT,

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

@@ -1 +1 @@
-export {};
+export declare function formatStoryboardResultsAsJUnit(results: StoryboardResult[]): string;

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

@@ -1 +1 @@
-export {};
+export declare function formatStoryboardResultsAsJUnit(results: StoryboardResult[]): string;

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

@@ -24,8 +24,20 @@ module.exports = __toCommonJS(junit_exports);
 var import_storyboard_tracks = require('../compliance/storyboard-tracks.js');
 var import_node_crypto = require("node:crypto");
 function xmlEscape(s) {
-  return String(s ?? "").replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
+  return xmlSafeText(String(s ?? "")).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
 }
+function xmlSafeText(value) {
+  return value.replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f]/g, escapeCodeUnit).replace(/[\uFDD0-\uFDEF\uFFFE\uFFFF]/g, escapeCodeUnit);
+}
+function escapeCodeUnit(char) {
+  return `\\u${char.charCodeAt(0).toString(16).padStart(4, "0")}`;
+}
+const RUNNER_AUTHORED_SKIP_REASONS = /* @__PURE__ */ new Set([
+  "capability_prerequisite_unavailable",
+  "session_probe_ungradable",
+  "fixture_unsatisfied"
+]);
+const MAX_SKIP_DETAIL_CHARS = 400;
 function hintLines(hints) {
   if (!hints || hints.length === 0) return [];
   return hints.map((h) => `Hint (${h.kind}): ${h.message}`);
@@ -41,6 +53,13 @@ function fenceUntrustedText(value, max = 500) {
 function formatAdvisoryFinding(validation) {
   return `[ADVISORY] ${fenceUntrustedText(validation.description)}: ${fenceUntrustedText(validation.error || "failed")}`;
 }
+function stepSkipMessage(step) {
+  const reason = step.skip_reason || "skipped";
+  const raw = step.skip?.detail;
+  if (raw === void 0 || !RUNNER_AUTHORED_SKIP_REASONS.has(step.skip_reason ?? "")) return reason;
+  const clipped = raw.length > MAX_SKIP_DETAIL_CHARS ? `${raw.slice(0, MAX_SKIP_DETAIL_CHARS)}\u2026` : raw;
+  return `${reason}: ${clipped}`;
+}
 function formatStoryboardResultsAsJUnit(results) {
   let totalTests = 0;
   let totalFailures = 0;
@@ -63,7 +82,7 @@ function formatStoryboardResultsAsJUnit(results) {
             totalSkipped += 1;
             suiteCases.push(
               `    <testcase classname="${xmlEscape(sb.storyboard_id)}" name="${xmlEscape(name)}" time="${time}">
-      <skipped message="${xmlEscape(step.skip_reason || "skipped")}"/>
+      <skipped message="${xmlEscape(stepSkipMessage(step))}"/>
     </testcase>`
             );
             continue;