@adcp/sdk 17.0.0-beta.25 → 17.0.0-beta.26

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) hide show
  1. package/dist/lib/discovery/property-crawler.d.mts +11 -0
  2. package/dist/lib/discovery/property-crawler.d.ts +11 -0
  3. package/dist/lib/discovery/property-crawler.js +15 -2
  4. package/dist/lib/discovery/property-crawler.mjs +15 -2
  5. package/dist/lib/discovery/resolve-agent-properties.d.mts +81 -8
  6. package/dist/lib/discovery/resolve-agent-properties.d.ts +81 -8
  7. package/dist/lib/discovery/resolve-agent-properties.js +94 -14
  8. package/dist/lib/discovery/resolve-agent-properties.mjs +91 -13
  9. package/dist/lib/discovery/validate-adagents.d.mts +7 -0
  10. package/dist/lib/discovery/validate-adagents.d.ts +7 -0
  11. package/dist/lib/entrypoints/discovery.d.mts +1 -1
  12. package/dist/lib/entrypoints/discovery.d.ts +1 -1
  13. package/dist/lib/entrypoints/discovery.js +4 -0
  14. package/dist/lib/entrypoints/discovery.mjs +5 -1
  15. package/dist/lib/index.d.mts +1 -1
  16. package/dist/lib/index.d.ts +1 -1
  17. package/dist/lib/index.js +4 -0
  18. package/dist/lib/index.mjs +5 -1
  19. package/dist/lib/supply-path/validation.d.mts +8 -0
  20. package/dist/lib/supply-path/validation.d.ts +8 -0
  21. package/dist/lib/testing/compliance/comply.js +1 -1
  22. package/dist/lib/testing/compliance/comply.mjs +3 -2
  23. package/dist/lib/testing/storyboard/index.d.mts +1 -1
  24. package/dist/lib/testing/storyboard/index.d.ts +1 -1
  25. package/dist/lib/testing/storyboard/index.js +6 -0
  26. package/dist/lib/testing/storyboard/index.mjs +6 -0
  27. package/dist/lib/testing/storyboard/loader.js +52 -28
  28. package/dist/lib/testing/storyboard/loader.mjs +52 -28
  29. package/dist/lib/testing/storyboard/runner.d.mts +24 -1
  30. package/dist/lib/testing/storyboard/runner.d.ts +24 -1
  31. package/dist/lib/testing/storyboard/runner.js +75 -7
  32. package/dist/lib/testing/storyboard/runner.mjs +72 -7
  33. package/dist/lib/testing/storyboard/types.d.mts +51 -6
  34. package/dist/lib/testing/storyboard/types.d.ts +51 -6
  35. package/dist/lib/testing/storyboard/validations.d.mts +1 -1
  36. package/dist/lib/testing/storyboard/validations.d.ts +1 -1
  37. package/dist/lib/types/wellknown-schemas.generated.d.mts +16 -16
  38. package/dist/lib/types/wellknown-schemas.generated.d.ts +16 -16
  39. package/dist/lib/version.d.mts +3 -3
  40. package/dist/lib/version.d.ts +3 -3
  41. package/dist/lib/version.js +3 -3
  42. package/dist/lib/version.mjs +3 -3
  43. package/docs/TYPE-SUMMARY.md +1 -1
  44. package/docs/guides/STORYBOARD-CAPABILITY-GATES.md +96 -0
  45. package/docs/guides/VALIDATE-YOUR-AGENT.md +5 -0
  46. package/docs/llms.txt +1 -1
  47. package/docs/migration-14.x-rc-worksheet.md +4 -4
  48. package/docs/migration-16-to-17.md +25 -0
  49. package/package.json +1 -1
@@ -159,6 +159,10 @@ function validatePhaseSkipIf(storyboardId, phase) {
159
159
  }
160
160
  }
161
161
  function validateRequiresAllCapabilities(storyboard) {
162
+ validateAnyOfGate(storyboard.requires_capability, `[${storyboard.id}] requires_capability`);
163
+ for (const phase of storyboard.phases ?? []) {
164
+ validateAnyOfGate(phase.requires_capability, `[${storyboard.id}] phase '${phase.id}': requires_capability`);
165
+ }
162
166
  const predicates = storyboard.requires_all_capabilities;
163
167
  if (predicates === void 0) return;
164
168
  if (!Array.isArray(predicates) || predicates.length < 2) {
@@ -167,37 +171,57 @@ function validateRequiresAllCapabilities(storyboard) {
167
171
  );
168
172
  }
169
173
  for (let index = 0; index < predicates.length; index++) {
170
- const raw = predicates[index];
171
- const prefix = `[${storyboard.id}] requires_all_capabilities[${index}]`;
172
- if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
173
- throw new Error(`${prefix}: must be a capability predicate object`);
174
- }
175
- const predicate = raw;
176
- if (typeof predicate.path !== "string" || predicate.path.trim().length === 0) {
177
- throw new Error(`${prefix}.path: must be a non-empty string`);
178
- }
179
- if (!CAPABILITY_PATH_PATTERN.test(predicate.path)) {
180
- throw new Error(`${prefix}.path: must be a canonical dotted capability path`);
181
- }
182
- const matcherKeys = ["equals", "present", "contains", "not_contains"].filter(
183
- (key) => Object.prototype.hasOwnProperty.call(predicate, key)
184
- );
185
- if (matcherKeys.length !== 1) {
186
- throw new Error(`${prefix}: must declare exactly one of equals, present, contains, or not_contains`);
187
- }
188
- const unknownKeys = Object.keys(predicate).filter((key) => key !== "path" && !matcherKeys.includes(key));
189
- if (unknownKeys.length > 0) {
190
- throw new Error(`${prefix}: unknown field${unknownKeys.length === 1 ? "" : "s"} ${unknownKeys.join(", ")}`);
191
- }
192
- if (matcherKeys[0] === "present" && typeof predicate.present !== "boolean") {
193
- throw new Error(`${prefix}.present: must be a boolean`);
174
+ validateCapabilityPredicateShape(predicates[index], `[${storyboard.id}] requires_all_capabilities[${index}]`);
175
+ }
176
+ }
177
+ function validateAnyOfGate(raw, prefix) {
178
+ if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return;
179
+ if (!Object.prototype.hasOwnProperty.call(raw, "any_of")) return;
180
+ validateCapabilityPredicateShape(raw, prefix);
181
+ }
182
+ function validateCapabilityPredicateShape(raw, prefix) {
183
+ if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
184
+ throw new Error(`${prefix}: must be a capability predicate object`);
185
+ }
186
+ const predicate = raw;
187
+ if (Object.prototype.hasOwnProperty.call(predicate, "any_of")) {
188
+ const unknownKeys2 = Object.keys(predicate).filter((key) => key !== "any_of");
189
+ if (unknownKeys2.length > 0) {
190
+ throw new Error(`${prefix}: any_of cannot be combined with ${unknownKeys2.join(", ")}`);
194
191
  }
195
- if (matcherKeys[0] === "equals" && predicate.equals !== null && !["boolean", "string", "number"].includes(typeof predicate.equals)) {
196
- throw new Error(`${prefix}.equals: must be a boolean, string, number, or null`);
192
+ const entries = predicate.any_of;
193
+ if (!Array.isArray(entries) || entries.length < 2) {
194
+ throw new Error(`${prefix}.any_of: must list at least two predicates`);
197
195
  }
198
- if ((matcherKeys[0] === "contains" || matcherKeys[0] === "not_contains") && !isJsonCapabilityValue(predicate[matcherKeys[0]])) {
199
- throw new Error(`${prefix}.${matcherKeys[0]}: must be a JSON-compatible capability value`);
196
+ for (let index = 0; index < entries.length; index++) {
197
+ validateCapabilityPredicateShape(entries[index], `${prefix}.any_of[${index}]`);
200
198
  }
199
+ return;
200
+ }
201
+ if (typeof predicate.path !== "string" || predicate.path.trim().length === 0) {
202
+ throw new Error(`${prefix}.path: must be a non-empty string`);
203
+ }
204
+ if (!CAPABILITY_PATH_PATTERN.test(predicate.path)) {
205
+ throw new Error(`${prefix}.path: must be a canonical dotted capability path`);
206
+ }
207
+ const matcherKeys = ["equals", "present", "contains", "not_contains"].filter(
208
+ (key) => Object.prototype.hasOwnProperty.call(predicate, key)
209
+ );
210
+ if (matcherKeys.length !== 1) {
211
+ throw new Error(`${prefix}: must declare exactly one of equals, present, contains, or not_contains`);
212
+ }
213
+ const unknownKeys = Object.keys(predicate).filter((key) => key !== "path" && !matcherKeys.includes(key));
214
+ if (unknownKeys.length > 0) {
215
+ throw new Error(`${prefix}: unknown field${unknownKeys.length === 1 ? "" : "s"} ${unknownKeys.join(", ")}`);
216
+ }
217
+ if (matcherKeys[0] === "present" && typeof predicate.present !== "boolean") {
218
+ throw new Error(`${prefix}.present: must be a boolean`);
219
+ }
220
+ if (matcherKeys[0] === "equals" && predicate.equals !== null && !["boolean", "string", "number"].includes(typeof predicate.equals)) {
221
+ throw new Error(`${prefix}.equals: must be a boolean, string, number, or null`);
222
+ }
223
+ if ((matcherKeys[0] === "contains" || matcherKeys[0] === "not_contains") && !isJsonCapabilityValue(predicate[matcherKeys[0]])) {
224
+ throw new Error(`${prefix}.${matcherKeys[0]}: must be a JSON-compatible capability value`);
201
225
  }
202
226
  }
203
227
  function isJsonCapabilityValue(value, seen = /* @__PURE__ */ new Set()) {
@@ -6,7 +6,7 @@
6
6
  * - runStoryboardStep(): run a single step (stateless, LLM-friendly)
7
7
  */
8
8
  import { PreparedStoryboardFixtures } from './prepared-fixtures.mjs';
9
- import type { RequiresCapabilityPredicate, Storyboard, StoryboardStep, StoryboardContext, StoryboardRunOptions, PrepareStoryboardFixturesOptions, StoryboardResult, StoryboardPhaseResult, StoryboardStepResult, StoryboardStepPreview, StrictValidationSummary, SchemaValidationError } from './types.mjs';
9
+ import type { AnyOfCapabilityPredicate, CapabilityPathPredicate, RequiresCapabilityPredicate, Storyboard, StoryboardStep, StoryboardContext, StoryboardRunOptions, PrepareStoryboardFixturesOptions, StoryboardResult, StoryboardPhaseResult, StoryboardStepResult, StoryboardStepPreview, StrictValidationSummary, SchemaValidationError } from './types.mjs';
10
10
  import type { AgentProfile, TestStepResult } from '../types.mjs';
11
11
  export declare function applyStoryboardVersionOptions(storyboard: Storyboard, options: StoryboardRunOptions): StoryboardRunOptions;
12
12
  export declare function applyAdcpVersionRunOptions(defaultAdcpVersion: string | undefined, options: StoryboardRunOptions): StoryboardRunOptions;
@@ -56,10 +56,33 @@ export declare function resolveCapabilityPath(raw: unknown, dottedPath: string):
56
56
  * that does not include `V` (structural JSON equality, no coercion). Missing and
57
57
  * non-array values skip; an empty array satisfies the predicate.
58
58
  *
59
+ * For `contains` and `not_contains`, an object `V` matches an object entry
60
+ * that carries every key of `V` with an equal value; the entry may carry
61
+ * other keys.
62
+ *
63
+ * An `any_of` predicate tests several paths, so it has no single `actual`
64
+ * value: this function throws a `TypeError` for one. Evaluate it with
65
+ * `evaluateCapabilityPredicateAgainstCapabilities`.
66
+ *
59
67
  * Exported for direct testing so the predicate semantics are pinned without
60
68
  * needing a full runStoryboard() roundtrip.
61
69
  */
62
70
  export declare function evaluateCapabilityPredicate(predicate: RequiresCapabilityPredicate, actual: unknown): string | null;
71
+ /** Type guard for the OR-composed `any_of` capability predicate. */
72
+ export declare function isAnyOfCapabilityPredicate(predicate: RequiresCapabilityPredicate): predicate is AnyOfCapabilityPredicate;
73
+ /**
74
+ * Every path predicate a capability gate tests, flattening `any_of` groups.
75
+ * Consumers that key on predicate paths (for example the compliance rollup's
76
+ * `compliance_testing` exclusion) read this instead of `predicate.path`.
77
+ */
78
+ export declare function capabilityPathPredicates(predicate: RequiresCapabilityPredicate): CapabilityPathPredicate[];
79
+ /**
80
+ * Evaluate a capability predicate, including `any_of` groups, against a raw
81
+ * `get_adcp_capabilities` response. Returns `null` when the predicate is
82
+ * satisfied and a human-readable detail otherwise. Path predicates resolve
83
+ * schema defaults on the same terms as the runner's gates.
84
+ */
85
+ export declare function evaluateCapabilityPredicateAgainstCapabilities(predicate: RequiresCapabilityPredicate, rawCapabilities: unknown, adcpVersion?: string): string | null;
63
86
  /**
64
87
  * Every root applicability predicate a storyboard authors, across
65
88
  * `requires_capability` and `requires_all_capabilities`. Exported so the
@@ -6,7 +6,7 @@
6
6
  * - runStoryboardStep(): run a single step (stateless, LLM-friendly)
7
7
  */
8
8
  import { PreparedStoryboardFixtures } from './prepared-fixtures';
9
- import type { RequiresCapabilityPredicate, Storyboard, StoryboardStep, StoryboardContext, StoryboardRunOptions, PrepareStoryboardFixturesOptions, StoryboardResult, StoryboardPhaseResult, StoryboardStepResult, StoryboardStepPreview, StrictValidationSummary, SchemaValidationError } from './types';
9
+ import type { AnyOfCapabilityPredicate, CapabilityPathPredicate, RequiresCapabilityPredicate, Storyboard, StoryboardStep, StoryboardContext, StoryboardRunOptions, PrepareStoryboardFixturesOptions, StoryboardResult, StoryboardPhaseResult, StoryboardStepResult, StoryboardStepPreview, StrictValidationSummary, SchemaValidationError } from './types';
10
10
  import type { AgentProfile, TestStepResult } from '../types';
11
11
  export declare function applyStoryboardVersionOptions(storyboard: Storyboard, options: StoryboardRunOptions): StoryboardRunOptions;
12
12
  export declare function applyAdcpVersionRunOptions(defaultAdcpVersion: string | undefined, options: StoryboardRunOptions): StoryboardRunOptions;
@@ -56,10 +56,33 @@ export declare function resolveCapabilityPath(raw: unknown, dottedPath: string):
56
56
  * that does not include `V` (structural JSON equality, no coercion). Missing and
57
57
  * non-array values skip; an empty array satisfies the predicate.
58
58
  *
59
+ * For `contains` and `not_contains`, an object `V` matches an object entry
60
+ * that carries every key of `V` with an equal value; the entry may carry
61
+ * other keys.
62
+ *
63
+ * An `any_of` predicate tests several paths, so it has no single `actual`
64
+ * value: this function throws a `TypeError` for one. Evaluate it with
65
+ * `evaluateCapabilityPredicateAgainstCapabilities`.
66
+ *
59
67
  * Exported for direct testing so the predicate semantics are pinned without
60
68
  * needing a full runStoryboard() roundtrip.
61
69
  */
62
70
  export declare function evaluateCapabilityPredicate(predicate: RequiresCapabilityPredicate, actual: unknown): string | null;
71
+ /** Type guard for the OR-composed `any_of` capability predicate. */
72
+ export declare function isAnyOfCapabilityPredicate(predicate: RequiresCapabilityPredicate): predicate is AnyOfCapabilityPredicate;
73
+ /**
74
+ * Every path predicate a capability gate tests, flattening `any_of` groups.
75
+ * Consumers that key on predicate paths (for example the compliance rollup's
76
+ * `compliance_testing` exclusion) read this instead of `predicate.path`.
77
+ */
78
+ export declare function capabilityPathPredicates(predicate: RequiresCapabilityPredicate): CapabilityPathPredicate[];
79
+ /**
80
+ * Evaluate a capability predicate, including `any_of` groups, against a raw
81
+ * `get_adcp_capabilities` response. Returns `null` when the predicate is
82
+ * satisfied and a human-readable detail otherwise. Path predicates resolve
83
+ * schema defaults on the same terms as the runner's gates.
84
+ */
85
+ export declare function evaluateCapabilityPredicateAgainstCapabilities(predicate: RequiresCapabilityPredicate, rawCapabilities: unknown, adcpVersion?: string): string | null;
63
86
  /**
64
87
  * Every root applicability predicate a storyboard authors, across
65
88
  * `requires_capability` and `requires_all_capabilities`. Exported so the
@@ -43,10 +43,13 @@ __export(runner_exports, {
43
43
  applyStoryboardVersionOptions: () => applyStoryboardVersionOptions,
44
44
  buildDiscoveryFailedResult: () => buildDiscoveryFailedResult,
45
45
  buildStepRequest: () => buildStepRequest,
46
+ capabilityPathPredicates: () => capabilityPathPredicates,
46
47
  collectCapabilityNotices: () => collectCapabilityNotices,
47
48
  describeStoryboardCapabilityGates: () => describeStoryboardCapabilityGates,
48
49
  evaluateCapabilityPredicate: () => evaluateCapabilityPredicate,
50
+ evaluateCapabilityPredicateAgainstCapabilities: () => evaluateCapabilityPredicateAgainstCapabilities,
49
51
  getFirstStepPreview: () => getFirstStepPreview,
52
+ isAnyOfCapabilityPredicate: () => isAnyOfCapabilityPredicate,
50
53
  listStrictOnlyFailures: () => listStrictOnlyFailures,
51
54
  prepareGovernedStoryboardWireArgs: () => prepareGovernedStoryboardWireArgs,
52
55
  prepareStoryboardFixtures: () => prepareStoryboardFixtures,
@@ -299,6 +302,11 @@ function schemaDefaultShouldApply(raw, dottedPath) {
299
302
  return current !== null && typeof current === "object";
300
303
  }
301
304
  function evaluateCapabilityPredicate(predicate, actual) {
305
+ if (isAnyOfCapabilityPredicate(predicate)) {
306
+ throw new TypeError(
307
+ "evaluateCapabilityPredicate: an any_of predicate tests several paths; use evaluateCapabilityPredicateAgainstCapabilities with the raw capabilities instead."
308
+ );
309
+ }
302
310
  if ("present" in predicate) {
303
311
  const isPresent = actual !== void 0 && actual !== null;
304
312
  if (predicate.present && !isPresent) {
@@ -336,7 +344,7 @@ function evaluateCapabilityPredicate(predicate, actual) {
336
344
  return null;
337
345
  }
338
346
  function capabilityContainsValue(path, actual, expected) {
339
- if (path !== "adcp.governance_enforcement.tasks") return capabilityValuesEqual(actual, expected);
347
+ if (path !== "adcp.governance_enforcement.tasks") return capabilityEntryMatches(actual, expected);
340
348
  if (!actual || !expected || typeof actual !== "object" || typeof expected !== "object") {
341
349
  return capabilityValuesEqual(actual, expected);
342
350
  }
@@ -349,6 +357,16 @@ function capabilityContainsValue(path, actual, expected) {
349
357
  if (!Array.isArray(actualModes)) return false;
350
358
  return actualTask.task === expectedTask.task && expectedTask.modes.every((mode) => actualModes.some((actualMode) => capabilityValuesEqual(actualMode, mode)));
351
359
  }
360
+ function isPlainCapabilityObject(value) {
361
+ return value !== null && typeof value === "object" && !Array.isArray(value);
362
+ }
363
+ function capabilityEntryMatches(actual, expected) {
364
+ if (!isPlainCapabilityObject(expected)) return capabilityValuesEqual(actual, expected);
365
+ if (!isPlainCapabilityObject(actual)) return false;
366
+ return Object.keys(expected).every(
367
+ (key) => Object.prototype.hasOwnProperty.call(actual, key) && capabilityValuesEqual(actual[key], expected[key])
368
+ );
369
+ }
352
370
  function capabilityValuesEqual(a, b) {
353
371
  if (a === b) return true;
354
372
  if (typeof a !== typeof b || a === null || b === null || typeof a !== "object") return false;
@@ -363,7 +381,39 @@ function capabilityValuesEqual(a, b) {
363
381
  const bKeys = Object.keys(bRecord).sort();
364
382
  return aKeys.length === bKeys.length && aKeys.every((key, index) => key === bKeys[index] && capabilityValuesEqual(aRecord[key], bRecord[key]));
365
383
  }
384
+ function isAnyOfCapabilityPredicate(predicate) {
385
+ return predicate !== null && typeof predicate === "object" && Object.prototype.hasOwnProperty.call(predicate, "any_of") && Array.isArray(predicate.any_of);
386
+ }
387
+ function capabilityPathPredicates(predicate) {
388
+ if (!isAnyOfCapabilityPredicate(predicate)) return [predicate];
389
+ return predicate.any_of.flatMap(capabilityPathPredicates);
390
+ }
391
+ function combineAnyOfDetails(predicate, details) {
392
+ return `Capability predicate \`${describeCapabilityPredicate(predicate)}\` not satisfied: no alternative passed (${details.join(" | ")})`;
393
+ }
394
+ function evaluateCapabilityPredicateAgainstCapabilities(predicate, rawCapabilities, adcpVersion) {
395
+ if (isAnyOfCapabilityPredicate(predicate)) {
396
+ const details = [];
397
+ for (const entry of predicate.any_of) {
398
+ const detail = evaluateCapabilityPredicateAgainstCapabilities(entry, rawCapabilities, adcpVersion);
399
+ if (detail === null) return null;
400
+ details.push(detail);
401
+ }
402
+ return combineAnyOfDetails(predicate, details);
403
+ }
404
+ const actual = resolveCapabilityPathForGate(rawCapabilities, predicate, adcpVersion);
405
+ return evaluateCapabilityPredicate(predicate, actual);
406
+ }
366
407
  function evaluateRequiresCapabilityGate(predicate, profile, agentTools, adcpVersion) {
408
+ if (isAnyOfCapabilityPredicate(predicate)) {
409
+ const details = [];
410
+ for (const entry of predicate.any_of) {
411
+ const detail = evaluateRequiresCapabilityGate(entry, profile, agentTools, adcpVersion);
412
+ if (detail === null) return null;
413
+ details.push(detail);
414
+ }
415
+ return combineAnyOfDetails(predicate, details);
416
+ }
367
417
  const rawCaps = profile?.raw_capabilities;
368
418
  if (rawCaps !== void 0) {
369
419
  const actual = resolveCapabilityPathForGate(rawCaps, predicate, adcpVersion);
@@ -402,6 +452,9 @@ function describeStoryboardCapabilityGates(storyboard) {
402
452
  return predicates.map(describeCapabilityPredicate).join(" AND ");
403
453
  }
404
454
  function describeCapabilityPredicate(predicate) {
455
+ if (isAnyOfCapabilityPredicate(predicate)) {
456
+ return `(${predicate.any_of.map(describeCapabilityPredicate).join(" OR ")})`;
457
+ }
405
458
  if ("present" in predicate) return `${predicate.path} ${predicate.present ? "present" : "absent"}`;
406
459
  if ("contains" in predicate) return `${predicate.path} contains ${JSON.stringify(predicate.contains)}`;
407
460
  if ("not_contains" in predicate) {
@@ -409,6 +462,23 @@ function describeCapabilityPredicate(predicate) {
409
462
  }
410
463
  return `${predicate.path} = ${JSON.stringify(predicate.equals)}`;
411
464
  }
465
+ function evaluateFailClosedCapabilityPredicate(predicate, rawCapabilities, adcpVersion) {
466
+ if (isAnyOfCapabilityPredicate(predicate)) {
467
+ const details = [];
468
+ for (const entry of predicate.any_of) {
469
+ const detail2 = evaluateFailClosedCapabilityPredicate(entry, rawCapabilities, adcpVersion);
470
+ if (detail2 === null) return null;
471
+ details.push(detail2);
472
+ }
473
+ return combineAnyOfDetails(predicate, details);
474
+ }
475
+ const declared = resolveCapabilityPath(rawCapabilities, predicate.path);
476
+ const resolved = resolveCapabilityPathForGate(rawCapabilities, predicate, adcpVersion);
477
+ const detail = evaluateCapabilityPredicate(predicate, resolved);
478
+ if (detail === null) return null;
479
+ const provenance = declared !== void 0 ? `declared value ${JSON.stringify(declared)}` : resolved !== void 0 ? `resolved schema default ${JSON.stringify(resolved)}` : "no declared or resolved value";
480
+ return `${detail} [${provenance}]`;
481
+ }
412
482
  function evaluateStoryboardCapabilityGates(storyboard, profile, agentTools, adcpVersion) {
413
483
  const predicates = [
414
484
  ...storyboard.requires_capability ? [{ predicate: storyboard.requires_capability, failClosed: false }] : [],
@@ -420,12 +490,7 @@ function evaluateStoryboardCapabilityGates(storyboard, profile, agentTools, adcp
420
490
  if (rawCapabilities === void 0) {
421
491
  return `Capability predicate \`${describeCapabilityPredicate(predicate)}\` could not be evaluated: no declared or resolved value (raw capabilities unavailable).`;
422
492
  }
423
- const declared = resolveCapabilityPath(rawCapabilities, predicate.path);
424
- const resolved = resolveCapabilityPathForGate(rawCapabilities, predicate, adcpVersion);
425
- const detail = evaluateCapabilityPredicate(predicate, resolved);
426
- if (detail === null) return null;
427
- const provenance = declared !== void 0 ? `declared value ${JSON.stringify(declared)}` : resolved !== void 0 ? `resolved schema default ${JSON.stringify(resolved)}` : "no declared or resolved value";
428
- return `${detail} [${provenance}]`;
493
+ return evaluateFailClosedCapabilityPredicate(predicate, rawCapabilities, adcpVersion);
429
494
  }).filter((detail) => detail !== null);
430
495
  if (failures.length === 0) return null;
431
496
  if (failures.length === 1) return failures[0];
@@ -8598,10 +8663,13 @@ function getFirstStepPreview(storyboard, context = {}) {
8598
8663
  applyStoryboardVersionOptions,
8599
8664
  buildDiscoveryFailedResult,
8600
8665
  buildStepRequest,
8666
+ capabilityPathPredicates,
8601
8667
  collectCapabilityNotices,
8602
8668
  describeStoryboardCapabilityGates,
8603
8669
  evaluateCapabilityPredicate,
8670
+ evaluateCapabilityPredicateAgainstCapabilities,
8604
8671
  getFirstStepPreview,
8672
+ isAnyOfCapabilityPredicate,
8605
8673
  listStrictOnlyFailures,
8606
8674
  prepareGovernedStoryboardWireArgs,
8607
8675
  prepareStoryboardFixtures,
@@ -341,6 +341,11 @@ function schemaDefaultShouldApply(raw, dottedPath) {
341
341
  return current !== null && typeof current === "object";
342
342
  }
343
343
  function evaluateCapabilityPredicate(predicate, actual) {
344
+ if (isAnyOfCapabilityPredicate(predicate)) {
345
+ throw new TypeError(
346
+ "evaluateCapabilityPredicate: an any_of predicate tests several paths; use evaluateCapabilityPredicateAgainstCapabilities with the raw capabilities instead."
347
+ );
348
+ }
344
349
  if ("present" in predicate) {
345
350
  const isPresent = actual !== void 0 && actual !== null;
346
351
  if (predicate.present && !isPresent) {
@@ -378,7 +383,7 @@ function evaluateCapabilityPredicate(predicate, actual) {
378
383
  return null;
379
384
  }
380
385
  function capabilityContainsValue(path, actual, expected) {
381
- if (path !== "adcp.governance_enforcement.tasks") return capabilityValuesEqual(actual, expected);
386
+ if (path !== "adcp.governance_enforcement.tasks") return capabilityEntryMatches(actual, expected);
382
387
  if (!actual || !expected || typeof actual !== "object" || typeof expected !== "object") {
383
388
  return capabilityValuesEqual(actual, expected);
384
389
  }
@@ -391,6 +396,16 @@ function capabilityContainsValue(path, actual, expected) {
391
396
  if (!Array.isArray(actualModes)) return false;
392
397
  return actualTask.task === expectedTask.task && expectedTask.modes.every((mode) => actualModes.some((actualMode) => capabilityValuesEqual(actualMode, mode)));
393
398
  }
399
+ function isPlainCapabilityObject(value) {
400
+ return value !== null && typeof value === "object" && !Array.isArray(value);
401
+ }
402
+ function capabilityEntryMatches(actual, expected) {
403
+ if (!isPlainCapabilityObject(expected)) return capabilityValuesEqual(actual, expected);
404
+ if (!isPlainCapabilityObject(actual)) return false;
405
+ return Object.keys(expected).every(
406
+ (key) => Object.prototype.hasOwnProperty.call(actual, key) && capabilityValuesEqual(actual[key], expected[key])
407
+ );
408
+ }
394
409
  function capabilityValuesEqual(a, b) {
395
410
  if (a === b) return true;
396
411
  if (typeof a !== typeof b || a === null || b === null || typeof a !== "object") return false;
@@ -405,7 +420,39 @@ function capabilityValuesEqual(a, b) {
405
420
  const bKeys = Object.keys(bRecord).sort();
406
421
  return aKeys.length === bKeys.length && aKeys.every((key, index) => key === bKeys[index] && capabilityValuesEqual(aRecord[key], bRecord[key]));
407
422
  }
423
+ function isAnyOfCapabilityPredicate(predicate) {
424
+ return predicate !== null && typeof predicate === "object" && Object.prototype.hasOwnProperty.call(predicate, "any_of") && Array.isArray(predicate.any_of);
425
+ }
426
+ function capabilityPathPredicates(predicate) {
427
+ if (!isAnyOfCapabilityPredicate(predicate)) return [predicate];
428
+ return predicate.any_of.flatMap(capabilityPathPredicates);
429
+ }
430
+ function combineAnyOfDetails(predicate, details) {
431
+ return `Capability predicate \`${describeCapabilityPredicate(predicate)}\` not satisfied: no alternative passed (${details.join(" | ")})`;
432
+ }
433
+ function evaluateCapabilityPredicateAgainstCapabilities(predicate, rawCapabilities, adcpVersion) {
434
+ if (isAnyOfCapabilityPredicate(predicate)) {
435
+ const details = [];
436
+ for (const entry of predicate.any_of) {
437
+ const detail = evaluateCapabilityPredicateAgainstCapabilities(entry, rawCapabilities, adcpVersion);
438
+ if (detail === null) return null;
439
+ details.push(detail);
440
+ }
441
+ return combineAnyOfDetails(predicate, details);
442
+ }
443
+ const actual = resolveCapabilityPathForGate(rawCapabilities, predicate, adcpVersion);
444
+ return evaluateCapabilityPredicate(predicate, actual);
445
+ }
408
446
  function evaluateRequiresCapabilityGate(predicate, profile, agentTools, adcpVersion) {
447
+ if (isAnyOfCapabilityPredicate(predicate)) {
448
+ const details = [];
449
+ for (const entry of predicate.any_of) {
450
+ const detail = evaluateRequiresCapabilityGate(entry, profile, agentTools, adcpVersion);
451
+ if (detail === null) return null;
452
+ details.push(detail);
453
+ }
454
+ return combineAnyOfDetails(predicate, details);
455
+ }
409
456
  const rawCaps = profile?.raw_capabilities;
410
457
  if (rawCaps !== void 0) {
411
458
  const actual = resolveCapabilityPathForGate(rawCaps, predicate, adcpVersion);
@@ -444,6 +491,9 @@ function describeStoryboardCapabilityGates(storyboard) {
444
491
  return predicates.map(describeCapabilityPredicate).join(" AND ");
445
492
  }
446
493
  function describeCapabilityPredicate(predicate) {
494
+ if (isAnyOfCapabilityPredicate(predicate)) {
495
+ return `(${predicate.any_of.map(describeCapabilityPredicate).join(" OR ")})`;
496
+ }
447
497
  if ("present" in predicate) return `${predicate.path} ${predicate.present ? "present" : "absent"}`;
448
498
  if ("contains" in predicate) return `${predicate.path} contains ${JSON.stringify(predicate.contains)}`;
449
499
  if ("not_contains" in predicate) {
@@ -451,6 +501,23 @@ function describeCapabilityPredicate(predicate) {
451
501
  }
452
502
  return `${predicate.path} = ${JSON.stringify(predicate.equals)}`;
453
503
  }
504
+ function evaluateFailClosedCapabilityPredicate(predicate, rawCapabilities, adcpVersion) {
505
+ if (isAnyOfCapabilityPredicate(predicate)) {
506
+ const details = [];
507
+ for (const entry of predicate.any_of) {
508
+ const detail2 = evaluateFailClosedCapabilityPredicate(entry, rawCapabilities, adcpVersion);
509
+ if (detail2 === null) return null;
510
+ details.push(detail2);
511
+ }
512
+ return combineAnyOfDetails(predicate, details);
513
+ }
514
+ const declared = resolveCapabilityPath(rawCapabilities, predicate.path);
515
+ const resolved = resolveCapabilityPathForGate(rawCapabilities, predicate, adcpVersion);
516
+ const detail = evaluateCapabilityPredicate(predicate, resolved);
517
+ if (detail === null) return null;
518
+ const provenance = declared !== void 0 ? `declared value ${JSON.stringify(declared)}` : resolved !== void 0 ? `resolved schema default ${JSON.stringify(resolved)}` : "no declared or resolved value";
519
+ return `${detail} [${provenance}]`;
520
+ }
454
521
  function evaluateStoryboardCapabilityGates(storyboard, profile, agentTools, adcpVersion) {
455
522
  const predicates = [
456
523
  ...storyboard.requires_capability ? [{ predicate: storyboard.requires_capability, failClosed: false }] : [],
@@ -462,12 +529,7 @@ function evaluateStoryboardCapabilityGates(storyboard, profile, agentTools, adcp
462
529
  if (rawCapabilities === void 0) {
463
530
  return `Capability predicate \`${describeCapabilityPredicate(predicate)}\` could not be evaluated: no declared or resolved value (raw capabilities unavailable).`;
464
531
  }
465
- const declared = resolveCapabilityPath(rawCapabilities, predicate.path);
466
- const resolved = resolveCapabilityPathForGate(rawCapabilities, predicate, adcpVersion);
467
- const detail = evaluateCapabilityPredicate(predicate, resolved);
468
- if (detail === null) return null;
469
- const provenance = declared !== void 0 ? `declared value ${JSON.stringify(declared)}` : resolved !== void 0 ? `resolved schema default ${JSON.stringify(resolved)}` : "no declared or resolved value";
470
- return `${detail} [${provenance}]`;
532
+ return evaluateFailClosedCapabilityPredicate(predicate, rawCapabilities, adcpVersion);
471
533
  }).filter((detail) => detail !== null);
472
534
  if (failures.length === 0) return null;
473
535
  if (failures.length === 1) return failures[0];
@@ -8640,10 +8702,13 @@ export {
8640
8702
  applyStoryboardVersionOptions,
8641
8703
  buildDiscoveryFailedResult,
8642
8704
  buildStepRequest,
8705
+ capabilityPathPredicates,
8643
8706
  collectCapabilityNotices,
8644
8707
  describeStoryboardCapabilityGates,
8645
8708
  evaluateCapabilityPredicate,
8709
+ evaluateCapabilityPredicateAgainstCapabilities,
8646
8710
  getFirstStepPreview,
8711
+ isAnyOfCapabilityPredicate,
8647
8712
  listStrictOnlyFailures,
8648
8713
  prepareGovernedStoryboardWireArgs,
8649
8714
  prepareStoryboardFixtures,
@@ -15,7 +15,8 @@ import type { AcceptancePolicyRegistryResolver } from '../../acceptance-policy/i
15
15
  export type CapabilityPredicateValue = boolean | string | number | null | CapabilityPredicateValue[] | {
16
16
  [key: string]: CapabilityPredicateValue;
17
17
  };
18
- export type RequiresCapabilityPredicate = {
18
+ /** A capability predicate that tests one dotted path with one matcher. */
19
+ export type CapabilityPathPredicate = {
19
20
  path: string;
20
21
  equals: boolean | string | number | null;
21
22
  } | {
@@ -28,6 +29,16 @@ export type RequiresCapabilityPredicate = {
28
29
  path: string;
29
30
  not_contains: CapabilityPredicateValue;
30
31
  };
32
+ /**
33
+ * OR-composition of two or more capability predicates: the gate passes when
34
+ * at least one entry passes. Entries are path predicates or nested `any_of`
35
+ * groups. Supported by @adcp/sdk releases after 17.0.0-beta.25; see
36
+ * `Storyboard.requires_capability` for how older runners treat the key.
37
+ */
38
+ export interface AnyOfCapabilityPredicate {
39
+ any_of: RequiresCapabilityPredicate[];
40
+ }
41
+ export type RequiresCapabilityPredicate = CapabilityPathPredicate | AnyOfCapabilityPredicate;
31
42
  export interface Storyboard {
32
43
  id: string;
33
44
  version: string;
@@ -195,20 +206,52 @@ export interface Storyboard {
195
206
  * response schema declares a default for that exact path and the parent
196
207
  * capability object is present. Like `present:`, absence is otherwise the
197
208
  * load-bearing signal — a seller that doesn't advertise the array hasn't
198
- * opted into the variant this storyboard tests. For
209
+ * opted into the variant this storyboard tests. When `V` is an object,
210
+ * an array entry matches when it is an object that carries every key of
211
+ * `V` with a structurally equal value; the entry MAY carry other keys
212
+ * (`contains: { pattern: sync_audiences }` matches
213
+ * `{ pattern: "sync_audiences", note: "x" }`). Scalars and arrays still
214
+ * match by structural equality. For
199
215
  * `adcp.governance_enforcement.tasks`, an entry matches when its task is
200
216
  * equal and its declared modes include every mode in the predicate;
201
217
  * sellers combine all modes for a task in one entry.
202
218
  *
203
219
  * - `not_contains: V` — negative array-membership matcher. The value at
204
- * `path` MUST be an array and MUST NOT include `V` (structural JSON equality,
205
- * except governance task-mode predicates match a subset; no coercion).
220
+ * `path` MUST be an array and MUST NOT include `V` (the same entry match
221
+ * as `contains`: structural JSON equality for scalars and arrays, a key
222
+ * subset for objects, governance task-mode predicates match a subset; no
223
+ * coercion).
206
224
  * This is useful for rejection scenarios that apply only when
207
225
  * an advertised allowlist omits a value. Missing and non-array values do
208
226
  * not satisfy the predicate; a separate discovery validation should grade
209
227
  * a required capability declaration. Schema defaults are materialized on
210
228
  * the same terms as `contains`.
211
229
  *
230
+ * In place of `path` and a matcher, a gate MAY declare `any_of`: a list of
231
+ * two or more predicates (path predicates or nested `any_of` groups). The
232
+ * gate passes when at least one entry passes, and each entry is evaluated
233
+ * by its own rules, including schema defaults and the no-raw-capabilities
234
+ * fallback below. `any_of` cannot be combined with `path` or a matcher on
235
+ * the same object. Example, "the field is absent, or it lists an entry
236
+ * whose `pattern` is `sync_audiences`":
237
+ *
238
+ * ```yaml
239
+ * requires_capability:
240
+ * any_of:
241
+ * - path: media_buy.audience_targeting.supported_activation_methods
242
+ * present: false
243
+ * - path: media_buy.audience_targeting.supported_activation_methods
244
+ * contains: { pattern: sync_audiences }
245
+ * ```
246
+ *
247
+ * `any_of` and object-subset `contains` are supported by @adcp/sdk
248
+ * releases after 17.0.0-beta.25. A runner without `any_of` support reads a
249
+ * predicate that has no `path`: with raw capabilities available it throws
250
+ * while resolving the missing path, and without them it treats the gate as
251
+ * satisfied. A runner without object-subset `contains` matches object
252
+ * values by exact structural equality, so an entry with extra keys does
253
+ * not match. Bundles that use either form need a runner that supports it.
254
+ *
212
255
  * When `raw_capabilities` is not available and the discovered profile does
213
256
  * not expose `get_adcp_capabilities`, `equals` gates are treated as
214
257
  * unsupported because there is no declaration proving the agent opted into
@@ -224,7 +267,9 @@ export interface Storyboard {
224
267
  * predicate skips the entire storyboard before runtime or tool gates.
225
268
  *
226
269
  * The loader rejects empty and single-entry arrays; use
227
- * `requires_capability` for a singular gate.
270
+ * `requires_capability` for a singular gate. An entry MAY be an `any_of`
271
+ * group (see `requires_capability`), which passes when one of its entries
272
+ * passes.
228
273
  *
229
274
  * Compound gates fail closed when the raw capabilities payload is
230
275
  * unavailable: advertised or auto-registered tools are not capability
@@ -612,7 +657,7 @@ export interface StoryboardPhase {
612
657
  * Predicate evaluated against the agent's declared capabilities before this
613
658
  * phase is set up or any of its steps are dispatched. Uses the same matcher
614
659
  * dialect as `Storyboard.requires_capability` (`equals`, `present`,
615
- * `contains`). When false, every step in the phase is emitted as a
660
+ * `contains`, `not_contains`, `any_of`). When false, every step in the phase is emitted as a
616
661
  * `not_applicable` skip and the runner continues with later phases.
617
662
  */
618
663
  requires_capability?: RequiresCapabilityPredicate;