@adcp/sdk 14.0.0-rc.38 → 14.0.0-rc.39

package/dist/lib/testing/storyboard/runner.d.mts

@@ -58,9 +58,29 @@ export declare function resolveCapabilityPath(raw: unknown, dottedPath: string):
  * needing a full runStoryboard() roundtrip.
  */
 export declare function evaluateCapabilityPredicate(predicate: RequiresCapabilityPredicate, actual: unknown): string | null;
+/**
+ * Every root applicability predicate a storyboard authors, across
+ * `requires_capability` and `requires_all_capabilities`. Exported so the
+ * compliance rollup keys on the same set the runner gates on, rather than
+ * re-listing the fields and drifting when one is added.
+ */
+export declare function storyboardCapabilityPredicates(storyboard: Storyboard): RequiresCapabilityPredicate[];
 export declare function describeStoryboardCapabilityGates(storyboard: Storyboard): string | null;
 export declare function __redactSecretsForTest(value: unknown): unknown;
 export declare function __filterResponseHeadersForTest(headers: Record<string, string> | undefined): Record<string, string> | undefined;
+/**
+ * Test seam for the session probe's mechanism-matched control resolution.
+ * Exercised against the real `createTestClient` shape so the live-token
+ * lookup cannot silently regress to a structure no client actually returns.
+ */
+/**
+ * Test seam for protected-target selection. Exercised directly so the
+ * public-tier and mutating-task exclusions cannot regress silently.
+ */
+export declare function __selectProtectedToolTargetForTest(tools: readonly string[] | undefined): string | undefined;
+/** Test seam for the ordered candidate list. */
+export declare function __protectedToolCandidatesForTest(tools: readonly string[] | undefined): string[];
+export declare function __sessionControlCredentialsForTest(mechanism: SessionControlMechanism, options: StoryboardRunOptions, client: unknown, agentUrl?: string): SessionControlResolution;
 export declare function __defaultAuthHeadersForRawProbeForTest(options: StoryboardRunOptions): Record<string, string> | undefined;
 /**
  * Run an entire storyboard against an agent.
@@ -74,6 +94,60 @@ export declare function __defaultAuthHeadersForRawProbeForTest(options: Storyboa
  * empty on instance B.
  */
 export declare function runStoryboard(agentUrlOrUrls: string | string[], storyboard: Storyboard, options?: StoryboardRunOptions): Promise<StoryboardResult>;
+/**
+ * What a finished run actually verified about the agent's signing surface.
+ *
+ *   - `not_probed` — the run has no request-signing probe steps.
+ *   - `graded` — at least one vector reached the agent.
+ *   - `probe_errored` — the probes could not complete: a transport or
+ *     precondition failure (MCP initialize, DNS, an unreadable vector cache).
+ *   - `transport_unverified` — the runner has no dispatch shape for this
+ *     run's protocol.
+ *   - `scope_excluded` — every probe was skipped by the run's own selection
+ *     (`onlyVectors`, `skipVectors`, a profile exclusion).
+ *   - `self_check_only` — what ran decided in-library against the SDK
+ *     verifier and never contacted the agent.
+ *
+ * The four unverified states are deliberately distinct: the runner-output
+ * contract keeps caller-scope exclusions (`selection_result`) apart from
+ * coverage gaps, and each one sends the operator somewhere different — fix
+ * the connection, grade another binding, drop a flag, or nothing at all.
+ * Neither may report a pass, though — the question is not why a vector was
+ * skipped but whether any produced evidence. Keying the verdict on one skip
+ * reason left every other exclusion route open: dropping the wire vectors
+ * and keeping the in-library self-check laundered a green `signed_requests`
+ * out of a step that grades the SDK and never contacts the agent
+ * (adcp-client#2954).
+ *
+ * "Reached the agent" is read from the probe's own HTTP status, the dispatch
+ * contract's signal: only a wire exchange yields a non-zero status, and an
+ * in-library grade reports 0 by definition. Deliberately not read from the
+ * step's validations — the runner appends invariant results to steps, so
+ * "its only check is `probe_passed`" silently stops matching the moment an
+ * invariant is registered.
+ *
+ * Exported as the single definition of this rule. The storyboard verdict,
+ * the compliance track rollup, the compliance report and the CLI exit
+ * contract all consume it — the CLI through `dist`, over a view of the
+ * mapped `TestStepResult` shape — because hand-written copies of it drifted
+ * within one revision of this change, one of them into a false CI failure.
+ */
+export type SigningCoverage = 'not_probed' | 'graded' | 'probe_errored' | 'transport_unverified' | 'scope_excluded' | 'self_check_only';
+/**
+ * Minimal step view the coverage rule needs. `StoryboardStepResult` satisfies
+ * it directly; the compliance projection maps `observation_data` onto
+ * `response`.
+ */
+export interface SigningCoverageStepView {
+    task?: string;
+    skipped?: boolean;
+    skip_reason?: string;
+    /** The probe's `HttpProbeResult`, as recorded on the step. */
+    response?: unknown;
+}
+export declare function signingCoverage(steps: readonly SigningCoverageStepView[]): SigningCoverage;
+/** True when signing probes ran and none of them reached the agent. */
+export declare function signingCoverageUnverified(steps: readonly SigningCoverageStepView[]): boolean;
 /**
  * Build a hard-failure StoryboardResult for when agent capability
  * discovery (`get_agent_info` / MCP `tools/list`) failed. Surfacing
@@ -135,6 +209,34 @@ export declare function summarizeStrictValidation(phases: StoryboardPhaseResult[
  * Context is passed in and returned, enabling step-by-step orchestration.
  */
 export declare function runStoryboardStep(agentUrl: string, storyboard: Storyboard, stepId: string, options?: StoryboardRunOptions): Promise<StoryboardStepResult>;
+/**
+ * Credential mechanism a sentinel step is exercising, derived from
+ * `step.auth.type`. The acceptance control must be the *same kind* of
+ * credential, because the storyboard's branches certify different claims:
+ *
+ * - `oauth_bearer` → `oauth_discovery` certifies "the agent validates inbound
+ *   OAuth tokens". A static API key accepted at the endpoint is no evidence
+ *   about that path, so it cannot stand in as the control — otherwise correct
+ *   PRM plus an unrelated shared secret would launder into
+ *   `auth_mechanism_verified`, which is the advertised-but-unserved failure
+ *   mode `security_baseline` exists to catch. Note the bound on the positive
+ *   claim too: an accepted OAuth control shows the endpoint accepted the
+ *   credential the runner was *configured with* as an OAuth token. The runner
+ *   does not verify that token's issuer cryptographically.
+ * - `api_key` / `basic` → the matching static-credential branch.
+ * - `any` → `auth: none` (the unauthenticated probe), which asserts only that
+ *   *some* credential is required, so any valid credential discriminates.
+ */
+type SessionControlMechanism = 'any' | 'oauth_bearer' | 'api_key' | 'basic';
+interface SessionControlUnavailable {
+    reason: string;
+    remedy: string;
+}
+type SessionControlResolution = {
+    headers: Record<string, string>;
+} | {
+    unavailable: SessionControlUnavailable;
+};
 /**
  * Force every outgoing request onto the storyboard's brand context.
  *
@@ -210,3 +312,4 @@ export declare function applyIdempotencyInvariant(request: Record<string, unknow
  * bound at preview time. They'll resolve when the step actually runs.
  */
 export declare function getFirstStepPreview(storyboard: Storyboard, context?: StoryboardContext): StoryboardStepPreview | undefined;
+export {};

package/dist/lib/testing/storyboard/runner.d.ts

@@ -58,9 +58,29 @@ export declare function resolveCapabilityPath(raw: unknown, dottedPath: string):
  * needing a full runStoryboard() roundtrip.
  */
 export declare function evaluateCapabilityPredicate(predicate: RequiresCapabilityPredicate, actual: unknown): string | null;
+/**
+ * Every root applicability predicate a storyboard authors, across
+ * `requires_capability` and `requires_all_capabilities`. Exported so the
+ * compliance rollup keys on the same set the runner gates on, rather than
+ * re-listing the fields and drifting when one is added.
+ */
+export declare function storyboardCapabilityPredicates(storyboard: Storyboard): RequiresCapabilityPredicate[];
 export declare function describeStoryboardCapabilityGates(storyboard: Storyboard): string | null;
 export declare function __redactSecretsForTest(value: unknown): unknown;
 export declare function __filterResponseHeadersForTest(headers: Record<string, string> | undefined): Record<string, string> | undefined;
+/**
+ * Test seam for the session probe's mechanism-matched control resolution.
+ * Exercised against the real `createTestClient` shape so the live-token
+ * lookup cannot silently regress to a structure no client actually returns.
+ */
+/**
+ * Test seam for protected-target selection. Exercised directly so the
+ * public-tier and mutating-task exclusions cannot regress silently.
+ */
+export declare function __selectProtectedToolTargetForTest(tools: readonly string[] | undefined): string | undefined;
+/** Test seam for the ordered candidate list. */
+export declare function __protectedToolCandidatesForTest(tools: readonly string[] | undefined): string[];
+export declare function __sessionControlCredentialsForTest(mechanism: SessionControlMechanism, options: StoryboardRunOptions, client: unknown, agentUrl?: string): SessionControlResolution;
 export declare function __defaultAuthHeadersForRawProbeForTest(options: StoryboardRunOptions): Record<string, string> | undefined;
 /**
  * Run an entire storyboard against an agent.
@@ -74,6 +94,60 @@ export declare function __defaultAuthHeadersForRawProbeForTest(options: Storyboa
  * empty on instance B.
  */
 export declare function runStoryboard(agentUrlOrUrls: string | string[], storyboard: Storyboard, options?: StoryboardRunOptions): Promise<StoryboardResult>;
+/**
+ * What a finished run actually verified about the agent's signing surface.
+ *
+ *   - `not_probed` — the run has no request-signing probe steps.
+ *   - `graded` — at least one vector reached the agent.
+ *   - `probe_errored` — the probes could not complete: a transport or
+ *     precondition failure (MCP initialize, DNS, an unreadable vector cache).
+ *   - `transport_unverified` — the runner has no dispatch shape for this
+ *     run's protocol.
+ *   - `scope_excluded` — every probe was skipped by the run's own selection
+ *     (`onlyVectors`, `skipVectors`, a profile exclusion).
+ *   - `self_check_only` — what ran decided in-library against the SDK
+ *     verifier and never contacted the agent.
+ *
+ * The four unverified states are deliberately distinct: the runner-output
+ * contract keeps caller-scope exclusions (`selection_result`) apart from
+ * coverage gaps, and each one sends the operator somewhere different — fix
+ * the connection, grade another binding, drop a flag, or nothing at all.
+ * Neither may report a pass, though — the question is not why a vector was
+ * skipped but whether any produced evidence. Keying the verdict on one skip
+ * reason left every other exclusion route open: dropping the wire vectors
+ * and keeping the in-library self-check laundered a green `signed_requests`
+ * out of a step that grades the SDK and never contacts the agent
+ * (adcp-client#2954).
+ *
+ * "Reached the agent" is read from the probe's own HTTP status, the dispatch
+ * contract's signal: only a wire exchange yields a non-zero status, and an
+ * in-library grade reports 0 by definition. Deliberately not read from the
+ * step's validations — the runner appends invariant results to steps, so
+ * "its only check is `probe_passed`" silently stops matching the moment an
+ * invariant is registered.
+ *
+ * Exported as the single definition of this rule. The storyboard verdict,
+ * the compliance track rollup, the compliance report and the CLI exit
+ * contract all consume it — the CLI through `dist`, over a view of the
+ * mapped `TestStepResult` shape — because hand-written copies of it drifted
+ * within one revision of this change, one of them into a false CI failure.
+ */
+export type SigningCoverage = 'not_probed' | 'graded' | 'probe_errored' | 'transport_unverified' | 'scope_excluded' | 'self_check_only';
+/**
+ * Minimal step view the coverage rule needs. `StoryboardStepResult` satisfies
+ * it directly; the compliance projection maps `observation_data` onto
+ * `response`.
+ */
+export interface SigningCoverageStepView {
+    task?: string;
+    skipped?: boolean;
+    skip_reason?: string;
+    /** The probe's `HttpProbeResult`, as recorded on the step. */
+    response?: unknown;
+}
+export declare function signingCoverage(steps: readonly SigningCoverageStepView[]): SigningCoverage;
+/** True when signing probes ran and none of them reached the agent. */
+export declare function signingCoverageUnverified(steps: readonly SigningCoverageStepView[]): boolean;
 /**
  * Build a hard-failure StoryboardResult for when agent capability
  * discovery (`get_agent_info` / MCP `tools/list`) failed. Surfacing
@@ -135,6 +209,34 @@ export declare function summarizeStrictValidation(phases: StoryboardPhaseResult[
  * Context is passed in and returned, enabling step-by-step orchestration.
  */
 export declare function runStoryboardStep(agentUrl: string, storyboard: Storyboard, stepId: string, options?: StoryboardRunOptions): Promise<StoryboardStepResult>;
+/**
+ * Credential mechanism a sentinel step is exercising, derived from
+ * `step.auth.type`. The acceptance control must be the *same kind* of
+ * credential, because the storyboard's branches certify different claims:
+ *
+ * - `oauth_bearer` → `oauth_discovery` certifies "the agent validates inbound
+ *   OAuth tokens". A static API key accepted at the endpoint is no evidence
+ *   about that path, so it cannot stand in as the control — otherwise correct
+ *   PRM plus an unrelated shared secret would launder into
+ *   `auth_mechanism_verified`, which is the advertised-but-unserved failure
+ *   mode `security_baseline` exists to catch. Note the bound on the positive
+ *   claim too: an accepted OAuth control shows the endpoint accepted the
+ *   credential the runner was *configured with* as an OAuth token. The runner
+ *   does not verify that token's issuer cryptographically.
+ * - `api_key` / `basic` → the matching static-credential branch.
+ * - `any` → `auth: none` (the unauthenticated probe), which asserts only that
+ *   *some* credential is required, so any valid credential discriminates.
+ */
+type SessionControlMechanism = 'any' | 'oauth_bearer' | 'api_key' | 'basic';
+interface SessionControlUnavailable {
+    reason: string;
+    remedy: string;
+}
+type SessionControlResolution = {
+    headers: Record<string, string>;
+} | {
+    unavailable: SessionControlUnavailable;
+};
 /**
  * Force every outgoing request onto the storyboard's brand context.
  *
@@ -210,3 +312,4 @@ export declare function applyIdempotencyInvariant(request: Record<string, unknow
  * bound at preview time. They'll resolve when the step actually runs.
  */
 export declare function getFirstStepPreview(storyboard: Storyboard, context?: StoryboardContext): StoryboardStepPreview | undefined;
+export {};