@adcp/sdk 17.0.0-beta.21 → 17.0.0-beta.22

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 (209) hide show
  1. package/README.md +26 -2
  2. package/dist/lib/client/core.d.mts +4 -0
  3. package/dist/lib/client/core.d.ts +4 -0
  4. package/dist/lib/client/core.js +13 -0
  5. package/dist/lib/client/core.mjs +12 -0
  6. package/dist/lib/conformance/property-lists.d.mts +1 -1
  7. package/dist/lib/conformance/property-lists.d.ts +1 -1
  8. package/dist/lib/conformance/property-lists.js +1 -1
  9. package/dist/lib/conformance/property-lists.mjs +1 -1
  10. package/dist/lib/core/SingleAgentClient.d.mts +10 -1
  11. package/dist/lib/core/SingleAgentClient.d.ts +10 -1
  12. package/dist/lib/core/SingleAgentClient.js +56 -7
  13. package/dist/lib/core/SingleAgentClient.mjs +61 -7
  14. package/dist/lib/core/targeting-helpers.d.mts +123 -0
  15. package/dist/lib/core/targeting-helpers.d.ts +123 -0
  16. package/dist/lib/core/targeting-helpers.js +412 -0
  17. package/dist/lib/core/targeting-helpers.mjs +370 -0
  18. package/dist/lib/entrypoints/client-account-changes.d.mts +5 -0
  19. package/dist/lib/entrypoints/client-account-changes.d.ts +5 -0
  20. package/dist/lib/entrypoints/client-account-changes.js +28 -0
  21. package/dist/lib/entrypoints/client-account-changes.mjs +4 -0
  22. package/dist/lib/entrypoints/client-webhook-stores.d.mts +2 -0
  23. package/dist/lib/entrypoints/client-webhook-stores.d.ts +2 -0
  24. package/dist/lib/entrypoints/client-webhook-stores.js +37 -0
  25. package/dist/lib/entrypoints/client-webhook-stores.mjs +16 -0
  26. package/dist/lib/entrypoints/discovery.d.mts +9 -0
  27. package/dist/lib/entrypoints/discovery.d.ts +9 -0
  28. package/dist/lib/entrypoints/discovery.js +72 -0
  29. package/dist/lib/entrypoints/discovery.mjs +56 -0
  30. package/dist/lib/entrypoints/errors.d.mts +11 -0
  31. package/dist/lib/entrypoints/errors.d.ts +11 -0
  32. package/dist/lib/entrypoints/errors.js +159 -0
  33. package/dist/lib/entrypoints/errors.mjs +132 -0
  34. package/dist/lib/entrypoints/media-buy.d.mts +5 -0
  35. package/dist/lib/entrypoints/media-buy.d.ts +5 -0
  36. package/dist/lib/entrypoints/media-buy.js +119 -0
  37. package/dist/lib/entrypoints/media-buy.mjs +100 -0
  38. package/dist/lib/entrypoints/registry.d.mts +5 -0
  39. package/dist/lib/entrypoints/registry.d.ts +5 -0
  40. package/dist/lib/entrypoints/registry.js +61 -0
  41. package/dist/lib/entrypoints/registry.mjs +40 -0
  42. package/dist/lib/entrypoints/utils.d.mts +7 -0
  43. package/dist/lib/entrypoints/utils.d.ts +7 -0
  44. package/dist/lib/entrypoints/utils.js +100 -0
  45. package/dist/lib/entrypoints/utils.mjs +72 -0
  46. package/dist/lib/entrypoints/version.d.mts +3 -0
  47. package/dist/lib/entrypoints/version.d.ts +3 -0
  48. package/dist/lib/entrypoints/version.js +57 -0
  49. package/dist/lib/entrypoints/version.mjs +36 -0
  50. package/dist/lib/index.d.mts +1 -1
  51. package/dist/lib/index.d.ts +1 -1
  52. package/dist/lib/media-buy/action-contracts.js +3 -3
  53. package/dist/lib/media-buy/action-contracts.mjs +1 -1
  54. package/dist/lib/media-buy/creative-start-policy.d.mts +19 -0
  55. package/dist/lib/media-buy/creative-start-policy.d.ts +19 -0
  56. package/dist/lib/media-buy/creative-start-policy.js +59 -0
  57. package/dist/lib/media-buy/creative-start-policy.mjs +31 -0
  58. package/dist/lib/media-buy/valid-actions.d.mts +47 -0
  59. package/dist/lib/media-buy/valid-actions.d.ts +47 -0
  60. package/dist/lib/media-buy/valid-actions.js +42 -0
  61. package/dist/lib/media-buy/valid-actions.mjs +18 -0
  62. package/dist/lib/net/pin-and-bind-fetch.d.mts +121 -0
  63. package/dist/lib/net/pin-and-bind-fetch.d.ts +121 -0
  64. package/dist/lib/net/pin-and-bind-fetch.js +209 -0
  65. package/dist/lib/net/pin-and-bind-fetch.mjs +183 -0
  66. package/dist/lib/registry/types.generated.d.ts +18 -2
  67. package/dist/lib/reporting/ledger/index.d.mts +1 -0
  68. package/dist/lib/reporting/ledger/index.d.ts +1 -0
  69. package/dist/lib/reporting/ledger/index.js +3 -1
  70. package/dist/lib/reporting/ledger/index.mjs +1 -0
  71. package/dist/lib/reporting/ledger/instant.d.mts +5 -0
  72. package/dist/lib/reporting/ledger/instant.d.ts +5 -0
  73. package/dist/lib/reporting/ledger/instant.js +10 -0
  74. package/dist/lib/reporting/ledger/instant.mjs +9 -0
  75. package/dist/lib/reporting/ledger/issue-events.d.mts +333 -0
  76. package/dist/lib/reporting/ledger/issue-events.d.ts +333 -0
  77. package/dist/lib/reporting/ledger/issue-events.js +310 -0
  78. package/dist/lib/reporting/ledger/issue-events.mjs +282 -0
  79. package/dist/lib/reporting/service/index.d.mts +36 -1
  80. package/dist/lib/reporting/service/index.d.ts +36 -1
  81. package/dist/lib/reporting/service/index.js +51 -1
  82. package/dist/lib/reporting/service/index.mjs +52 -2
  83. package/dist/lib/reporting/service/scheduler-support.d.mts +1 -1
  84. package/dist/lib/reporting/service/scheduler-support.d.ts +1 -1
  85. package/dist/lib/reporting/service/scheduler-support.js +1 -1
  86. package/dist/lib/reporting/service/scheduler-support.mjs +1 -1
  87. package/dist/lib/server/capabilities-release-projection.d.mts +43 -0
  88. package/dist/lib/server/capabilities-release-projection.d.ts +43 -0
  89. package/dist/lib/server/capabilities-release-projection.js +128 -0
  90. package/dist/lib/server/capabilities-release-projection.mjs +112 -0
  91. package/dist/lib/server/create-adcp-server.d.mts +29 -5
  92. package/dist/lib/server/create-adcp-server.d.ts +29 -5
  93. package/dist/lib/server/create-adcp-server.js +95 -22
  94. package/dist/lib/server/create-adcp-server.mjs +106 -21
  95. package/dist/lib/server/decisioning/capabilities.d.mts +27 -0
  96. package/dist/lib/server/decisioning/capabilities.d.ts +27 -0
  97. package/dist/lib/server/decisioning/runtime/from-platform.js +99 -27
  98. package/dist/lib/server/decisioning/runtime/from-platform.mjs +103 -27
  99. package/dist/lib/server/declared-input-schema.d.mts +108 -0
  100. package/dist/lib/server/declared-input-schema.d.ts +108 -0
  101. package/dist/lib/server/declared-input-schema.js +167 -0
  102. package/dist/lib/server/declared-input-schema.mjs +137 -0
  103. package/dist/lib/server/envelope-allowlist.d.mts +1 -105
  104. package/dist/lib/server/envelope-allowlist.d.ts +1 -105
  105. package/dist/lib/server/envelope-allowlist.js +3 -79
  106. package/dist/lib/server/envelope-allowlist.mjs +1 -71
  107. package/dist/lib/server/errors.d.mts +1 -186
  108. package/dist/lib/server/errors.d.ts +1 -186
  109. package/dist/lib/server/errors.js +3 -98
  110. package/dist/lib/server/errors.mjs +1 -94
  111. package/dist/lib/server/index.d.mts +1 -1
  112. package/dist/lib/server/index.d.ts +1 -1
  113. package/dist/lib/server/mcp-modern-server.js +21 -4
  114. package/dist/lib/server/mcp-modern-server.mjs +21 -4
  115. package/dist/lib/server/media-buy-action-resolver.d.mts +7 -0
  116. package/dist/lib/server/media-buy-action-resolver.d.ts +7 -0
  117. package/dist/lib/server/media-buy-action-resolver.js +10 -1
  118. package/dist/lib/server/media-buy-action-resolver.mjs +10 -1
  119. package/dist/lib/server/media-buy-helpers.d.mts +1 -47
  120. package/dist/lib/server/media-buy-helpers.d.ts +1 -47
  121. package/dist/lib/server/media-buy-helpers.js +3 -23
  122. package/dist/lib/server/media-buy-helpers.mjs +1 -18
  123. package/dist/lib/server/pick-safe-details.d.mts +1 -89
  124. package/dist/lib/server/pick-safe-details.d.ts +1 -89
  125. package/dist/lib/server/pick-safe-details.js +3 -61
  126. package/dist/lib/server/pick-safe-details.mjs +1 -56
  127. package/dist/lib/server/pin-and-bind-fetch.d.mts +1 -121
  128. package/dist/lib/server/pin-and-bind-fetch.d.ts +1 -121
  129. package/dist/lib/server/pin-and-bind-fetch.js +3 -190
  130. package/dist/lib/server/pin-and-bind-fetch.mjs +1 -183
  131. package/dist/lib/server/targeting-helpers.d.mts +1 -123
  132. package/dist/lib/server/targeting-helpers.d.ts +1 -123
  133. package/dist/lib/server/targeting-helpers.js +3 -393
  134. package/dist/lib/server/targeting-helpers.mjs +1 -370
  135. package/dist/lib/server/test-controller.js +7 -3
  136. package/dist/lib/server/test-controller.mjs +7 -3
  137. package/dist/lib/storage/memory-ledger.js +219 -1
  138. package/dist/lib/storage/memory-ledger.mjs +223 -1
  139. package/dist/lib/testing/compliance/storyboard-tracks.js +0 -4
  140. package/dist/lib/testing/compliance/storyboard-tracks.mjs +0 -4
  141. package/dist/lib/testing/comply-controller.js +7 -2
  142. package/dist/lib/testing/comply-controller.mjs +7 -2
  143. package/dist/lib/testing/storyboard/request-signing/grader.d.mts +21 -0
  144. package/dist/lib/testing/storyboard/request-signing/grader.d.ts +21 -0
  145. package/dist/lib/testing/storyboard/request-signing/grader.js +31 -0
  146. package/dist/lib/testing/storyboard/request-signing/grader.mjs +30 -0
  147. package/dist/lib/testing/storyboard/request-signing/probe-dispatch.js +1 -1
  148. package/dist/lib/testing/storyboard/request-signing/probe-dispatch.mjs +2 -1
  149. package/dist/lib/testing/storyboard/request-signing/types.d.mts +12 -0
  150. package/dist/lib/testing/storyboard/request-signing/types.d.ts +12 -0
  151. package/dist/lib/testing/storyboard/request-signing/vector-loader.js +7 -2
  152. package/dist/lib/testing/storyboard/request-signing/vector-loader.mjs +7 -2
  153. package/dist/lib/testing/storyboard/runner.js +2 -2
  154. package/dist/lib/testing/storyboard/runner.mjs +2 -2
  155. package/dist/lib/testing/storyboard/validations.d.mts +1 -1
  156. package/dist/lib/testing/storyboard/validations.d.ts +1 -1
  157. package/dist/lib/utils/adcp-error-response.d.mts +196 -0
  158. package/dist/lib/utils/adcp-error-response.d.ts +196 -0
  159. package/dist/lib/utils/adcp-error-response.js +118 -0
  160. package/dist/lib/utils/adcp-error-response.mjs +95 -0
  161. package/dist/lib/utils/buyer-retry-policy.js +2 -2
  162. package/dist/lib/utils/buyer-retry-policy.mjs +1 -1
  163. package/dist/lib/utils/capabilities.d.mts +6 -0
  164. package/dist/lib/utils/capabilities.d.ts +6 -0
  165. package/dist/lib/utils/capabilities.js +6 -2
  166. package/dist/lib/utils/capabilities.mjs +6 -2
  167. package/dist/lib/utils/envelope-allowlist.d.mts +105 -0
  168. package/dist/lib/utils/envelope-allowlist.d.ts +105 -0
  169. package/dist/lib/utils/envelope-allowlist.js +98 -0
  170. package/dist/lib/utils/envelope-allowlist.mjs +71 -0
  171. package/dist/lib/utils/pick-safe-details.d.mts +89 -0
  172. package/dist/lib/utils/pick-safe-details.d.ts +89 -0
  173. package/dist/lib/utils/pick-safe-details.js +80 -0
  174. package/dist/lib/utils/pick-safe-details.mjs +56 -0
  175. package/dist/lib/v2/projection/augment-response.d.mts +4 -0
  176. package/dist/lib/v2/projection/augment-response.d.ts +4 -0
  177. package/dist/lib/v2/projection/creative-delivery.d.mts +20 -3
  178. package/dist/lib/v2/projection/creative-delivery.d.ts +20 -3
  179. package/dist/lib/v2/projection/creative-delivery.js +20 -4
  180. package/dist/lib/v2/projection/creative-delivery.mjs +19 -4
  181. package/dist/lib/v2/projection/index.d.mts +2 -2
  182. package/dist/lib/v2/projection/index.d.ts +2 -2
  183. package/dist/lib/v2/projection/index.js +4 -0
  184. package/dist/lib/v2/projection/index.mjs +5 -1
  185. package/dist/lib/v2/projection/legacy-metadata.d.mts +7 -0
  186. package/dist/lib/v2/projection/legacy-metadata.d.ts +7 -0
  187. package/dist/lib/v2/projection/legacy-metadata.js +14 -0
  188. package/dist/lib/v2/projection/legacy-metadata.mjs +12 -0
  189. package/dist/lib/v2/projection/legacy-routes.d.mts +11 -0
  190. package/dist/lib/v2/projection/legacy-routes.d.ts +11 -0
  191. package/dist/lib/v2/projection/legacy-routes.js +2 -1
  192. package/dist/lib/v2/projection/legacy-routes.mjs +7 -2
  193. package/dist/lib/v2/projection/v1-to-v2.d.mts +21 -1
  194. package/dist/lib/v2/projection/v1-to-v2.d.ts +21 -1
  195. package/dist/lib/v2/projection/v1-to-v2.js +18 -11
  196. package/dist/lib/v2/projection/v1-to-v2.mjs +19 -11
  197. package/dist/lib/version.d.mts +3 -3
  198. package/dist/lib/version.d.ts +3 -3
  199. package/dist/lib/version.js +3 -3
  200. package/dist/lib/version.mjs +3 -3
  201. package/docs/TYPE-SUMMARY.md +2 -2
  202. package/docs/guides/CREATIVE-DELIVERY.md +12 -0
  203. package/docs/guides/REPORTING-LEDGER.md +121 -0
  204. package/docs/guides/VALIDATE-YOUR-AGENT.md +1 -0
  205. package/docs/llms.txt +2 -2
  206. package/docs/migration-14.x-rc-worksheet.md +4 -4
  207. package/docs/migration-16-to-17.md +149 -0
  208. package/docs/migration-reporting-storage-package.md +10 -0
  209. package/package.json +106 -1
@@ -105,6 +105,13 @@ export interface GradeOptions extends LoadVectorsOptions {
105
105
  * provided (its own `protocol_methods_required_for` governs).
106
106
  */
107
107
  agentProtocolMethodsRequiredFor?: readonly string[];
108
+ /**
109
+ * The agent's `get_adcp_capabilities` response, used to evaluate a vector's
110
+ * `applies_when` condition (adcp#8064). A vector whose condition does not
111
+ * hold skips as `capability_profile_mismatch`. Without this option,
112
+ * conditional vectors are graded.
113
+ */
114
+ agentCapabilities?: Record<string, unknown>;
108
115
  /**
109
116
  * Transport shape the agent speaks. `'mcp'` (default) wraps each
110
117
  * vector body in a JSON-RPC `tools/call` envelope and POSTs to the MCP
@@ -316,6 +323,20 @@ export declare function advertisedContentDigestPolicyExclusion(vector: PositiveV
316
323
  * 001 unchanged.
317
324
  */
318
325
  export declare function advertisedRequiredForExclusion(vector: PositiveVector | NegativeVector, kind: 'positive' | 'negative', agentRequiredFor: readonly string[]): SemanticVectorExclusion | undefined;
326
+ /**
327
+ * Evaluate a vector's `applies_when` condition (adcp#8064) against the agent's
328
+ * advertised `get_adcp_capabilities` response. A vector whose condition does
329
+ * not hold tests a path the agent does not offer, so it skips as
330
+ * `capability_profile_mismatch` instead of failing. Vector 027 uses this:
331
+ * condition (b) of `request_signature_required` applies only while
332
+ * `webhook_signing.legacy_hmac_fallback` is `true`, and an absent
333
+ * `webhook_signing` block does not satisfy it.
334
+ *
335
+ * Supported form: a dotted capability path compared with `==` or `!=` to a
336
+ * JSON scalar. Without capabilities, or with any other expression, the vector
337
+ * stays graded, so a condition the grader cannot read never hides a failure.
338
+ */
339
+ export declare function appliesWhenExclusion(vector: PositiveVector | NegativeVector, agentCapabilities: unknown): SemanticVectorExclusion | undefined;
319
340
  /**
320
341
  * The `protocol_methods_required_for` slice of `capabilityMismatch`
321
342
  * (adcp#4326 namespace): negative vectors that grade a JSON-RPC protocol
@@ -20,6 +20,7 @@ var grader_exports = {};
20
20
  __export(grader_exports, {
21
21
  advertisedContentDigestPolicyExclusion: () => advertisedContentDigestPolicyExclusion,
22
22
  advertisedRequiredForExclusion: () => advertisedRequiredForExclusion,
23
+ appliesWhenExclusion: () => appliesWhenExclusion,
23
24
  gradeOneVector: () => gradeOneVector,
24
25
  gradeRequestSigning: () => gradeRequestSigning,
25
26
  protocolMethodCoverageMismatch: () => protocolMethodCoverageMismatch,
@@ -224,6 +225,10 @@ function preflightSkip(vector, kind, contract, options, agentUrl) {
224
225
  };
225
226
  }
226
227
  }
228
+ const appliesWhen = appliesWhenExclusion(vector, options.agentCapabilities);
229
+ if (appliesWhen) {
230
+ return { ...base, skipped: true, skip_reason: appliesWhen.skip_reason, diagnostic: appliesWhen.diagnostic };
231
+ }
227
232
  const semantic = semanticVectorExclusion(vector);
228
233
  if (semantic) {
229
234
  return { ...base, skipped: true, skip_reason: semantic.skip_reason, diagnostic: semantic.diagnostic };
@@ -660,6 +665,31 @@ function advertisedRequiredForExclusion(vector, kind, agentRequiredFor) {
660
665
  diagnostic: `Vector asserts required_for includes [${missing.join(", ")}] but the agent declares required_for [${agentRequiredFor.join(", ")}]. The vector tests a rejection path the agent has not opted into; add the operation to request_signing.required_for to grade it.`
661
666
  };
662
667
  }
668
+ const APPLIES_WHEN_GRAMMAR = /^\s*([A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)*)\s*(==|!=)\s*(.+?)\s*$/;
669
+ const capabilityRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
670
+ function appliesWhenExclusion(vector, agentCapabilities) {
671
+ const expression = vector.applies_when;
672
+ if (expression === void 0 || !capabilityRecord(agentCapabilities)) return void 0;
673
+ const [, path, operator, literal] = APPLIES_WHEN_GRAMMAR.exec(expression) ?? [];
674
+ if (!path || !operator || !literal) return void 0;
675
+ let expected;
676
+ try {
677
+ expected = JSON.parse(literal);
678
+ } catch {
679
+ return void 0;
680
+ }
681
+ if (typeof expected === "object" && expected !== null) return void 0;
682
+ let actual = agentCapabilities;
683
+ for (const segment of path.split(".")) {
684
+ const descriptor = capabilityRecord(actual) ? Object.getOwnPropertyDescriptor(actual, segment) : void 0;
685
+ actual = descriptor && "value" in descriptor ? descriptor.value : void 0;
686
+ }
687
+ if (actual === expected === (operator === "==")) return void 0;
688
+ return {
689
+ skip_reason: "capability_profile_mismatch",
690
+ diagnostic: `Vector applies only when \`${expression}\`, which the agent's advertised capabilities do not satisfy.`
691
+ };
692
+ }
663
693
  function capabilityMismatch(vector, kind, agentCap) {
664
694
  const vectorCap = vector.verifier_capability;
665
695
  if (vectorCap.supported !== agentCap.supported) {
@@ -699,6 +729,7 @@ function buildNegativeDiagnostic(vector, probe) {
699
729
  0 && (module.exports = {
700
730
  advertisedContentDigestPolicyExclusion,
701
731
  advertisedRequiredForExclusion,
732
+ appliesWhenExclusion,
702
733
  gradeOneVector,
703
734
  gradeRequestSigning,
704
735
  protocolMethodCoverageMismatch,
@@ -203,6 +203,10 @@ function preflightSkip(vector, kind, contract, options, agentUrl) {
203
203
  };
204
204
  }
205
205
  }
206
+ const appliesWhen = appliesWhenExclusion(vector, options.agentCapabilities);
207
+ if (appliesWhen) {
208
+ return { ...base, skipped: true, skip_reason: appliesWhen.skip_reason, diagnostic: appliesWhen.diagnostic };
209
+ }
206
210
  const semantic = semanticVectorExclusion(vector);
207
211
  if (semantic) {
208
212
  return { ...base, skipped: true, skip_reason: semantic.skip_reason, diagnostic: semantic.diagnostic };
@@ -639,6 +643,31 @@ function advertisedRequiredForExclusion(vector, kind, agentRequiredFor) {
639
643
  diagnostic: `Vector asserts required_for includes [${missing.join(", ")}] but the agent declares required_for [${agentRequiredFor.join(", ")}]. The vector tests a rejection path the agent has not opted into; add the operation to request_signing.required_for to grade it.`
640
644
  };
641
645
  }
646
+ const APPLIES_WHEN_GRAMMAR = /^\s*([A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)*)\s*(==|!=)\s*(.+?)\s*$/;
647
+ const capabilityRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
648
+ function appliesWhenExclusion(vector, agentCapabilities) {
649
+ const expression = vector.applies_when;
650
+ if (expression === void 0 || !capabilityRecord(agentCapabilities)) return void 0;
651
+ const [, path, operator, literal] = APPLIES_WHEN_GRAMMAR.exec(expression) ?? [];
652
+ if (!path || !operator || !literal) return void 0;
653
+ let expected;
654
+ try {
655
+ expected = JSON.parse(literal);
656
+ } catch {
657
+ return void 0;
658
+ }
659
+ if (typeof expected === "object" && expected !== null) return void 0;
660
+ let actual = agentCapabilities;
661
+ for (const segment of path.split(".")) {
662
+ const descriptor = capabilityRecord(actual) ? Object.getOwnPropertyDescriptor(actual, segment) : void 0;
663
+ actual = descriptor && "value" in descriptor ? descriptor.value : void 0;
664
+ }
665
+ if (actual === expected === (operator === "==")) return void 0;
666
+ return {
667
+ skip_reason: "capability_profile_mismatch",
668
+ diagnostic: `Vector applies only when \`${expression}\`, which the agent's advertised capabilities do not satisfy.`
669
+ };
670
+ }
642
671
  function capabilityMismatch(vector, kind, agentCap) {
643
672
  const vectorCap = vector.verifier_capability;
644
673
  if (vectorCap.supported !== agentCap.supported) {
@@ -677,6 +706,7 @@ function buildNegativeDiagnostic(vector, probe) {
677
706
  export {
678
707
  advertisedContentDigestPolicyExclusion,
679
708
  advertisedRequiredForExclusion,
709
+ appliesWhenExclusion,
680
710
  gradeOneVector,
681
711
  gradeRequestSigning,
682
712
  protocolMethodCoverageMismatch,
@@ -116,7 +116,7 @@ async function probeRequestSigningVector(stepId, agentUrl, options) {
116
116
  }
117
117
  const agentContentDigestPolicy = declaredContentDigestPolicy(options, loaded.sourceDir);
118
118
  const agentRequiredFor = declaredRequiredFor(options);
119
- const semantic = (agentContentDigestPolicy ? (0, import_grader.advertisedContentDigestPolicyExclusion)(vector, parsed.kind, agentContentDigestPolicy) : void 0) ?? (agentRequiredFor ? (0, import_grader.advertisedRequiredForExclusion)(vector, parsed.kind, agentRequiredFor) : void 0) ?? (0, import_grader.semanticVectorExclusion)(vector, declaredProtocolMethodCoverage(options, loaded.sourceDir));
119
+ const semantic = (agentContentDigestPolicy ? (0, import_grader.advertisedContentDigestPolicyExclusion)(vector, parsed.kind, agentContentDigestPolicy) : void 0) ?? (agentRequiredFor ? (0, import_grader.advertisedRequiredForExclusion)(vector, parsed.kind, agentRequiredFor) : void 0) ?? (0, import_grader.appliesWhenExclusion)(vector, options._profile?.raw_capabilities) ?? (0, import_grader.semanticVectorExclusion)(vector, declaredProtocolMethodCoverage(options, loaded.sourceDir));
120
120
  if (semantic) {
121
121
  return skipProbe(agentUrl, semantic.skip_reason, semantic.diagnostic);
122
122
  }
@@ -2,6 +2,7 @@ import { basename, dirname } from "path";
2
2
  import {
3
3
  advertisedContentDigestPolicyExclusion,
4
4
  advertisedRequiredForExclusion,
5
+ appliesWhenExclusion,
5
6
  gradeOneVector,
6
7
  semanticVectorExclusion
7
8
  } from "./grader.mjs";
@@ -84,7 +85,7 @@ async function probeRequestSigningVector(stepId, agentUrl, options) {
84
85
  }
85
86
  const agentContentDigestPolicy = declaredContentDigestPolicy(options, loaded.sourceDir);
86
87
  const agentRequiredFor = declaredRequiredFor(options);
87
- const semantic = (agentContentDigestPolicy ? advertisedContentDigestPolicyExclusion(vector, parsed.kind, agentContentDigestPolicy) : void 0) ?? (agentRequiredFor ? advertisedRequiredForExclusion(vector, parsed.kind, agentRequiredFor) : void 0) ?? semanticVectorExclusion(vector, declaredProtocolMethodCoverage(options, loaded.sourceDir));
88
+ const semantic = (agentContentDigestPolicy ? advertisedContentDigestPolicyExclusion(vector, parsed.kind, agentContentDigestPolicy) : void 0) ?? (agentRequiredFor ? advertisedRequiredForExclusion(vector, parsed.kind, agentRequiredFor) : void 0) ?? appliesWhenExclusion(vector, options._profile?.raw_capabilities) ?? semanticVectorExclusion(vector, declaredProtocolMethodCoverage(options, loaded.sourceDir));
88
89
  if (semantic) {
89
90
  return skipProbe(agentUrl, semantic.skip_reason, semantic.diagnostic);
90
91
  }
@@ -48,6 +48,12 @@ export interface PositiveVector {
48
48
  jwks_override?: JwksOverride;
49
49
  expected_signature_base?: string;
50
50
  spec_reference?: string;
51
+ /**
52
+ * Capability condition from the authored fixture (adcp#8064), e.g.
53
+ * `webhook_signing.legacy_hmac_fallback == true`. The vector grades only for
54
+ * agents whose `get_adcp_capabilities` response satisfies it.
55
+ */
56
+ applies_when?: string;
51
57
  }
52
58
  export interface NegativeVector {
53
59
  kind: 'negative';
@@ -64,6 +70,12 @@ export interface NegativeVector {
64
70
  expected_failed_step: number | string;
65
71
  requires_contract?: ContractId;
66
72
  spec_reference?: string;
73
+ /**
74
+ * Capability condition from the authored fixture (adcp#8064), e.g.
75
+ * `webhook_signing.legacy_hmac_fallback == true`. The vector grades only for
76
+ * agents whose `get_adcp_capabilities` response satisfies it.
77
+ */
78
+ applies_when?: string;
67
79
  }
68
80
  export type Vector = PositiveVector | NegativeVector;
69
81
  /**
@@ -48,6 +48,12 @@ export interface PositiveVector {
48
48
  jwks_override?: JwksOverride;
49
49
  expected_signature_base?: string;
50
50
  spec_reference?: string;
51
+ /**
52
+ * Capability condition from the authored fixture (adcp#8064), e.g.
53
+ * `webhook_signing.legacy_hmac_fallback == true`. The vector grades only for
54
+ * agents whose `get_adcp_capabilities` response satisfies it.
55
+ */
56
+ applies_when?: string;
51
57
  }
52
58
  export interface NegativeVector {
53
59
  kind: 'negative';
@@ -64,6 +70,12 @@ export interface NegativeVector {
64
70
  expected_failed_step: number | string;
65
71
  requires_contract?: ContractId;
66
72
  spec_reference?: string;
73
+ /**
74
+ * Capability condition from the authored fixture (adcp#8064), e.g.
75
+ * `webhook_signing.legacy_hmac_fallback == true`. The vector grades only for
76
+ * agents whose `get_adcp_capabilities` response satisfies it.
77
+ */
78
+ applies_when?: string;
67
79
  }
68
80
  export type Vector = PositiveVector | NegativeVector;
69
81
  /**
@@ -228,7 +228,8 @@ function parsePositive(id, raw) {
228
228
  jwks_ref,
229
229
  jwks_override,
230
230
  expected_signature_base: typeof r.expected_signature_base === "string" ? r.expected_signature_base : void 0,
231
- spec_reference: typeof r.spec_reference === "string" ? r.spec_reference : void 0
231
+ spec_reference: typeof r.spec_reference === "string" ? r.spec_reference : void 0,
232
+ applies_when: optionalAppliesWhen(id, r)
232
233
  };
233
234
  }
234
235
  function parseNegative(id, raw) {
@@ -265,12 +266,16 @@ function parseNegative(id, raw) {
265
266
  expected_error_code: errorCode,
266
267
  expected_failed_step: failedStep,
267
268
  requires_contract: contract,
268
- spec_reference: typeof r.spec_reference === "string" ? r.spec_reference : void 0
269
+ spec_reference: typeof r.spec_reference === "string" ? r.spec_reference : void 0,
270
+ applies_when: optionalAppliesWhen(id, r)
269
271
  };
270
272
  }
271
273
  function optionalSigningProfileVersion(vector) {
272
274
  return typeof vector.signing_profile_version === "string" ? vector.signing_profile_version : "3.1";
273
275
  }
276
+ function optionalAppliesWhen(id, vector) {
277
+ return vector.applies_when === void 0 ? void 0 : str(vector.applies_when, `${id}.applies_when`);
278
+ }
274
279
  function parseJwksSelector(id, r) {
275
280
  const hasRef = r.jwks_ref !== void 0;
276
281
  const hasOverride = r.jwks_override !== void 0;
@@ -201,7 +201,8 @@ function parsePositive(id, raw) {
201
201
  jwks_ref,
202
202
  jwks_override,
203
203
  expected_signature_base: typeof r.expected_signature_base === "string" ? r.expected_signature_base : void 0,
204
- spec_reference: typeof r.spec_reference === "string" ? r.spec_reference : void 0
204
+ spec_reference: typeof r.spec_reference === "string" ? r.spec_reference : void 0,
205
+ applies_when: optionalAppliesWhen(id, r)
205
206
  };
206
207
  }
207
208
  function parseNegative(id, raw) {
@@ -238,12 +239,16 @@ function parseNegative(id, raw) {
238
239
  expected_error_code: errorCode,
239
240
  expected_failed_step: failedStep,
240
241
  requires_contract: contract,
241
- spec_reference: typeof r.spec_reference === "string" ? r.spec_reference : void 0
242
+ spec_reference: typeof r.spec_reference === "string" ? r.spec_reference : void 0,
243
+ applies_when: optionalAppliesWhen(id, r)
242
244
  };
243
245
  }
244
246
  function optionalSigningProfileVersion(vector) {
245
247
  return typeof vector.signing_profile_version === "string" ? vector.signing_profile_version : "3.1";
246
248
  }
249
+ function optionalAppliesWhen(id, vector) {
250
+ return vector.applies_when === void 0 ? void 0 : str(vector.applies_when, `${id}.applies_when`);
251
+ }
247
252
  function parseJwksSelector(id, r) {
248
253
  const hasRef = r.jwks_ref !== void 0;
249
254
  const hasOverride = r.jwks_override !== void 0;
@@ -3432,9 +3432,9 @@ async function executeStoryboardPass(agentUrls, storyboard, options, dispatchOff
3432
3432
  const cascade = step.stateful ? cascadeForPhase(phase, priorPhaseIds) : { tripped: false };
3433
3433
  if (cascade.tripped && step.stateful && routedCapabilityDetail === void 0) {
3434
3434
  const resolvedTask = (0, import_agent_routing.resolveTaskName)(step, selectedOptions);
3435
- const missingTool = selectedOptions.agentTools && (routingContext && step.requires_tool && !selectedOptions.agentTools.includes(step.requires_tool) ? step.requires_tool : resolvedTask && !(0, import_runner_owned_task.isRunnerOwnedTask)(resolvedTask) && !selectedOptions.agentTools.includes(resolvedTask) ? resolvedTask : void 0);
3435
+ const missingTool = selectedOptions.agentTools && (step.requires_tool && !selectedOptions.agentTools.includes(step.requires_tool) ? step.requires_tool : resolvedTask && !(0, import_runner_owned_task.isRunnerOwnedTask)(resolvedTask) && !selectedOptions.agentTools.includes(resolvedTask) ? resolvedTask : void 0);
3436
3436
  if (missingTool) {
3437
- const missingReason = routingContext && missingTool === "comply_test_controller" ? "missing_test_controller" : "missing_tool";
3437
+ const missingReason = missingTool === "comply_test_controller" && (routingContext || step.requires_tool === missingTool) ? "missing_test_controller" : "missing_tool";
3438
3438
  const toolDetail = `Agent did not advertise tool "${missingTool}"; agent tools: [${selectedOptions.agentTools.join(", ")}].`;
3439
3439
  const missingToolResult = {
3440
3440
  storyboard_id: storyboard.id,
@@ -3474,9 +3474,9 @@ async function executeStoryboardPass(agentUrls, storyboard, options, dispatchOff
3474
3474
  const cascade = step.stateful ? cascadeForPhase(phase, priorPhaseIds) : { tripped: false };
3475
3475
  if (cascade.tripped && step.stateful && routedCapabilityDetail === void 0) {
3476
3476
  const resolvedTask = resolveTaskName(step, selectedOptions);
3477
- const missingTool = selectedOptions.agentTools && (routingContext && step.requires_tool && !selectedOptions.agentTools.includes(step.requires_tool) ? step.requires_tool : resolvedTask && !isRunnerOwnedTask(resolvedTask) && !selectedOptions.agentTools.includes(resolvedTask) ? resolvedTask : void 0);
3477
+ const missingTool = selectedOptions.agentTools && (step.requires_tool && !selectedOptions.agentTools.includes(step.requires_tool) ? step.requires_tool : resolvedTask && !isRunnerOwnedTask(resolvedTask) && !selectedOptions.agentTools.includes(resolvedTask) ? resolvedTask : void 0);
3478
3478
  if (missingTool) {
3479
- const missingReason = routingContext && missingTool === "comply_test_controller" ? "missing_test_controller" : "missing_tool";
3479
+ const missingReason = missingTool === "comply_test_controller" && (routingContext || step.requires_tool === missingTool) ? "missing_test_controller" : "missing_tool";
3480
3480
  const toolDetail = `Agent did not advertise tool "${missingTool}"; agent tools: [${selectedOptions.agentTools.join(", ")}].`;
3481
3481
  const missingToolResult = {
3482
3482
  storyboard_id: storyboard.id,
@@ -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.21";
203
+ export declare const RUNNER_CAPABILITY_VERSION = "17.0.0-beta.22";
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.21";
203
+ export declare const RUNNER_CAPABILITY_VERSION = "17.0.0-beta.22";
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
  /**
@@ -0,0 +1,196 @@
1
+ /**
2
+ * Server-side helpers for producing L3-compliant AdCP error responses.
3
+ *
4
+ * Use `adcpError()` in MCP tool handlers to return structured errors
5
+ * that clients can automatically detect, classify, and act on.
6
+ */
7
+ import { type StandardErrorCode, type ErrorRecovery } from '../types/error-codes.mjs';
8
+ import type { ValidationIssue } from '../validation/schema-validator.mjs';
9
+ export interface AdcpErrorOptions {
10
+ message: string;
11
+ /**
12
+ * Opaque request context to echo beside `adcp_error`. Only a non-null,
13
+ * non-array object is echoable, matching the framework envelope behavior.
14
+ */
15
+ context?: unknown;
16
+ /**
17
+ * Override the recovery classification. Defaults to
18
+ * `STANDARD_ERROR_CODES[code].recovery` for known codes, `'terminal'`
19
+ * otherwise. Dropped from the wire shape for codes whose entry in
20
+ * `ADCP_ERROR_FIELD_ALLOWLIST` excludes it; normalized back to the
21
+ * standard table value for allowlisted standard-code envelopes.
22
+ */
23
+ recovery?: ErrorRecovery;
24
+ /**
25
+ * Name of the request field the error applies to (validation /
26
+ * constraint errors). Dropped from the wire shape for codes whose
27
+ * `ADCP_ERROR_FIELD_ALLOWLIST` entry excludes it (e.g. `IDEMPOTENCY_CONFLICT`
28
+ * — a conflict response MUST NOT echo prior payload state).
29
+ */
30
+ field?: string;
31
+ /**
32
+ * Human-readable remediation hint. Dropped from the wire shape for
33
+ * codes whose `ADCP_ERROR_FIELD_ALLOWLIST` entry excludes it (e.g.
34
+ * `IDEMPOTENCY_CONFLICT`).
35
+ */
36
+ suggestion?: string;
37
+ /**
38
+ * Seconds to wait before retrying a transient error. Only meaningful
39
+ * on retryable codes (`RATE_LIMITED`, `SERVICE_UNAVAILABLE`); dropped
40
+ * on terminal codes whose allowlist excludes it (`IDEMPOTENCY_CONFLICT`
41
+ * — a computed `retry_after` on conflict would leak cached-entry age).
42
+ */
43
+ retry_after?: number;
44
+ /**
45
+ * Code-specific diagnostic payload. Dropped from the wire shape for
46
+ * codes whose `ADCP_ERROR_FIELD_ALLOWLIST` entry excludes it
47
+ * (`IDEMPOTENCY_CONFLICT` — a conflict response MUST NOT echo the
48
+ * prior request payload or cached response body).
49
+ */
50
+ details?: Record<string, unknown>;
51
+ /**
52
+ * Schema validation issues surfaced at the top level of `adcp_error`
53
+ * so operators see JSON Pointers on the first render. Primary use is
54
+ * `VALIDATION_ERROR`; framework validation hooks populate this
55
+ * automatically and also mirror the same array to `details.issues`
56
+ * for buyers that already index into `details` per AdCP spec
57
+ * convention.
58
+ */
59
+ issues?: Array<Omit<ValidationIssue, 'schemaPath'> & {
60
+ schemaPath?: string;
61
+ }>;
62
+ /**
63
+ * Buyer-actionable classification. Populate when the top-level `code`
64
+ * is coarse or producer-internal and a buyer-safe `{code, message}` pair
65
+ * (drawn from the standard error vocabulary) would give the buyer's
66
+ * agent something to act on. Per AdCP 3.2 `core/error.json`, `message`
67
+ * MUST be safe to show to the buyer — no vendor identifiers, ad-server
68
+ * type names, internal object names, internal IDs, or stack traces. The
69
+ * envelope allowlist for `IDEMPOTENCY_CONFLICT` / `IDEMPOTENCY_IN_FLIGHT`
70
+ * drops this key — those codes are wire-shape-restricted and never carry
71
+ * a buyer-actionable classification.
72
+ */
73
+ buyer_reason?: {
74
+ code: string;
75
+ message: string;
76
+ };
77
+ /**
78
+ * Whether the failed state-changing request changed seller state (AdCP 3.3
79
+ * `error.mutation_outcome`). Set `'not_applied'` only with pre-commit
80
+ * evidence: a typed rejection raised before the idempotency claim and
81
+ * before any write. Leave it unset to make no claim.
82
+ */
83
+ mutation_outcome?: AdcpMutationOutcome;
84
+ }
85
+ /** AdCP 3.3 `error.mutation_outcome` values. */
86
+ export type AdcpMutationOutcome = 'not_applied' | 'unknown' | 'applied';
87
+ export interface AdcpErrorPayload {
88
+ code: string;
89
+ message: string;
90
+ /**
91
+ * Closed-enum classifier. Populated by `adcpError()` from
92
+ * `STANDARD_ERROR_CODES[code].recovery` unless the caller provides an
93
+ * override. Marked optional because per-code inside-`adcp_error`
94
+ * allowlists may deliberately drop it from the wire shape — consumers
95
+ * reading a payload parsed off the wire MUST tolerate `undefined`.
96
+ */
97
+ recovery?: ErrorRecovery;
98
+ field?: string;
99
+ suggestion?: string;
100
+ retry_after?: number;
101
+ details?: Record<string, unknown>;
102
+ /**
103
+ * Schema validation issues (`VALIDATION_ERROR`) exposed at the top
104
+ * level so the list is the first thing a reader sees when inspecting
105
+ * the envelope. Also mirrored at `details.issues` for spec-convention
106
+ * compatibility.
107
+ */
108
+ issues?: Array<Omit<ValidationIssue, 'schemaPath'> & {
109
+ schemaPath?: string;
110
+ }>;
111
+ /**
112
+ * Buyer-actionable classification of the failure. See
113
+ * {@link AdcpErrorOptions.buyer_reason} for the buyer-safety contract.
114
+ */
115
+ buyer_reason?: {
116
+ code: string;
117
+ message: string;
118
+ };
119
+ mutation_outcome?: AdcpMutationOutcome;
120
+ }
121
+ export interface AdcpErrorResponse {
122
+ [key: string]: unknown;
123
+ content: Array<{
124
+ type: 'text';
125
+ text: string;
126
+ }>;
127
+ isError: true;
128
+ structuredContent: {
129
+ adcp_error: AdcpErrorPayload;
130
+ context?: object;
131
+ };
132
+ }
133
+ /**
134
+ * Build an L3-compliant MCP tool error response with all three transport layers:
135
+ *
136
+ * 1. `structuredContent.adcp_error` — programmatic extraction (L3)
137
+ * 2. `content[0].text` — JSON text fallback (L2)
138
+ * 3. `isError: true` — MCP error signal
139
+ *
140
+ * Recovery is auto-populated from the standard error code table when not provided.
141
+ *
142
+ * Before returning, any field NOT allowlisted for the given code in
143
+ * {@link ADCP_ERROR_FIELD_ALLOWLIST} is dropped — sellers get the builder's
144
+ * ergonomics for every code AND the strict wire shape for codes that have
145
+ * a registered allowlist. `IDEMPOTENCY_CONFLICT` is the canonical case:
146
+ * payload-shaped diagnostics like `field`, `suggestion`, and `details`
147
+ * silently drop while standard `recovery` metadata is preserved as the
148
+ * canonical standard-table value. Codes without a registered allowlist
149
+ * pass through unchanged.
150
+ *
151
+ * **Two-layer wire shape.** This builder emits the envelope layer
152
+ * (`structuredContent.adcp_error`) only. For tools whose response
153
+ * schema declares a typed Error arm (`errors[]` required at the top
154
+ * level), the framework dispatcher synthesises the payload-layer
155
+ * `errors[]` from the same data at finalize time, so the wire carries
156
+ * both the envelope marker and the typed Error arm together — no
157
+ * adopter code change required. The list of affected tools is derived
158
+ * at server build from the bundled schema cache. RFC:
159
+ * `docs/proposals/adcperror-two-layer-emission.md`.
160
+ *
161
+ * @example
162
+ * ```typescript
163
+ * import { adcpError } from '@adcp/sdk';
164
+ *
165
+ * server.registerTool("get_products", { inputSchema: schema }, async request => {
166
+ * const { query, context } = request;
167
+ * if (!products.length) {
168
+ * return adcpError('PRODUCT_NOT_FOUND', {
169
+ * message: 'No products match query',
170
+ * field: 'query',
171
+ * suggestion: 'Try a broader search term',
172
+ * context,
173
+ * });
174
+ * }
175
+ * return { content: [...], structuredContent: { products, context } };
176
+ * });
177
+ * ```
178
+ */
179
+ export declare function adcpError(code: StandardErrorCode | (string & {}), options: AdcpErrorOptions): AdcpErrorResponse;
180
+ /**
181
+ * Drop every field not in {@link ADCP_ERROR_FIELD_ALLOWLIST} for `code`.
182
+ * When an allowlisted standard code carries `recovery`, normalize it to
183
+ * the fixed classifier from `STANDARD_ERROR_CODES` instead of trusting a
184
+ * caller-supplied value.
185
+ * Codes without an entry pass through unchanged — the allowlist is
186
+ * opt-in per code, not a global filter. The returned object is re-typed
187
+ * as `AdcpErrorPayload` on the assumption that `code` and `message`
188
+ * (the only required fields) are in every registered allowlist; that
189
+ * invariant is re-asserted at runtime by the module-load check in
190
+ * `envelope-allowlist.ts`.
191
+ */
192
+ export declare function applyAdcpErrorAllowlist(code: string, payload: Record<string, unknown>): AdcpErrorPayload;
193
+ export declare function sanitizeStructuredAdcpError<T extends {
194
+ code: string;
195
+ message: string;
196
+ }>(error: T): T;