@adcp/sdk 14.0.0-rc.52 → 14.0.0-rc.53

package/dist/lib/testing/compliance/comply.js

@@ -911,6 +911,314 @@ function buildNotApplicableStoryboardResult(agentUrl, na) {
     notices: []
   };
 }
+async function runComplyStoryboard(agentUrl, storyboard, runOptions, profile, routeStoryboard) {
+  if (!routeStoryboard || (0, import_runner.storyboardCapabilityGateUnmet)(storyboard, runOptions) !== null) {
+    return (0, import_runner.runStoryboard)(agentUrl, storyboard, runOptions);
+  }
+  const routing = await routeStoryboard(storyboard, { agent_url: agentUrl, profile });
+  if (routing === void 0 || routing === null) return (0, import_runner.runStoryboard)(agentUrl, storyboard, runOptions);
+  if (typeof routing !== "object") {
+    throw new TypeError(
+      `routeStoryboard(${storyboard.id}) must return undefined, { skip } or { agents, default_agent }; got ${typeof routing}.`
+    );
+  }
+  if ("skip" in routing) {
+    if ("agents" in routing) {
+      throw new TypeError(`routeStoryboard(${storyboard.id}) returned both \`skip\` and \`agents\`; return one.`);
+    }
+    if (typeof routing.skip !== "string" || routing.skip.trim() === "") {
+      throw new TypeError(`routeStoryboard(${storyboard.id}) returned \`skip\` without a non-empty reason string.`);
+    }
+    return buildRouteSkippedStoryboardResult(agentUrl, storyboard, routing.skip, runOptions);
+  }
+  const routed = buildRoutedStoryboardRun(agentUrl, storyboard, runOptions, routing);
+  if ("refused" in routed) return buildRouteSkippedStoryboardResult(agentUrl, storyboard, routed.refused, runOptions);
+  const result = await (0, import_runner.runStoryboard)("", routed.storyboard, routed.options);
+  return gradeRoutedResultForAgentUnderTest(result, routed.agentUnderTestIndexes, routed.keyByIndex);
+}
+function sameAgentUrl(a, b) {
+  try {
+    return new URL(a).href === new URL(b).href;
+  } catch {
+    return a === b;
+  }
+}
+function isCredentialObject(auth) {
+  if (!auth || typeof auth !== "object" || Array.isArray(auth)) return false;
+  const a = auth;
+  const nonEmpty = (v) => typeof v === "string" && v.length > 0;
+  const isObject = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+  switch (a.type) {
+    case "bearer":
+      return nonEmpty(a.token);
+    case "basic":
+      return nonEmpty(a.username) && typeof a.password === "string";
+    case "oauth":
+      return isObject(a.tokens);
+    case "oauth_client_credentials":
+      return isObject(a.credentials);
+    default:
+      return false;
+  }
+}
+function referencesTestKitAuth(value) {
+  if (typeof value === "string") return value.includes("$test_kit.auth");
+  if (Array.isArray(value)) return value.some(referencesTestKitAuth);
+  if (value && typeof value === "object") return Object.values(value).some(referencesTestKitAuth);
+  return false;
+}
+function stepAuthUsesTestKit(auth) {
+  return !!auth && typeof auth === "object" && !!auth.from_test_kit;
+}
+function testKitCredentialLeak(storyboard, agentUnderTestKeys) {
+  if (referencesTestKitAuth(storyboard.context)) {
+    return "its context references `$test_kit.auth`, which comply() will not forward to other routed agents.";
+  }
+  for (const phase of storyboard.phases ?? []) {
+    for (const step of phase.steps ?? []) {
+      if (step.agent !== void 0 && agentUnderTestKeys.has(step.agent)) continue;
+      const { task: _task, ...rest } = step;
+      if (stepAuthUsesTestKit(step.auth) || referencesTestKitAuth(rest)) {
+        return `step "${step.id}" is not pinned to the agent under test but reads test-kit credentials; comply() will not forward them to other routed agents.`;
+      }
+    }
+  }
+  return void 0;
+}
+function storyboardGradingShape(storyboard) {
+  return JSON.stringify({
+    requires: storyboard.requires,
+    requires_capability: storyboard.requires_capability,
+    requires_all_capabilities: storyboard.requires_all_capabilities,
+    invariants: storyboard.invariants,
+    phases: (storyboard.phases ?? []).map((phase) => ({
+      id: phase.id,
+      optional: phase.optional,
+      branch_set: phase.branch_set,
+      requires_capability: phase.requires_capability,
+      steps: (phase.steps ?? []).map((step) => ({
+        id: step.id,
+        task: step.task,
+        agent: step.agent,
+        validations: step.validations,
+        expect_error: step.expect_error,
+        requires_tool: step.requires_tool
+      }))
+    }))
+  });
+}
+function buildRoutedStoryboardRun(agentUrl, selected, runOptions, route) {
+  const where = `routeStoryboard(${selected.id})`;
+  const storyboard = route.storyboard ?? selected;
+  if (!storyboard || typeof storyboard !== "object" || storyboard.id !== selected.id) {
+    throw new TypeError(
+      `${where} returned a replacement storyboard with a different id; it must keep id "${selected.id}" so the result is attributed to the selected storyboard and its bundle.`
+    );
+  }
+  if (storyboard !== selected && storyboardGradingShape(storyboard) !== storyboardGradingShape(selected)) {
+    throw new TypeError(
+      `${where} returned a replacement storyboard that changes what is graded (phases, steps, tasks, agent pins, validations, expectations or gates). A replacement may only change request payloads and context.`
+    );
+  }
+  const agents = route.agents;
+  if (!agents || typeof agents !== "object" || Object.keys(agents).length === 0) {
+    throw new TypeError(`${where} returned a route without a non-empty \`agents\` map.`);
+  }
+  const defaultKey = route.default_agent;
+  if (typeof defaultKey !== "string" || !Object.prototype.hasOwnProperty.call(agents, defaultKey)) {
+    throw new TypeError(`${where} returned a \`default_agent\` that is not a key in \`agents\`.`);
+  }
+  const headers = runOptions.headers;
+  if (headers && Object.keys(headers).length > 0) {
+    throw new Error(
+      `${where}: refusing to route while run-level \`headers\` are set; the runner sends them to every routed agent. Remove the headers or skip this storyboard.`
+    );
+  }
+  const ordered = [defaultKey, ...Object.keys(agents).filter((key) => key !== defaultKey)];
+  const isolated = {};
+  const agentUnderTestIndexes = /* @__PURE__ */ new Set();
+  const agentUnderTestKeys = /* @__PURE__ */ new Set();
+  const keyByIndex = /* @__PURE__ */ new Map();
+  ordered.forEach((key, index) => {
+    const entry = agents[key];
+    if (!entry || typeof entry !== "object" || typeof entry.url !== "string" || entry.url === "") {
+      throw new TypeError(`${where}: agents['${key}'] needs a non-empty \`url\`.`);
+    }
+    const isAgentUnderTest = sameAgentUrl(entry.url, agentUrl);
+    if (key === defaultKey && !isAgentUnderTest) {
+      throw new Error(
+        `${where}: agents['${key}'] (the default_agent) must be the agent under test (${(0, import_oauth_metadata_graph.redactOAuthUrlForOutput)(agentUrl)}); comply() attributes the result to that agent.`
+      );
+    }
+    const hasOwnAuth = Object.prototype.hasOwnProperty.call(entry, "auth");
+    if (hasOwnAuth ? !isCredentialObject(entry.auth) : !isAgentUnderTest) {
+      throw new Error(
+        `${where}: agents['${key}'] (${(0, import_oauth_metadata_graph.redactOAuthUrlForOutput)(entry.url)}) must declare its own \`auth\` credential object ({ type: "bearer" | "basic" | "oauth" | "oauth_client_credentials", ... }). Without it the runner falls back to the credential for the agent under test.`
+      );
+    }
+    const auth = hasOwnAuth ? entry.auth : runOptions.auth;
+    isolated[key] = {
+      url: entry.url,
+      ...auth !== void 0 && { auth },
+      ...entry.transport !== void 0 && { transport: entry.transport }
+    };
+    keyByIndex.set(index + 1, key);
+    if (isAgentUnderTest) {
+      agentUnderTestIndexes.add(index + 1);
+      agentUnderTestKeys.add(key);
+    }
+  });
+  const leak = testKitCredentialLeak(storyboard, agentUnderTestKeys);
+  if (leak) return { refused: `${selected.id} cannot be routed: ${leak}` };
+  const context = runOptions.context !== void 0 || route.context !== void 0 ? { ...runOptions.context, ...route.context } : void 0;
+  const options = {
+    ...runOptions,
+    agents: isolated,
+    default_agent: defaultKey,
+    // A broken peer agent must grade as a coverage gap for the agent under
+    // test, not fail the whole storyboard: resilient discovery turns it into
+    // per-step routing failures attributed to that peer's `agent_index`.
+    discovery_resilient: true,
+    ...context !== void 0 && { context }
+  };
+  delete options.auth;
+  delete options._client;
+  delete options._profile;
+  delete options.profile;
+  delete options._controllerCapabilities;
+  delete options.agentTools;
+  return { storyboard, options, agentUnderTestIndexes, keyByIndex };
+}
+function gradeRoutedResultForAgentUnderTest(result, agentUnderTestIndexes, keyByIndex) {
+  const isDiscoveryFailure = result.phases.length === 1 && result.phases[0].phase_id === "discovery_failed" && result.failed_count > 0;
+  const downgraded = /* @__PURE__ */ new Map();
+  const phases = result.phases.map((phase) => {
+    let changed = false;
+    const steps = phase.steps.map((step) => {
+      if (step.passed || step.skipped) return step;
+      const peer = isDiscoveryFailure ? "a routed agent" : step.agent_index !== void 0 && !agentUnderTestIndexes.has(step.agent_index) ? `routed agent "${keyByIndex.get(step.agent_index) ?? step.agent_index}"` : void 0;
+      if (!peer) return step;
+      changed = true;
+      const assertionErrors = (result.assertions ?? []).filter((a) => !a.passed && a.scope !== "storyboard" && a.step_id === step.step_id).map((a) => a.error ?? a.description);
+      const detail = sanitizeAgentText(
+        `Step served by ${peer} failed; comply() grades it as a coverage gap for the agent under test, not a failure. ${step.error ?? "No error detail."}` + (assertionErrors.length > 0 ? ` Assertions: ${assertionErrors.join("; ")}` : ""),
+        1e3
+      );
+      downgraded.set(step.step_id, detail);
+      const { error: _error, ...rest } = step;
+      return {
+        ...rest,
+        passed: true,
+        skipped: true,
+        skip_reason: "prerequisite_failed",
+        skip: { reason: "prerequisite_failed", detail }
+      };
+    });
+    return changed ? { ...phase, steps, passed: steps.every((step) => step.passed) } : phase;
+  });
+  const autPassed = phases.some(
+    (phase) => phase.steps.some(
+      (step) => step.passed && !step.skipped && step.agent_index !== void 0 && agentUnderTestIndexes.has(step.agent_index)
+    )
+  );
+  if (downgraded.size === 0 && (autPassed || result.passed_count === 0)) return result;
+  const assertions = result.assertions?.filter(
+    (a) => a.passed || a.scope === "storyboard" || a.step_id === void 0 || !downgraded.has(a.step_id)
+  );
+  const graded = {
+    ...result,
+    phases,
+    ...assertions !== void 0 && { assertions },
+    failed_count: result.failed_count - downgraded.size,
+    skipped_count: result.skipped_count + downgraded.size
+  };
+  if (!autPassed && graded.passed_count > 0) {
+    graded.phases = [
+      ...graded.phases,
+      {
+        phase_id: "agent_under_test_coverage",
+        phase_title: "Agent under test coverage",
+        passed: true,
+        duration_ms: 0,
+        steps: [
+          {
+            storyboard_id: result.storyboard_id,
+            step_id: "agent_under_test_coverage",
+            phase_id: "agent_under_test_coverage",
+            title: "No step served by the agent under test passed",
+            task: "",
+            passed: true,
+            skipped: true,
+            skip_reason: "prerequisite_failed",
+            skip: {
+              reason: "prerequisite_failed",
+              detail: "Every passing step in this routed storyboard was served by another agent, so it carries no evidence about the agent under test."
+            },
+            duration_ms: 0,
+            validations: [],
+            context: {},
+            extraction: { path: "none" }
+          }
+        ]
+      }
+    ];
+    graded.skipped_count += 1;
+  }
+  graded.overall_passed = result.overall_passed || graded.failed_count === 0 && !(graded.assertions ?? []).some((a) => !a.passed && a.scope === "storyboard") && (0, import_storyboard_tracks.collectDetachedAssertionFailures)(graded).length === 0;
+  return graded;
+}
+function buildRouteSkippedStoryboardResult(agentUrl, storyboard, reason, runOptions) {
+  const detail = sanitizeAgentText(reason, 1e3);
+  const requirement = storyboard.requires?.includes("multi_agent") ? "multi_agent" : void 0;
+  const stepId = requirement ? `requirement_unmet:${requirement}` : "requirement_unmet:route_storyboard";
+  return {
+    storyboard_id: storyboard.id,
+    storyboard_title: storyboard.title,
+    agent_url: (0, import_oauth_metadata_graph.redactOAuthUrlForOutput)(agentUrl),
+    overall_passed: true,
+    phases: [
+      {
+        phase_id: "requirement_unmet",
+        phase_title: requirement ? `Requirement unmet: ${requirement}` : "Requirement unmet: not routable",
+        passed: true,
+        duration_ms: 0,
+        steps: [
+          {
+            storyboard_id: storyboard.id,
+            step_id: stepId,
+            phase_id: "requirement_unmet",
+            title: requirement ? `Storyboard skipped: requires '${requirement}'` : "Storyboard skipped: not routable by this run",
+            task: "",
+            passed: true,
+            skipped: true,
+            skip_reason: "requirement_unmet",
+            skip: { reason: "requirement_unmet", detail, ...requirement && { requirement } },
+            duration_ms: 0,
+            validations: [],
+            context: {},
+            extraction: { path: "none" }
+          }
+        ]
+      }
+    ],
+    context: {},
+    total_duration_ms: 0,
+    passed_count: 0,
+    failed_count: 0,
+    skipped_count: 1,
+    runner_capability_version: import_version.LIBRARY_VERSION,
+    tested_at: (/* @__PURE__ */ new Date()).toISOString(),
+    strict_validation_summary: {
+      observable: false,
+      checked: 0,
+      passed: 0,
+      failed: 0,
+      strict_only_failures: 0,
+      lenient_also_failed: 0
+    },
+    notices: (0, import_runner.collectCapabilityNotices)(storyboard, runOptions._profile)
+  };
+}
 function extractFailures(results, storyboards, agentRef, fixOptions = {}) {
   const failures = [];
   const sbLookup = /* @__PURE__ */ new Map();
@@ -1010,8 +1318,12 @@ async function complyImpl(agentUrl, options) {
     complianceDir,
     schemaRoot,
     hostedStableLineAlias,
+    routeStoryboard,
     ...testOptions
   } = options;
+  if (routeStoryboard !== void 0 && typeof routeStoryboard !== "function") {
+    throw new TypeError("routeStoryboard must be a function");
+  }
   const resolveOptions = {
     ...version !== void 0 && { version },
     ...complianceDir !== void 0 && { complianceDir },
@@ -1216,7 +1528,7 @@ async function complyImpl(agentUrl, options) {
         stoppedForTimeoutBudget = true;
         break;
       }
-      const result = await (0, import_runner.runStoryboard)(agentUrl, sb, runOptions);
+      const result = await runComplyStoryboard(agentUrl, sb, runOptions, profile, routeStoryboard);
       storyboardResults.push(result);
       executedStoryboards.push(sb);
     }

package/dist/lib/testing/compliance/comply.mjs

@@ -1,6 +1,12 @@
 import { createTestClient, discoverAgentProfile, seedTestClientSigningCapability } from "../client.mjs";
 import { collectDetachedAssertionFailures, mapStoryboardResultsToTrackResult, TRACK_LABELS } from "./storyboard-tracks.mjs";
-import { applyAdcpVersionRunOptions, runStoryboard, storyboardCapabilityPredicates } from "../storyboard/runner.mjs";
+import {
+  applyAdcpVersionRunOptions,
+  collectCapabilityNotices,
+  runStoryboard,
+  storyboardCapabilityGateUnmet,
+  storyboardCapabilityPredicates
+} from "../storyboard/runner.mjs";
 import { applyNativeA2AComplianceTransportOptions } from "../storyboard/native-a2a-compliance.mjs";
 import { validateTestKit } from "../storyboard/test-kit.mjs";
 import { checkAccountDiscoveryGate, isAccountBearingSpecialism } from "./spec-conformance.mjs";
@@ -888,6 +894,314 @@ function buildNotApplicableStoryboardResult(agentUrl, na) {
     notices: []
   };
 }
+async function runComplyStoryboard(agentUrl, storyboard, runOptions, profile, routeStoryboard) {
+  if (!routeStoryboard || storyboardCapabilityGateUnmet(storyboard, runOptions) !== null) {
+    return runStoryboard(agentUrl, storyboard, runOptions);
+  }
+  const routing = await routeStoryboard(storyboard, { agent_url: agentUrl, profile });
+  if (routing === void 0 || routing === null) return runStoryboard(agentUrl, storyboard, runOptions);
+  if (typeof routing !== "object") {
+    throw new TypeError(
+      `routeStoryboard(${storyboard.id}) must return undefined, { skip } or { agents, default_agent }; got ${typeof routing}.`
+    );
+  }
+  if ("skip" in routing) {
+    if ("agents" in routing) {
+      throw new TypeError(`routeStoryboard(${storyboard.id}) returned both \`skip\` and \`agents\`; return one.`);
+    }
+    if (typeof routing.skip !== "string" || routing.skip.trim() === "") {
+      throw new TypeError(`routeStoryboard(${storyboard.id}) returned \`skip\` without a non-empty reason string.`);
+    }
+    return buildRouteSkippedStoryboardResult(agentUrl, storyboard, routing.skip, runOptions);
+  }
+  const routed = buildRoutedStoryboardRun(agentUrl, storyboard, runOptions, routing);
+  if ("refused" in routed) return buildRouteSkippedStoryboardResult(agentUrl, storyboard, routed.refused, runOptions);
+  const result = await runStoryboard("", routed.storyboard, routed.options);
+  return gradeRoutedResultForAgentUnderTest(result, routed.agentUnderTestIndexes, routed.keyByIndex);
+}
+function sameAgentUrl(a, b) {
+  try {
+    return new URL(a).href === new URL(b).href;
+  } catch {
+    return a === b;
+  }
+}
+function isCredentialObject(auth) {
+  if (!auth || typeof auth !== "object" || Array.isArray(auth)) return false;
+  const a = auth;
+  const nonEmpty = (v) => typeof v === "string" && v.length > 0;
+  const isObject = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+  switch (a.type) {
+    case "bearer":
+      return nonEmpty(a.token);
+    case "basic":
+      return nonEmpty(a.username) && typeof a.password === "string";
+    case "oauth":
+      return isObject(a.tokens);
+    case "oauth_client_credentials":
+      return isObject(a.credentials);
+    default:
+      return false;
+  }
+}
+function referencesTestKitAuth(value) {
+  if (typeof value === "string") return value.includes("$test_kit.auth");
+  if (Array.isArray(value)) return value.some(referencesTestKitAuth);
+  if (value && typeof value === "object") return Object.values(value).some(referencesTestKitAuth);
+  return false;
+}
+function stepAuthUsesTestKit(auth) {
+  return !!auth && typeof auth === "object" && !!auth.from_test_kit;
+}
+function testKitCredentialLeak(storyboard, agentUnderTestKeys) {
+  if (referencesTestKitAuth(storyboard.context)) {
+    return "its context references `$test_kit.auth`, which comply() will not forward to other routed agents.";
+  }
+  for (const phase of storyboard.phases ?? []) {
+    for (const step of phase.steps ?? []) {
+      if (step.agent !== void 0 && agentUnderTestKeys.has(step.agent)) continue;
+      const { task: _task, ...rest } = step;
+      if (stepAuthUsesTestKit(step.auth) || referencesTestKitAuth(rest)) {
+        return `step "${step.id}" is not pinned to the agent under test but reads test-kit credentials; comply() will not forward them to other routed agents.`;
+      }
+    }
+  }
+  return void 0;
+}
+function storyboardGradingShape(storyboard) {
+  return JSON.stringify({
+    requires: storyboard.requires,
+    requires_capability: storyboard.requires_capability,
+    requires_all_capabilities: storyboard.requires_all_capabilities,
+    invariants: storyboard.invariants,
+    phases: (storyboard.phases ?? []).map((phase) => ({
+      id: phase.id,
+      optional: phase.optional,
+      branch_set: phase.branch_set,
+      requires_capability: phase.requires_capability,
+      steps: (phase.steps ?? []).map((step) => ({
+        id: step.id,
+        task: step.task,
+        agent: step.agent,
+        validations: step.validations,
+        expect_error: step.expect_error,
+        requires_tool: step.requires_tool
+      }))
+    }))
+  });
+}
+function buildRoutedStoryboardRun(agentUrl, selected, runOptions, route) {
+  const where = `routeStoryboard(${selected.id})`;
+  const storyboard = route.storyboard ?? selected;
+  if (!storyboard || typeof storyboard !== "object" || storyboard.id !== selected.id) {
+    throw new TypeError(
+      `${where} returned a replacement storyboard with a different id; it must keep id "${selected.id}" so the result is attributed to the selected storyboard and its bundle.`
+    );
+  }
+  if (storyboard !== selected && storyboardGradingShape(storyboard) !== storyboardGradingShape(selected)) {
+    throw new TypeError(
+      `${where} returned a replacement storyboard that changes what is graded (phases, steps, tasks, agent pins, validations, expectations or gates). A replacement may only change request payloads and context.`
+    );
+  }
+  const agents = route.agents;
+  if (!agents || typeof agents !== "object" || Object.keys(agents).length === 0) {
+    throw new TypeError(`${where} returned a route without a non-empty \`agents\` map.`);
+  }
+  const defaultKey = route.default_agent;
+  if (typeof defaultKey !== "string" || !Object.prototype.hasOwnProperty.call(agents, defaultKey)) {
+    throw new TypeError(`${where} returned a \`default_agent\` that is not a key in \`agents\`.`);
+  }
+  const headers = runOptions.headers;
+  if (headers && Object.keys(headers).length > 0) {
+    throw new Error(
+      `${where}: refusing to route while run-level \`headers\` are set; the runner sends them to every routed agent. Remove the headers or skip this storyboard.`
+    );
+  }
+  const ordered = [defaultKey, ...Object.keys(agents).filter((key) => key !== defaultKey)];
+  const isolated = {};
+  const agentUnderTestIndexes = /* @__PURE__ */ new Set();
+  const agentUnderTestKeys = /* @__PURE__ */ new Set();
+  const keyByIndex = /* @__PURE__ */ new Map();
+  ordered.forEach((key, index) => {
+    const entry = agents[key];
+    if (!entry || typeof entry !== "object" || typeof entry.url !== "string" || entry.url === "") {
+      throw new TypeError(`${where}: agents['${key}'] needs a non-empty \`url\`.`);
+    }
+    const isAgentUnderTest = sameAgentUrl(entry.url, agentUrl);
+    if (key === defaultKey && !isAgentUnderTest) {
+      throw new Error(
+        `${where}: agents['${key}'] (the default_agent) must be the agent under test (${redactOAuthUrlForOutput(agentUrl)}); comply() attributes the result to that agent.`
+      );
+    }
+    const hasOwnAuth = Object.prototype.hasOwnProperty.call(entry, "auth");
+    if (hasOwnAuth ? !isCredentialObject(entry.auth) : !isAgentUnderTest) {
+      throw new Error(
+        `${where}: agents['${key}'] (${redactOAuthUrlForOutput(entry.url)}) must declare its own \`auth\` credential object ({ type: "bearer" | "basic" | "oauth" | "oauth_client_credentials", ... }). Without it the runner falls back to the credential for the agent under test.`
+      );
+    }
+    const auth = hasOwnAuth ? entry.auth : runOptions.auth;
+    isolated[key] = {
+      url: entry.url,
+      ...auth !== void 0 && { auth },
+      ...entry.transport !== void 0 && { transport: entry.transport }
+    };
+    keyByIndex.set(index + 1, key);
+    if (isAgentUnderTest) {
+      agentUnderTestIndexes.add(index + 1);
+      agentUnderTestKeys.add(key);
+    }
+  });
+  const leak = testKitCredentialLeak(storyboard, agentUnderTestKeys);
+  if (leak) return { refused: `${selected.id} cannot be routed: ${leak}` };
+  const context = runOptions.context !== void 0 || route.context !== void 0 ? { ...runOptions.context, ...route.context } : void 0;
+  const options = {
+    ...runOptions,
+    agents: isolated,
+    default_agent: defaultKey,
+    // A broken peer agent must grade as a coverage gap for the agent under
+    // test, not fail the whole storyboard: resilient discovery turns it into
+    // per-step routing failures attributed to that peer's `agent_index`.
+    discovery_resilient: true,
+    ...context !== void 0 && { context }
+  };
+  delete options.auth;
+  delete options._client;
+  delete options._profile;
+  delete options.profile;
+  delete options._controllerCapabilities;
+  delete options.agentTools;
+  return { storyboard, options, agentUnderTestIndexes, keyByIndex };
+}
+function gradeRoutedResultForAgentUnderTest(result, agentUnderTestIndexes, keyByIndex) {
+  const isDiscoveryFailure = result.phases.length === 1 && result.phases[0].phase_id === "discovery_failed" && result.failed_count > 0;
+  const downgraded = /* @__PURE__ */ new Map();
+  const phases = result.phases.map((phase) => {
+    let changed = false;
+    const steps = phase.steps.map((step) => {
+      if (step.passed || step.skipped) return step;
+      const peer = isDiscoveryFailure ? "a routed agent" : step.agent_index !== void 0 && !agentUnderTestIndexes.has(step.agent_index) ? `routed agent "${keyByIndex.get(step.agent_index) ?? step.agent_index}"` : void 0;
+      if (!peer) return step;
+      changed = true;
+      const assertionErrors = (result.assertions ?? []).filter((a) => !a.passed && a.scope !== "storyboard" && a.step_id === step.step_id).map((a) => a.error ?? a.description);
+      const detail = sanitizeAgentText(
+        `Step served by ${peer} failed; comply() grades it as a coverage gap for the agent under test, not a failure. ${step.error ?? "No error detail."}` + (assertionErrors.length > 0 ? ` Assertions: ${assertionErrors.join("; ")}` : ""),
+        1e3
+      );
+      downgraded.set(step.step_id, detail);
+      const { error: _error, ...rest } = step;
+      return {
+        ...rest,
+        passed: true,
+        skipped: true,
+        skip_reason: "prerequisite_failed",
+        skip: { reason: "prerequisite_failed", detail }
+      };
+    });
+    return changed ? { ...phase, steps, passed: steps.every((step) => step.passed) } : phase;
+  });
+  const autPassed = phases.some(
+    (phase) => phase.steps.some(
+      (step) => step.passed && !step.skipped && step.agent_index !== void 0 && agentUnderTestIndexes.has(step.agent_index)
+    )
+  );
+  if (downgraded.size === 0 && (autPassed || result.passed_count === 0)) return result;
+  const assertions = result.assertions?.filter(
+    (a) => a.passed || a.scope === "storyboard" || a.step_id === void 0 || !downgraded.has(a.step_id)
+  );
+  const graded = {
+    ...result,
+    phases,
+    ...assertions !== void 0 && { assertions },
+    failed_count: result.failed_count - downgraded.size,
+    skipped_count: result.skipped_count + downgraded.size
+  };
+  if (!autPassed && graded.passed_count > 0) {
+    graded.phases = [
+      ...graded.phases,
+      {
+        phase_id: "agent_under_test_coverage",
+        phase_title: "Agent under test coverage",
+        passed: true,
+        duration_ms: 0,
+        steps: [
+          {
+            storyboard_id: result.storyboard_id,
+            step_id: "agent_under_test_coverage",
+            phase_id: "agent_under_test_coverage",
+            title: "No step served by the agent under test passed",
+            task: "",
+            passed: true,
+            skipped: true,
+            skip_reason: "prerequisite_failed",
+            skip: {
+              reason: "prerequisite_failed",
+              detail: "Every passing step in this routed storyboard was served by another agent, so it carries no evidence about the agent under test."
+            },
+            duration_ms: 0,
+            validations: [],
+            context: {},
+            extraction: { path: "none" }
+          }
+        ]
+      }
+    ];
+    graded.skipped_count += 1;
+  }
+  graded.overall_passed = result.overall_passed || graded.failed_count === 0 && !(graded.assertions ?? []).some((a) => !a.passed && a.scope === "storyboard") && collectDetachedAssertionFailures(graded).length === 0;
+  return graded;
+}
+function buildRouteSkippedStoryboardResult(agentUrl, storyboard, reason, runOptions) {
+  const detail = sanitizeAgentText(reason, 1e3);
+  const requirement = storyboard.requires?.includes("multi_agent") ? "multi_agent" : void 0;
+  const stepId = requirement ? `requirement_unmet:${requirement}` : "requirement_unmet:route_storyboard";
+  return {
+    storyboard_id: storyboard.id,
+    storyboard_title: storyboard.title,
+    agent_url: redactOAuthUrlForOutput(agentUrl),
+    overall_passed: true,
+    phases: [
+      {
+        phase_id: "requirement_unmet",
+        phase_title: requirement ? `Requirement unmet: ${requirement}` : "Requirement unmet: not routable",
+        passed: true,
+        duration_ms: 0,
+        steps: [
+          {
+            storyboard_id: storyboard.id,
+            step_id: stepId,
+            phase_id: "requirement_unmet",
+            title: requirement ? `Storyboard skipped: requires '${requirement}'` : "Storyboard skipped: not routable by this run",
+            task: "",
+            passed: true,
+            skipped: true,
+            skip_reason: "requirement_unmet",
+            skip: { reason: "requirement_unmet", detail, ...requirement && { requirement } },
+            duration_ms: 0,
+            validations: [],
+            context: {},
+            extraction: { path: "none" }
+          }
+        ]
+      }
+    ],
+    context: {},
+    total_duration_ms: 0,
+    passed_count: 0,
+    failed_count: 0,
+    skipped_count: 1,
+    runner_capability_version: LIBRARY_VERSION,
+    tested_at: (/* @__PURE__ */ new Date()).toISOString(),
+    strict_validation_summary: {
+      observable: false,
+      checked: 0,
+      passed: 0,
+      failed: 0,
+      strict_only_failures: 0,
+      lenient_also_failed: 0
+    },
+    notices: collectCapabilityNotices(storyboard, runOptions._profile)
+  };
+}
 function extractFailures(results, storyboards, agentRef, fixOptions = {}) {
   const failures = [];
   const sbLookup = /* @__PURE__ */ new Map();
@@ -987,8 +1301,12 @@ async function complyImpl(agentUrl, options) {
     complianceDir,
     schemaRoot,
     hostedStableLineAlias,
+    routeStoryboard,
     ...testOptions
   } = options;
+  if (routeStoryboard !== void 0 && typeof routeStoryboard !== "function") {
+    throw new TypeError("routeStoryboard must be a function");
+  }
   const resolveOptions = {
     ...version !== void 0 && { version },
     ...complianceDir !== void 0 && { complianceDir },
@@ -1193,7 +1511,7 @@ async function complyImpl(agentUrl, options) {
         stoppedForTimeoutBudget = true;
         break;
       }
-      const result = await runStoryboard(agentUrl, sb, runOptions);
+      const result = await runComplyStoryboard(agentUrl, sb, runOptions, profile, routeStoryboard);
       storyboardResults.push(result);
       executedStoryboards.push(sb);
     }