@adcp/sdk 9.1.2 → 9.2.2

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

@@ -169,10 +169,44 @@ function resolveCapabilityPath(raw, dottedPath) {
     for (const key of keys) {
         if (current === null || typeof current !== 'object')
             return undefined;
+        if (!Object.prototype.hasOwnProperty.call(current, key))
+            return undefined;
         current = current[key];
     }
     return current;
 }
+const GET_ADCP_CAPABILITIES_RESPONSE_SCHEMA_REF = 'protocol/get-adcp-capabilities-response.json';
+function resolveCapabilityPathForGate(raw, predicate, adcpVersion) {
+    const actual = resolveCapabilityPath(raw, predicate.path);
+    if (actual !== undefined)
+        return actual;
+    // `present:` is an absence-detection matcher — an absent field IS the
+    // load-bearing signal. Materializing a schema default would make a defaulted
+    // field never read as absent, silently flipping the gate (e.g. a signals
+    // seller that omits `signals.discovery_modes`, default `["brief"]`, would run
+    // a `present: true`-gated scenario that should skip). Defaults are resolved
+    // only for the value matchers (`equals` / `contains`), where the default's
+    // VALUE is what the gate tests.
+    if ('present' in predicate)
+        return undefined;
+    if (!schemaDefaultShouldApply(raw, predicate.path))
+        return undefined;
+    return (0, schema_loader_1.getSchemaDefaultByPath)(GET_ADCP_CAPABILITIES_RESPONSE_SCHEMA_REF, predicate.path, adcpVersion);
+}
+function schemaDefaultShouldApply(raw, dottedPath) {
+    const keys = dottedPath.split('.');
+    if (keys.length <= 1)
+        return raw !== null && typeof raw === 'object';
+    let current = raw;
+    for (const key of keys.slice(0, -1)) {
+        if (current === null || typeof current !== 'object')
+            return false;
+        if (!Object.prototype.hasOwnProperty.call(current, key))
+            return false;
+        current = current[key];
+    }
+    return current !== null && typeof current === 'object';
+}
 /**
  * Evaluate a `requires_capability` predicate against the value already
  * resolved from the agent's raw capabilities. Returns `null` when the
@@ -182,8 +216,8 @@ function resolveCapabilityPath(raw, dottedPath) {
  * Three matcher forms — see `Storyboard.requires_capability` for full semantics:
  *
  * - `equals: V` — scalar equality. `actual` must be declared and must equal
- *   `V`. Absent fields (`undefined`) skip because the agent has not opted
- *   into the capability or capability variant this storyboard tests.
+ *   `V`. Absent fields (`undefined`) skip unless the capabilities schema
+ *   declares a default that the gate materialized before predicate evaluation.
  *
  * - `present: B` — presence is the load-bearing signal. `present: true`
  *   skips when the field is absent (treats `undefined` and `null` as absent).
@@ -193,12 +227,15 @@ function resolveCapabilityPath(raw, dottedPath) {
  *   non-conformant for object-typed capabilities (`"type": "object"` rejects
  *   null in JSON Schema), but is coalesced with absent here in the spirit of
  *   Postel — agents that misdeclare a not-supported capability as `null`
- *   get the same not_applicable skip as agents that omit the field.
+ *   get the same not_applicable skip as agents that omit the field. Schema
+ *   defaults are deliberately NOT materialized for this matcher: presence is
+ *   the signal, so a default would defeat the gate (see
+ *   `resolveCapabilityPathForGate`).
  *
  * - `contains: V` — array-membership. `actual` must be an array that
  *   includes `V` (strict equality, no coercion). Empty arrays, non-arrays,
- *   and absent fields all skip — absence means the agent hasn't opted into
- *   the array variant this storyboard tests.
+ *   and absent fields all skip unless the capabilities schema declares a
+ *   default that the gate materialized before predicate evaluation.
  *
  * Exported for direct testing so the predicate semantics are pinned without
  * needing a full runStoryboard() roundtrip.
@@ -237,10 +274,10 @@ function evaluateCapabilityPredicate(predicate, actual) {
     }
     return null;
 }
-function evaluateRequiresCapabilityGate(predicate, profile, agentTools) {
+function evaluateRequiresCapabilityGate(predicate, profile, agentTools, adcpVersion) {
     const rawCaps = profile?.raw_capabilities;
     if (rawCaps !== undefined) {
-        const actual = resolveCapabilityPath(rawCaps, predicate.path);
+        const actual = resolveCapabilityPathForGate(rawCaps, predicate, adcpVersion);
         return evaluateCapabilityPredicate(predicate, actual);
     }
     const tools = agentTools ?? profile?.tools;
@@ -249,12 +286,12 @@ function evaluateRequiresCapabilityGate(predicate, profile, agentTools) {
     }
     return null;
 }
-function collectPhaseCapabilitySkipDetails(storyboard, profile, agentTools) {
+function collectPhaseCapabilitySkipDetails(storyboard, profile, agentTools, adcpVersion) {
     const skipDetails = new Map();
     for (const phase of storyboard.phases) {
         if (!phase.requires_capability)
             continue;
-        const unmetDetail = evaluateRequiresCapabilityGate(phase.requires_capability, profile, agentTools);
+        const unmetDetail = evaluateRequiresCapabilityGate(phase.requires_capability, profile, agentTools, adcpVersion);
         if (unmetDetail !== null) {
             skipDetails.set(phase.id, unmetDetail);
         }
@@ -825,6 +862,17 @@ async function runStoryboardBody(agentUrlOrUrls, storyboard, options) {
         }
         return runMultiPass(agentUrls, storyboard, options);
     }
+    const allRequires = resolveStoryboardRequires(storyboard, options);
+    if (allRequires.length) {
+        const unmet = checkRequires(allRequires, storyboard, options, options._profile);
+        if (unmet) {
+            const resultAgentUrls = options.agents ? Object.values(options.agents).map(e => e.url) : agentUrls;
+            return {
+                ...buildRequirementUnmetResult(resultAgentUrls, storyboard, unmet.requirement, unmet.detail),
+                notices: collectCapabilityNotices(storyboard, options._profile?.raw_capabilities),
+            };
+        }
+    }
     if (options.agents) {
         // Project the agents map's URLs into the legacy `agentUrls` array so
         // downstream signatures (per-step `agent_url:` records, etc.) keep
@@ -1008,6 +1056,7 @@ const REQUIREMENT_TO_SKIP_REASON = {
     real_wire: 'requirement_unmet',
     webhook_receiver: 'requirement_unmet',
     request_signer: 'not_applicable',
+    multi_agent: 'requirement_unmet',
 };
 function isKnownRequirement(requirement) {
     return types_1.KNOWN_REQUIREMENTS.has(requirement);
@@ -1167,8 +1216,14 @@ function normalizeAgentToolNames(tools) {
  *     threaded through), the gate is a no-op — the caller accepted
  *     responsibility for capability compatibility by reusing an external
  *     client. Spec: adcp-client#1702.
+ *   - `multi_agent` — `options.agents` is set and the storyboard's
+ *     declared route keys (`default_agent` and step-level `agent:` overrides)
+ *     resolve to at least two distinct entries in that map. Raw
+ *     `options.agents` cardinality is not enough; the requirement describes
+ *     the topology this storyboard actually routes through.
+ *     Spec: adcp-client#2281.
  */
-function checkRequires(requires, options, profile) {
+function checkRequires(requires, storyboard, options, profile) {
     for (const requirement of requires) {
         if (!isKnownRequirement(requirement)) {
             return {
@@ -1243,10 +1298,46 @@ function checkRequires(requires, options, profile) {
                         'register the test keypair before the 4.0 cut to avoid a hard compliance failure then.',
                 };
             }
+            case 'multi_agent': {
+                const routeKeys = collectMultiAgentRequirementRouteKeys(storyboard, options);
+                if (routeKeys.length >= 2)
+                    break;
+                const availableKeys = options.agents ? Object.keys(options.agents) : [];
+                const routed = routeKeys.length ? routeKeys.join(', ') : '(none)';
+                const available = availableKeys.length ? availableKeys.join(', ') : '(none)';
+                return {
+                    requirement,
+                    detail: "Storyboard requires 'multi_agent'; configure `agents` and route this storyboard " +
+                        'to at least two distinct agent keys via `default_agent` and/or step-level `agent:` overrides. ' +
+                        `Resolved route keys: [${routed}]. Available agents: [${available}].`,
+                };
+            }
         }
     }
     return null;
 }
+function collectMultiAgentRequirementRouteKeys(storyboard, options) {
+    const agents = options.agents;
+    if (!agents)
+        return [];
+    const routeKeys = new Set();
+    if (options.default_agent !== undefined && options.default_agent in agents) {
+        routeKeys.add(options.default_agent);
+    }
+    for (const phase of storyboard.phases ?? []) {
+        for (const step of phase.steps ?? []) {
+            if (step.agent !== undefined && step.agent in agents) {
+                routeKeys.add(step.agent);
+            }
+        }
+    }
+    return [...routeKeys];
+}
+function resolveStoryboardRequires(storyboard, options) {
+    const declared = storyboard.requires ?? [];
+    const implicit = detectImplicitRequires(storyboard, options);
+    return [...declared, ...implicit.filter(r => !declared.includes(r))];
+}
 /**
  * Webhook-token regex used to autodetect the implicit `webhook_receiver`
  * requirement. Matches `{{runner.webhook_url:<step_id>}}` and the bare
@@ -1739,11 +1830,9 @@ async function executeStoryboardPass(agentUrls, storyboard, options, dispatchOff
     // standalone runner path options._profile may be undefined; notices will be
     // collected again from the fully-fetched profile at result-build time.
     const preflightNotices = collectCapabilityNotices(storyboard, options._profile?.raw_capabilities);
-    const declared = storyboard.requires ?? [];
-    const implicit = detectImplicitRequires(storyboard, options);
-    const allRequires = [...declared, ...implicit.filter(r => !declared.includes(r))];
+    const allRequires = resolveStoryboardRequires(storyboard, options);
     if (allRequires.length) {
-        const unmet = checkRequires(allRequires, options, profile);
+        const unmet = checkRequires(allRequires, storyboard, options, profile);
         if (unmet) {
             if (!callerOwnsClients)
                 await (0, protocols_1.closeConnections)(options.protocol);
@@ -1772,7 +1861,7 @@ async function executeStoryboardPass(agentUrls, storyboard, options, dispatchOff
     // tests (e.g. `adcp.idempotency.supported: false`), skip the whole storyboard
     // rather than producing a cascade of misleading per-phase failures.
     if (storyboard.requires_capability) {
-        const unmetDetail = evaluateRequiresCapabilityGate(storyboard.requires_capability, profile, options.agentTools);
+        const unmetDetail = evaluateRequiresCapabilityGate(storyboard.requires_capability, profile, options.agentTools, options.adcpVersion);
         if (unmetDetail !== null) {
             if (!callerOwnsClients)
                 await (0, protocols_1.closeConnections)(options.protocol);
@@ -1913,7 +2002,7 @@ async function executeStoryboardPass(agentUrls, storyboard, options, dispatchOff
     // an implementor reading the report can't tell "nothing tested" from
     // "everything passed".
     const hasExecutableSteps = storyboard.phases.some(p => p.steps.length > 0);
-    const phaseCapabilitySkipDetails = collectPhaseCapabilitySkipDetails(storyboard, profile, options.agentTools);
+    const phaseCapabilitySkipDetails = collectPhaseCapabilitySkipDetails(storyboard, profile, options.agentTools, options.adcpVersion);
     const skipControllerSeedingForPhaseGates = allExecutablePhasesCapabilitySkipped(storyboard, phaseCapabilitySkipDetails);
     if (!hasExecutableSteps) {
         const isScenarioComposed = (storyboard.requires_scenarios?.length ?? 0) > 0;
@@ -2854,7 +2943,7 @@ async function runMultiPass(agentUrls, storyboard, options) {
             ...(options.agentTools ? {} : { agentTools: normalizeAgentToolNames(preSeedProfile.tools) }),
         };
     }
-    const phaseCapabilitySkipDetails = collectPhaseCapabilitySkipDetails(storyboard, preSeedProfile, options.agentTools);
+    const phaseCapabilitySkipDetails = collectPhaseCapabilitySkipDetails(storyboard, preSeedProfile, options.agentTools, options.adcpVersion);
     const preSeededResult = allExecutablePhasesCapabilitySkipped(storyboard, phaseCapabilitySkipDetails)
         ? null
         : await (0, seeding_1.runControllerSeeding)(preSeedClients[0], storyboard, options, preSeedContext);