@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.
- package/README.md +26 -2
- package/dist/lib/client/core.d.mts +4 -0
- package/dist/lib/client/core.d.ts +4 -0
- package/dist/lib/client/core.js +13 -0
- package/dist/lib/client/core.mjs +12 -0
- package/dist/lib/conformance/property-lists.d.mts +1 -1
- package/dist/lib/conformance/property-lists.d.ts +1 -1
- package/dist/lib/conformance/property-lists.js +1 -1
- package/dist/lib/conformance/property-lists.mjs +1 -1
- package/dist/lib/core/SingleAgentClient.d.mts +10 -1
- package/dist/lib/core/SingleAgentClient.d.ts +10 -1
- package/dist/lib/core/SingleAgentClient.js +56 -7
- package/dist/lib/core/SingleAgentClient.mjs +61 -7
- package/dist/lib/core/targeting-helpers.d.mts +123 -0
- package/dist/lib/core/targeting-helpers.d.ts +123 -0
- package/dist/lib/core/targeting-helpers.js +412 -0
- package/dist/lib/core/targeting-helpers.mjs +370 -0
- package/dist/lib/entrypoints/client-account-changes.d.mts +5 -0
- package/dist/lib/entrypoints/client-account-changes.d.ts +5 -0
- package/dist/lib/entrypoints/client-account-changes.js +28 -0
- package/dist/lib/entrypoints/client-account-changes.mjs +4 -0
- package/dist/lib/entrypoints/client-webhook-stores.d.mts +2 -0
- package/dist/lib/entrypoints/client-webhook-stores.d.ts +2 -0
- package/dist/lib/entrypoints/client-webhook-stores.js +37 -0
- package/dist/lib/entrypoints/client-webhook-stores.mjs +16 -0
- package/dist/lib/entrypoints/discovery.d.mts +9 -0
- package/dist/lib/entrypoints/discovery.d.ts +9 -0
- package/dist/lib/entrypoints/discovery.js +72 -0
- package/dist/lib/entrypoints/discovery.mjs +56 -0
- package/dist/lib/entrypoints/errors.d.mts +11 -0
- package/dist/lib/entrypoints/errors.d.ts +11 -0
- package/dist/lib/entrypoints/errors.js +159 -0
- package/dist/lib/entrypoints/errors.mjs +132 -0
- package/dist/lib/entrypoints/media-buy.d.mts +5 -0
- package/dist/lib/entrypoints/media-buy.d.ts +5 -0
- package/dist/lib/entrypoints/media-buy.js +119 -0
- package/dist/lib/entrypoints/media-buy.mjs +100 -0
- package/dist/lib/entrypoints/registry.d.mts +5 -0
- package/dist/lib/entrypoints/registry.d.ts +5 -0
- package/dist/lib/entrypoints/registry.js +61 -0
- package/dist/lib/entrypoints/registry.mjs +40 -0
- package/dist/lib/entrypoints/utils.d.mts +7 -0
- package/dist/lib/entrypoints/utils.d.ts +7 -0
- package/dist/lib/entrypoints/utils.js +100 -0
- package/dist/lib/entrypoints/utils.mjs +72 -0
- package/dist/lib/entrypoints/version.d.mts +3 -0
- package/dist/lib/entrypoints/version.d.ts +3 -0
- package/dist/lib/entrypoints/version.js +57 -0
- package/dist/lib/entrypoints/version.mjs +36 -0
- package/dist/lib/index.d.mts +1 -1
- package/dist/lib/index.d.ts +1 -1
- package/dist/lib/media-buy/action-contracts.js +3 -3
- package/dist/lib/media-buy/action-contracts.mjs +1 -1
- package/dist/lib/media-buy/creative-start-policy.d.mts +19 -0
- package/dist/lib/media-buy/creative-start-policy.d.ts +19 -0
- package/dist/lib/media-buy/creative-start-policy.js +59 -0
- package/dist/lib/media-buy/creative-start-policy.mjs +31 -0
- package/dist/lib/media-buy/valid-actions.d.mts +47 -0
- package/dist/lib/media-buy/valid-actions.d.ts +47 -0
- package/dist/lib/media-buy/valid-actions.js +42 -0
- package/dist/lib/media-buy/valid-actions.mjs +18 -0
- package/dist/lib/net/pin-and-bind-fetch.d.mts +121 -0
- package/dist/lib/net/pin-and-bind-fetch.d.ts +121 -0
- package/dist/lib/net/pin-and-bind-fetch.js +209 -0
- package/dist/lib/net/pin-and-bind-fetch.mjs +183 -0
- package/dist/lib/registry/types.generated.d.ts +18 -2
- package/dist/lib/reporting/ledger/index.d.mts +1 -0
- package/dist/lib/reporting/ledger/index.d.ts +1 -0
- package/dist/lib/reporting/ledger/index.js +3 -1
- package/dist/lib/reporting/ledger/index.mjs +1 -0
- package/dist/lib/reporting/ledger/instant.d.mts +5 -0
- package/dist/lib/reporting/ledger/instant.d.ts +5 -0
- package/dist/lib/reporting/ledger/instant.js +10 -0
- package/dist/lib/reporting/ledger/instant.mjs +9 -0
- package/dist/lib/reporting/ledger/issue-events.d.mts +333 -0
- package/dist/lib/reporting/ledger/issue-events.d.ts +333 -0
- package/dist/lib/reporting/ledger/issue-events.js +310 -0
- package/dist/lib/reporting/ledger/issue-events.mjs +282 -0
- package/dist/lib/reporting/service/index.d.mts +36 -1
- package/dist/lib/reporting/service/index.d.ts +36 -1
- package/dist/lib/reporting/service/index.js +51 -1
- package/dist/lib/reporting/service/index.mjs +52 -2
- package/dist/lib/reporting/service/scheduler-support.d.mts +1 -1
- package/dist/lib/reporting/service/scheduler-support.d.ts +1 -1
- package/dist/lib/reporting/service/scheduler-support.js +1 -1
- package/dist/lib/reporting/service/scheduler-support.mjs +1 -1
- package/dist/lib/server/capabilities-release-projection.d.mts +43 -0
- package/dist/lib/server/capabilities-release-projection.d.ts +43 -0
- package/dist/lib/server/capabilities-release-projection.js +128 -0
- package/dist/lib/server/capabilities-release-projection.mjs +112 -0
- package/dist/lib/server/create-adcp-server.d.mts +29 -5
- package/dist/lib/server/create-adcp-server.d.ts +29 -5
- package/dist/lib/server/create-adcp-server.js +95 -22
- package/dist/lib/server/create-adcp-server.mjs +106 -21
- package/dist/lib/server/decisioning/capabilities.d.mts +27 -0
- package/dist/lib/server/decisioning/capabilities.d.ts +27 -0
- package/dist/lib/server/decisioning/runtime/from-platform.js +99 -27
- package/dist/lib/server/decisioning/runtime/from-platform.mjs +103 -27
- package/dist/lib/server/declared-input-schema.d.mts +108 -0
- package/dist/lib/server/declared-input-schema.d.ts +108 -0
- package/dist/lib/server/declared-input-schema.js +167 -0
- package/dist/lib/server/declared-input-schema.mjs +137 -0
- package/dist/lib/server/envelope-allowlist.d.mts +1 -105
- package/dist/lib/server/envelope-allowlist.d.ts +1 -105
- package/dist/lib/server/envelope-allowlist.js +3 -79
- package/dist/lib/server/envelope-allowlist.mjs +1 -71
- package/dist/lib/server/errors.d.mts +1 -186
- package/dist/lib/server/errors.d.ts +1 -186
- package/dist/lib/server/errors.js +3 -98
- package/dist/lib/server/errors.mjs +1 -94
- package/dist/lib/server/index.d.mts +1 -1
- package/dist/lib/server/index.d.ts +1 -1
- package/dist/lib/server/mcp-modern-server.js +21 -4
- package/dist/lib/server/mcp-modern-server.mjs +21 -4
- package/dist/lib/server/media-buy-action-resolver.d.mts +7 -0
- package/dist/lib/server/media-buy-action-resolver.d.ts +7 -0
- package/dist/lib/server/media-buy-action-resolver.js +10 -1
- package/dist/lib/server/media-buy-action-resolver.mjs +10 -1
- package/dist/lib/server/media-buy-helpers.d.mts +1 -47
- package/dist/lib/server/media-buy-helpers.d.ts +1 -47
- package/dist/lib/server/media-buy-helpers.js +3 -23
- package/dist/lib/server/media-buy-helpers.mjs +1 -18
- package/dist/lib/server/pick-safe-details.d.mts +1 -89
- package/dist/lib/server/pick-safe-details.d.ts +1 -89
- package/dist/lib/server/pick-safe-details.js +3 -61
- package/dist/lib/server/pick-safe-details.mjs +1 -56
- package/dist/lib/server/pin-and-bind-fetch.d.mts +1 -121
- package/dist/lib/server/pin-and-bind-fetch.d.ts +1 -121
- package/dist/lib/server/pin-and-bind-fetch.js +3 -190
- package/dist/lib/server/pin-and-bind-fetch.mjs +1 -183
- package/dist/lib/server/targeting-helpers.d.mts +1 -123
- package/dist/lib/server/targeting-helpers.d.ts +1 -123
- package/dist/lib/server/targeting-helpers.js +3 -393
- package/dist/lib/server/targeting-helpers.mjs +1 -370
- package/dist/lib/server/test-controller.js +7 -3
- package/dist/lib/server/test-controller.mjs +7 -3
- package/dist/lib/storage/memory-ledger.js +219 -1
- package/dist/lib/storage/memory-ledger.mjs +223 -1
- package/dist/lib/testing/compliance/storyboard-tracks.js +0 -4
- package/dist/lib/testing/compliance/storyboard-tracks.mjs +0 -4
- package/dist/lib/testing/comply-controller.js +7 -2
- package/dist/lib/testing/comply-controller.mjs +7 -2
- package/dist/lib/testing/storyboard/request-signing/grader.d.mts +21 -0
- package/dist/lib/testing/storyboard/request-signing/grader.d.ts +21 -0
- package/dist/lib/testing/storyboard/request-signing/grader.js +31 -0
- package/dist/lib/testing/storyboard/request-signing/grader.mjs +30 -0
- package/dist/lib/testing/storyboard/request-signing/probe-dispatch.js +1 -1
- package/dist/lib/testing/storyboard/request-signing/probe-dispatch.mjs +2 -1
- package/dist/lib/testing/storyboard/request-signing/types.d.mts +12 -0
- package/dist/lib/testing/storyboard/request-signing/types.d.ts +12 -0
- package/dist/lib/testing/storyboard/request-signing/vector-loader.js +7 -2
- package/dist/lib/testing/storyboard/request-signing/vector-loader.mjs +7 -2
- package/dist/lib/testing/storyboard/runner.js +2 -2
- package/dist/lib/testing/storyboard/runner.mjs +2 -2
- package/dist/lib/testing/storyboard/validations.d.mts +1 -1
- package/dist/lib/testing/storyboard/validations.d.ts +1 -1
- package/dist/lib/utils/adcp-error-response.d.mts +196 -0
- package/dist/lib/utils/adcp-error-response.d.ts +196 -0
- package/dist/lib/utils/adcp-error-response.js +118 -0
- package/dist/lib/utils/adcp-error-response.mjs +95 -0
- package/dist/lib/utils/buyer-retry-policy.js +2 -2
- package/dist/lib/utils/buyer-retry-policy.mjs +1 -1
- package/dist/lib/utils/capabilities.d.mts +6 -0
- package/dist/lib/utils/capabilities.d.ts +6 -0
- package/dist/lib/utils/capabilities.js +6 -2
- package/dist/lib/utils/capabilities.mjs +6 -2
- package/dist/lib/utils/envelope-allowlist.d.mts +105 -0
- package/dist/lib/utils/envelope-allowlist.d.ts +105 -0
- package/dist/lib/utils/envelope-allowlist.js +98 -0
- package/dist/lib/utils/envelope-allowlist.mjs +71 -0
- package/dist/lib/utils/pick-safe-details.d.mts +89 -0
- package/dist/lib/utils/pick-safe-details.d.ts +89 -0
- package/dist/lib/utils/pick-safe-details.js +80 -0
- package/dist/lib/utils/pick-safe-details.mjs +56 -0
- package/dist/lib/v2/projection/augment-response.d.mts +4 -0
- package/dist/lib/v2/projection/augment-response.d.ts +4 -0
- package/dist/lib/v2/projection/creative-delivery.d.mts +20 -3
- package/dist/lib/v2/projection/creative-delivery.d.ts +20 -3
- package/dist/lib/v2/projection/creative-delivery.js +20 -4
- package/dist/lib/v2/projection/creative-delivery.mjs +19 -4
- package/dist/lib/v2/projection/index.d.mts +2 -2
- package/dist/lib/v2/projection/index.d.ts +2 -2
- package/dist/lib/v2/projection/index.js +4 -0
- package/dist/lib/v2/projection/index.mjs +5 -1
- package/dist/lib/v2/projection/legacy-metadata.d.mts +7 -0
- package/dist/lib/v2/projection/legacy-metadata.d.ts +7 -0
- package/dist/lib/v2/projection/legacy-metadata.js +14 -0
- package/dist/lib/v2/projection/legacy-metadata.mjs +12 -0
- package/dist/lib/v2/projection/legacy-routes.d.mts +11 -0
- package/dist/lib/v2/projection/legacy-routes.d.ts +11 -0
- package/dist/lib/v2/projection/legacy-routes.js +2 -1
- package/dist/lib/v2/projection/legacy-routes.mjs +7 -2
- package/dist/lib/v2/projection/v1-to-v2.d.mts +21 -1
- package/dist/lib/v2/projection/v1-to-v2.d.ts +21 -1
- package/dist/lib/v2/projection/v1-to-v2.js +18 -11
- package/dist/lib/v2/projection/v1-to-v2.mjs +19 -11
- package/dist/lib/version.d.mts +3 -3
- package/dist/lib/version.d.ts +3 -3
- package/dist/lib/version.js +3 -3
- package/dist/lib/version.mjs +3 -3
- package/docs/TYPE-SUMMARY.md +2 -2
- package/docs/guides/CREATIVE-DELIVERY.md +12 -0
- package/docs/guides/REPORTING-LEDGER.md +121 -0
- package/docs/guides/VALIDATE-YOUR-AGENT.md +1 -0
- package/docs/llms.txt +2 -2
- package/docs/migration-14.x-rc-worksheet.md +4 -4
- package/docs/migration-16-to-17.md +149 -0
- package/docs/migration-reporting-storage-package.md +10 -0
- 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 && (
|
|
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 =
|
|
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 && (
|
|
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 =
|
|
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.
|
|
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.
|
|
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;
|