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

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 (55) hide show
  1. package/dist/lib/discovery/agent-directory.d.mts +10 -3
  2. package/dist/lib/discovery/agent-directory.d.ts +10 -3
  3. package/dist/lib/discovery/property-crawler.d.mts +11 -0
  4. package/dist/lib/discovery/property-crawler.d.ts +11 -0
  5. package/dist/lib/discovery/property-crawler.js +15 -2
  6. package/dist/lib/discovery/property-crawler.mjs +15 -2
  7. package/dist/lib/discovery/resolve-agent-properties.d.mts +170 -8
  8. package/dist/lib/discovery/resolve-agent-properties.d.ts +170 -8
  9. package/dist/lib/discovery/resolve-agent-properties.js +155 -14
  10. package/dist/lib/discovery/resolve-agent-properties.mjs +151 -13
  11. package/dist/lib/discovery/types.d.mts +14 -0
  12. package/dist/lib/discovery/types.d.ts +14 -0
  13. package/dist/lib/discovery/validate-adagents.d.mts +7 -0
  14. package/dist/lib/discovery/validate-adagents.d.ts +7 -0
  15. package/dist/lib/entrypoints/discovery.d.mts +1 -1
  16. package/dist/lib/entrypoints/discovery.d.ts +1 -1
  17. package/dist/lib/entrypoints/discovery.js +6 -0
  18. package/dist/lib/entrypoints/discovery.mjs +7 -1
  19. package/dist/lib/index.d.mts +1 -1
  20. package/dist/lib/index.d.ts +1 -1
  21. package/dist/lib/index.js +6 -0
  22. package/dist/lib/index.mjs +7 -1
  23. package/dist/lib/registry/types.generated.d.ts +5 -5
  24. package/dist/lib/supply-path/validation.d.mts +8 -0
  25. package/dist/lib/supply-path/validation.d.ts +8 -0
  26. package/dist/lib/testing/compliance/comply.js +9 -2
  27. package/dist/lib/testing/compliance/comply.mjs +11 -3
  28. package/dist/lib/testing/storyboard/index.d.mts +1 -1
  29. package/dist/lib/testing/storyboard/index.d.ts +1 -1
  30. package/dist/lib/testing/storyboard/index.js +6 -0
  31. package/dist/lib/testing/storyboard/index.mjs +6 -0
  32. package/dist/lib/testing/storyboard/loader.js +52 -28
  33. package/dist/lib/testing/storyboard/loader.mjs +52 -28
  34. package/dist/lib/testing/storyboard/runner.d.mts +24 -1
  35. package/dist/lib/testing/storyboard/runner.d.ts +24 -1
  36. package/dist/lib/testing/storyboard/runner.js +75 -7
  37. package/dist/lib/testing/storyboard/runner.mjs +72 -7
  38. package/dist/lib/testing/storyboard/types.d.mts +51 -6
  39. package/dist/lib/testing/storyboard/types.d.ts +51 -6
  40. package/dist/lib/testing/storyboard/validations.d.mts +1 -1
  41. package/dist/lib/testing/storyboard/validations.d.ts +1 -1
  42. package/dist/lib/types/wellknown-schemas.generated.d.mts +16 -16
  43. package/dist/lib/types/wellknown-schemas.generated.d.ts +16 -16
  44. package/dist/lib/version.d.mts +3 -3
  45. package/dist/lib/version.d.ts +3 -3
  46. package/dist/lib/version.js +3 -3
  47. package/dist/lib/version.mjs +3 -3
  48. package/docs/TYPE-SUMMARY.md +1 -1
  49. package/docs/guides/STORYBOARD-CAPABILITY-GATES.md +96 -0
  50. package/docs/guides/VALIDATE-YOUR-AGENT.md +5 -0
  51. package/docs/llms.txt +1 -1
  52. package/docs/migration-14.x-rc-worksheet.md +4 -4
  53. package/docs/migration-16-to-17.md +31 -0
  54. package/docs/migration-agent-resolution-3.3.md +18 -0
  55. package/package.json +1 -1
@@ -57,7 +57,10 @@ import {
57
57
  resolveAgentProperties,
58
58
  listAgentPropertyMap,
59
59
  getAllProperties,
60
- canonicalizeAgentUrl
60
+ canonicalizeAgentUrl,
61
+ agentUrlMatchesAuthorizedEntry,
62
+ usesOriginOnlyAgentMatching,
63
+ resolvePublisherSigningKeyPin
61
64
  } from "./discovery/resolve-agent-properties.mjs";
62
65
  import {
63
66
  resolveInlinePublisherProperties,
@@ -1068,6 +1071,7 @@ export {
1068
1071
  addSpanAttributes,
1069
1072
  adjustedMediaBuyDeliveryNotification,
1070
1073
  agentSignalId,
1074
+ agentUrlMatchesAuthorizedEntry,
1071
1075
  applyBrandAssetMappings,
1072
1076
  applyTargetingInput,
1073
1077
  assertCreativeTransition,
@@ -1476,6 +1480,7 @@ export {
1476
1480
  resolveInlinePublisherProperties,
1477
1481
  resolvePlatformExtensionsReference,
1478
1482
  resolvePreviewAuthority,
1483
+ resolvePublisherSigningKeyPin,
1479
1484
  resolveRecovery,
1480
1485
  resolveSecret,
1481
1486
  resolveSingularInline,
@@ -1544,6 +1549,7 @@ export {
1544
1549
  urlRender,
1545
1550
  useIdempotencyKey,
1546
1551
  usesDeprecatedAssetsField,
1552
+ usesOriginOnlyAgentMatching,
1547
1553
  usesV3CreativeAssignments,
1548
1554
  usesV3RenderFields,
1549
1555
  usesV3Renders,
@@ -544,7 +544,7 @@ export interface paths {
544
544
  };
545
545
  /**
546
546
  * Agent domain lookup
547
- * @description Get all publisher domains associated with an agent.
547
+ * @description Get all publisher domains whose adagents.json authorizes an agent. `agentUrl` is matched with the [adagents.json agent URL matching](/docs/governance/property/adagents#agent-url-matching) rule: an origin-only `authorized_agents[].url` (`https://agent.example.com`) authorizes every agent URL at that origin, and an entry with a path matches that canonical URL only, with a non-root trailing slash significant.
548
548
  */
549
549
  get: operations["getAgentDomains"];
550
550
  put?: never;
@@ -568,7 +568,7 @@ export interface paths {
568
568
  *
569
569
  * Spec: [docs/aao/directory-api.mdx](/docs/aao/directory-api) (adcp#4823). This endpoint is the spec-compliant richer-shape replacement for the legacy `/api/registry/lookup/agent/{agentUrl}/domains`, which returns domain strings only.
570
570
  *
571
- * `agent_url` is matched with [AdCP URL canonicalization](/docs/reference/url-canonicalization) and a **non-root trailing slash is significant**: `https://a.example/mcp` and `https://a.example/mcp/` are different agents and can return different publisher sets, the same rule the SDK applies in `verify_agent_authorization`. Ask for the spelling the publisher's adagents.json lists. (Through 2026-10-18 this endpoint folded the two spellings together and answered both with the slashless agent's publishers; that disagreed with the spec and with the validator.) The `agent_url` in the response echoes the canonicalized lookup key, slash included.
571
+ * `agent_url` is matched with the [adagents.json agent URL matching](/docs/governance/property/adagents#agent-url-matching) rule, after [AdCP URL canonicalization](/docs/reference/url-canonicalization) of both sides. A publisher whose `authorized_agents[].url` is **origin-only** (`https://a.example` or `https://a.example/`) authorizes every agent URL with that canonical origin (same scheme, host and port), so it is returned for `https://a.example/mcp` and `https://a.example/a2a` alike (DR-0023, AdCP 3.3). An entry **with a path** matches that canonical URL only, and a **non-root trailing slash is significant**: `https://a.example/mcp` and `https://a.example/mcp/` are different agents and can return different publisher sets. Ask for the spelling the publisher's adagents.json lists. (Through 2026-10-18 this endpoint folded the two trailing-slash spellings together and answered both with the slashless agent's publishers; that disagreed with the spec and with the validator.) The `agent_url` in the response echoes the canonicalized lookup key, slash included.
572
572
  */
573
573
  get: operations["getPublishersForAgentLegacyApiPrefix"];
574
574
  put?: never;
@@ -592,7 +592,7 @@ export interface paths {
592
592
  *
593
593
  * Spec: [docs/aao/directory-api.mdx](/docs/aao/directory-api) (adcp#4823). This endpoint is the spec-compliant richer-shape replacement for the legacy `/api/registry/lookup/agent/{agentUrl}/domains`, which returns domain strings only.
594
594
  *
595
- * `agent_url` is matched with [AdCP URL canonicalization](/docs/reference/url-canonicalization) and a **non-root trailing slash is significant**: `https://a.example/mcp` and `https://a.example/mcp/` are different agents and can return different publisher sets, the same rule the SDK applies in `verify_agent_authorization`. Ask for the spelling the publisher's adagents.json lists. (Through 2026-10-18 this endpoint folded the two spellings together and answered both with the slashless agent's publishers; that disagreed with the spec and with the validator.) The `agent_url` in the response echoes the canonicalized lookup key, slash included.
595
+ * `agent_url` is matched with the [adagents.json agent URL matching](/docs/governance/property/adagents#agent-url-matching) rule, after [AdCP URL canonicalization](/docs/reference/url-canonicalization) of both sides. A publisher whose `authorized_agents[].url` is **origin-only** (`https://a.example` or `https://a.example/`) authorizes every agent URL with that canonical origin (same scheme, host and port), so it is returned for `https://a.example/mcp` and `https://a.example/a2a` alike (DR-0023, AdCP 3.3). An entry **with a path** matches that canonical URL only, and a **non-root trailing slash is significant**: `https://a.example/mcp` and `https://a.example/mcp/` are different agents and can return different publisher sets. Ask for the spelling the publisher's adagents.json lists. (Through 2026-10-18 this endpoint folded the two trailing-slash spellings together and answered both with the slashless agent's publishers; that disagreed with the spec and with the validator.) The `agent_url` in the response echoes the canonicalized lookup key, slash included.
596
596
  */
597
597
  get: operations["getPublishersForAgent"];
598
598
  put?: never;
@@ -2582,7 +2582,7 @@ export interface components {
2582
2582
  stats?: components["schemas"]["AgentStats"];
2583
2583
  capabilities?: components["schemas"]["AgentCapabilities"];
2584
2584
  compliance?: components["schemas"]["AgentCompliance"];
2585
- /** @description Every raw agent_url spelling the directory has indexed under this agent's identity, with the listed (canonical) url first. The registry keys an agent by identity, folding a non-root trailing slash, but GET /v1/agents/{agent_url}/publishers matches spec-exactly with the slash significant — so a client answering "which publishers authorize this agent" must query once per spelling here and merge the results. */
2585
+ /** @description Every raw agent_url spelling the directory has indexed under this agent's identity, with the listed (canonical) url first. The registry keys an agent by identity, folding a non-root trailing slash, but GET /v1/agents/{agent_url}/publishers matches with adagents.json agent URL matching, where the slash is significant for an entry with a path — so a client answering "which publishers authorize this agent" must query once per spelling here and merge the results. Publishers that authorize the agent's bare origin are returned for every spelling. */
2586
2586
  declared_urls?: string[];
2587
2587
  publisher_domains?: string[];
2588
2588
  property_summary?: components["schemas"]["PropertySummary"];
@@ -8781,7 +8781,7 @@ export interface operations {
8781
8781
  getAgentAuthorizations: {
8782
8782
  parameters: {
8783
8783
  query: {
8784
- /** @description Agent URL to look up. Canonicalized server-side per AdCP URL canonicalization: the scheme and host fold, the path does not. */
8784
+ /** @description Agent URL to look up. Canonicalized server-side per AdCP URL canonicalization: the scheme and host fold, the path does not. Returns the rows whose `agent_url` authorizes it under adagents.json agent URL matching: rows for the same canonical URL, plus rows whose `agent_url` is origin-only (`https://agent.example.com`) for the same canonical origin, which authorize every path at that origin. */
8785
8785
  agent_url: string;
8786
8786
  /** @description `effective` (default) applies override layer; `raw` reads base table. */
8787
8787
  include?: "raw" | "effective";
@@ -4,6 +4,14 @@ export declare function records(value: unknown): Record<string, unknown>[];
4
4
  export declare function strings(value: unknown): value is string[];
5
5
  /** Domain identity never strips www or conflates sibling publisher namespaces. */
6
6
  export declare function domain(value: unknown): string | null;
7
+ /**
8
+ * Exact canonical agent URL used by every supply-path leg. Semantics version 1
9
+ * compares `authorized_agents[].url` by exact canonical URL, including an
10
+ * origin-only entry: the 3.3 rule that an origin-only entry authorizes the agent
11
+ * at any path on that origin (adcp#8862) does not apply here until a new
12
+ * supply-path semantics version adopts it, planned for 4.0. Do not swap this for
13
+ * `agentUrlMatchesAuthorizedEntry`. See adcontextprotocol/adcp#8943.
14
+ */
7
15
  export declare function agentIdentity(value: unknown): string | null;
8
16
  export declare function validateSupplyPathRequest(input: SupplyPathRequest): SupplyPathRequest;
9
17
  /** Runtime boundary for cached remote verdicts. Unknown extensions are preserved. */
@@ -4,6 +4,14 @@ export declare function records(value: unknown): Record<string, unknown>[];
4
4
  export declare function strings(value: unknown): value is string[];
5
5
  /** Domain identity never strips www or conflates sibling publisher namespaces. */
6
6
  export declare function domain(value: unknown): string | null;
7
+ /**
8
+ * Exact canonical agent URL used by every supply-path leg. Semantics version 1
9
+ * compares `authorized_agents[].url` by exact canonical URL, including an
10
+ * origin-only entry: the 3.3 rule that an origin-only entry authorizes the agent
11
+ * at any path on that origin (adcp#8862) does not apply here until a new
12
+ * supply-path semantics version adopts it, planned for 4.0. Do not swap this for
13
+ * `agentUrlMatchesAuthorizedEntry`. See adcontextprotocol/adcp#8943.
14
+ */
7
15
  export declare function agentIdentity(value: unknown): string | null;
8
16
  export declare function validateSupplyPathRequest(input: SupplyPathRequest): SupplyPathRequest;
9
17
  /** Runtime boundary for cached remote verdicts. Unknown extensions are preserved. */
@@ -569,6 +569,13 @@ const NEUTRAL_BUNDLE_SKIP_REASONS = /* @__PURE__ */ new Set([
569
569
  "capability_prerequisite_unavailable"
570
570
  ]);
571
571
  const CAPABILITY_ROLLUP_MIN_ADCP_VERSION = "3.2";
572
+ const CAPABILITY_ROLLUP_MIN_3_1_PATCH = 24;
573
+ const STABLE_3_1_RELEASE_PATTERN = /^3\.1\.(\d+)$/;
574
+ function carriesApplicabilityOrderRule(adcpVersion) {
575
+ if (compareAdcpVersionStrings(adcpVersion, CAPABILITY_ROLLUP_MIN_ADCP_VERSION) >= 0) return true;
576
+ const patch = STABLE_3_1_RELEASE_PATTERN.exec(adcpVersion)?.[1];
577
+ return patch !== void 0 && Number.parseInt(patch, 10) >= CAPABILITY_ROLLUP_MIN_3_1_PATCH;
578
+ }
572
579
  const CAPABILITY_UNSUPPORTED_ROW_ID = "capability_unsupported";
573
580
  const CAPABILITY_UNSUPPORTED_RESULT_KEYS = /* @__PURE__ */ new Set([
574
581
  "storyboard_id",
@@ -616,8 +623,8 @@ function isCapabilityUnsupportedSkip(storyboard, result) {
616
623
  const predicates = (0, import_runner.storyboardCapabilityPredicates)(storyboard);
617
624
  if (predicates.length === 0) return false;
618
625
  if (typeof storyboard.adcp_version !== "string") return false;
619
- if (compareAdcpVersionStrings(storyboard.adcp_version, CAPABILITY_ROLLUP_MIN_ADCP_VERSION) < 0) return false;
620
- if (predicates.some((predicate) => capabilityPathSegments(predicate.path).includes("compliance_testing"))) {
626
+ if (!carriesApplicabilityOrderRule(storyboard.adcp_version)) return false;
627
+ if (predicates.flatMap(import_runner.capabilityPathPredicates).some((predicate) => capabilityPathSegments(predicate.path).includes("compliance_testing"))) {
621
628
  return false;
622
629
  }
623
630
  for (const key of Object.keys(result)) {
@@ -15,7 +15,8 @@ import {
15
15
  storyboardCapabilityGateUnmet,
16
16
  storyboardRequiresCapabilityEvidence,
17
17
  storyboardAllowsCapabilityDiagnostic,
18
- storyboardCapabilityPredicates
18
+ storyboardCapabilityPredicates,
19
+ capabilityPathPredicates
19
20
  } from "../storyboard/runner.mjs";
20
21
  import { applyNativeA2AComplianceTransportOptions } from "../storyboard/native-a2a-compliance.mjs";
21
22
  import { validateTestKit } from "../storyboard/test-kit.mjs";
@@ -562,6 +563,13 @@ const NEUTRAL_BUNDLE_SKIP_REASONS = /* @__PURE__ */ new Set([
562
563
  "capability_prerequisite_unavailable"
563
564
  ]);
564
565
  const CAPABILITY_ROLLUP_MIN_ADCP_VERSION = "3.2";
566
+ const CAPABILITY_ROLLUP_MIN_3_1_PATCH = 24;
567
+ const STABLE_3_1_RELEASE_PATTERN = /^3\.1\.(\d+)$/;
568
+ function carriesApplicabilityOrderRule(adcpVersion) {
569
+ if (compareAdcpVersionStrings(adcpVersion, CAPABILITY_ROLLUP_MIN_ADCP_VERSION) >= 0) return true;
570
+ const patch = STABLE_3_1_RELEASE_PATTERN.exec(adcpVersion)?.[1];
571
+ return patch !== void 0 && Number.parseInt(patch, 10) >= CAPABILITY_ROLLUP_MIN_3_1_PATCH;
572
+ }
565
573
  const CAPABILITY_UNSUPPORTED_ROW_ID = "capability_unsupported";
566
574
  const CAPABILITY_UNSUPPORTED_RESULT_KEYS = /* @__PURE__ */ new Set([
567
575
  "storyboard_id",
@@ -609,8 +617,8 @@ function isCapabilityUnsupportedSkip(storyboard, result) {
609
617
  const predicates = storyboardCapabilityPredicates(storyboard);
610
618
  if (predicates.length === 0) return false;
611
619
  if (typeof storyboard.adcp_version !== "string") return false;
612
- if (compareAdcpVersionStrings(storyboard.adcp_version, CAPABILITY_ROLLUP_MIN_ADCP_VERSION) < 0) return false;
613
- if (predicates.some((predicate) => capabilityPathSegments(predicate.path).includes("compliance_testing"))) {
620
+ if (!carriesApplicabilityOrderRule(storyboard.adcp_version)) return false;
621
+ if (predicates.flatMap(capabilityPathPredicates).some((predicate) => capabilityPathSegments(predicate.path).includes("compliance_testing"))) {
614
622
  return false;
615
623
  }
616
624
  for (const key of Object.keys(result)) {
@@ -17,7 +17,7 @@ export type { CapturedWebhook, CapturedWebhookChallenge, CreateWebhookReceiverOp
17
17
  export { createRunnerVariables } from './context.mjs';
18
18
  export type { RunnerVariables } from './context.mjs';
19
19
  export { WEBHOOK_ASSERTION_TASKS } from './webhook-assertions.mjs';
20
- export { prepareStoryboardFixtures, runStoryboard, runStoryboardStep, applyAdcpVersionRunOptions, applyStoryboardVersionOptions, getFirstStepPreview, summarizeStrictValidation, listStrictOnlyFailures, resolveCapabilityPath, evaluateCapabilityPredicate, describeStoryboardCapabilityGates, buildDiscoveryFailedResult, } from './runner.mjs';
20
+ export { prepareStoryboardFixtures, runStoryboard, runStoryboardStep, applyAdcpVersionRunOptions, applyStoryboardVersionOptions, getFirstStepPreview, summarizeStrictValidation, listStrictOnlyFailures, resolveCapabilityPath, evaluateCapabilityPredicate, evaluateCapabilityPredicateAgainstCapabilities, isAnyOfCapabilityPredicate, capabilityPathPredicates, describeStoryboardCapabilityGates, buildDiscoveryFailedResult, } from './runner.mjs';
21
21
  export { parseStoryboard, loadStoryboardFile, normalizeValidationOnlyTasks, VALIDATION_ONLY_TASK } from './loader.mjs';
22
22
  export { applyFixtureBindingsToRequest, buildFixtureResolutionSpecs, FixtureBindingRegistry, matchesFixtureRequirements, matchFixtureRequirementsWithWitness, normalizeFixtureContextOutputs, normalizeFixtureMatchExpression, validateFixtureResolutionDeclarations, } from './fixture-resolution.mjs';
23
23
  export type { FixtureContextOutput } from './types.mjs';
@@ -17,7 +17,7 @@ export type { CapturedWebhook, CapturedWebhookChallenge, CreateWebhookReceiverOp
17
17
  export { createRunnerVariables } from './context';
18
18
  export type { RunnerVariables } from './context';
19
19
  export { WEBHOOK_ASSERTION_TASKS } from './webhook-assertions';
20
- export { prepareStoryboardFixtures, runStoryboard, runStoryboardStep, applyAdcpVersionRunOptions, applyStoryboardVersionOptions, getFirstStepPreview, summarizeStrictValidation, listStrictOnlyFailures, resolveCapabilityPath, evaluateCapabilityPredicate, describeStoryboardCapabilityGates, buildDiscoveryFailedResult, } from './runner';
20
+ export { prepareStoryboardFixtures, runStoryboard, runStoryboardStep, applyAdcpVersionRunOptions, applyStoryboardVersionOptions, getFirstStepPreview, summarizeStrictValidation, listStrictOnlyFailures, resolveCapabilityPath, evaluateCapabilityPredicate, evaluateCapabilityPredicateAgainstCapabilities, isAnyOfCapabilityPredicate, capabilityPathPredicates, describeStoryboardCapabilityGates, buildDiscoveryFailedResult, } from './runner';
21
21
  export { parseStoryboard, loadStoryboardFile, normalizeValidationOnlyTasks, VALIDATION_ONLY_TASK } from './loader';
22
22
  export { applyFixtureBindingsToRequest, buildFixtureResolutionSpecs, FixtureBindingRegistry, matchesFixtureRequirements, matchFixtureRequirementsWithWitness, normalizeFixtureContextOutputs, normalizeFixtureMatchExpression, validateFixtureResolutionDeclarations, } from './fixture-resolution';
23
23
  export type { FixtureContextOutput } from './types';
@@ -56,6 +56,7 @@ __export(storyboard_exports, {
56
56
  buildFixtureResolutionSpecs: () => import_fixture_resolution.buildFixtureResolutionSpecs,
57
57
  buildProtectedResourceMetadataUrl: () => import_oauth_metadata_graph.buildProtectedResourceMetadataUrl,
58
58
  buildRequest: () => import_request_builder.buildRequest,
59
+ capabilityPathPredicates: () => import_runner.capabilityPathPredicates,
59
60
  clearAssertionRegistry: () => import_assertions.clearAssertionRegistry,
60
61
  clearSandboxCache: () => import_sandbox_entities.clearSandboxCache,
61
62
  compareCollectionPairs: () => import_collection_selection.compareCollectionPairs,
@@ -66,6 +67,7 @@ __export(storyboard_exports, {
66
67
  detectContextRejectionHints: () => import_rejection_hints.detectContextRejectionHints,
67
68
  diffCollectionPairSets: () => import_collection_selection.diffCollectionPairSets,
68
69
  evaluateCapabilityPredicate: () => import_runner.evaluateCapabilityPredicate,
70
+ evaluateCapabilityPredicateAgainstCapabilities: () => import_runner.evaluateCapabilityPredicateAgainstCapabilities,
69
71
  evaluateCollectionSelection: () => import_collection_selection.evaluateCollectionSelection,
70
72
  executeStoryboardTask: () => import_task_map.executeStoryboardTask,
71
73
  expandCreativeAssetDirectives: () => import_creative_assets.expandCreativeAssetDirectives,
@@ -87,6 +89,7 @@ __export(storyboard_exports, {
87
89
  gradeOAuthMetadataGraphVector: () => import_oauth_metadata_graph.gradeOAuthMetadataGraphVector,
88
90
  hasRequestBuilder: () => import_request_builder.hasRequestBuilder,
89
91
  injectContext: () => import_context2.injectContext,
92
+ isAnyOfCapabilityPredicate: () => import_runner.isAnyOfCapabilityPredicate,
90
93
  isComplianceVersionSupported: () => import_compliance.isComplianceVersionSupported,
91
94
  isProtectedContextKey: () => import_protected_context.isProtectedContextKey,
92
95
  isSandboxDomain: () => import_sandbox_entities.isSandboxDomain,
@@ -205,6 +208,7 @@ var import_creative_build_probe = require('./creative-build-probe.js');
205
208
  buildFixtureResolutionSpecs,
206
209
  buildProtectedResourceMetadataUrl,
207
210
  buildRequest,
211
+ capabilityPathPredicates,
208
212
  clearAssertionRegistry,
209
213
  clearSandboxCache,
210
214
  compareCollectionPairs,
@@ -215,6 +219,7 @@ var import_creative_build_probe = require('./creative-build-probe.js');
215
219
  detectContextRejectionHints,
216
220
  diffCollectionPairSets,
217
221
  evaluateCapabilityPredicate,
222
+ evaluateCapabilityPredicateAgainstCapabilities,
218
223
  evaluateCollectionSelection,
219
224
  executeStoryboardTask,
220
225
  expandCreativeAssetDirectives,
@@ -236,6 +241,7 @@ var import_creative_build_probe = require('./creative-build-probe.js');
236
241
  gradeOAuthMetadataGraphVector,
237
242
  hasRequestBuilder,
238
243
  injectContext,
244
+ isAnyOfCapabilityPredicate,
239
245
  isComplianceVersionSupported,
240
246
  isProtectedContextKey,
241
247
  isSandboxDomain,
@@ -25,6 +25,9 @@ import {
25
25
  listStrictOnlyFailures,
26
26
  resolveCapabilityPath,
27
27
  evaluateCapabilityPredicate,
28
+ evaluateCapabilityPredicateAgainstCapabilities,
29
+ isAnyOfCapabilityPredicate,
30
+ capabilityPathPredicates,
28
31
  describeStoryboardCapabilityGates,
29
32
  buildDiscoveryFailedResult
30
33
  } from "./runner.mjs";
@@ -161,6 +164,7 @@ export {
161
164
  buildFixtureResolutionSpecs,
162
165
  buildProtectedResourceMetadataUrl,
163
166
  buildRequest,
167
+ capabilityPathPredicates,
164
168
  clearAssertionRegistry,
165
169
  clearSandboxCache,
166
170
  compareCollectionPairs,
@@ -171,6 +175,7 @@ export {
171
175
  detectContextRejectionHints,
172
176
  diffCollectionPairSets,
173
177
  evaluateCapabilityPredicate,
178
+ evaluateCapabilityPredicateAgainstCapabilities,
174
179
  evaluateCollectionSelection,
175
180
  executeStoryboardTask,
176
181
  expandCreativeAssetDirectives,
@@ -192,6 +197,7 @@ export {
192
197
  gradeOAuthMetadataGraphVector,
193
198
  hasRequestBuilder,
194
199
  injectContext,
200
+ isAnyOfCapabilityPredicate,
195
201
  isComplianceVersionSupported,
196
202
  isProtectedContextKey,
197
203
  isSandboxDomain,
@@ -187,6 +187,10 @@ function validatePhaseSkipIf(storyboardId, phase) {
187
187
  }
188
188
  }
189
189
  function validateRequiresAllCapabilities(storyboard) {
190
+ validateAnyOfGate(storyboard.requires_capability, `[${storyboard.id}] requires_capability`);
191
+ for (const phase of storyboard.phases ?? []) {
192
+ validateAnyOfGate(phase.requires_capability, `[${storyboard.id}] phase '${phase.id}': requires_capability`);
193
+ }
190
194
  const predicates = storyboard.requires_all_capabilities;
191
195
  if (predicates === void 0) return;
192
196
  if (!Array.isArray(predicates) || predicates.length < 2) {
@@ -195,37 +199,57 @@ function validateRequiresAllCapabilities(storyboard) {
195
199
  );
196
200
  }
197
201
  for (let index = 0; index < predicates.length; index++) {
198
- const raw = predicates[index];
199
- const prefix = `[${storyboard.id}] requires_all_capabilities[${index}]`;
200
- if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
201
- throw new Error(`${prefix}: must be a capability predicate object`);
202
- }
203
- const predicate = raw;
204
- if (typeof predicate.path !== "string" || predicate.path.trim().length === 0) {
205
- throw new Error(`${prefix}.path: must be a non-empty string`);
206
- }
207
- if (!CAPABILITY_PATH_PATTERN.test(predicate.path)) {
208
- throw new Error(`${prefix}.path: must be a canonical dotted capability path`);
209
- }
210
- const matcherKeys = ["equals", "present", "contains", "not_contains"].filter(
211
- (key) => Object.prototype.hasOwnProperty.call(predicate, key)
212
- );
213
- if (matcherKeys.length !== 1) {
214
- throw new Error(`${prefix}: must declare exactly one of equals, present, contains, or not_contains`);
215
- }
216
- const unknownKeys = Object.keys(predicate).filter((key) => key !== "path" && !matcherKeys.includes(key));
217
- if (unknownKeys.length > 0) {
218
- throw new Error(`${prefix}: unknown field${unknownKeys.length === 1 ? "" : "s"} ${unknownKeys.join(", ")}`);
219
- }
220
- if (matcherKeys[0] === "present" && typeof predicate.present !== "boolean") {
221
- throw new Error(`${prefix}.present: must be a boolean`);
202
+ validateCapabilityPredicateShape(predicates[index], `[${storyboard.id}] requires_all_capabilities[${index}]`);
203
+ }
204
+ }
205
+ function validateAnyOfGate(raw, prefix) {
206
+ if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return;
207
+ if (!Object.prototype.hasOwnProperty.call(raw, "any_of")) return;
208
+ validateCapabilityPredicateShape(raw, prefix);
209
+ }
210
+ function validateCapabilityPredicateShape(raw, prefix) {
211
+ if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
212
+ throw new Error(`${prefix}: must be a capability predicate object`);
213
+ }
214
+ const predicate = raw;
215
+ if (Object.prototype.hasOwnProperty.call(predicate, "any_of")) {
216
+ const unknownKeys2 = Object.keys(predicate).filter((key) => key !== "any_of");
217
+ if (unknownKeys2.length > 0) {
218
+ throw new Error(`${prefix}: any_of cannot be combined with ${unknownKeys2.join(", ")}`);
222
219
  }
223
- if (matcherKeys[0] === "equals" && predicate.equals !== null && !["boolean", "string", "number"].includes(typeof predicate.equals)) {
224
- throw new Error(`${prefix}.equals: must be a boolean, string, number, or null`);
220
+ const entries = predicate.any_of;
221
+ if (!Array.isArray(entries) || entries.length < 2) {
222
+ throw new Error(`${prefix}.any_of: must list at least two predicates`);
225
223
  }
226
- if ((matcherKeys[0] === "contains" || matcherKeys[0] === "not_contains") && !isJsonCapabilityValue(predicate[matcherKeys[0]])) {
227
- throw new Error(`${prefix}.${matcherKeys[0]}: must be a JSON-compatible capability value`);
224
+ for (let index = 0; index < entries.length; index++) {
225
+ validateCapabilityPredicateShape(entries[index], `${prefix}.any_of[${index}]`);
228
226
  }
227
+ return;
228
+ }
229
+ if (typeof predicate.path !== "string" || predicate.path.trim().length === 0) {
230
+ throw new Error(`${prefix}.path: must be a non-empty string`);
231
+ }
232
+ if (!CAPABILITY_PATH_PATTERN.test(predicate.path)) {
233
+ throw new Error(`${prefix}.path: must be a canonical dotted capability path`);
234
+ }
235
+ const matcherKeys = ["equals", "present", "contains", "not_contains"].filter(
236
+ (key) => Object.prototype.hasOwnProperty.call(predicate, key)
237
+ );
238
+ if (matcherKeys.length !== 1) {
239
+ throw new Error(`${prefix}: must declare exactly one of equals, present, contains, or not_contains`);
240
+ }
241
+ const unknownKeys = Object.keys(predicate).filter((key) => key !== "path" && !matcherKeys.includes(key));
242
+ if (unknownKeys.length > 0) {
243
+ throw new Error(`${prefix}: unknown field${unknownKeys.length === 1 ? "" : "s"} ${unknownKeys.join(", ")}`);
244
+ }
245
+ if (matcherKeys[0] === "present" && typeof predicate.present !== "boolean") {
246
+ throw new Error(`${prefix}.present: must be a boolean`);
247
+ }
248
+ if (matcherKeys[0] === "equals" && predicate.equals !== null && !["boolean", "string", "number"].includes(typeof predicate.equals)) {
249
+ throw new Error(`${prefix}.equals: must be a boolean, string, number, or null`);
250
+ }
251
+ if ((matcherKeys[0] === "contains" || matcherKeys[0] === "not_contains") && !isJsonCapabilityValue(predicate[matcherKeys[0]])) {
252
+ throw new Error(`${prefix}.${matcherKeys[0]}: must be a JSON-compatible capability value`);
229
253
  }
230
254
  }
231
255
  function isJsonCapabilityValue(value, seen = /* @__PURE__ */ new Set()) {
@@ -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