@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.
Files changed (68) hide show
  1. package/bin/adcp-storyboard-summary.js +47 -0
  2. package/bin/adcp.js +4 -0
  3. package/dist/lib/discovery/agent-directory.d.mts +10 -3
  4. package/dist/lib/discovery/agent-directory.d.ts +10 -3
  5. package/dist/lib/discovery/resolve-agent-properties.d.mts +94 -5
  6. package/dist/lib/discovery/resolve-agent-properties.d.ts +94 -5
  7. package/dist/lib/discovery/resolve-agent-properties.js +61 -0
  8. package/dist/lib/discovery/resolve-agent-properties.mjs +60 -0
  9. package/dist/lib/discovery/types.d.mts +14 -0
  10. package/dist/lib/discovery/types.d.ts +14 -0
  11. package/dist/lib/entrypoints/discovery.d.mts +1 -1
  12. package/dist/lib/entrypoints/discovery.d.ts +1 -1
  13. package/dist/lib/entrypoints/discovery.js +2 -0
  14. package/dist/lib/entrypoints/discovery.mjs +3 -1
  15. package/dist/lib/index.d.mts +1 -1
  16. package/dist/lib/index.d.ts +1 -1
  17. package/dist/lib/index.js +2 -0
  18. package/dist/lib/index.mjs +3 -1
  19. package/dist/lib/registry/types.generated.d.ts +8 -6
  20. package/dist/lib/testing/compliance/comply.d.mts +16 -1
  21. package/dist/lib/testing/compliance/comply.d.ts +16 -1
  22. package/dist/lib/testing/compliance/comply.js +77 -6
  23. package/dist/lib/testing/compliance/comply.mjs +83 -7
  24. package/dist/lib/testing/compliance/index.d.mts +1 -1
  25. package/dist/lib/testing/compliance/index.d.ts +1 -1
  26. package/dist/lib/testing/compliance/storyboard-tracks.d.mts +6 -0
  27. package/dist/lib/testing/compliance/storyboard-tracks.d.ts +6 -0
  28. package/dist/lib/testing/compliance/storyboard-tracks.js +26 -4
  29. package/dist/lib/testing/compliance/storyboard-tracks.mjs +24 -3
  30. package/dist/lib/testing/compliance/summary.d.mts +3 -1
  31. package/dist/lib/testing/compliance/summary.d.ts +3 -1
  32. package/dist/lib/testing/compliance/summary.js +2 -1
  33. package/dist/lib/testing/compliance/summary.mjs +2 -1
  34. package/dist/lib/testing/compliance/types.d.mts +30 -1
  35. package/dist/lib/testing/compliance/types.d.ts +30 -1
  36. package/dist/lib/testing/index.d.mts +1 -1
  37. package/dist/lib/testing/index.d.ts +1 -1
  38. package/dist/lib/testing/index.js +4 -0
  39. package/dist/lib/testing/index.mjs +4 -0
  40. package/dist/lib/testing/storyboard/index.d.mts +4 -2
  41. package/dist/lib/testing/storyboard/index.d.ts +4 -2
  42. package/dist/lib/testing/storyboard/index.js +7 -0
  43. package/dist/lib/testing/storyboard/index.mjs +6 -1
  44. package/dist/lib/testing/storyboard/runner.d.mts +7 -0
  45. package/dist/lib/testing/storyboard/runner.d.ts +7 -0
  46. package/dist/lib/testing/storyboard/runner.js +15 -0
  47. package/dist/lib/testing/storyboard/runner.mjs +14 -0
  48. package/dist/lib/testing/storyboard/types.d.mts +77 -0
  49. package/dist/lib/testing/storyboard/types.d.ts +77 -0
  50. package/dist/lib/testing/storyboard/validations.d.mts +1 -1
  51. package/dist/lib/testing/storyboard/validations.d.ts +1 -1
  52. package/dist/lib/testing/storyboard/verdict-explanation.d.mts +47 -0
  53. package/dist/lib/testing/storyboard/verdict-explanation.d.ts +47 -0
  54. package/dist/lib/testing/storyboard/verdict-explanation.js +309 -0
  55. package/dist/lib/testing/storyboard/verdict-explanation.mjs +283 -0
  56. package/dist/lib/testing/types.d.mts +11 -1
  57. package/dist/lib/testing/types.d.ts +11 -1
  58. package/dist/lib/version.d.mts +3 -3
  59. package/dist/lib/version.d.ts +3 -3
  60. package/dist/lib/version.js +3 -3
  61. package/dist/lib/version.mjs +3 -3
  62. package/docs/TYPE-SUMMARY.md +2 -2
  63. package/docs/guides/VALIDATE-YOUR-AGENT.md +28 -0
  64. package/docs/llms.txt +2 -2
  65. package/docs/migration-14.x-rc-worksheet.md +4 -4
  66. package/docs/migration-16-to-17.md +7 -1
  67. package/docs/migration-agent-resolution-3.3.md +18 -0
  68. package/package.json +1 -1
package/dist/lib/index.js CHANGED
@@ -648,6 +648,7 @@ __export(index_exports, {
648
648
  resolveInlinePublisherProperties: () => import_inline_publisher_properties.resolveInlinePublisherProperties,
649
649
  resolvePlatformExtensionsReference: () => import_canonical_references.resolvePlatformExtensionsReference,
650
650
  resolvePreviewAuthority: () => import_preview_authority.resolvePreviewAuthority,
651
+ resolvePublisherSigningKeyPin: () => import_resolve_agent_properties.resolvePublisherSigningKeyPin,
651
652
  resolveRecovery: () => import_error_extraction.resolveRecovery,
652
653
  resolveSecret: () => import_oauth4.resolveSecret,
653
654
  resolveSingularInline: () => import_inline_publisher_properties.resolveSingularInline,
@@ -1520,6 +1521,7 @@ function createAdCPClientFromEnv() {
1520
1521
  resolveInlinePublisherProperties,
1521
1522
  resolvePlatformExtensionsReference,
1522
1523
  resolvePreviewAuthority,
1524
+ resolvePublisherSigningKeyPin,
1523
1525
  resolveRecovery,
1524
1526
  resolveSecret,
1525
1527
  resolveSingularInline,
@@ -59,7 +59,8 @@ import {
59
59
  getAllProperties,
60
60
  canonicalizeAgentUrl,
61
61
  agentUrlMatchesAuthorizedEntry,
62
- usesOriginOnlyAgentMatching
62
+ usesOriginOnlyAgentMatching,
63
+ resolvePublisherSigningKeyPin
63
64
  } from "./discovery/resolve-agent-properties.mjs";
64
65
  import {
65
66
  resolveInlinePublisherProperties,
@@ -1479,6 +1480,7 @@ export {
1479
1480
  resolveInlinePublisherProperties,
1480
1481
  resolvePlatformExtensionsReference,
1481
1482
  resolvePreviewAuthority,
1483
+ resolvePublisherSigningKeyPin,
1482
1484
  resolveRecovery,
1483
1485
  resolveSecret,
1484
1486
  resolveSingularInline,
@@ -544,7 +544,7 @@ export interface paths {
544
544
  };
545
545
  /**
546
546
  * Agent domain lookup
547
- * @description Get all publisher domains associated with an agent.
547
+ * @description Get all publisher domains whose adagents.json authorizes an agent. `agentUrl` is matched with the [adagents.json agent URL matching](/docs/governance/property/adagents#agent-url-matching) rule: an origin-only `authorized_agents[].url` (`https://agent.example.com`) authorizes every agent URL at that origin, and an entry with a path matches that canonical URL only, with a non-root trailing slash significant.
548
548
  */
549
549
  get: operations["getAgentDomains"];
550
550
  put?: never;
@@ -568,7 +568,7 @@ export interface paths {
568
568
  *
569
569
  * Spec: [docs/aao/directory-api.mdx](/docs/aao/directory-api) (adcp#4823). This endpoint is the spec-compliant richer-shape replacement for the legacy `/api/registry/lookup/agent/{agentUrl}/domains`, which returns domain strings only.
570
570
  *
571
- * `agent_url` is matched with [AdCP URL canonicalization](/docs/reference/url-canonicalization) and a **non-root trailing slash is significant**: `https://a.example/mcp` and `https://a.example/mcp/` are different agents and can return different publisher sets, the same rule the SDK applies in `verify_agent_authorization`. Ask for the spelling the publisher's adagents.json lists. (Through 2026-10-18 this endpoint folded the two spellings together and answered both with the slashless agent's publishers; that disagreed with the spec and with the validator.) The `agent_url` in the response echoes the canonicalized lookup key, slash included.
571
+ * `agent_url` is matched with the [adagents.json agent URL matching](/docs/governance/property/adagents#agent-url-matching) rule, after [AdCP URL canonicalization](/docs/reference/url-canonicalization) of both sides. A publisher whose `authorized_agents[].url` is **origin-only** (`https://a.example` or `https://a.example/`) authorizes every agent URL with that canonical origin (same scheme, host and port), so it is returned for `https://a.example/mcp` and `https://a.example/a2a` alike (DR-0023, AdCP 3.3). An entry **with a path** matches that canonical URL only, and a **non-root trailing slash is significant**: `https://a.example/mcp` and `https://a.example/mcp/` are different agents and can return different publisher sets. Ask for the spelling the publisher's adagents.json lists. (Through 2026-10-18 this endpoint folded the two trailing-slash spellings together and answered both with the slashless agent's publishers; that disagreed with the spec and with the validator.) The `agent_url` in the response echoes the canonicalized lookup key, slash included.
572
572
  */
573
573
  get: operations["getPublishersForAgentLegacyApiPrefix"];
574
574
  put?: never;
@@ -592,7 +592,7 @@ export interface paths {
592
592
  *
593
593
  * Spec: [docs/aao/directory-api.mdx](/docs/aao/directory-api) (adcp#4823). This endpoint is the spec-compliant richer-shape replacement for the legacy `/api/registry/lookup/agent/{agentUrl}/domains`, which returns domain strings only.
594
594
  *
595
- * `agent_url` is matched with [AdCP URL canonicalization](/docs/reference/url-canonicalization) and a **non-root trailing slash is significant**: `https://a.example/mcp` and `https://a.example/mcp/` are different agents and can return different publisher sets, the same rule the SDK applies in `verify_agent_authorization`. Ask for the spelling the publisher's adagents.json lists. (Through 2026-10-18 this endpoint folded the two spellings together and answered both with the slashless agent's publishers; that disagreed with the spec and with the validator.) The `agent_url` in the response echoes the canonicalized lookup key, slash included.
595
+ * `agent_url` is matched with the [adagents.json agent URL matching](/docs/governance/property/adagents#agent-url-matching) rule, after [AdCP URL canonicalization](/docs/reference/url-canonicalization) of both sides. A publisher whose `authorized_agents[].url` is **origin-only** (`https://a.example` or `https://a.example/`) authorizes every agent URL with that canonical origin (same scheme, host and port), so it is returned for `https://a.example/mcp` and `https://a.example/a2a` alike (DR-0023, AdCP 3.3). An entry **with a path** matches that canonical URL only, and a **non-root trailing slash is significant**: `https://a.example/mcp` and `https://a.example/mcp/` are different agents and can return different publisher sets. Ask for the spelling the publisher's adagents.json lists. (Through 2026-10-18 this endpoint folded the two trailing-slash spellings together and answered both with the slashless agent's publishers; that disagreed with the spec and with the validator.) The `agent_url` in the response echoes the canonicalized lookup key, slash included.
596
596
  */
597
597
  get: operations["getPublishersForAgent"];
598
598
  put?: never;
@@ -2582,7 +2582,7 @@ export interface components {
2582
2582
  stats?: components["schemas"]["AgentStats"];
2583
2583
  capabilities?: components["schemas"]["AgentCapabilities"];
2584
2584
  compliance?: components["schemas"]["AgentCompliance"];
2585
- /** @description Every raw agent_url spelling the directory has indexed under this agent's identity, with the listed (canonical) url first. The registry keys an agent by identity, folding a non-root trailing slash, but GET /v1/agents/{agent_url}/publishers matches spec-exactly with the slash significant — so a client answering "which publishers authorize this agent" must query once per spelling here and merge the results. */
2585
+ /** @description Every raw agent_url spelling the directory has indexed under this agent's identity, with the listed (canonical) url first. The registry keys an agent by identity, folding a non-root trailing slash, but GET /v1/agents/{agent_url}/publishers matches with adagents.json agent URL matching, where the slash is significant for an entry with a path — so a client answering "which publishers authorize this agent" must query once per spelling here and merge the results. Publishers that authorize the agent's bare origin are returned for every spelling. */
2586
2586
  declared_urls?: string[];
2587
2587
  publisher_domains?: string[];
2588
2588
  property_summary?: components["schemas"]["PropertySummary"];
@@ -6576,6 +6576,7 @@ export interface operations {
6576
6576
  properties_total: number;
6577
6577
  /** @description Canonical list of property_id strings the agent is authorized for under this publisher. Present iff the request included `?include=properties`. Same population as `properties_authorized` but surfaced as IDs for set-diff comparison. */
6578
6578
  property_ids?: string[];
6579
+ /** @description Scope-agnostic summary: true only when every in-window authorized_agents entry that matches the agent carries signing_keys. Verifiers compute the pin per message scope, so a pin can apply where this reads false. */
6579
6580
  signing_keys_pinned: boolean;
6580
6581
  /** @enum {string} */
6581
6582
  status: "authorized" | "revoked";
@@ -6658,6 +6659,7 @@ export interface operations {
6658
6659
  properties_total: number;
6659
6660
  /** @description Canonical list of property_id strings the agent is authorized for under this publisher. Present iff the request included `?include=properties`. Same population as `properties_authorized` but surfaced as IDs for set-diff comparison. */
6660
6661
  property_ids?: string[];
6662
+ /** @description Scope-agnostic summary: true only when every in-window authorized_agents entry that matches the agent carries signing_keys. Verifiers compute the pin per message scope, so a pin can apply where this reads false. */
6661
6663
  signing_keys_pinned: boolean;
6662
6664
  /** @enum {string} */
6663
6665
  status: "authorized" | "revoked";
@@ -8781,7 +8783,7 @@ export interface operations {
8781
8783
  getAgentAuthorizations: {
8782
8784
  parameters: {
8783
8785
  query: {
8784
- /** @description Agent URL to look up. Canonicalized server-side per AdCP URL canonicalization: the scheme and host fold, the path does not. */
8786
+ /** @description Agent URL to look up. Canonicalized server-side per AdCP URL canonicalization: the scheme and host fold, the path does not. Returns the rows whose `agent_url` authorizes it under adagents.json agent URL matching: rows for the same canonical URL, plus rows whose `agent_url` is origin-only (`https://agent.example.com`) for the same canonical origin, which authorize every path at that origin. */
8785
8787
  agent_url: string;
8786
8788
  /** @description `effective` (default) applies override layer; `raw` reads base table. */
8787
8789
  include?: "raw" | "effective";
@@ -8826,7 +8828,7 @@ export interface operations {
8826
8828
  created_at: string;
8827
8829
  /** Format: date-time */
8828
8830
  updated_at: string;
8829
- /** @description Publisher-pinned JWK set (authorized_agents[*].signing_keys) from the source adagents.json. Consumers verifying inbound TMP signatures key on kid → JWK. Null when the publisher declared no keys; consumers fall back to the agent-hosted JWKS per spec R-2 (docs/governance/property/adagents.mdx). */
8831
+ /** @description Publisher-pinned JWK set (authorized_agents[*].signing_keys) from the source adagents.json. Consumers verifying inbound TMP signatures key on kid → JWK. Null when the publisher declared no keys; consumers fall back to the agent-hosted JWKS per spec R-2 (docs/governance/property/adagents.mdx). This is one entry's pin. Rows from the same publisher combine per message scope: among the rows that authorize that scope, the publisher pins the agent only if every one carries keys, and the pin is the union of their keys (docs/governance/property/adagents.mdx#agent-url-matching). */
8830
8832
  signing_keys: components["schemas"]["SigningKey"][] | null;
8831
8833
  /** @description Collection constraints (authorized_agents[*].collections) from the source adagents.json. Null when the entry is unconstrained. When set, the row does NOT authorize the property unqualified — consumers MUST scope it to these selectors. A selector without collection_ids is a bulk grant for all collections declared at that publisher_domain. */
8832
8834
  collections: ({
@@ -10,7 +10,7 @@
10
10
  import type { TestOptions, TestResult, AgentProfile } from '../types.mjs';
11
11
  import type { NotApplicableStoryboard, ResolvedBundle } from '../storyboard/compliance.mjs';
12
12
  import type { AgentEntry, Storyboard, StoryboardContext, StoryboardResult, StoryboardRunOptions } from '../storyboard/types.mjs';
13
- import type { ComplianceBundleResult, ComplianceTrack, ComplianceFailure, ComplianceResult, ComplianceSummary, AdvisoryObservation, OverallStatus } from './types.mjs';
13
+ import type { ComplianceBundleResult, ComplianceTrack, ComplianceFailure, ComplianceVerdictExplanation, ComplianceResult, ComplianceSummary, AdvisoryObservation, OverallStatus } from './types.mjs';
14
14
  import type { VersionEnvelopeMode } from '../../protocols/index.mjs';
15
15
  /**
16
16
  * Collect advisory observations from test results.
@@ -258,6 +258,20 @@ export declare function extractFailures(results: StoryboardResult[], storyboards
258
258
  hostedStableLineAlias?: string;
259
259
  testKitPath?: string;
260
260
  }): ComplianceFailure[];
261
+ /**
262
+ * One explanation per failing storyboard (adcp#8576), with a `fix_command`
263
+ * that re-runs the whole storyboard. `storyboard_level` marks the verdicts no
264
+ * `failures[]` row explains — the ones that used to surface only as
265
+ * "storyboard-level verdict failed".
266
+ */
267
+ export declare function extractVerdictExplanations(results: StoryboardResult[], storyboards: Storyboard[], agentRef: string, failures: readonly ComplianceFailure[], fixOptions?: Parameters<typeof buildFixCommand>[3]): ComplianceVerdictExplanation[];
268
+ declare function buildFixCommand(agentRef: string, storyboardId: string, stepId: string | undefined, options: {
269
+ complianceVersion?: string;
270
+ complianceDir?: string;
271
+ schemaRoot?: string;
272
+ hostedStableLineAlias?: string;
273
+ testKitPath?: string;
274
+ }): string;
261
275
  /**
262
276
  * Rotate a storyboard list to start at `offset % length`, preserving relative
263
277
  * order (the head wraps to the tail). Pure and deterministic: offset 0, an
@@ -287,3 +301,4 @@ export declare function computeOverallStatus(summary: ComplianceSummary): Overal
287
301
  */
288
302
  export declare function formatComplianceResults(result: ComplianceResult): string;
289
303
  export declare function formatComplianceResultsJSON(result: ComplianceResult): string;
304
+ export {};
@@ -10,7 +10,7 @@
10
10
  import type { TestOptions, TestResult, AgentProfile } from '../types';
11
11
  import type { NotApplicableStoryboard, ResolvedBundle } from '../storyboard/compliance';
12
12
  import type { AgentEntry, Storyboard, StoryboardContext, StoryboardResult, StoryboardRunOptions } from '../storyboard/types';
13
- import type { ComplianceBundleResult, ComplianceTrack, ComplianceFailure, ComplianceResult, ComplianceSummary, AdvisoryObservation, OverallStatus } from './types';
13
+ import type { ComplianceBundleResult, ComplianceTrack, ComplianceFailure, ComplianceVerdictExplanation, ComplianceResult, ComplianceSummary, AdvisoryObservation, OverallStatus } from './types';
14
14
  import type { VersionEnvelopeMode } from '../../protocols';
15
15
  /**
16
16
  * Collect advisory observations from test results.
@@ -258,6 +258,20 @@ export declare function extractFailures(results: StoryboardResult[], storyboards
258
258
  hostedStableLineAlias?: string;
259
259
  testKitPath?: string;
260
260
  }): ComplianceFailure[];
261
+ /**
262
+ * One explanation per failing storyboard (adcp#8576), with a `fix_command`
263
+ * that re-runs the whole storyboard. `storyboard_level` marks the verdicts no
264
+ * `failures[]` row explains — the ones that used to surface only as
265
+ * "storyboard-level verdict failed".
266
+ */
267
+ export declare function extractVerdictExplanations(results: StoryboardResult[], storyboards: Storyboard[], agentRef: string, failures: readonly ComplianceFailure[], fixOptions?: Parameters<typeof buildFixCommand>[3]): ComplianceVerdictExplanation[];
268
+ declare function buildFixCommand(agentRef: string, storyboardId: string, stepId: string | undefined, options: {
269
+ complianceVersion?: string;
270
+ complianceDir?: string;
271
+ schemaRoot?: string;
272
+ hostedStableLineAlias?: string;
273
+ testKitPath?: string;
274
+ }): string;
261
275
  /**
262
276
  * Rotate a storyboard list to start at `offset % length`, preserving relative
263
277
  * order (the head wraps to the tail). Pure and deterministic: offset 0, an
@@ -287,3 +301,4 @@ export declare function computeOverallStatus(summary: ComplianceSummary): Overal
287
301
  */
288
302
  export declare function formatComplianceResults(result: ComplianceResult): string;
289
303
  export declare function formatComplianceResultsJSON(result: ComplianceResult): string;
304
+ export {};
@@ -25,6 +25,7 @@ __export(comply_exports, {
25
25
  computeOverallStatus: () => computeOverallStatus,
26
26
  detectAuthRejection: () => detectAuthRejection,
27
27
  extractFailures: () => extractFailures,
28
+ extractVerdictExplanations: () => extractVerdictExplanations,
28
29
  formatComplianceResults: () => formatComplianceResults,
29
30
  formatComplianceResultsJSON: () => formatComplianceResultsJSON,
30
31
  partitionStoryboardsByRequiredTools: () => partitionStoryboardsByRequiredTools,
@@ -569,6 +570,13 @@ const NEUTRAL_BUNDLE_SKIP_REASONS = /* @__PURE__ */ new Set([
569
570
  "capability_prerequisite_unavailable"
570
571
  ]);
571
572
  const CAPABILITY_ROLLUP_MIN_ADCP_VERSION = "3.2";
573
+ const CAPABILITY_ROLLUP_MIN_3_1_PATCH = 24;
574
+ const STABLE_3_1_RELEASE_PATTERN = /^3\.1\.(\d+)$/;
575
+ function carriesApplicabilityOrderRule(adcpVersion) {
576
+ if (compareAdcpVersionStrings(adcpVersion, CAPABILITY_ROLLUP_MIN_ADCP_VERSION) >= 0) return true;
577
+ const patch = STABLE_3_1_RELEASE_PATTERN.exec(adcpVersion)?.[1];
578
+ return patch !== void 0 && Number.parseInt(patch, 10) >= CAPABILITY_ROLLUP_MIN_3_1_PATCH;
579
+ }
572
580
  const CAPABILITY_UNSUPPORTED_ROW_ID = "capability_unsupported";
573
581
  const CAPABILITY_UNSUPPORTED_RESULT_KEYS = /* @__PURE__ */ new Set([
574
582
  "storyboard_id",
@@ -616,7 +624,7 @@ function isCapabilityUnsupportedSkip(storyboard, result) {
616
624
  const predicates = (0, import_runner.storyboardCapabilityPredicates)(storyboard);
617
625
  if (predicates.length === 0) return false;
618
626
  if (typeof storyboard.adcp_version !== "string") return false;
619
- if (compareAdcpVersionStrings(storyboard.adcp_version, CAPABILITY_ROLLUP_MIN_ADCP_VERSION) < 0) return false;
627
+ if (!carriesApplicabilityOrderRule(storyboard.adcp_version)) return false;
620
628
  if (predicates.flatMap(import_runner.capabilityPathPredicates).some((predicate) => capabilityPathSegments(predicate.path).includes("compliance_testing"))) {
621
629
  return false;
622
630
  }
@@ -957,7 +965,10 @@ async function runComplyStoryboard(agentUrl, storyboard, runOptions, profile, ro
957
965
  const routed = buildRoutedStoryboardRun(agentUrl, storyboard, runOptions, routing);
958
966
  if ("refused" in routed) return buildRouteSkippedStoryboardResult(agentUrl, storyboard, routed.refused, runOptions);
959
967
  const result = await (0, import_runner.runStoryboard)("", routed.storyboard, routed.options);
960
- return gradeRoutedResultForAgentUnderTest(result, routed.agentUnderTestIndexes, routed.keyByIndex);
968
+ return (0, import_runner.attachStoryboardVerdictExplanation)(
969
+ gradeRoutedResultForAgentUnderTest(result, routed.agentUnderTestIndexes, routed.keyByIndex),
970
+ routed.storyboard
971
+ );
961
972
  }
962
973
  function sameAgentUrl(a, b) {
963
974
  try {
@@ -1311,6 +1322,23 @@ function extractFailures(results, storyboards, agentRef, fixOptions = {}) {
1311
1322
  }
1312
1323
  return failures;
1313
1324
  }
1325
+ function extractVerdictExplanations(results, storyboards, agentRef, failures, fixOptions = {}) {
1326
+ const trackById = new Map(storyboards.map((sb) => [sb.id, sb.track ?? "core"]));
1327
+ const explained = new Set(failures.map((failure) => failure.storyboard_id));
1328
+ const explanations = [];
1329
+ for (const result of results) {
1330
+ const explanation = (0, import_storyboard_tracks.storyboardVerdictExplanation)(result);
1331
+ if (!explanation) continue;
1332
+ explanations.push({
1333
+ track: trackById.get(result.storyboard_id) ?? "core",
1334
+ storyboard_id: result.storyboard_id,
1335
+ ...explanation,
1336
+ storyboard_level: !explained.has(result.storyboard_id),
1337
+ fix_command: buildFixCommand(agentRef, result.storyboard_id, void 0, fixOptions)
1338
+ });
1339
+ }
1340
+ return explanations;
1341
+ }
1314
1342
  function findStoryboardStepExpected(storyboard, stepId) {
1315
1343
  if (!storyboard) return void 0;
1316
1344
  for (const phase of storyboard.phases) {
@@ -1640,13 +1668,21 @@ async function complyImpl(agentUrl, options) {
1640
1668
  const overallStatus = stoppedForTimeoutBudget ? "partial" : computeOverallStatus(summary);
1641
1669
  const safeAgentUrl = (0, import_oauth_metadata_graph.redactOAuthUrlForOutput)(agentUrl);
1642
1670
  const agentRef = options.agent_alias || safeAgentUrl;
1643
- const failures = extractFailures(storyboardResults, runnableStoryboards, agentRef, {
1671
+ const fixOptions = {
1644
1672
  complianceVersion: complianceIndex.adcp_version,
1645
1673
  ...complianceDir !== void 0 && { complianceDir },
1646
1674
  ...schemaRoot !== void 0 && { schemaRoot },
1647
1675
  ...hostedStableLineAlias !== void 0 && { hostedStableLineAlias },
1648
1676
  ...options.testKitPath !== void 0 && { testKitPath: options.testKitPath }
1649
- });
1677
+ };
1678
+ const failures = extractFailures(storyboardResults, runnableStoryboards, agentRef, fixOptions);
1679
+ const verdictExplanations = extractVerdictExplanations(
1680
+ storyboardResults,
1681
+ runnableStoryboards,
1682
+ agentRef,
1683
+ failures,
1684
+ fixOptions
1685
+ );
1650
1686
  const aggregatedNotices = /* @__PURE__ */ new Map();
1651
1687
  for (const sbResult of storyboardResults) {
1652
1688
  for (const notice of sbResult.notices) {
@@ -1674,6 +1710,7 @@ async function complyImpl(agentUrl, options) {
1674
1710
  summary,
1675
1711
  observations: allObservations,
1676
1712
  failures: failures.length > 0 ? failures : void 0,
1713
+ ...verdictExplanations.length > 0 && { verdict_explanations: verdictExplanations },
1677
1714
  storyboards_executed: executedStoryboards.map((sb) => sb.id),
1678
1715
  ...resolvedBundles !== void 0 && {
1679
1716
  bundle_results: buildComplianceBundleResults(resolvedBundles, storyboardResults, {
@@ -1842,13 +1879,21 @@ async function runWithDegradedProfile(agentUrl, profile, storyboards, options, e
1842
1879
  const overallStatus = stoppedForTimeoutBudget ? "partial" : computeOverallStatus(summary);
1843
1880
  const safeAgentUrl = (0, import_oauth_metadata_graph.redactOAuthUrlForOutput)(agentUrl);
1844
1881
  const agentRef = options.agent_alias || safeAgentUrl;
1845
- const failures = extractFailures(storyboardResults, storyboards, agentRef, {
1882
+ const fixOptions = {
1846
1883
  complianceVersion: adcpVersion,
1847
1884
  ...options.complianceDir !== void 0 && { complianceDir: options.complianceDir },
1848
1885
  ...options.schemaRoot !== void 0 && { schemaRoot: options.schemaRoot },
1849
1886
  ...options.hostedStableLineAlias !== void 0 && { hostedStableLineAlias: options.hostedStableLineAlias },
1850
1887
  ...options.testKitPath !== void 0 && { testKitPath: options.testKitPath }
1851
- });
1888
+ };
1889
+ const failures = extractFailures(storyboardResults, storyboards, agentRef, fixOptions);
1890
+ const verdictExplanations = extractVerdictExplanations(
1891
+ storyboardResults,
1892
+ storyboards,
1893
+ agentRef,
1894
+ failures,
1895
+ fixOptions
1896
+ );
1852
1897
  for (const t of trackResults) t._view = "canonical";
1853
1898
  const skippedTracks = trackResults.filter((t) => t.status === "skip").map((t) => ({
1854
1899
  track: t.track,
@@ -1867,6 +1912,7 @@ async function runWithDegradedProfile(agentUrl, profile, storyboards, options, e
1867
1912
  summary,
1868
1913
  observations: allObservations,
1869
1914
  failures: failures.length > 0 ? failures : void 0,
1915
+ ...verdictExplanations.length > 0 && { verdict_explanations: verdictExplanations },
1870
1916
  storyboards_executed: executedStoryboards.map((sb) => sb.id),
1871
1917
  controller_detected: false,
1872
1918
  tested_at: (/* @__PURE__ */ new Date()).toISOString(),
@@ -2118,6 +2164,10 @@ ${overallIcon} AdCP Compliance Report
2118
2164
  }
2119
2165
  if (failedSteps.length > 3) {
2120
2166
  output += ` ... and ${failedSteps.length - 3} more
2167
+ `;
2168
+ }
2169
+ if (failedSteps.length === 0 && scenario.verdict_detail) {
2170
+ output += ` Why: ${fenceAgentText(scenario.verdict_detail, 600)}
2121
2171
  `;
2122
2172
  }
2123
2173
  }
@@ -2164,6 +2214,26 @@ How to Fix
2164
2214
  }
2165
2215
  if (failuresWithExpected.length > 5) {
2166
2216
  output += ` ... and ${failuresWithExpected.length - 5} more (use --json for all)
2217
+ `;
2218
+ }
2219
+ }
2220
+ const storyboardLevel = (result.verdict_explanations ?? []).filter((explanation) => explanation.storyboard_level);
2221
+ if (storyboardLevel.length > 0) {
2222
+ output += `
2223
+ Storyboard-level Verdicts
2224
+ `;
2225
+ output += `${"\u2500".repeat(50)}
2226
+ `;
2227
+ for (const explanation of storyboardLevel.slice(0, 5)) {
2228
+ output += `\u274C ${explanation.storyboard_id} (${explanation.verdict_reason})
2229
+ `;
2230
+ output += ` Why: ${fenceAgentText(explanation.verdict_detail, 600)}
2231
+ `;
2232
+ output += ` Debug: ${explanation.fix_command}
2233
+ `;
2234
+ }
2235
+ if (storyboardLevel.length > 5) {
2236
+ output += ` ... and ${storyboardLevel.length - 5} more (use --json for all)
2167
2237
  `;
2168
2238
  }
2169
2239
  }
@@ -2276,6 +2346,7 @@ function formatMachineValue(value) {
2276
2346
  computeOverallStatus,
2277
2347
  detectAuthRejection,
2278
2348
  extractFailures,
2349
+ extractVerdictExplanations,
2279
2350
  formatComplianceResults,
2280
2351
  formatComplianceResultsJSON,
2281
2352
  partitionStoryboardsByRequiredTools,
@@ -7,9 +7,15 @@ import {
7
7
  seedAuthRejectedTestClientProfile,
8
8
  withTestClientScope
9
9
  } from "../client.mjs";
10
- import { collectDetachedAssertionFailures, mapStoryboardResultsToTrackResult, TRACK_LABELS } from "./storyboard-tracks.mjs";
10
+ import {
11
+ collectDetachedAssertionFailures,
12
+ mapStoryboardResultsToTrackResult,
13
+ storyboardVerdictExplanation,
14
+ TRACK_LABELS
15
+ } from "./storyboard-tracks.mjs";
11
16
  import {
12
17
  applyAdcpVersionRunOptions,
18
+ attachStoryboardVerdictExplanation,
13
19
  collectCapabilityNotices,
14
20
  runStoryboard,
15
21
  storyboardCapabilityGateUnmet,
@@ -563,6 +569,13 @@ const NEUTRAL_BUNDLE_SKIP_REASONS = /* @__PURE__ */ new Set([
563
569
  "capability_prerequisite_unavailable"
564
570
  ]);
565
571
  const CAPABILITY_ROLLUP_MIN_ADCP_VERSION = "3.2";
572
+ const CAPABILITY_ROLLUP_MIN_3_1_PATCH = 24;
573
+ const STABLE_3_1_RELEASE_PATTERN = /^3\.1\.(\d+)$/;
574
+ function carriesApplicabilityOrderRule(adcpVersion) {
575
+ if (compareAdcpVersionStrings(adcpVersion, CAPABILITY_ROLLUP_MIN_ADCP_VERSION) >= 0) return true;
576
+ const patch = STABLE_3_1_RELEASE_PATTERN.exec(adcpVersion)?.[1];
577
+ return patch !== void 0 && Number.parseInt(patch, 10) >= CAPABILITY_ROLLUP_MIN_3_1_PATCH;
578
+ }
566
579
  const CAPABILITY_UNSUPPORTED_ROW_ID = "capability_unsupported";
567
580
  const CAPABILITY_UNSUPPORTED_RESULT_KEYS = /* @__PURE__ */ new Set([
568
581
  "storyboard_id",
@@ -610,7 +623,7 @@ function isCapabilityUnsupportedSkip(storyboard, result) {
610
623
  const predicates = storyboardCapabilityPredicates(storyboard);
611
624
  if (predicates.length === 0) return false;
612
625
  if (typeof storyboard.adcp_version !== "string") return false;
613
- if (compareAdcpVersionStrings(storyboard.adcp_version, CAPABILITY_ROLLUP_MIN_ADCP_VERSION) < 0) return false;
626
+ if (!carriesApplicabilityOrderRule(storyboard.adcp_version)) return false;
614
627
  if (predicates.flatMap(capabilityPathPredicates).some((predicate) => capabilityPathSegments(predicate.path).includes("compliance_testing"))) {
615
628
  return false;
616
629
  }
@@ -951,7 +964,10 @@ async function runComplyStoryboard(agentUrl, storyboard, runOptions, profile, ro
951
964
  const routed = buildRoutedStoryboardRun(agentUrl, storyboard, runOptions, routing);
952
965
  if ("refused" in routed) return buildRouteSkippedStoryboardResult(agentUrl, storyboard, routed.refused, runOptions);
953
966
  const result = await runStoryboard("", routed.storyboard, routed.options);
954
- return gradeRoutedResultForAgentUnderTest(result, routed.agentUnderTestIndexes, routed.keyByIndex);
967
+ return attachStoryboardVerdictExplanation(
968
+ gradeRoutedResultForAgentUnderTest(result, routed.agentUnderTestIndexes, routed.keyByIndex),
969
+ routed.storyboard
970
+ );
955
971
  }
956
972
  function sameAgentUrl(a, b) {
957
973
  try {
@@ -1305,6 +1321,23 @@ function extractFailures(results, storyboards, agentRef, fixOptions = {}) {
1305
1321
  }
1306
1322
  return failures;
1307
1323
  }
1324
+ function extractVerdictExplanations(results, storyboards, agentRef, failures, fixOptions = {}) {
1325
+ const trackById = new Map(storyboards.map((sb) => [sb.id, sb.track ?? "core"]));
1326
+ const explained = new Set(failures.map((failure) => failure.storyboard_id));
1327
+ const explanations = [];
1328
+ for (const result of results) {
1329
+ const explanation = storyboardVerdictExplanation(result);
1330
+ if (!explanation) continue;
1331
+ explanations.push({
1332
+ track: trackById.get(result.storyboard_id) ?? "core",
1333
+ storyboard_id: result.storyboard_id,
1334
+ ...explanation,
1335
+ storyboard_level: !explained.has(result.storyboard_id),
1336
+ fix_command: buildFixCommand(agentRef, result.storyboard_id, void 0, fixOptions)
1337
+ });
1338
+ }
1339
+ return explanations;
1340
+ }
1308
1341
  function findStoryboardStepExpected(storyboard, stepId) {
1309
1342
  if (!storyboard) return void 0;
1310
1343
  for (const phase of storyboard.phases) {
@@ -1634,13 +1667,21 @@ async function complyImpl(agentUrl, options) {
1634
1667
  const overallStatus = stoppedForTimeoutBudget ? "partial" : computeOverallStatus(summary);
1635
1668
  const safeAgentUrl = redactOAuthUrlForOutput(agentUrl);
1636
1669
  const agentRef = options.agent_alias || safeAgentUrl;
1637
- const failures = extractFailures(storyboardResults, runnableStoryboards, agentRef, {
1670
+ const fixOptions = {
1638
1671
  complianceVersion: complianceIndex.adcp_version,
1639
1672
  ...complianceDir !== void 0 && { complianceDir },
1640
1673
  ...schemaRoot !== void 0 && { schemaRoot },
1641
1674
  ...hostedStableLineAlias !== void 0 && { hostedStableLineAlias },
1642
1675
  ...options.testKitPath !== void 0 && { testKitPath: options.testKitPath }
1643
- });
1676
+ };
1677
+ const failures = extractFailures(storyboardResults, runnableStoryboards, agentRef, fixOptions);
1678
+ const verdictExplanations = extractVerdictExplanations(
1679
+ storyboardResults,
1680
+ runnableStoryboards,
1681
+ agentRef,
1682
+ failures,
1683
+ fixOptions
1684
+ );
1644
1685
  const aggregatedNotices = /* @__PURE__ */ new Map();
1645
1686
  for (const sbResult of storyboardResults) {
1646
1687
  for (const notice of sbResult.notices) {
@@ -1668,6 +1709,7 @@ async function complyImpl(agentUrl, options) {
1668
1709
  summary,
1669
1710
  observations: allObservations,
1670
1711
  failures: failures.length > 0 ? failures : void 0,
1712
+ ...verdictExplanations.length > 0 && { verdict_explanations: verdictExplanations },
1671
1713
  storyboards_executed: executedStoryboards.map((sb) => sb.id),
1672
1714
  ...resolvedBundles !== void 0 && {
1673
1715
  bundle_results: buildComplianceBundleResults(resolvedBundles, storyboardResults, {
@@ -1836,13 +1878,21 @@ async function runWithDegradedProfile(agentUrl, profile, storyboards, options, e
1836
1878
  const overallStatus = stoppedForTimeoutBudget ? "partial" : computeOverallStatus(summary);
1837
1879
  const safeAgentUrl = redactOAuthUrlForOutput(agentUrl);
1838
1880
  const agentRef = options.agent_alias || safeAgentUrl;
1839
- const failures = extractFailures(storyboardResults, storyboards, agentRef, {
1881
+ const fixOptions = {
1840
1882
  complianceVersion: adcpVersion,
1841
1883
  ...options.complianceDir !== void 0 && { complianceDir: options.complianceDir },
1842
1884
  ...options.schemaRoot !== void 0 && { schemaRoot: options.schemaRoot },
1843
1885
  ...options.hostedStableLineAlias !== void 0 && { hostedStableLineAlias: options.hostedStableLineAlias },
1844
1886
  ...options.testKitPath !== void 0 && { testKitPath: options.testKitPath }
1845
- });
1887
+ };
1888
+ const failures = extractFailures(storyboardResults, storyboards, agentRef, fixOptions);
1889
+ const verdictExplanations = extractVerdictExplanations(
1890
+ storyboardResults,
1891
+ storyboards,
1892
+ agentRef,
1893
+ failures,
1894
+ fixOptions
1895
+ );
1846
1896
  for (const t of trackResults) t._view = "canonical";
1847
1897
  const skippedTracks = trackResults.filter((t) => t.status === "skip").map((t) => ({
1848
1898
  track: t.track,
@@ -1861,6 +1911,7 @@ async function runWithDegradedProfile(agentUrl, profile, storyboards, options, e
1861
1911
  summary,
1862
1912
  observations: allObservations,
1863
1913
  failures: failures.length > 0 ? failures : void 0,
1914
+ ...verdictExplanations.length > 0 && { verdict_explanations: verdictExplanations },
1864
1915
  storyboards_executed: executedStoryboards.map((sb) => sb.id),
1865
1916
  controller_detected: false,
1866
1917
  tested_at: (/* @__PURE__ */ new Date()).toISOString(),
@@ -2112,6 +2163,10 @@ ${overallIcon} AdCP Compliance Report
2112
2163
  }
2113
2164
  if (failedSteps.length > 3) {
2114
2165
  output += ` ... and ${failedSteps.length - 3} more
2166
+ `;
2167
+ }
2168
+ if (failedSteps.length === 0 && scenario.verdict_detail) {
2169
+ output += ` Why: ${fenceAgentText(scenario.verdict_detail, 600)}
2115
2170
  `;
2116
2171
  }
2117
2172
  }
@@ -2158,6 +2213,26 @@ How to Fix
2158
2213
  }
2159
2214
  if (failuresWithExpected.length > 5) {
2160
2215
  output += ` ... and ${failuresWithExpected.length - 5} more (use --json for all)
2216
+ `;
2217
+ }
2218
+ }
2219
+ const storyboardLevel = (result.verdict_explanations ?? []).filter((explanation) => explanation.storyboard_level);
2220
+ if (storyboardLevel.length > 0) {
2221
+ output += `
2222
+ Storyboard-level Verdicts
2223
+ `;
2224
+ output += `${"\u2500".repeat(50)}
2225
+ `;
2226
+ for (const explanation of storyboardLevel.slice(0, 5)) {
2227
+ output += `\u274C ${explanation.storyboard_id} (${explanation.verdict_reason})
2228
+ `;
2229
+ output += ` Why: ${fenceAgentText(explanation.verdict_detail, 600)}
2230
+ `;
2231
+ output += ` Debug: ${explanation.fix_command}
2232
+ `;
2233
+ }
2234
+ if (storyboardLevel.length > 5) {
2235
+ output += ` ... and ${storyboardLevel.length - 5} more (use --json for all)
2161
2236
  `;
2162
2237
  }
2163
2238
  }
@@ -2269,6 +2344,7 @@ export {
2269
2344
  computeOverallStatus,
2270
2345
  detectAuthRejection,
2271
2346
  extractFailures,
2347
+ extractVerdictExplanations,
2272
2348
  formatComplianceResults,
2273
2349
  formatComplianceResultsJSON,
2274
2350
  partitionStoryboardsByRequiredTools,
@@ -8,4 +8,4 @@ export type { ComplyOptions, ComplianceBundleAssessmentOptions, ComplyRouteStory
8
8
  export { buildComplianceSummary, buildCrashSummary, formatComplianceSummaryText, formatComplianceSummaryMarkdown, } from './summary.mjs';
9
9
  export type { ComplianceSummaryArtifact, ComplianceSummaryFailure, ComplianceSummaryFailureKind, ComplianceSummaryIncompleteStoryboard, BuildSummaryOptions, BuildCrashSummaryOptions, } from './summary.mjs';
10
10
  export { SAMPLE_BRIEFS, getBriefById, getBriefsByVertical } from './briefs.mjs';
11
- export type { ComplianceTrack, TrackResult, TestedTrackEntry, TrackStatus, OverallStatus, ComplianceFailure, ComplianceBundleResult, ComplianceBundleStatus, ComplianceResult, ComplianceSummary, AdvisoryObservation, ObservationCategory, ObservationSeverity, ObservationSource, SampleBrief, } from './types.mjs';
11
+ export type { ComplianceTrack, TrackResult, TestedTrackEntry, TrackStatus, OverallStatus, ComplianceFailure, ComplianceVerdictExplanation, ComplianceBundleResult, ComplianceBundleStatus, ComplianceResult, ComplianceSummary, AdvisoryObservation, ObservationCategory, ObservationSeverity, ObservationSource, SampleBrief, } from './types.mjs';
@@ -8,4 +8,4 @@ export type { ComplyOptions, ComplianceBundleAssessmentOptions, ComplyRouteStory
8
8
  export { buildComplianceSummary, buildCrashSummary, formatComplianceSummaryText, formatComplianceSummaryMarkdown, } from './summary';
9
9
  export type { ComplianceSummaryArtifact, ComplianceSummaryFailure, ComplianceSummaryFailureKind, ComplianceSummaryIncompleteStoryboard, BuildSummaryOptions, BuildCrashSummaryOptions, } from './summary';
10
10
  export { SAMPLE_BRIEFS, getBriefById, getBriefsByVertical } from './briefs';
11
- export type { ComplianceTrack, TrackResult, TestedTrackEntry, TrackStatus, OverallStatus, ComplianceFailure, ComplianceBundleResult, ComplianceBundleStatus, ComplianceResult, ComplianceSummary, AdvisoryObservation, ObservationCategory, ObservationSeverity, ObservationSource, SampleBrief, } from './types';
11
+ export type { ComplianceTrack, TrackResult, TestedTrackEntry, TrackStatus, OverallStatus, ComplianceFailure, ComplianceVerdictExplanation, ComplianceBundleResult, ComplianceBundleStatus, ComplianceResult, ComplianceSummary, AdvisoryObservation, ObservationCategory, ObservationSeverity, ObservationSource, SampleBrief, } from './types';
@@ -8,12 +8,18 @@
8
8
  import type { AgentProfile } from '../types.mjs';
9
9
  import type { ComplianceTrack, TrackResult } from './types.mjs';
10
10
  import type { AssertionResult, StoryboardResult, StoryboardStepResult } from '../storyboard/types.mjs';
11
+ import { type StoryboardVerdictExplanation } from '../storyboard/verdict-explanation.mjs';
11
12
  export interface DetachedAssertionFailure {
12
13
  assertion: AssertionResult;
13
14
  owningStep?: StoryboardStepResult;
14
15
  }
15
16
  /** Assertion failures that are not represented by a counted failed step. */
16
17
  export declare function collectDetachedAssertionFailures(result: StoryboardResult): DetachedAssertionFailure[];
18
+ /**
19
+ * The verdict explanation the runner attached, or one derived from the result
20
+ * when it carries none. `undefined` for a passing result.
21
+ */
22
+ export declare function storyboardVerdictExplanation(result: StoryboardResult): StoryboardVerdictExplanation | undefined;
17
23
  /** Labels for each compliance track. */
18
24
  export declare const TRACK_LABELS: Record<ComplianceTrack, string>;
19
25
  /**
@@ -8,12 +8,18 @@
8
8
  import type { AgentProfile } from '../types';
9
9
  import type { ComplianceTrack, TrackResult } from './types';
10
10
  import type { AssertionResult, StoryboardResult, StoryboardStepResult } from '../storyboard/types';
11
+ import { type StoryboardVerdictExplanation } from '../storyboard/verdict-explanation';
11
12
  export interface DetachedAssertionFailure {
12
13
  assertion: AssertionResult;
13
14
  owningStep?: StoryboardStepResult;
14
15
  }
15
16
  /** Assertion failures that are not represented by a counted failed step. */
16
17
  export declare function collectDetachedAssertionFailures(result: StoryboardResult): DetachedAssertionFailure[];
18
+ /**
19
+ * The verdict explanation the runner attached, or one derived from the result
20
+ * when it carries none. `undefined` for a passing result.
21
+ */
22
+ export declare function storyboardVerdictExplanation(result: StoryboardResult): StoryboardVerdictExplanation | undefined;
17
23
  /** Labels for each compliance track. */
18
24
  export declare const TRACK_LABELS: Record<ComplianceTrack, string>;
19
25
  /**