@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
@@ -15,7 +15,8 @@ import type { AcceptancePolicyRegistryResolver } from '../../acceptance-policy';
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;
@@ -200,7 +200,7 @@ export interface UpstreamTrafficQueryResult {
200
200
  */
201
201
  export declare function runValidations(validations: StoryboardValidation[], context: ValidationContext): ValidationResult[];
202
202
  /** Capability semver emitted in run summaries and used for advisory expiry. */
203
- export declare const RUNNER_CAPABILITY_VERSION = "17.0.0-beta.25";
203
+ export declare const RUNNER_CAPABILITY_VERSION = "17.0.0-beta.26";
204
204
  /** True when a failed validation contributes to the owning step's grade. */
205
205
  export declare function validationFailsStep(result: ValidationResult): boolean;
206
206
  /**
@@ -200,7 +200,7 @@ export interface UpstreamTrafficQueryResult {
200
200
  */
201
201
  export declare function runValidations(validations: StoryboardValidation[], context: ValidationContext): ValidationResult[];
202
202
  /** Capability semver emitted in run summaries and used for advisory expiry. */
203
- export declare const RUNNER_CAPABILITY_VERSION = "17.0.0-beta.25";
203
+ export declare const RUNNER_CAPABILITY_VERSION = "17.0.0-beta.26";
204
204
  /** True when a failed validation contributes to the owning step's grade. */
205
205
  export declare function validationFailsStep(result: ValidationResult): boolean;
206
206
  /**
@@ -954,8 +954,8 @@ export declare const BrandJsonSchema: z.ZodUnion<readonly [z.ZodObject<{
954
954
  surface: z.ZodOptional<z.ZodEnum<{
955
955
  text: "text";
956
956
  icon: "icon";
957
- cta: "cta";
958
957
  accent: "accent";
958
+ cta: "cta";
959
959
  background: "background";
960
960
  border: "border";
961
961
  foreground: "foreground";
@@ -972,8 +972,8 @@ export declare const BrandJsonSchema: z.ZodUnion<readonly [z.ZodObject<{
972
972
  applies_to: z.ZodOptional<z.ZodArray<z.ZodEnum<{
973
973
  text: "text";
974
974
  icon: "icon";
975
- cta: "cta";
976
975
  accent: "accent";
976
+ cta: "cta";
977
977
  background: "background";
978
978
  border: "border";
979
979
  foreground: "foreground";
@@ -991,8 +991,8 @@ export declare const BrandJsonSchema: z.ZodUnion<readonly [z.ZodObject<{
991
991
  surface: z.ZodOptional<z.ZodEnum<{
992
992
  text: "text";
993
993
  icon: "icon";
994
- cta: "cta";
995
994
  accent: "accent";
995
+ cta: "cta";
996
996
  background: "background";
997
997
  border: "border";
998
998
  foreground: "foreground";
@@ -1017,8 +1017,8 @@ export declare const BrandJsonSchema: z.ZodUnion<readonly [z.ZodObject<{
1017
1017
  surface: z.ZodOptional<z.ZodEnum<{
1018
1018
  text: "text";
1019
1019
  icon: "icon";
1020
- cta: "cta";
1021
1020
  accent: "accent";
1021
+ cta: "cta";
1022
1022
  background: "background";
1023
1023
  border: "border";
1024
1024
  foreground: "foreground";
@@ -1043,8 +1043,8 @@ export declare const BrandJsonSchema: z.ZodUnion<readonly [z.ZodObject<{
1043
1043
  surface: z.ZodOptional<z.ZodEnum<{
1044
1044
  text: "text";
1045
1045
  icon: "icon";
1046
- cta: "cta";
1047
1046
  accent: "accent";
1047
+ cta: "cta";
1048
1048
  background: "background";
1049
1049
  border: "border";
1050
1050
  foreground: "foreground";
@@ -1108,8 +1108,8 @@ export declare const BrandJsonSchema: z.ZodUnion<readonly [z.ZodObject<{
1108
1108
  surface: z.ZodOptional<z.ZodEnum<{
1109
1109
  text: "text";
1110
1110
  icon: "icon";
1111
- cta: "cta";
1112
1111
  accent: "accent";
1112
+ cta: "cta";
1113
1113
  background: "background";
1114
1114
  border: "border";
1115
1115
  foreground: "foreground";
@@ -1134,8 +1134,8 @@ export declare const BrandJsonSchema: z.ZodUnion<readonly [z.ZodObject<{
1134
1134
  surface: z.ZodOptional<z.ZodEnum<{
1135
1135
  text: "text";
1136
1136
  icon: "icon";
1137
- cta: "cta";
1138
1137
  accent: "accent";
1138
+ cta: "cta";
1139
1139
  background: "background";
1140
1140
  border: "border";
1141
1141
  foreground: "foreground";
@@ -1193,8 +1193,8 @@ export declare const BrandJsonSchema: z.ZodUnion<readonly [z.ZodObject<{
1193
1193
  surface: z.ZodOptional<z.ZodEnum<{
1194
1194
  text: "text";
1195
1195
  icon: "icon";
1196
- cta: "cta";
1197
1196
  accent: "accent";
1197
+ cta: "cta";
1198
1198
  background: "background";
1199
1199
  border: "border";
1200
1200
  foreground: "foreground";
@@ -2121,8 +2121,8 @@ export declare const BrandJsonSchema: z.ZodUnion<readonly [z.ZodObject<{
2121
2121
  surface: z.ZodOptional<z.ZodEnum<{
2122
2122
  text: "text";
2123
2123
  icon: "icon";
2124
- cta: "cta";
2125
2124
  accent: "accent";
2125
+ cta: "cta";
2126
2126
  background: "background";
2127
2127
  border: "border";
2128
2128
  foreground: "foreground";
@@ -2139,8 +2139,8 @@ export declare const BrandJsonSchema: z.ZodUnion<readonly [z.ZodObject<{
2139
2139
  applies_to: z.ZodOptional<z.ZodArray<z.ZodEnum<{
2140
2140
  text: "text";
2141
2141
  icon: "icon";
2142
- cta: "cta";
2143
2142
  accent: "accent";
2143
+ cta: "cta";
2144
2144
  background: "background";
2145
2145
  border: "border";
2146
2146
  foreground: "foreground";
@@ -2158,8 +2158,8 @@ export declare const BrandJsonSchema: z.ZodUnion<readonly [z.ZodObject<{
2158
2158
  surface: z.ZodOptional<z.ZodEnum<{
2159
2159
  text: "text";
2160
2160
  icon: "icon";
2161
- cta: "cta";
2162
2161
  accent: "accent";
2162
+ cta: "cta";
2163
2163
  background: "background";
2164
2164
  border: "border";
2165
2165
  foreground: "foreground";
@@ -2184,8 +2184,8 @@ export declare const BrandJsonSchema: z.ZodUnion<readonly [z.ZodObject<{
2184
2184
  surface: z.ZodOptional<z.ZodEnum<{
2185
2185
  text: "text";
2186
2186
  icon: "icon";
2187
- cta: "cta";
2188
2187
  accent: "accent";
2188
+ cta: "cta";
2189
2189
  background: "background";
2190
2190
  border: "border";
2191
2191
  foreground: "foreground";
@@ -2210,8 +2210,8 @@ export declare const BrandJsonSchema: z.ZodUnion<readonly [z.ZodObject<{
2210
2210
  surface: z.ZodOptional<z.ZodEnum<{
2211
2211
  text: "text";
2212
2212
  icon: "icon";
2213
- cta: "cta";
2214
2213
  accent: "accent";
2214
+ cta: "cta";
2215
2215
  background: "background";
2216
2216
  border: "border";
2217
2217
  foreground: "foreground";
@@ -2275,8 +2275,8 @@ export declare const BrandJsonSchema: z.ZodUnion<readonly [z.ZodObject<{
2275
2275
  surface: z.ZodOptional<z.ZodEnum<{
2276
2276
  text: "text";
2277
2277
  icon: "icon";
2278
- cta: "cta";
2279
2278
  accent: "accent";
2279
+ cta: "cta";
2280
2280
  background: "background";
2281
2281
  border: "border";
2282
2282
  foreground: "foreground";
@@ -2301,8 +2301,8 @@ export declare const BrandJsonSchema: z.ZodUnion<readonly [z.ZodObject<{
2301
2301
  surface: z.ZodOptional<z.ZodEnum<{
2302
2302
  text: "text";
2303
2303
  icon: "icon";
2304
- cta: "cta";
2305
2304
  accent: "accent";
2305
+ cta: "cta";
2306
2306
  background: "background";
2307
2307
  border: "border";
2308
2308
  foreground: "foreground";
@@ -2360,8 +2360,8 @@ export declare const BrandJsonSchema: z.ZodUnion<readonly [z.ZodObject<{
2360
2360
  surface: z.ZodOptional<z.ZodEnum<{
2361
2361
  text: "text";
2362
2362
  icon: "icon";
2363
- cta: "cta";
2364
2363
  accent: "accent";
2364
+ cta: "cta";
2365
2365
  background: "background";
2366
2366
  border: "border";
2367
2367
  foreground: "foreground";
@@ -954,8 +954,8 @@ export declare const BrandJsonSchema: z.ZodUnion<readonly [z.ZodObject<{
954
954
  surface: z.ZodOptional<z.ZodEnum<{
955
955
  text: "text";
956
956
  icon: "icon";
957
- cta: "cta";
958
957
  accent: "accent";
958
+ cta: "cta";
959
959
  background: "background";
960
960
  border: "border";
961
961
  foreground: "foreground";
@@ -972,8 +972,8 @@ export declare const BrandJsonSchema: z.ZodUnion<readonly [z.ZodObject<{
972
972
  applies_to: z.ZodOptional<z.ZodArray<z.ZodEnum<{
973
973
  text: "text";
974
974
  icon: "icon";
975
- cta: "cta";
976
975
  accent: "accent";
976
+ cta: "cta";
977
977
  background: "background";
978
978
  border: "border";
979
979
  foreground: "foreground";
@@ -991,8 +991,8 @@ export declare const BrandJsonSchema: z.ZodUnion<readonly [z.ZodObject<{
991
991
  surface: z.ZodOptional<z.ZodEnum<{
992
992
  text: "text";
993
993
  icon: "icon";
994
- cta: "cta";
995
994
  accent: "accent";
995
+ cta: "cta";
996
996
  background: "background";
997
997
  border: "border";
998
998
  foreground: "foreground";
@@ -1017,8 +1017,8 @@ export declare const BrandJsonSchema: z.ZodUnion<readonly [z.ZodObject<{
1017
1017
  surface: z.ZodOptional<z.ZodEnum<{
1018
1018
  text: "text";
1019
1019
  icon: "icon";
1020
- cta: "cta";
1021
1020
  accent: "accent";
1021
+ cta: "cta";
1022
1022
  background: "background";
1023
1023
  border: "border";
1024
1024
  foreground: "foreground";
@@ -1043,8 +1043,8 @@ export declare const BrandJsonSchema: z.ZodUnion<readonly [z.ZodObject<{
1043
1043
  surface: z.ZodOptional<z.ZodEnum<{
1044
1044
  text: "text";
1045
1045
  icon: "icon";
1046
- cta: "cta";
1047
1046
  accent: "accent";
1047
+ cta: "cta";
1048
1048
  background: "background";
1049
1049
  border: "border";
1050
1050
  foreground: "foreground";
@@ -1108,8 +1108,8 @@ export declare const BrandJsonSchema: z.ZodUnion<readonly [z.ZodObject<{
1108
1108
  surface: z.ZodOptional<z.ZodEnum<{
1109
1109
  text: "text";
1110
1110
  icon: "icon";
1111
- cta: "cta";
1112
1111
  accent: "accent";
1112
+ cta: "cta";
1113
1113
  background: "background";
1114
1114
  border: "border";
1115
1115
  foreground: "foreground";
@@ -1134,8 +1134,8 @@ export declare const BrandJsonSchema: z.ZodUnion<readonly [z.ZodObject<{
1134
1134
  surface: z.ZodOptional<z.ZodEnum<{
1135
1135
  text: "text";
1136
1136
  icon: "icon";
1137
- cta: "cta";
1138
1137
  accent: "accent";
1138
+ cta: "cta";
1139
1139
  background: "background";
1140
1140
  border: "border";
1141
1141
  foreground: "foreground";
@@ -1193,8 +1193,8 @@ export declare const BrandJsonSchema: z.ZodUnion<readonly [z.ZodObject<{
1193
1193
  surface: z.ZodOptional<z.ZodEnum<{
1194
1194
  text: "text";
1195
1195
  icon: "icon";
1196
- cta: "cta";
1197
1196
  accent: "accent";
1197
+ cta: "cta";
1198
1198
  background: "background";
1199
1199
  border: "border";
1200
1200
  foreground: "foreground";
@@ -2121,8 +2121,8 @@ export declare const BrandJsonSchema: z.ZodUnion<readonly [z.ZodObject<{
2121
2121
  surface: z.ZodOptional<z.ZodEnum<{
2122
2122
  text: "text";
2123
2123
  icon: "icon";
2124
- cta: "cta";
2125
2124
  accent: "accent";
2125
+ cta: "cta";
2126
2126
  background: "background";
2127
2127
  border: "border";
2128
2128
  foreground: "foreground";
@@ -2139,8 +2139,8 @@ export declare const BrandJsonSchema: z.ZodUnion<readonly [z.ZodObject<{
2139
2139
  applies_to: z.ZodOptional<z.ZodArray<z.ZodEnum<{
2140
2140
  text: "text";
2141
2141
  icon: "icon";
2142
- cta: "cta";
2143
2142
  accent: "accent";
2143
+ cta: "cta";
2144
2144
  background: "background";
2145
2145
  border: "border";
2146
2146
  foreground: "foreground";
@@ -2158,8 +2158,8 @@ export declare const BrandJsonSchema: z.ZodUnion<readonly [z.ZodObject<{
2158
2158
  surface: z.ZodOptional<z.ZodEnum<{
2159
2159
  text: "text";
2160
2160
  icon: "icon";
2161
- cta: "cta";
2162
2161
  accent: "accent";
2162
+ cta: "cta";
2163
2163
  background: "background";
2164
2164
  border: "border";
2165
2165
  foreground: "foreground";
@@ -2184,8 +2184,8 @@ export declare const BrandJsonSchema: z.ZodUnion<readonly [z.ZodObject<{
2184
2184
  surface: z.ZodOptional<z.ZodEnum<{
2185
2185
  text: "text";
2186
2186
  icon: "icon";
2187
- cta: "cta";
2188
2187
  accent: "accent";
2188
+ cta: "cta";
2189
2189
  background: "background";
2190
2190
  border: "border";
2191
2191
  foreground: "foreground";
@@ -2210,8 +2210,8 @@ export declare const BrandJsonSchema: z.ZodUnion<readonly [z.ZodObject<{
2210
2210
  surface: z.ZodOptional<z.ZodEnum<{
2211
2211
  text: "text";
2212
2212
  icon: "icon";
2213
- cta: "cta";
2214
2213
  accent: "accent";
2214
+ cta: "cta";
2215
2215
  background: "background";
2216
2216
  border: "border";
2217
2217
  foreground: "foreground";
@@ -2275,8 +2275,8 @@ export declare const BrandJsonSchema: z.ZodUnion<readonly [z.ZodObject<{
2275
2275
  surface: z.ZodOptional<z.ZodEnum<{
2276
2276
  text: "text";
2277
2277
  icon: "icon";
2278
- cta: "cta";
2279
2278
  accent: "accent";
2279
+ cta: "cta";
2280
2280
  background: "background";
2281
2281
  border: "border";
2282
2282
  foreground: "foreground";
@@ -2301,8 +2301,8 @@ export declare const BrandJsonSchema: z.ZodUnion<readonly [z.ZodObject<{
2301
2301
  surface: z.ZodOptional<z.ZodEnum<{
2302
2302
  text: "text";
2303
2303
  icon: "icon";
2304
- cta: "cta";
2305
2304
  accent: "accent";
2305
+ cta: "cta";
2306
2306
  background: "background";
2307
2307
  border: "border";
2308
2308
  foreground: "foreground";
@@ -2360,8 +2360,8 @@ export declare const BrandJsonSchema: z.ZodUnion<readonly [z.ZodObject<{
2360
2360
  surface: z.ZodOptional<z.ZodEnum<{
2361
2361
  text: "text";
2362
2362
  icon: "icon";
2363
- cta: "cta";
2364
2363
  accent: "accent";
2364
+ cta: "cta";
2365
2365
  background: "background";
2366
2366
  border: "border";
2367
2367
  foreground: "foreground";
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * AdCP SDK library version
3
3
  */
4
- export declare const LIBRARY_VERSION = "17.0.0-beta.25";
4
+ export declare const LIBRARY_VERSION = "17.0.0-beta.26";
5
5
  /**
6
6
  * AdCP specification version this library is built for
7
7
  */
@@ -33,10 +33,10 @@ export type AdcpVersion = (typeof COMPATIBLE_ADCP_VERSIONS)[number];
33
33
  * Full version information
34
34
  */
35
35
  export declare const VERSION_INFO: {
36
- readonly library: "17.0.0-beta.25";
36
+ readonly library: "17.0.0-beta.26";
37
37
  readonly adcp: "3.3.0-beta.6";
38
38
  readonly compatibleVersions: readonly ["v3", "3.0.0", "3.0", "3.0.1", "3.0.2", "3.0.3", "3.0.4", "3.0.5", "3.0.6", "3.0.7", "3.0.8", "3.0.9", "3.0.10", "3.0.11", "3.0.12", "3.0.13", "3.0.14", "3.0.15", "3.0.16", "3.0.17", "3.0.18", "3.0.19", "3.0.20", "3.0.21", "3.0.22", "3.0.23", "3.0.24", "3.0.25", "3.1.0", "3.1", "3.1.1", "3.1.2", "3.1.3", "3.1.4", "3.1.5", "3.1.6", "3.1.7", "3.1.8", "3.1.9", "3.1.10", "3.1.11", "3.1.12", "3.1.13", "3.1.14", "3.1.15", "3.1.16", "3.1.17", "3.1.18", "3.1.19", "3.1.20", "3.1.21", "3.1.22", "3.1.23", "3.1.24", "3.1.25", "3.1.26", "3.1.27", "3.1.28", "3.1.29", "3.1.30", "3.1.31", "3.2.1", "3.2", "3.2.2", "3.2.3", "3.2.4", "3.2.5", "3.2.6", "3.2.7", "3.2.8", "3.3.0-beta.6", "3.3-beta.6"];
39
- readonly generatedAt: "2026-11-14T01:28:39.866Z";
39
+ readonly generatedAt: "2026-11-14T15:52:16.390Z";
40
40
  };
41
41
  /**
42
42
  * Get the AdCP specification version this library is built for
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * AdCP SDK library version
3
3
  */
4
- export declare const LIBRARY_VERSION = "17.0.0-beta.25";
4
+ export declare const LIBRARY_VERSION = "17.0.0-beta.26";
5
5
  /**
6
6
  * AdCP specification version this library is built for
7
7
  */
@@ -33,10 +33,10 @@ export type AdcpVersion = (typeof COMPATIBLE_ADCP_VERSIONS)[number];
33
33
  * Full version information
34
34
  */
35
35
  export declare const VERSION_INFO: {
36
- readonly library: "17.0.0-beta.25";
36
+ readonly library: "17.0.0-beta.26";
37
37
  readonly adcp: "3.3.0-beta.6";
38
38
  readonly compatibleVersions: readonly ["v3", "3.0.0", "3.0", "3.0.1", "3.0.2", "3.0.3", "3.0.4", "3.0.5", "3.0.6", "3.0.7", "3.0.8", "3.0.9", "3.0.10", "3.0.11", "3.0.12", "3.0.13", "3.0.14", "3.0.15", "3.0.16", "3.0.17", "3.0.18", "3.0.19", "3.0.20", "3.0.21", "3.0.22", "3.0.23", "3.0.24", "3.0.25", "3.1.0", "3.1", "3.1.1", "3.1.2", "3.1.3", "3.1.4", "3.1.5", "3.1.6", "3.1.7", "3.1.8", "3.1.9", "3.1.10", "3.1.11", "3.1.12", "3.1.13", "3.1.14", "3.1.15", "3.1.16", "3.1.17", "3.1.18", "3.1.19", "3.1.20", "3.1.21", "3.1.22", "3.1.23", "3.1.24", "3.1.25", "3.1.26", "3.1.27", "3.1.28", "3.1.29", "3.1.30", "3.1.31", "3.2.1", "3.2", "3.2.2", "3.2.3", "3.2.4", "3.2.5", "3.2.6", "3.2.7", "3.2.8", "3.3.0-beta.6", "3.3-beta.6"];
39
- readonly generatedAt: "2026-11-14T01:28:39.866Z";
39
+ readonly generatedAt: "2026-11-14T15:52:16.390Z";
40
40
  };
41
41
  /**
42
42
  * Get the AdCP specification version this library is built for
@@ -31,7 +31,7 @@ __export(version_exports, {
31
31
  toReleasePrecisionVersion: () => toReleasePrecisionVersion
32
32
  });
33
33
  module.exports = __toCommonJS(version_exports);
34
- const LIBRARY_VERSION = "17.0.0-beta.25";
34
+ const LIBRARY_VERSION = "17.0.0-beta.26";
35
35
  const ADCP_VERSION = "3.3.0-beta.6";
36
36
  const ADCP_MAJOR_VERSION = 3;
37
37
  const COMPATIBLE_ADCP_VERSIONS = [
@@ -109,10 +109,10 @@ const COMPATIBLE_ADCP_VERSIONS = [
109
109
  "3.3-beta.6"
110
110
  ];
111
111
  const VERSION_INFO = {
112
- library: "17.0.0-beta.25",
112
+ library: "17.0.0-beta.26",
113
113
  adcp: "3.3.0-beta.6",
114
114
  compatibleVersions: COMPATIBLE_ADCP_VERSIONS,
115
- generatedAt: "2026-11-14T01:28:39.866Z"
115
+ generatedAt: "2026-11-14T15:52:16.390Z"
116
116
  };
117
117
  function getAdcpVersion() {
118
118
  return ADCP_VERSION;
@@ -1,4 +1,4 @@
1
- const LIBRARY_VERSION = "17.0.0-beta.25";
1
+ const LIBRARY_VERSION = "17.0.0-beta.26";
2
2
  const ADCP_VERSION = "3.3.0-beta.6";
3
3
  const ADCP_MAJOR_VERSION = 3;
4
4
  const COMPATIBLE_ADCP_VERSIONS = [
@@ -76,10 +76,10 @@ const COMPATIBLE_ADCP_VERSIONS = [
76
76
  "3.3-beta.6"
77
77
  ];
78
78
  const VERSION_INFO = {
79
- library: "17.0.0-beta.25",
79
+ library: "17.0.0-beta.26",
80
80
  adcp: "3.3.0-beta.6",
81
81
  compatibleVersions: COMPATIBLE_ADCP_VERSIONS,
82
- generatedAt: "2026-11-14T01:28:39.866Z"
82
+ generatedAt: "2026-11-14T15:52:16.390Z"
83
83
  };
84
84
  function getAdcpVersion() {
85
85
  return ADCP_VERSION;
@@ -1,7 +1,7 @@
1
1
  # AdCP Type Summary
2
2
 
3
3
  > Generated at: 2026-11-14
4
- > @adcp/sdk v17.0.0-beta.25
4
+ > @adcp/sdk v17.0.0-beta.26
5
5
 
6
6
  Curated reference of the types that matter for using the AdCP client. For full generated types see `src/lib/types/tools.generated.ts` and `src/lib/types/core.generated.ts`.
7
7
 
@@ -0,0 +1,96 @@
1
+ # Storyboard capability gates
2
+
3
+ A storyboard, or one of its phases, can declare which capabilities an agent
4
+ must advertise in `get_adcp_capabilities` for it to apply. When the agent does
5
+ not satisfy the gate, the runner grades the storyboard or phase
6
+ `not_applicable` instead of running it. This page lists the gate forms the
7
+ `@adcp/sdk` runner understands. `Storyboard.requires_capability` in
8
+ `src/lib/testing/storyboard/types.ts` holds the normative detail.
9
+
10
+ ## Where gates go
11
+
12
+ | Field | Scope | Composition |
13
+ | -------------------------------------- | --------------- | -------------------------------------------------- |
14
+ | `requires_capability` | storyboard root | one predicate |
15
+ | `requires_all_capabilities` | storyboard root | two or more predicates, all must pass; fail closed |
16
+ | `phases[].requires_capability` | one phase | one predicate; a skipped phase grades its steps `not_applicable` |
17
+
18
+ A predicate is either a path predicate or an `any_of` group.
19
+
20
+ ## Path predicates
21
+
22
+ `path` is a dotted path into the raw `get_adcp_capabilities` response. Each
23
+ path predicate declares exactly one matcher.
24
+
25
+ | Matcher | Passes when |
26
+ | ------------------ | ------------------------------------------------------------------------------ |
27
+ | `equals: V` | the value is declared and equals `V` |
28
+ | `present: true` | the value is present (not `undefined` or `null`) |
29
+ | `present: false` | the value is absent |
30
+ | `contains: V` | the value is an array with an entry that matches `V` |
31
+ | `not_contains: V` | the value is an array with no entry that matches `V` |
32
+
33
+ An array entry matches `V` by structural JSON equality when `V` is a scalar or
34
+ an array. When `V` is an object, an entry matches when it is an object that
35
+ carries every key of `V` with an equal value. The entry may carry other keys.
36
+ Activation-method entries are open objects, so
37
+ `contains: { pattern: sync_audiences }` matches
38
+ `{ pattern: "sync_audiences", note: "crm only" }`.
39
+
40
+ `equals`, `contains` and `not_contains` resolve a schema default for an absent
41
+ path when the parent object is present. `present` never does, because absence
42
+ is what it tests.
43
+
44
+ ## `any_of` groups
45
+
46
+ An `any_of` group lists two or more predicates, each a path predicate or a
47
+ nested `any_of` group. The group passes when at least one entry passes. It
48
+ cannot be combined with `path` or a matcher on the same object. It can appear
49
+ anywhere a predicate can, including as an entry of `requires_all_capabilities`.
50
+
51
+ This phase runs only for a seller that accepts inline audience member pushes:
52
+ `supported_activation_methods` is absent, as in 3.2, or it lists an entry
53
+ whose `pattern` is `sync_audiences`.
54
+
55
+ ```yaml
56
+ phases:
57
+ - id: audience_binding
58
+ requires_capability:
59
+ any_of:
60
+ - path: media_buy.audience_targeting.supported_activation_methods
61
+ present: false
62
+ - path: media_buy.audience_targeting.supported_activation_methods
63
+ contains: { pattern: sync_audiences }
64
+ ```
65
+
66
+ When no entry passes, the skip detail names every alternative and why it
67
+ failed.
68
+
69
+ ## Without raw capabilities
70
+
71
+ When the runner has no raw capabilities payload, it falls back the same way
72
+ for each path predicate, including each entry of an `any_of` group:
73
+
74
+ - `equals` gates skip when the agent does not advertise `get_adcp_capabilities`.
75
+ - Other matchers pass, except for the raw opt-ins `oauth.supported equals true`
76
+ and `experimental_features contains trusted_match.core`.
77
+ - `requires_all_capabilities` fails closed: every predicate in it skips.
78
+
79
+ ## Runner support
80
+
81
+ `any_of` groups and object-subset `contains` / `not_contains` ship in
82
+ `@adcp/sdk` releases after `17.0.0-beta.25`. Older runners keep working with
83
+ older bundles, which do not use either form. A bundle that uses them needs a
84
+ runner that supports them:
85
+
86
+ - **`any_of` on an older runner.** The predicate has no `path`. With raw
87
+ capabilities available, the runner throws while resolving the missing path,
88
+ so the storyboard errors instead of being graded. Without raw capabilities,
89
+ it treats the gate as satisfied and runs the phase or storyboard.
90
+ - **Object-subset `contains` on an older runner.** Objects match only by exact
91
+ structural equality, so an entry with extra keys does not match and the gate
92
+ skips more often than intended.
93
+
94
+ The runner's loader validates every `any_of` group, and every
95
+ `requires_all_capabilities` entry, when it loads a storyboard. Legacy singular
96
+ path gates keep their historical, unvalidated loading.
@@ -78,6 +78,11 @@ npx @adcp/sdk@15.9 storyboard run http://localhost:3001/mcp --file ./my-wip.yaml
78
78
  npx @adcp/sdk@15.9 storyboard run http://localhost:3001/mcp --json > report.json
79
79
  ```
80
80
 
81
+ Writing a storyboard that applies only to agents declaring a capability? See
82
+ [STORYBOARD-CAPABILITY-GATES.md](./STORYBOARD-CAPABILITY-GATES.md) for the
83
+ `requires_capability` matchers, `any_of` groups and how older runners treat
84
+ them.
85
+
81
86
  For a publisher split across sales, signals, governance, or creative tenants,
82
87
  provide an agents map and omit the storyboard ID to assess the whole topology:
83
88
 
package/docs/llms.txt CHANGED
@@ -1,7 +1,7 @@
1
1
  # Ad Context Protocol (AdCP)
2
2
 
3
3
  > Generated at: 2026-11-14
4
- > Library: @adcp/sdk v17.0.0-beta.25
4
+ > Library: @adcp/sdk v17.0.0-beta.26
5
5
  > AdCP major version: 3
6
6
  > Canonical URL: https://adcontextprotocol.github.io/adcp-client/llms.txt
7
7
  > Note: the `Library` stamp reflects the package.json version at doc-generation time. The narrative below describes the surface that lands on the next-published minor — including any 6.7 helpers documented here ahead of the release tag.