@binclusive/a11y 0.1.0

package/src/runner/codegraph-lookup.test.ts

@@ -0,0 +1,93 @@
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import { createCodeGraphLookup } from "./codegraph-lookup";
+import { LookupCounter, meterLookup } from "./lookup";
+
+/**
+ * These tests drive the REAL published `@binclusive/code-graph` CLI as a subprocess
+ * over a real directory (a small `test/fixtures/code-graph-lookup` module), so they
+ * exercise the actual stdout contract this seam depends on — not a mock. Each spawns
+ * a ts-morph cheap pass (~1-2s), so they carry an explicit per-test timeout.
+ */
+const CODE_GRAPH_SRC = fileURLToPath(
+  new URL("../../test/fixtures/code-graph-lookup", import.meta.url),
+);
+const TIMEOUT = 30_000;
+
+describe("createCodeGraphLookup — structural lookups over the published CLI", () => {
+  it(
+    "a `file` query returns the module's structural JSON",
+    async () => {
+      const tool = createCodeGraphLookup({ root: CODE_GRAPH_SRC });
+      const result = await tool.lookup({ kind: "file", target: "schema.ts" });
+
+      expect(result.status).toBe("ok");
+      if (result.status !== "ok") return;
+      const data = result.data as { found: boolean; kind?: string; json?: unknown };
+      expect(data.found).toBe(true);
+      expect(data.kind).toBe("file");
+      // The `--file` view is a module record — assert its shape at the boundary.
+      const json = data.json as { module?: { file?: string } };
+      expect(json.module?.file).toBe("schema.ts");
+    },
+    TIMEOUT,
+  );
+
+  it(
+    "a `summary` query returns the project health JSON",
+    async () => {
+      const tool = createCodeGraphLookup({ root: CODE_GRAPH_SRC });
+      const result = await tool.lookup({ kind: "summary", target: "" });
+
+      expect(result.status).toBe("ok");
+      if (result.status !== "ok") return;
+      const data = result.data as { found: boolean; json?: unknown };
+      expect(data.found).toBe(true);
+      const json = data.json as { fileCount?: number };
+      expect(typeof json.fileCount).toBe("number");
+    },
+    TIMEOUT,
+  );
+
+  it(
+    "a missing file is a `found: false` envelope, not a throw",
+    async () => {
+      const tool = createCodeGraphLookup({ root: CODE_GRAPH_SRC });
+      const result = await tool.lookup({ kind: "file", target: "does-not-exist.ts" });
+
+      expect(result.status).toBe("ok");
+      if (result.status !== "ok") return;
+      const data = result.data as { found: boolean };
+      expect(data.found).toBe(false);
+    },
+    TIMEOUT,
+  );
+
+  it("an unknown kind is refused without spawning a subprocess", async () => {
+    const tool = createCodeGraphLookup({ root: CODE_GRAPH_SRC });
+    const result = await tool.lookup({ kind: "not-a-real-kind", target: "x" });
+
+    expect(result.status).toBe("ok");
+    if (result.status !== "ok") return;
+    const data = result.data as { found: boolean; reason?: string };
+    expect(data.found).toBe(false);
+    expect(data.reason).toContain("unsupported lookup kind");
+  });
+
+  it(
+    "the per-finding cap still short-circuits the tool via meterLookup",
+    async () => {
+      const tool = createCodeGraphLookup({ root: CODE_GRAPH_SRC });
+      const counter = new LookupCounter(1);
+      const metered = meterLookup(tool, counter);
+
+      const first = await metered.lookup({ kind: "summary", target: "" });
+      expect(first.status).toBe("ok");
+      const second = await metered.lookup({ kind: "summary", target: "" });
+      // Budget spent: the second call is capped and never reaches code-graph.
+      expect(second.status).toBe("capped");
+      expect(counter.used).toBe(1);
+    },
+    TIMEOUT,
+  );
+});

package/src/runner/codegraph-lookup.ts

@@ -0,0 +1,197 @@
+/**
+ * The code-graph implementation of the structural-lookup seam (#2097).
+ *
+ * This fills the {@link LookupTool} interface `lookup.ts` left open: it answers a
+ * reasoner's structural questions ("which module is this / what does it export",
+ * "who calls this function") by shelling out to the published
+ * `@binclusive/code-graph` CLI and returning its deterministic JSON. Calling it as
+ * a subprocess — rather than importing its internals — keeps the boundary at
+ * code-graph's stdout contract: one JSON document per query, nothing else.
+ *
+ * The tool spends NO model tokens, so it is metered on the count-based per-finding
+ * budget by {@link meterLookup} in the runner — this tool never returns `capped`
+ * itself (only the meter wrapper does). It is also TOTAL: every failure mode (an
+ * unknown query kind, a missing file, no tsconfig for the edge pass, a subprocess
+ * crash or timeout) becomes a `{ found: false }` envelope in `data`, never a
+ * throw. The AI lane is non-blocking; a structure lookup that can't answer is a
+ * gap the reasoner works around, not an error that ends the pass.
+ *
+ * The CLI is resolved from the installed `@binclusive/code-graph` dependency, so
+ * the customer's cwd never matters and the same compiled artifact runs in the
+ * Docker image as locally. The published package ships a compiled ESM bin
+ * (`dist/index.js`), so it runs under plain `node` — no tsx loader needed.
+ */
+import { spawn } from "node:child_process";
+import { createRequire } from "node:module";
+import type { LookupQuery, LookupResult, LookupTool } from "./lookup";
+
+const require = createRequire(import.meta.url);
+/**
+ * The published code-graph CLI entry. Resolved by subpath from the installed
+ * dependency — the package exposes its bin as `dist/index.js` (no `main`/`exports`
+ * map), so the explicit subpath is how a consumer reaches it.
+ */
+const CODE_GRAPH_CLI = require.resolve("@binclusive/code-graph/dist/index.js");
+
+/** A slow subprocess must not stall a pass; the pull loop stays responsive. */
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+/**
+ * The structural questions code-graph can answer for the agent lane. The seam's
+ * {@link LookupQuery.kind} is an open `string`; these are the values this tool
+ * understands (with a couple of natural aliases). Anything else is a `found:
+ * false` envelope, not a throw — the reasoner never crashes on a typo.
+ */
+export type CodeGraphQueryKind =
+  /** One module + its functions/imports/importedBy — "what is in this file". */
+  | "file"
+  /** Callers of one function id (direct + transitive) — "where does this flow / who uses it". */
+  | "callers"
+  /** Whole-project structural health summary — "orient me in this codebase". */
+  | "summary";
+
+/**
+ * What a code-graph lookup yields, carried in {@link LookupResult}'s `data`. The
+ * reasoner narrows on `found`; `json` is the deterministic structural document
+ * code-graph emitted for that query kind (shape documented per kind in SPEC.md).
+ */
+export type CodeGraphLookupData =
+  | { readonly found: true; readonly kind: CodeGraphQueryKind; readonly json: unknown }
+  | { readonly found: false; readonly reason: string };
+
+export interface CodeGraphLookupConfig {
+  /**
+   * Absolute path to the directory code-graph analyzes — the customer's checked
+   * -out repo (or the diff-scoped subtree). Every query is relative to this root.
+   */
+  readonly root: string;
+  /** Per-lookup wall-clock budget. Defaults to {@link DEFAULT_TIMEOUT_MS}. */
+  readonly timeoutMs?: number;
+}
+
+/**
+ * Build a {@link LookupTool} backed by the vendored code-graph CLI. Inject the
+ * result into the runner's `RunInput.lookup`; the harness caps how many times the
+ * reasoner may call it per finding.
+ */
+export function createCodeGraphLookup(config: CodeGraphLookupConfig): LookupTool {
+  const timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+
+  return {
+    async lookup(query: LookupQuery): Promise<LookupResult> {
+      const plan = planQuery(config.root, query);
+      if (plan === null) {
+        return ok({ found: false, reason: `unsupported lookup kind: ${query.kind}` });
+      }
+
+      const { code, stdout } = await runCli(plan.argv, timeoutMs);
+      if (code !== 0) {
+        // code-graph clean-exits 2 with a one-line reason (bad path, no tsconfig
+        // for the edge pass, …); 1 is a CI-gate fail we don't drive here.
+        return ok({ found: false, reason: `code-graph exited ${code}` });
+      }
+
+      // A missing --file / an empty result writes a stderr warning and NO stdout
+      // at exit 0, so empty-or-unparseable stdout is a genuine "not found".
+      const parsed = parseJson(stdout);
+      if (!parsed.ok) {
+        return ok({ found: false, reason: parsed.reason });
+      }
+      return ok({ found: true, kind: plan.kind, json: parsed.value });
+    },
+  };
+}
+
+/** Wrap code-graph's answer in the seam's `ok` result (never `capped` here). */
+function ok(data: CodeGraphLookupData): LookupResult {
+  return { status: "ok", data };
+}
+
+/** Normalize the open `kind` string onto a supported query, with aliases. */
+function normalizeKind(kind: string): CodeGraphQueryKind | null {
+  switch (kind) {
+    case "file":
+    case "module":
+      return "file";
+    case "callers":
+    case "blast":
+    case "usages":
+      return "callers";
+    case "summary":
+    case "overview":
+      return "summary";
+    default:
+      return null;
+  }
+}
+
+/** Translate a query into the code-graph argv, or `null` for an unknown kind. */
+function planQuery(
+  root: string,
+  query: LookupQuery,
+): { readonly kind: CodeGraphQueryKind; readonly argv: readonly string[] } | null {
+  const kind = normalizeKind(query.kind);
+  if (kind === null) return null;
+
+  switch (kind) {
+    case "file":
+      // Module + its functions, as JSON (root-relative file path in target).
+      return { kind, argv: [root, "--file", query.target, "--json"] };
+    case "callers":
+      // Blast radius needs the opt-in edge pass (calls/calledBy) — requires a
+      // reachable tsconfig; code-graph clean-exits 2 when there is none.
+      return { kind, argv: [root, "--edges", "--blast", query.target, "--json"] };
+    case "summary":
+      // The bare invocation already emits the JSON summary; target is ignored.
+      return { kind, argv: [root] };
+    default: {
+      const exhaustive: never = kind;
+      return exhaustive;
+    }
+  }
+}
+
+/** Run the vendored CLI under tsx, capturing stdout. Total: never rejects. */
+function runCli(
+  argv: readonly string[],
+  timeoutMs: number,
+): Promise<{ readonly code: number; readonly stdout: string }> {
+  return new Promise((resolve) => {
+    const child = spawn(process.execPath, [CODE_GRAPH_CLI, ...argv], {
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+
+    let stdout = "";
+    const timer = setTimeout(() => child.kill("SIGKILL"), timeoutMs);
+
+    child.stdout.on("data", (chunk: Buffer) => {
+      stdout += chunk.toString("utf8");
+    });
+    // Drain stderr so a chatty warning can't fill the pipe buffer and deadlock.
+    child.stderr.resume();
+
+    child.on("error", () => {
+      clearTimeout(timer);
+      resolve({ code: -1, stdout: "" });
+    });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      resolve({ code: code ?? -1, stdout });
+    });
+  });
+}
+
+type ParseResult =
+  | { readonly ok: true; readonly value: unknown }
+  | { readonly ok: false; readonly reason: string };
+
+/** Parse code-graph's stdout as JSON. Empty output = a not-found lookup. */
+function parseJson(stdout: string): ParseResult {
+  const trimmed = stdout.trim();
+  if (trimmed.length === 0) return { ok: false, reason: "no result" };
+  try {
+    return { ok: true, value: JSON.parse(trimmed) };
+  } catch {
+    return { ok: false, reason: "code-graph output was not JSON" };
+  }
+}

package/src/runner/index.ts

@@ -0,0 +1,86 @@
+/**
+ * `@binclusive/a11y` runner — the provider-agnostic AI lane (issue #2095).
+ *
+ * The harness that sits on top of the deterministic engine: a BYO-provider
+ * abstraction + a capped, non-blocking pull loop that consumes the engine's
+ * deterministic findings and emits agent-provenance findings through the SAME
+ * metadata-only contract projection. The code-graph lookups (#2097) live behind
+ * the `LookupTool` seam. The reasoning CORE (#2096) — the ported per-framework
+ * checklists + pattern catalog and the concrete `AgentReasoner` — fills the
+ * reasoning seam (`./reasoning`). The enrich/discover deepening (#2098) is now
+ * FILLED: the reasoner returns a `ReasonResult` (in-place enrichment + discovered
+ * findings), parsed at a tolerant zod boundary and deduped against the floor.
+ */
+export {
+  type BudgetSnapshot,
+  meterProvider,
+  TokenCeilingExceeded,
+  TokenLedger,
+} from "./budget";
+export {
+  LookupCounter,
+  type LookupQuery,
+  type LookupResult,
+  type LookupTool,
+  meterLookup,
+} from "./lookup";
+export {
+  type CodeGraphLookupConfig,
+  type CodeGraphLookupData,
+  type CodeGraphQueryKind,
+  createCodeGraphLookup,
+} from "./codegraph-lookup";
+export {
+  isMeterableUsage,
+  type Provider,
+  type ProviderMessage,
+  type ProviderRequest,
+  type ProviderResponse,
+  type TokenUsage,
+  usageTotal,
+} from "./provider";
+export {
+  type AnthropicProviderConfig,
+  createAnthropicProvider,
+  DEFAULT_ANTHROPIC_MODEL,
+} from "./providers/anthropic";
+export {
+  type AgentFinding,
+  type AgentReasoner,
+  EMPTY_RESULT,
+  type ReasonContext,
+  type ReasonResult,
+} from "./reasoner";
+export {
+  DEFAULT_RUNNER_CONFIG,
+  type PassOutcome,
+  type PassReport,
+  type RunInput,
+  type RunnerConfig,
+  type RunOutcome,
+  runAgentLane,
+} from "./runner";
+export {
+  type ChecklistArea,
+  type Discovery,
+  type FixSeverity,
+  type FixSuggestion,
+  type FixType,
+  FIX_TYPES,
+  type FrameworkGuidance,
+  frameworkGuidanceFor,
+  type PatternCatalogEntry,
+  REACT_GUIDANCE,
+  SHOPIFY_GUIDANCE,
+} from "./reasoning";
+export {
+  createSkillsReasoner,
+  type SkillsReasonerOptions,
+} from "./reasoning/skills-reasoner";
+export {
+  buildSystemPrompt,
+  buildUserPrompt,
+  type ParsedReasonResponse,
+  parseReasonResponse,
+  suggestionMessage,
+} from "./reasoning/prompt";

package/src/runner/lookup.ts

@@ -0,0 +1,69 @@
+/**
+ * The structural-lookup seam — how the reasoner asks about code STRUCTURE
+ * (which component renders this, where a prop flows) without reading raw source
+ * into a model prompt. The concrete implementation is `tools/code-graph` (#2097);
+ * the harness only defines the interface and enforces the per-finding cap.
+ *
+ * A lookup is a SOFT cap, unlike the token ceiling. "one pass per finding + ~3-5
+ * lookups" (issue #2095): exceeding the lookup budget yields a `capped` result the
+ * reasoner reads as "finalize with what you have" — FEWER lookups, still a
+ * finding. Only the token ceiling is hard (it ends the run). Lookups spend no
+ * model tokens, so they are metered on their own count-based budget, independent
+ * of the token ledger.
+ */
+
+/**
+ * A structural query. Left deliberately open — `kind`/`target` are the minimal
+ * shape the harness needs to pass a query through; #2097 owns the real taxonomy
+ * of queries the code-graph answers.
+ */
+export interface LookupQuery {
+  readonly kind: string;
+  readonly target: string;
+}
+
+export type LookupResult =
+  | { readonly status: "ok"; readonly data: unknown }
+  /** The per-finding lookup budget is spent — finalize the pass with what you have. */
+  | { readonly status: "capped" };
+
+/** The seam #2097 implements over the code-graph. */
+export interface LookupTool {
+  readonly lookup: (query: LookupQuery) => Promise<LookupResult>;
+}
+
+/** Counts lookups against a per-finding budget. Fresh per pass. */
+export class LookupCounter {
+  #used = 0;
+
+  constructor(readonly cap: number) {}
+
+  get used(): number {
+    return this.#used;
+  }
+
+  exhausted(): boolean {
+    return this.#used >= this.cap;
+  }
+
+  /** Charge one lookup slot. Called by {@link meterLookup} before it delegates. */
+  charge(): void {
+    this.#used += 1;
+  }
+}
+
+/**
+ * Wrap a lookup tool so it stops delegating once the per-finding cap is reached,
+ * returning `{ status: "capped" }` instead. Soft by design: the reasoner keeps
+ * going and produces a finding from what it already learned. The slot is charged
+ * before delegating, so a throwing tool still consumes its budget.
+ */
+export function meterLookup(tool: LookupTool, counter: LookupCounter): LookupTool {
+  return {
+    async lookup(query) {
+      if (counter.exhausted()) return { status: "capped" };
+      counter.charge();
+      return tool.lookup(query);
+    },
+  };
+}

package/src/runner/provider.ts

@@ -0,0 +1,72 @@
+/**
+ * The provider abstraction — the BYO seam of the AI lane.
+ *
+ * The runner drives ANY language model through this ONE interface. Nothing here
+ * names Anthropic, OpenAI, or any vendor: the customer implements {@link Provider}
+ * over their OWN SDK and their OWN key, and injects it. The engine ships no LLM
+ * credential and no vendor SDK — provider-agnostic by construction (epic #2083,
+ * "BYO provider; Claude Code not required").
+ *
+ * The one hard requirement the runner places on a provider: every response must
+ * report its {@link TokenUsage}. That is what makes the per-PR token ceiling
+ * enforceable across an untrusted, vendor-specific model. A provider that cannot
+ * report usage cannot be metered — so usage is part of the contract, not optional.
+ */
+
+/** One turn in a request. Vendor-neutral: `system` + a flat message list. */
+export interface ProviderMessage {
+  readonly role: "user" | "assistant";
+  readonly content: string;
+}
+
+export interface ProviderRequest {
+  /** Optional system framing (the reasoning skills live here — seam for #2096). */
+  readonly system?: string;
+  readonly messages: readonly ProviderMessage[];
+  /** Upper bound on output tokens the caller wants; the provider may honor it. */
+  readonly maxOutputTokens?: number;
+}
+
+/**
+ * Token accounting for one completion. Both counts are required — the ceiling is
+ * enforced on `inputTokens + outputTokens`, so a provider that omits either can't
+ * be trusted to stay under budget.
+ */
+export interface TokenUsage {
+  readonly inputTokens: number;
+  readonly outputTokens: number;
+}
+
+export interface ProviderResponse {
+  readonly text: string;
+  readonly usage: TokenUsage;
+}
+
+/**
+ * The one method the runner calls. Implement it over your model of choice; the
+ * runner meters every call against the per-PR token ceiling (see
+ * {@link ./budget.meterProvider}). Implementations should surface transport
+ * failures by rejecting — the runner treats a rejected pass as a non-fatal,
+ * recorded error and keeps going (never fails the run).
+ */
+export interface Provider {
+  readonly complete: (request: ProviderRequest) => Promise<ProviderResponse>;
+}
+
+/** The total tokens one usage record spends — meaningful only for a {@link isMeterableUsage | meterable} record. */
+export function usageTotal(usage: TokenUsage): number {
+  return usage.inputTokens + usage.outputTokens;
+}
+
+/**
+ * Whether a usage record can be trusted against the ceiling: BOTH counts finite
+ * and non-negative. A malformed provider response — `NaN`, `±Infinity`, or a
+ * negative count — makes the ceiling comparison silently mis-evaluate
+ * (`NaN >= ceiling` is always `false`), disabling the cap and letting the run
+ * spend past budget. The ledger gates on this and treats an unmeterable usage as
+ * AT-OR-OVER the ceiling, never under it (issue #2169).
+ */
+export function isMeterableUsage(usage: TokenUsage): boolean {
+  const ok = (n: number): boolean => Number.isFinite(n) && n >= 0;
+  return ok(usage.inputTokens) && ok(usage.outputTokens);
+}

package/src/runner/providers/anthropic.ts

@@ -0,0 +1,168 @@
+/**
+ * The concrete, ship-in-the-box {@link Provider} — Anthropic's Messages API over
+ * global `fetch` (epic #2083, issue #2182).
+ *
+ * The {@link Provider} interface (`../provider`) is the BYO seam: nothing in the
+ * runner names a vendor, and a customer can still inject their own model. This
+ * module fills that seam with ONE default implementation so a bare `LLM_API_KEY`
+ * drives the AI lane end to end — no vendor SDK, no extra install. The engine
+ * ships lean: the whole provider is a single `fetch` POST, mapping the vendor-
+ * neutral {@link ProviderRequest} onto the Anthropic request body and the reply
+ * back onto {@link ProviderResponse} (crucially, its {@link TokenUsage} — the
+ * runner's token ceiling is only enforceable because usage is reported).
+ *
+ * Per the {@link Provider} contract, this SURFACES transport failures by
+ * REJECTING: a non-2xx, a malformed body, or a network error throws. The runner
+ * catches a rejected pass and records it as a non-fatal error, so a provider
+ * that throws degrades the run to "no agent findings for that pass", never a
+ * crash — the AI lane stays non-blocking.
+ *
+ * A HANG is a failure a `throw` alone does not cover, so the `fetch` is bounded
+ * by an {@link AbortController} + timeout (mirroring `src/phone-home.ts`). A
+ * stalled provider — network stall, provider outage, no response — is aborted at
+ * the bound and surfaced as a rejection like any other transport failure, so the
+ * runner records the pass as errored and keeps going. Without this, a single hung
+ * request would hang the whole CI job, turning the non-blocking soft-degrade into
+ * a hard block on the customer's PR pipeline (issue #2192).
+ */
+import type { Provider, ProviderRequest, ProviderResponse, TokenUsage } from "../provider";
+
+/**
+ * The default model for the low-cap advisory CI lane: a fast, cost-appropriate
+ * model. Overridable via the provider config (wired to `LLM_MODEL`), so dialing
+ * up to a stronger model is one env var, not a code change.
+ */
+export const DEFAULT_ANTHROPIC_MODEL = "claude-haiku-4-5-20251001";
+
+/** Anthropic's dated API version header — pinned so a server-side default shift can't drift the shape. */
+const ANTHROPIC_VERSION = "2023-06-01";
+const DEFAULT_BASE_URL = "https://api.anthropic.com";
+/** A pass is one short suggestion; cap output when the caller doesn't ask. */
+const DEFAULT_MAX_OUTPUT_TOKENS = 1024;
+
+/**
+ * The safe default wall-clock bound on one provider request (issue #2192). A
+ * low-cap advisory completion (≤ {@link DEFAULT_MAX_OUTPUT_TOKENS} output tokens
+ * on a fast model) returns in seconds; 60s leaves generous headroom for a slow
+ * healthy response while still bounding a genuine hang, so a stalled request
+ * aborts and degrades the AI lane softly instead of stalling CI. Override via
+ * {@link AnthropicProviderConfig.timeoutMs} (wired to `LLM_TIMEOUT_MS`).
+ */
+export const DEFAULT_REQUEST_TIMEOUT_MS = 60_000;
+
+export interface AnthropicProviderConfig {
+  /** The customer's Anthropic key (from `LLM_API_KEY`). Never logged. */
+  readonly apiKey: string;
+  /** Model id. Defaults to {@link DEFAULT_ANTHROPIC_MODEL}. */
+  readonly model?: string;
+  /** Injectable for tests / alternate gateways. Defaults to `globalThis.fetch`. */
+  readonly fetchImpl?: typeof fetch;
+  /** Override the API origin (self-hosted gateway / proxy). Defaults to Anthropic. */
+  readonly baseUrl?: string;
+  /**
+   * Wall-clock bound on one request before it aborts (from `LLM_TIMEOUT_MS`).
+   * Defaults to {@link DEFAULT_REQUEST_TIMEOUT_MS}. A non-finite or non-positive
+   * value falls back to the default — a bad knob can't disable the bound and
+   * re-open the hang hole (issue #2192).
+   */
+  readonly timeoutMs?: number;
+}
+
+/** Anthropic's `messages` response, narrowed at the boundary — never trusted raw. */
+interface AnthropicResponseBody {
+  readonly content?: ReadonlyArray<{ readonly type?: string; readonly text?: string }>;
+  readonly usage?: { readonly input_tokens?: number; readonly output_tokens?: number };
+}
+
+/** Concatenate the text blocks of a Messages reply into one string. */
+function textOf(body: AnthropicResponseBody): string {
+  if (!Array.isArray(body.content)) return "";
+  return body.content
+    .filter((block) => block.type === "text" && typeof block.text === "string")
+    .map((block) => block.text)
+    .join("");
+}
+
+/**
+ * A single reported token count, or `+Infinity` when the body reports it absent,
+ * non-numeric, `NaN`, or negative. Anthropic always reports both counts; a body
+ * that doesn't is malformed, so we parse-don't-validate at the boundary and map
+ * the bad count to a fail-closed sentinel rather than silently charging 0. The
+ * ledger meters `+Infinity` as at-or-over the ceiling, stopping the lane instead
+ * of letting a malformed response run past the cap (issue #2169).
+ */
+function meterableCount(raw: number | undefined): number {
+  return typeof raw === "number" && Number.isFinite(raw) && raw >= 0 ? raw : Number.POSITIVE_INFINITY;
+}
+
+/**
+ * The token usage the runner meters against the per-PR ceiling — parsed from the
+ * untrusted body, never read raw. A missing or malformed count maps to `+Infinity`
+ * (see {@link meterableCount}) so the ceiling fails closed on a bad provider
+ * response rather than under-counting toward a silent overspend.
+ */
+function usageOf(body: AnthropicResponseBody): TokenUsage {
+  return {
+    inputTokens: meterableCount(body.usage?.input_tokens),
+    outputTokens: meterableCount(body.usage?.output_tokens),
+  };
+}
+
+/**
+ * Build the ship-in-the-box Anthropic {@link Provider}. Inject into the runner's
+ * `RunInput.provider`; the harness meters every `complete` call against the token
+ * ceiling. Rejects on any transport / shape failure — the runner treats that as a
+ * non-fatal, recorded pass error.
+ */
+export function createAnthropicProvider(config: AnthropicProviderConfig): Provider {
+  const model = config.model ?? DEFAULT_ANTHROPIC_MODEL;
+  const fetchImpl = config.fetchImpl ?? globalThis.fetch;
+  const endpoint = `${config.baseUrl ?? DEFAULT_BASE_URL}/v1/messages`;
+  const timeoutMs =
+    typeof config.timeoutMs === "number" && Number.isFinite(config.timeoutMs) && config.timeoutMs > 0
+      ? config.timeoutMs
+      : DEFAULT_REQUEST_TIMEOUT_MS;
+
+  return {
+    async complete(request: ProviderRequest): Promise<ProviderResponse> {
+      // Bound the whole exchange — connect AND body read: a hang at either stage
+      // aborts at the timeout and surfaces as a rejection, closing the
+      // non-blocking hole a bare `throw` can't (#2192). We own this controller,
+      // so any abort here IS our timeout. The signal cancels an in-flight body
+      // read too, so a stalled response can't slip past a resolved-headers fetch.
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), timeoutMs);
+      try {
+        const response = await fetchImpl(endpoint, {
+          method: "POST",
+          headers: {
+            "content-type": "application/json",
+            "x-api-key": config.apiKey,
+            "anthropic-version": ANTHROPIC_VERSION,
+          },
+          body: JSON.stringify({
+            model,
+            max_tokens: request.maxOutputTokens ?? DEFAULT_MAX_OUTPUT_TOKENS,
+            ...(request.system !== undefined ? { system: request.system } : {}),
+            messages: request.messages.map((m) => ({ role: m.role, content: m.content })),
+          }),
+          signal: controller.signal,
+        });
+
+        if (!response.ok) {
+          // Surface as a rejection — the runner records the pass as a non-fatal
+          // error and keeps going. The key never reaches the message.
+          throw new Error(`Anthropic API returned HTTP ${response.status}`);
+        }
+
+        const body = (await response.json()) as AnthropicResponseBody;
+        return { text: textOf(body), usage: usageOf(body) };
+      } catch (error) {
+        if (controller.signal.aborted) throw new Error(`Anthropic request timed out after ${timeoutMs}ms`);
+        throw error;
+      } finally {
+        clearTimeout(timer);
+      }
+    },
+  };
+}