@adcp/sdk 17.0.0-beta.26 → 17.0.0-beta.28
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/bin/adcp-storyboard-summary.js +47 -0
- package/bin/adcp.js +4 -0
- package/dist/lib/discovery/agent-directory.d.mts +10 -3
- package/dist/lib/discovery/agent-directory.d.ts +10 -3
- package/dist/lib/discovery/resolve-agent-properties.d.mts +94 -5
- package/dist/lib/discovery/resolve-agent-properties.d.ts +94 -5
- package/dist/lib/discovery/resolve-agent-properties.js +61 -0
- package/dist/lib/discovery/resolve-agent-properties.mjs +60 -0
- package/dist/lib/discovery/types.d.mts +14 -0
- package/dist/lib/discovery/types.d.ts +14 -0
- package/dist/lib/entrypoints/discovery.d.mts +1 -1
- package/dist/lib/entrypoints/discovery.d.ts +1 -1
- package/dist/lib/entrypoints/discovery.js +2 -0
- package/dist/lib/entrypoints/discovery.mjs +3 -1
- package/dist/lib/index.d.mts +1 -1
- package/dist/lib/index.d.ts +1 -1
- package/dist/lib/index.js +2 -0
- package/dist/lib/index.mjs +3 -1
- package/dist/lib/registry/types.generated.d.ts +8 -6
- package/dist/lib/testing/compliance/comply.d.mts +16 -1
- package/dist/lib/testing/compliance/comply.d.ts +16 -1
- package/dist/lib/testing/compliance/comply.js +77 -6
- package/dist/lib/testing/compliance/comply.mjs +83 -7
- package/dist/lib/testing/compliance/index.d.mts +1 -1
- package/dist/lib/testing/compliance/index.d.ts +1 -1
- package/dist/lib/testing/compliance/storyboard-tracks.d.mts +6 -0
- package/dist/lib/testing/compliance/storyboard-tracks.d.ts +6 -0
- package/dist/lib/testing/compliance/storyboard-tracks.js +26 -4
- package/dist/lib/testing/compliance/storyboard-tracks.mjs +24 -3
- package/dist/lib/testing/compliance/summary.d.mts +3 -1
- package/dist/lib/testing/compliance/summary.d.ts +3 -1
- package/dist/lib/testing/compliance/summary.js +2 -1
- package/dist/lib/testing/compliance/summary.mjs +2 -1
- package/dist/lib/testing/compliance/types.d.mts +30 -1
- package/dist/lib/testing/compliance/types.d.ts +30 -1
- package/dist/lib/testing/index.d.mts +1 -1
- package/dist/lib/testing/index.d.ts +1 -1
- package/dist/lib/testing/index.js +4 -0
- package/dist/lib/testing/index.mjs +4 -0
- package/dist/lib/testing/storyboard/index.d.mts +4 -2
- package/dist/lib/testing/storyboard/index.d.ts +4 -2
- package/dist/lib/testing/storyboard/index.js +7 -0
- package/dist/lib/testing/storyboard/index.mjs +6 -1
- package/dist/lib/testing/storyboard/runner.d.mts +7 -0
- package/dist/lib/testing/storyboard/runner.d.ts +7 -0
- package/dist/lib/testing/storyboard/runner.js +15 -0
- package/dist/lib/testing/storyboard/runner.mjs +14 -0
- package/dist/lib/testing/storyboard/types.d.mts +77 -0
- package/dist/lib/testing/storyboard/types.d.ts +77 -0
- package/dist/lib/testing/storyboard/validations.d.mts +1 -1
- package/dist/lib/testing/storyboard/validations.d.ts +1 -1
- package/dist/lib/testing/storyboard/verdict-explanation.d.mts +47 -0
- package/dist/lib/testing/storyboard/verdict-explanation.d.ts +47 -0
- package/dist/lib/testing/storyboard/verdict-explanation.js +309 -0
- package/dist/lib/testing/storyboard/verdict-explanation.mjs +283 -0
- package/dist/lib/testing/types.d.mts +11 -1
- package/dist/lib/testing/types.d.ts +11 -1
- 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/VALIDATE-YOUR-AGENT.md +28 -0
- package/docs/llms.txt +2 -2
- package/docs/migration-14.x-rc-worksheet.md +4 -4
- package/docs/migration-16-to-17.md +7 -1
- package/docs/migration-agent-resolution-3.3.md +18 -0
- package/package.json +1 -1
|
@@ -0,0 +1,283 @@
|
|
|
1
|
+
const CONTROLLER_SEEDING_PHASE_ID = "__controller_seeding__";
|
|
2
|
+
const FIXTURE_PHASE_IDS = /* @__PURE__ */ new Set(["fixture_resolution", "prepared_fixtures_preparation_failed"]);
|
|
3
|
+
const RUNNER_ERROR_CHECKS = /* @__PURE__ */ new Set(["prepared_fixtures_authorization"]);
|
|
4
|
+
const CONTROLLER_SKIP_REASONS = /* @__PURE__ */ new Set(["missing_test_controller", "controller_seeding_failed"]);
|
|
5
|
+
const CONTROLLER_REQUIREMENTS = /* @__PURE__ */ new Set(["controller", "seeded_state"]);
|
|
6
|
+
const NEUTRAL_SKIP_REASONS = /* @__PURE__ */ new Set([
|
|
7
|
+
"not_applicable",
|
|
8
|
+
"peer_branch_taken",
|
|
9
|
+
"peer_substituted",
|
|
10
|
+
"missing_test_kit_contract",
|
|
11
|
+
"fixture_unavailable",
|
|
12
|
+
"fixture_unsatisfied",
|
|
13
|
+
"fixture_seed_unsupported",
|
|
14
|
+
"capability_unsupported"
|
|
15
|
+
]);
|
|
16
|
+
const REASON_PRECEDENCE = [
|
|
17
|
+
"runner_error",
|
|
18
|
+
"step_failed",
|
|
19
|
+
"fixture_error",
|
|
20
|
+
"assertion_failed",
|
|
21
|
+
"controller_prerequisite_unmet",
|
|
22
|
+
"required_phase_not_executed",
|
|
23
|
+
"no_executed_steps",
|
|
24
|
+
"coverage_unverified"
|
|
25
|
+
];
|
|
26
|
+
const MAX_CONTRIBUTORS = 20;
|
|
27
|
+
const MAX_MESSAGE_LENGTH = 300;
|
|
28
|
+
const MAX_DETAIL_LENGTH = 600;
|
|
29
|
+
function explainStoryboardVerdict(result, options = {}) {
|
|
30
|
+
if (result.overall_passed) return void 0;
|
|
31
|
+
const knownPhases = options.storyboard?.phases ?? [];
|
|
32
|
+
const optionalPhaseIds = new Set(knownPhases.filter((phase) => phase.optional === true).map((phase) => phase.id));
|
|
33
|
+
const optionalOnly = knownPhases.length > 0 && knownPhases.every((phase) => phase.optional === true);
|
|
34
|
+
const isOptionalPhase = (phaseId) => optionalPhaseIds.has(phaseId);
|
|
35
|
+
const phaseViews = result.passes?.length ? result.passes.flatMap((pass) => pass.phases.map((phase) => ({ phase, passIndex: pass.pass_index }))) : result.phases.map((phase) => ({ phase }));
|
|
36
|
+
const contributors = [];
|
|
37
|
+
const add = (row) => {
|
|
38
|
+
contributors.push(row);
|
|
39
|
+
};
|
|
40
|
+
const countedFailures = /* @__PURE__ */ new Set();
|
|
41
|
+
const uncountedFailures = [];
|
|
42
|
+
for (const view of phaseViews) {
|
|
43
|
+
const { phase, passIndex } = view;
|
|
44
|
+
for (const step of phase.steps) {
|
|
45
|
+
if (step.passed || step.skipped) continue;
|
|
46
|
+
if (step.counts_toward_failure === false || isOptionalPhase(phase.phase_id)) {
|
|
47
|
+
uncountedFailures.push({ view, step });
|
|
48
|
+
continue;
|
|
49
|
+
}
|
|
50
|
+
countedFailures.add(step);
|
|
51
|
+
add({
|
|
52
|
+
kind: "step",
|
|
53
|
+
id: step.step_id,
|
|
54
|
+
reason: classifyFailedStep(phase, step),
|
|
55
|
+
status: "failed",
|
|
56
|
+
phase_id: phase.phase_id,
|
|
57
|
+
...passIndex !== void 0 && { pass_index: passIndex },
|
|
58
|
+
...messageOf(step.error ?? firstFailedValidationMessage(step))
|
|
59
|
+
});
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
const assertionOwners = /* @__PURE__ */ new Set();
|
|
63
|
+
for (const assertion of result.assertions ?? []) {
|
|
64
|
+
if (assertion.passed) continue;
|
|
65
|
+
const owner = assertion.scope === "step" ? findOwningStep(result, phaseViews, assertion) : void 0;
|
|
66
|
+
if (owner) assertionOwners.add(owner);
|
|
67
|
+
if (owner && countedFailures.has(owner)) continue;
|
|
68
|
+
add({
|
|
69
|
+
kind: "assertion",
|
|
70
|
+
id: assertion.assertion_id,
|
|
71
|
+
reason: "assertion_failed",
|
|
72
|
+
status: "failed",
|
|
73
|
+
...owner && { phase_id: owner.phase_id },
|
|
74
|
+
...assertion.pass_index !== void 0 && { pass_index: assertion.pass_index },
|
|
75
|
+
...messageOf(assertionMessage(assertion, owner))
|
|
76
|
+
});
|
|
77
|
+
}
|
|
78
|
+
const namedUncounted = /* @__PURE__ */ new Set();
|
|
79
|
+
const ungradedUncounted = [];
|
|
80
|
+
const uncountedRow = ({
|
|
81
|
+
view,
|
|
82
|
+
step
|
|
83
|
+
}) => ({
|
|
84
|
+
kind: "step",
|
|
85
|
+
id: step.step_id,
|
|
86
|
+
reason: "step_failed",
|
|
87
|
+
status: "failed",
|
|
88
|
+
phase_id: view.phase.phase_id,
|
|
89
|
+
...view.passIndex !== void 0 && { pass_index: view.passIndex },
|
|
90
|
+
...messageOf(step.error ?? firstFailedValidationMessage(step))
|
|
91
|
+
});
|
|
92
|
+
for (const failure of uncountedFailures) {
|
|
93
|
+
if (failure.view.phase.passed || assertionOwners.has(failure.step)) continue;
|
|
94
|
+
if (isOptionalPhase(failure.view.phase.phase_id) && !optionalOnly) {
|
|
95
|
+
ungradedUncounted.push(failure);
|
|
96
|
+
continue;
|
|
97
|
+
}
|
|
98
|
+
namedUncounted.add(failure.step);
|
|
99
|
+
add(uncountedRow(failure));
|
|
100
|
+
}
|
|
101
|
+
let requiredPhaseHasExecutedPass = false;
|
|
102
|
+
const vacuousSkips = [];
|
|
103
|
+
for (const view of phaseViews) {
|
|
104
|
+
const { phase, passIndex } = view;
|
|
105
|
+
if (isSyntheticPhase(phase.phase_id) || isOptionalPhase(phase.phase_id) && !optionalOnly) continue;
|
|
106
|
+
if (phase.passed) {
|
|
107
|
+
if (phase.steps.some((step) => !step.skipped && step.passed)) requiredPhaseHasExecutedPass = true;
|
|
108
|
+
for (const step of phase.steps) if (step.skipped) vacuousSkips.push({ view, step });
|
|
109
|
+
continue;
|
|
110
|
+
}
|
|
111
|
+
if (phase.steps.some((step) => countedFailures.has(step) || namedUncounted.has(step) || assertionOwners.has(step))) {
|
|
112
|
+
continue;
|
|
113
|
+
}
|
|
114
|
+
const skipped = phase.steps.filter((step) => step.skipped);
|
|
115
|
+
const causal = skipped.filter((step) => !NEUTRAL_SKIP_REASONS.has(detailedSkipReason(step) ?? ""));
|
|
116
|
+
const named = causal.length > 0 ? causal : skipped;
|
|
117
|
+
if (named.length === 0) {
|
|
118
|
+
add({
|
|
119
|
+
kind: "phase",
|
|
120
|
+
id: phase.phase_id,
|
|
121
|
+
reason: "required_phase_not_executed",
|
|
122
|
+
status: "not_passed",
|
|
123
|
+
phase_id: phase.phase_id,
|
|
124
|
+
...passIndex !== void 0 && { pass_index: passIndex },
|
|
125
|
+
message: `Phase '${phase.phase_id}' did not pass`
|
|
126
|
+
});
|
|
127
|
+
continue;
|
|
128
|
+
}
|
|
129
|
+
for (const step of named) add(skippedStepContributor(phase, step, passIndex));
|
|
130
|
+
}
|
|
131
|
+
if (contributors.length === 0 && !requiredPhaseHasExecutedPass) {
|
|
132
|
+
const named = vacuousSkips.filter(({ step }) => !NEUTRAL_SKIP_REASONS.has(detailedSkipReason(step) ?? ""));
|
|
133
|
+
for (const { view, step } of named.length > 0 ? named : vacuousSkips) {
|
|
134
|
+
const row = skippedStepContributor(view.phase, step, view.passIndex);
|
|
135
|
+
add(row.reason === "required_phase_not_executed" ? { ...row, reason: "no_executed_steps" } : row);
|
|
136
|
+
}
|
|
137
|
+
if (contributors.length === 0 && !options.coverageUnverified) {
|
|
138
|
+
add({
|
|
139
|
+
kind: "phase",
|
|
140
|
+
id: "storyboard",
|
|
141
|
+
reason: "no_executed_steps",
|
|
142
|
+
status: "not_passed",
|
|
143
|
+
message: "No required step executed and passed"
|
|
144
|
+
});
|
|
145
|
+
}
|
|
146
|
+
}
|
|
147
|
+
if (options.coverageUnverified) {
|
|
148
|
+
const probes = phaseViews.flatMap(
|
|
149
|
+
({ phase, passIndex }) => phase.steps.filter((step) => step.skipped).map((step) => ({ phase, step, passIndex }))
|
|
150
|
+
);
|
|
151
|
+
if (probes.length === 0) {
|
|
152
|
+
add({
|
|
153
|
+
kind: "phase",
|
|
154
|
+
id: "storyboard",
|
|
155
|
+
reason: "coverage_unverified",
|
|
156
|
+
status: "not_passed",
|
|
157
|
+
message: "No request-signing probe reached the agent"
|
|
158
|
+
});
|
|
159
|
+
}
|
|
160
|
+
for (const { phase, step, passIndex } of probes) {
|
|
161
|
+
add({ ...skippedStepContributor(phase, step, passIndex), reason: "coverage_unverified" });
|
|
162
|
+
}
|
|
163
|
+
}
|
|
164
|
+
if (contributors.length === 0) for (const failure of ungradedUncounted) add(uncountedRow(failure));
|
|
165
|
+
const reason = REASON_PRECEDENCE.find((candidate) => contributors.some((row) => row.reason === candidate)) ?? "unexplained";
|
|
166
|
+
const bounded = contributors.slice(0, MAX_CONTRIBUTORS);
|
|
167
|
+
return {
|
|
168
|
+
verdict_reason: reason,
|
|
169
|
+
verdict_detail: buildDetail(reason, contributors),
|
|
170
|
+
verdict_contributing: bounded
|
|
171
|
+
};
|
|
172
|
+
}
|
|
173
|
+
function applyStoryboardVerdictExplanation(result, options = {}) {
|
|
174
|
+
delete result.verdict_reason;
|
|
175
|
+
delete result.verdict_detail;
|
|
176
|
+
delete result.verdict_contributing;
|
|
177
|
+
const explanation = explainStoryboardVerdict(result, options);
|
|
178
|
+
if (explanation) Object.assign(result, explanation);
|
|
179
|
+
return result;
|
|
180
|
+
}
|
|
181
|
+
function classifyFailedStep(phase, step) {
|
|
182
|
+
if (step.validations.some((validation) => !validation.passed && RUNNER_ERROR_CHECKS.has(validation.check))) {
|
|
183
|
+
return "runner_error";
|
|
184
|
+
}
|
|
185
|
+
if (phase.phase_id === CONTROLLER_SEEDING_PHASE_ID) return "controller_prerequisite_unmet";
|
|
186
|
+
if (FIXTURE_PHASE_IDS.has(phase.phase_id)) return "fixture_error";
|
|
187
|
+
return "step_failed";
|
|
188
|
+
}
|
|
189
|
+
function skippedStepContributor(phase, step, passIndex) {
|
|
190
|
+
const skipReason = detailedSkipReason(step);
|
|
191
|
+
const requirement = step.skip?.requirement;
|
|
192
|
+
const controllerGap = skipReason !== void 0 && CONTROLLER_SKIP_REASONS.has(skipReason) || requirement !== void 0 && CONTROLLER_REQUIREMENTS.has(requirement);
|
|
193
|
+
return {
|
|
194
|
+
kind: "step",
|
|
195
|
+
id: step.step_id,
|
|
196
|
+
reason: controllerGap ? "controller_prerequisite_unmet" : "required_phase_not_executed",
|
|
197
|
+
status: "skipped",
|
|
198
|
+
phase_id: phase.phase_id,
|
|
199
|
+
...passIndex !== void 0 && { pass_index: passIndex },
|
|
200
|
+
...skipReason !== void 0 && { skip_reason: skipReason },
|
|
201
|
+
...requirement !== void 0 && { requirement },
|
|
202
|
+
...messageOf(step.skip?.detail)
|
|
203
|
+
};
|
|
204
|
+
}
|
|
205
|
+
function detailedSkipReason(step) {
|
|
206
|
+
return step.skip_reason ?? step.skip?.reason;
|
|
207
|
+
}
|
|
208
|
+
function isSyntheticPhase(phaseId) {
|
|
209
|
+
return phaseId === CONTROLLER_SEEDING_PHASE_ID || FIXTURE_PHASE_IDS.has(phaseId);
|
|
210
|
+
}
|
|
211
|
+
function findOwningStep(result, phaseViews, assertion) {
|
|
212
|
+
const phases = assertion.pass_index === void 0 ? result.phases : phaseViews.filter((view) => view.passIndex === assertion.pass_index).map((view) => view.phase);
|
|
213
|
+
for (const phase of phases) {
|
|
214
|
+
const step = phase.steps.find((candidate) => candidate.step_id === assertion.step_id);
|
|
215
|
+
if (step) return step;
|
|
216
|
+
}
|
|
217
|
+
return void 0;
|
|
218
|
+
}
|
|
219
|
+
function assertionMessage(assertion, owner) {
|
|
220
|
+
const base = assertion.error ?? assertion.description;
|
|
221
|
+
if (owner?.skipped) return `${base} (on skipped step '${owner.step_id}')`;
|
|
222
|
+
return base;
|
|
223
|
+
}
|
|
224
|
+
function firstFailedValidationMessage(step) {
|
|
225
|
+
const failed = step.validations.find((validation) => !validation.passed);
|
|
226
|
+
if (!failed) return void 0;
|
|
227
|
+
return failed.error ? `${failed.description}: ${failed.error}` : failed.description;
|
|
228
|
+
}
|
|
229
|
+
function messageOf(text) {
|
|
230
|
+
if (typeof text !== "string") return {};
|
|
231
|
+
const trimmed = text.replace(/\s+/g, " ").trim();
|
|
232
|
+
if (trimmed.length === 0) return {};
|
|
233
|
+
return { message: truncate(trimmed, MAX_MESSAGE_LENGTH) };
|
|
234
|
+
}
|
|
235
|
+
function truncate(text, max) {
|
|
236
|
+
return text.length <= max ? text : `${text.slice(0, max - 1)}\u2026`;
|
|
237
|
+
}
|
|
238
|
+
const REASON_LEADS = {
|
|
239
|
+
step_failed: "A step failed",
|
|
240
|
+
assertion_failed: "A storyboard-level assertion failed",
|
|
241
|
+
controller_prerequisite_unmet: "Required steps did not run because comply_test_controller or its seeding was unavailable",
|
|
242
|
+
required_phase_not_executed: "A required phase did not run",
|
|
243
|
+
no_executed_steps: "No required step executed and passed, so the run proves nothing",
|
|
244
|
+
fixture_error: "Fixture resolution or preparation failed before the behavior under test could run",
|
|
245
|
+
coverage_unverified: "No request-signing probe reached the agent, so signing coverage is unverified",
|
|
246
|
+
runner_error: "The runner or host could not proceed; this is not an agent failure",
|
|
247
|
+
unexplained: "The runner could not attribute this verdict; please report it as a runner bug"
|
|
248
|
+
};
|
|
249
|
+
function buildDetail(reason, contributors) {
|
|
250
|
+
const primary = contributors.filter((row) => row.reason === reason);
|
|
251
|
+
const parts = [REASON_LEADS[reason]];
|
|
252
|
+
const described = primary.slice(0, 3).map(describeContributor);
|
|
253
|
+
if (described.length > 0) parts[0] += `: ${described.join("; ")}`;
|
|
254
|
+
if (primary.length > described.length) parts[0] += ` (+${primary.length - described.length} more)`;
|
|
255
|
+
const others = REASON_PRECEDENCE.filter(
|
|
256
|
+
(candidate) => candidate !== reason && contributors.some((row) => row.reason === candidate)
|
|
257
|
+
);
|
|
258
|
+
if (others.length > 0) parts.push(`Also: ${others.join(", ")}`);
|
|
259
|
+
if (contributors.length > MAX_CONTRIBUTORS) {
|
|
260
|
+
parts.push(`${contributors.length - MAX_CONTRIBUTORS} contributor(s) omitted`);
|
|
261
|
+
}
|
|
262
|
+
return truncate(`${parts.map(stripTrailingPeriods).join(". ")}.`, MAX_DETAIL_LENGTH);
|
|
263
|
+
}
|
|
264
|
+
function stripTrailingPeriods(text) {
|
|
265
|
+
let out = text.trimEnd();
|
|
266
|
+
while (out.endsWith(".")) out = out.slice(0, -1).trimEnd();
|
|
267
|
+
return out;
|
|
268
|
+
}
|
|
269
|
+
function describeContributor(row) {
|
|
270
|
+
const where = row.pass_index !== void 0 ? ` (pass ${row.pass_index})` : "";
|
|
271
|
+
if (row.kind === "assertion") return `${row.id}${where}${row.message ? ` \u2014 ${row.message}` : ""}`;
|
|
272
|
+
if (row.status === "skipped") {
|
|
273
|
+
const why = row.requirement ? `${row.skip_reason ?? "skipped"}: ${row.requirement}` : row.skip_reason ?? "skipped";
|
|
274
|
+
return `${row.id}${where} skipped (${why})`;
|
|
275
|
+
}
|
|
276
|
+
if (row.status === "failed") return `${row.id}${where} failed`;
|
|
277
|
+
return `${row.id}${where}${row.message ? ` \u2014 ${row.message}` : ""}`;
|
|
278
|
+
}
|
|
279
|
+
export {
|
|
280
|
+
CONTROLLER_SEEDING_PHASE_ID,
|
|
281
|
+
applyStoryboardVerdictExplanation,
|
|
282
|
+
explainStoryboardVerdict
|
|
283
|
+
};
|
|
@@ -5,7 +5,7 @@ import type { FormatReferenceStructuredObject as FormatID } from '../types/core.
|
|
|
5
5
|
import type { AdcpVersion } from '../version.mjs';
|
|
6
6
|
import type { TransportOptions, VersionEnvelopeMode } from '../protocols/index.mjs';
|
|
7
7
|
import type { AgentRequestSigningConfig } from '../types/adcp.mjs';
|
|
8
|
-
import type { RunnerRequestRecord, RunnerResponseRecord, RunnerExtractionRecord } from './storyboard/types.mjs';
|
|
8
|
+
import type { RunnerRequestRecord, RunnerResponseRecord, RunnerExtractionRecord, StoryboardVerdictContributor, StoryboardVerdictReason } from './storyboard/types.mjs';
|
|
9
9
|
import type { AuthorizationRequirements } from '../auth/oauth/authorization-required.mjs';
|
|
10
10
|
export type TestScenario = 'health_check' | 'discovery' | 'create_media_buy' | 'full_sales_flow' | 'reporting_flow' | 'creative_sync' | 'creative_inline' | 'creative_reference' | 'pricing_models' | 'creative_flow' | 'creative_lifecycle' | 'signals_flow' | 'error_handling' | 'validation' | 'pricing_edge_cases' | 'temporal_validation' | 'behavior_analysis' | 'response_consistency' | 'governance_property_lists' | 'governance_content_standards' | 'property_list_filters' | 'campaign_governance' | 'campaign_governance_denied' | 'campaign_governance_conditions' | 'campaign_governance_delivery' | 'seller_governance_context' | 'si_session_lifecycle' | 'si_availability' | 'si_handoff' | 'capability_discovery' | 'schema_compliance' | 'sync_audiences' | 'media_buy_lifecycle' | 'terminal_state_enforcement' | 'package_lifecycle' | 'error_codes' | 'error_structure' | 'error_transport' | 'deterministic_creative' | 'deterministic_media_buy' | 'deterministic_account' | 'deterministic_session' | 'deterministic_delivery' | 'deterministic_budget' | 'controller_validation' | 'brand_identity' | 'brand_rights_flow' | 'creative_approval';
|
|
11
11
|
export interface TestOptions {
|
|
@@ -399,6 +399,16 @@ export interface TestResult {
|
|
|
399
399
|
total_duration_ms: number;
|
|
400
400
|
tested_at: string;
|
|
401
401
|
agent_profile?: AgentProfile;
|
|
402
|
+
/**
|
|
403
|
+
* Storyboard-level verdict explanation (adcp#8576). Set only on the
|
|
404
|
+
* synthetic `<storyboard_id>/storyboard` scenario that `comply()` emits
|
|
405
|
+
* when a storyboard fails without a counted failed step. Mirrors
|
|
406
|
+
* `StoryboardResult.verdict_reason` / `verdict_detail` /
|
|
407
|
+
* `verdict_contributing`.
|
|
408
|
+
*/
|
|
409
|
+
verdict_reason?: StoryboardVerdictReason;
|
|
410
|
+
verdict_detail?: string;
|
|
411
|
+
verdict_contributing?: StoryboardVerdictContributor[];
|
|
402
412
|
}
|
|
403
413
|
export interface SuiteResult {
|
|
404
414
|
agent_url: string;
|
|
@@ -5,7 +5,7 @@ import type { FormatReferenceStructuredObject as FormatID } from '../types/core.
|
|
|
5
5
|
import type { AdcpVersion } from '../version';
|
|
6
6
|
import type { TransportOptions, VersionEnvelopeMode } from '../protocols';
|
|
7
7
|
import type { AgentRequestSigningConfig } from '../types/adcp';
|
|
8
|
-
import type { RunnerRequestRecord, RunnerResponseRecord, RunnerExtractionRecord } from './storyboard/types';
|
|
8
|
+
import type { RunnerRequestRecord, RunnerResponseRecord, RunnerExtractionRecord, StoryboardVerdictContributor, StoryboardVerdictReason } from './storyboard/types';
|
|
9
9
|
import type { AuthorizationRequirements } from '../auth/oauth/authorization-required';
|
|
10
10
|
export type TestScenario = 'health_check' | 'discovery' | 'create_media_buy' | 'full_sales_flow' | 'reporting_flow' | 'creative_sync' | 'creative_inline' | 'creative_reference' | 'pricing_models' | 'creative_flow' | 'creative_lifecycle' | 'signals_flow' | 'error_handling' | 'validation' | 'pricing_edge_cases' | 'temporal_validation' | 'behavior_analysis' | 'response_consistency' | 'governance_property_lists' | 'governance_content_standards' | 'property_list_filters' | 'campaign_governance' | 'campaign_governance_denied' | 'campaign_governance_conditions' | 'campaign_governance_delivery' | 'seller_governance_context' | 'si_session_lifecycle' | 'si_availability' | 'si_handoff' | 'capability_discovery' | 'schema_compliance' | 'sync_audiences' | 'media_buy_lifecycle' | 'terminal_state_enforcement' | 'package_lifecycle' | 'error_codes' | 'error_structure' | 'error_transport' | 'deterministic_creative' | 'deterministic_media_buy' | 'deterministic_account' | 'deterministic_session' | 'deterministic_delivery' | 'deterministic_budget' | 'controller_validation' | 'brand_identity' | 'brand_rights_flow' | 'creative_approval';
|
|
11
11
|
export interface TestOptions {
|
|
@@ -399,6 +399,16 @@ export interface TestResult {
|
|
|
399
399
|
total_duration_ms: number;
|
|
400
400
|
tested_at: string;
|
|
401
401
|
agent_profile?: AgentProfile;
|
|
402
|
+
/**
|
|
403
|
+
* Storyboard-level verdict explanation (adcp#8576). Set only on the
|
|
404
|
+
* synthetic `<storyboard_id>/storyboard` scenario that `comply()` emits
|
|
405
|
+
* when a storyboard fails without a counted failed step. Mirrors
|
|
406
|
+
* `StoryboardResult.verdict_reason` / `verdict_detail` /
|
|
407
|
+
* `verdict_contributing`.
|
|
408
|
+
*/
|
|
409
|
+
verdict_reason?: StoryboardVerdictReason;
|
|
410
|
+
verdict_detail?: string;
|
|
411
|
+
verdict_contributing?: StoryboardVerdictContributor[];
|
|
402
412
|
}
|
|
403
413
|
export interface SuiteResult {
|
|
404
414
|
agent_url: string;
|
package/dist/lib/version.d.mts
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* AdCP SDK library version
|
|
3
3
|
*/
|
|
4
|
-
export declare const LIBRARY_VERSION = "17.0.0-beta.
|
|
4
|
+
export declare const LIBRARY_VERSION = "17.0.0-beta.28";
|
|
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.
|
|
36
|
+
readonly library: "17.0.0-beta.28";
|
|
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-
|
|
39
|
+
readonly generatedAt: "2026-11-15T14:00:59.479Z";
|
|
40
40
|
};
|
|
41
41
|
/**
|
|
42
42
|
* Get the AdCP specification version this library is built for
|
package/dist/lib/version.d.ts
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* AdCP SDK library version
|
|
3
3
|
*/
|
|
4
|
-
export declare const LIBRARY_VERSION = "17.0.0-beta.
|
|
4
|
+
export declare const LIBRARY_VERSION = "17.0.0-beta.28";
|
|
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.
|
|
36
|
+
readonly library: "17.0.0-beta.28";
|
|
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-
|
|
39
|
+
readonly generatedAt: "2026-11-15T14:00:59.479Z";
|
|
40
40
|
};
|
|
41
41
|
/**
|
|
42
42
|
* Get the AdCP specification version this library is built for
|
package/dist/lib/version.js
CHANGED
|
@@ -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.
|
|
34
|
+
const LIBRARY_VERSION = "17.0.0-beta.28";
|
|
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.
|
|
112
|
+
library: "17.0.0-beta.28",
|
|
113
113
|
adcp: "3.3.0-beta.6",
|
|
114
114
|
compatibleVersions: COMPATIBLE_ADCP_VERSIONS,
|
|
115
|
-
generatedAt: "2026-11-
|
|
115
|
+
generatedAt: "2026-11-15T14:00:59.479Z"
|
|
116
116
|
};
|
|
117
117
|
function getAdcpVersion() {
|
|
118
118
|
return ADCP_VERSION;
|
package/dist/lib/version.mjs
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
const LIBRARY_VERSION = "17.0.0-beta.
|
|
1
|
+
const LIBRARY_VERSION = "17.0.0-beta.28";
|
|
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.
|
|
79
|
+
library: "17.0.0-beta.28",
|
|
80
80
|
adcp: "3.3.0-beta.6",
|
|
81
81
|
compatibleVersions: COMPATIBLE_ADCP_VERSIONS,
|
|
82
|
-
generatedAt: "2026-11-
|
|
82
|
+
generatedAt: "2026-11-15T14:00:59.479Z"
|
|
83
83
|
};
|
|
84
84
|
function getAdcpVersion() {
|
|
85
85
|
return ADCP_VERSION;
|
package/docs/TYPE-SUMMARY.md
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# AdCP Type Summary
|
|
2
2
|
|
|
3
|
-
> Generated at: 2026-11-
|
|
4
|
-
> @adcp/sdk v17.0.0-beta.
|
|
3
|
+
> Generated at: 2026-11-15
|
|
4
|
+
> @adcp/sdk v17.0.0-beta.28
|
|
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
|
|
|
@@ -161,6 +161,34 @@ All `expect_webhook*` steps require `webhook_receiver` runner support. If the
|
|
|
161
161
|
`triggered_by` step is missing, skipped, or failed, the assertion skips with
|
|
162
162
|
`prerequisite_failed` instead of treating the absence as a passing result.
|
|
163
163
|
|
|
164
|
+
### Why a storyboard failed when no step did
|
|
165
|
+
|
|
166
|
+
A storyboard's verdict (`overall_passed`) can be `false` while every step you
|
|
167
|
+
can see passed or was skipped. Every failing result says why:
|
|
168
|
+
|
|
169
|
+
| Field | Where | Meaning |
|
|
170
|
+
|---|---|---|
|
|
171
|
+
| `verdict_reason` | `StoryboardResult` (`storyboard run --json`), the `<storyboard_id>/storyboard` scenario in `tracks[].scenarios[]` | Primary cause, one of the codes below. Absent on a passing result. |
|
|
172
|
+
| `verdict_detail` | same | One line of runner-authored text. It names failed steps without quoting their errors. |
|
|
173
|
+
| `verdict_contributing[]` | same | Every step, assertion, phase or requirement behind the verdict: `kind`, `id`, `reason`, `status` (`failed` / `skipped` / `not_passed`), and where known `phase_id`, `pass_index`, `skip_reason`, `requirement`, `message`. At most 20 rows. |
|
|
174
|
+
| `verdict_explanations[]` | `ComplianceResult` (full assessment `--json`) | One entry per failing storyboard, with the fields above, `storyboard_level: true` when no `failures[]` row explains it, and a `fix_command` that re-runs the storyboard. |
|
|
175
|
+
|
|
176
|
+
| `verdict_reason` | What happened | What to do |
|
|
177
|
+
|---|---|---|
|
|
178
|
+
| `step_failed` | A step failed. Usually a counted failure; on a storyboard with only optional phases, a failed optional step. | Read that step's `error` and `validations`. |
|
|
179
|
+
| `assertion_failed` | A storyboard-level invariant (for example `status.monotonic`) failed, or an assertion failed on a skipped step. | Read the assertion row's `message`. |
|
|
180
|
+
| `controller_prerequisite_unmet` | Required steps needed `comply_test_controller` or its pre-flight seeding, and it was absent or seeding failed. | Implement the controller scenarios the storyboard names, or fix the seeding error. |
|
|
181
|
+
| `required_phase_not_executed` | A required phase did not pass because its steps were skipped (`prerequisite_failed`, `missing_tool`, `unsatisfied_contract`, `requirement_unmet`, a capability gate). | Follow each row's `skip_reason`. |
|
|
182
|
+
| `no_executed_steps` | Nothing failed, but no required step executed and passed. | Advertise the tools the storyboard needs. |
|
|
183
|
+
| `fixture_error` | Fixture resolution or preparation failed before the behavior under test ran. | Fix the fixture or test kit. |
|
|
184
|
+
| `coverage_unverified` | A request-signing storyboard never reached the agent. | Use a transport the vectors can frame. |
|
|
185
|
+
| `runner_error` | The runner or host refused to proceed. Not an agent failure. | Report it to whoever runs the grader. |
|
|
186
|
+
| `unexplained` | The runner could not attribute the verdict. | Report it as a runner bug. |
|
|
187
|
+
|
|
188
|
+
The fields explain the verdict. They never change `overall_passed`, the counts,
|
|
189
|
+
or any track or bundle grade. The human output of `adcp storyboard run` prints
|
|
190
|
+
the same reason under the summary line (`Why: [...]`).
|
|
191
|
+
|
|
164
192
|
### Running against pre-publish artifacts
|
|
165
193
|
|
|
166
194
|
Use a matching compliance bundle and schema root to validate a protocol build
|
package/docs/llms.txt
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# Ad Context Protocol (AdCP)
|
|
2
2
|
|
|
3
|
-
> Generated at: 2026-11-
|
|
4
|
-
> Library: @adcp/sdk v17.0.0-beta.
|
|
3
|
+
> Generated at: 2026-11-15
|
|
4
|
+
> Library: @adcp/sdk v17.0.0-beta.28
|
|
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.
|
|
@@ -16,8 +16,8 @@ pin using `ADCP_VERSION` inside that tarball.
|
|
|
16
16
|
|
|
17
17
|
| Fact | Value |
|
|
18
18
|
| --- | --- |
|
|
19
|
-
| Checkout `package.json` version | `@adcp/sdk@17.0.0-beta.
|
|
20
|
-
| npm integrity | registry-derived after publication; run `npm view @adcp/sdk@17.0.0-beta.
|
|
19
|
+
| Checkout `package.json` version | `@adcp/sdk@17.0.0-beta.28` |
|
|
20
|
+
| npm integrity | registry-derived after publication; run `npm view @adcp/sdk@17.0.0-beta.28 dist.integrity` |
|
|
21
21
|
| Node.js runtime | `^20.19.0 || >=22.12.0` |
|
|
22
22
|
| Default AdCP wire release | `3.3.0-beta.6` |
|
|
23
23
|
| Maintained wire releases | `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` |
|
|
@@ -26,8 +26,8 @@ pin using `ADCP_VERSION` inside that tarball.
|
|
|
26
26
|
For a checkout at the published release commit, install the exact package version:
|
|
27
27
|
|
|
28
28
|
```bash
|
|
29
|
-
npm install --save-exact '@adcp/sdk@17.0.0-beta.
|
|
30
|
-
npm view '@adcp/sdk@17.0.0-beta.
|
|
29
|
+
npm install --save-exact '@adcp/sdk@17.0.0-beta.28'
|
|
30
|
+
npm view '@adcp/sdk@17.0.0-beta.28' dist.integrity
|
|
31
31
|
```
|
|
32
32
|
|
|
33
33
|
### Required and optional peers
|
|
@@ -171,7 +171,13 @@ now sees a match. Pass the release you negotiated (for example `'3.2'`) to keep
|
|
|
171
171
|
exact canonical-URL matching. At 3.3 every matching entry authorizes the
|
|
172
172
|
agent, and its scope is the union of theirs: an exact entry and an origin-only
|
|
173
173
|
entry for the same agent combine, so a narrower entry never removes scope
|
|
174
|
-
another grants. `matched_entries` lists them all.
|
|
174
|
+
another grants. `matched_entries` lists them all. Their `signing_keys` combine
|
|
175
|
+
by the same reasoning, over the entries that also authorize the signed message's
|
|
176
|
+
scope: the agent is pinned only if every such entry pins, and may then sign with
|
|
177
|
+
any of their keys. The new
|
|
178
|
+
`resolvePublisherSigningKeyPin(adagents, agentUrl, { adcpVersion, country, propertyIds, at })`
|
|
179
|
+
applies that rule
|
|
180
|
+
([adcp#9016](https://github.com/adcontextprotocol/adcp/issues/9016)). Below 3.3, two exact matches
|
|
175
181
|
still fail closed as `ambiguous_agent_url`. `PropertyCrawler`
|
|
176
182
|
uses each agent's served release, else its new `adcpVersion` option.
|
|
177
183
|
Supply-path verification keeps exact matching under semantics version 1
|
|
@@ -92,6 +92,24 @@ successful fetch confirmed removal of the pin. A pinned key must also appear in
|
|
|
92
92
|
the agent JWKS and match by RFC 7638 thumbprint. `kid`-only entries match nothing;
|
|
93
93
|
revoked entries cannot authorize delivery. `key_origins` remains enforced.
|
|
94
94
|
|
|
95
|
+
Build `signingKeys` from the publisher's adagents.json with
|
|
96
|
+
`resolvePublisherSigningKeyPin(adagents, agentUrl, { adcpVersion, country, propertyIds, at })`,
|
|
97
|
+
passing the scope of the signed message. At AdCP 3.3 more than one
|
|
98
|
+
`authorized_agents[]` entry can match one agent, such as an origin-only entry
|
|
99
|
+
and the agent's full URL. Only entries that match the agent and authorize the
|
|
100
|
+
message's scope count. The publisher pins the agent only if every such entry
|
|
101
|
+
carries `signing_keys`, and the pin is then the union of their keys. One such
|
|
102
|
+
entry without `signing_keys` means no pin
|
|
103
|
+
([adcp#9016](https://github.com/adcontextprotocol/adcp/issues/9016)). An entry
|
|
104
|
+
that authorizes nothing for the message never pins or unpins it. A message
|
|
105
|
+
about several properties gets one pin per property, and the key must satisfy
|
|
106
|
+
each.
|
|
107
|
+
|
|
108
|
+
The helper returns `undefined` for no pin, and `[]` (accept no key) when the
|
|
109
|
+
agent is not authorized for the message, so being unauthorized never reads as
|
|
110
|
+
unpinned. Use the same call in `refresh`, returning `null` when it gives
|
|
111
|
+
`undefined`.
|
|
112
|
+
|
|
95
113
|
## Governance
|
|
96
114
|
|
|
97
115
|
Supply `buyerIdentity` for each authenticated request to governance verification
|