trail-code 0.0.0-stage → 0.28.0-semantic.3

package/dist/ai/crux.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Tier-2 "meaning" call for the code graph — batched one request per file.
+ *
+ * Given a source file (with 1-based line numbers) and the list of definitions in
+ * it, one call returns, for each definition:
+ *   1. `summary` — one plain-English sentence: what the symbol is *for*, at the
+ *      business-logic level, not a restatement of its signature.
+ *   2. `crux_start`/`crux_end` — the smallest contiguous range of FILE line
+ *      numbers (inside that symbol's own span) that a reviewer must read to see
+ *      the decision or rule the code encodes. `0/0` means there is no single
+ *      crux (a trivial getter, a plain data holder).
+ *
+ * Batching per file means N definitions cost one request, not N — and the model
+ * sees each symbol's neighbours, which sharpens the summaries. Line numbers are
+ * consumed once, at write time, to slice the crux text verbatim from source.
+ */
+import type { ChatModel, ChatResponse } from "./llm/types.js";
+import type { Kind } from "../graph/types.js";
+/** One definition we want described, located by its line span within the file. */
+export interface NodeRef {
+    id: string;
+    kind: Kind;
+    signature: string | null;
+    startLine: number;
+    endLine: number;
+}
+export interface FileCruxInput {
+    path: string;
+    source: string;
+    nodes: NodeRef[];
+}
+export interface NodeCrux {
+    id: string;
+    summary: string;
+    crux_start: number;
+    crux_end: number;
+}
+export interface CruxSummarizer {
+    describeFile(input: FileCruxInput): Promise<NodeCrux[]>;
+    /** Set by {@link ChatCruxSummarizer} after each call; optional on fakes. */
+    lastMiss?: CruxMiss | null;
+}
+/** Why a crux call produced no usable summaries (#235). */
+export type CruxMissKind = "empty-toolCalls" | "unparseable" | "truncated" | "empty-parsed" | "id-mismatch";
+export interface CruxMiss {
+    kind: CruxMissKind;
+    finishReason: string | null;
+    /** `id-mismatch` only: how many entries came back, and the first one's raw id. */
+    returned?: number;
+    firstId?: string;
+}
+/**
+ * Classify an empty/unusable crux reply. `null` means at least one usable summary.
+ * With `requested`, a summary only counts when its id is one we asked for: enrich
+ * looks results up by node id, so a summary under any other id is never applied.
+ */
+export declare function classifyCruxMiss(res: ChatResponse, parsed: NodeCrux[], requested?: readonly string[]): CruxMiss | null;
+/** Per-file error text: miss class + the provider's finish_reason (#235). */
+export declare function formatCruxMiss(kind: CruxMissKind, finishReason: string | null): string;
+/**
+ * The model's text for an `id-mismatch`, kept apart from {@link formatCruxMiss}:
+ * the failure gate matches words like "quota" in the error message, and a
+ * returned id can carry any source text, so it must never reach the gate.
+ */
+export declare function formatCruxMissDetail(miss: CruxMiss | null | undefined): string;
+/**
+ * Map an id the model returned onto one of the ids we asked for, or null.
+ *
+ * Models echo decorated target rows instead of the bare id (#259, #298, #486).
+ * Rather than cut the string at a guessed delimiter, every rule compares against
+ * the requested ids, so the result is always an id we asked for — never a
+ * fragment of a hallucinated one — and no rule assumes which characters an id
+ * may contain. In order:
+ *   1. exact match;
+ *   2. a requested id followed by ` | ` (the row echoed from the id onwards);
+ *   3. the same two with a leading `id=` removed;
+ *   4. a row ending in ` | id=<requested id>` (the current layout echoed whole).
+ * When several requested ids qualify, the longest wins.
+ */
+export declare function resolveTargetId(raw: string, requested: readonly string[]): string | null;
+/** Crux summarizer backed by any {@link ChatModel} via forced tool calling. */
+export declare class ChatCruxSummarizer implements CruxSummarizer {
+    private model;
+    lastMiss: CruxMiss | null;
+    constructor(model: ChatModel);
+    describeFile(input: FileCruxInput): Promise<NodeCrux[]>;
+}
+//# sourceMappingURL=crux.d.ts.map

package/dist/ai/crux.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crux.d.ts","sourceRoot":"","sources":["../../src/ai/crux.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE9D,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAE9C,kFAAkF;AAClF,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,IAAI,CAAC;IACX,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,OAAO,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,YAAY,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;IACxD,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAC;CAC5B;AAED,2DAA2D;AAC3D,MAAM,MAAM,YAAY,GACpB,iBAAiB,GACjB,aAAa,GACb,WAAW,GACX,cAAc,GACd,aAAa,CAAC;AAElB,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,YAAY,CAAC;IACnB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,kFAAkF;IAClF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAQD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,YAAY,EACjB,MAAM,EAAE,QAAQ,EAAE,EAClB,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,GAC5B,QAAQ,GAAG,IAAI,CAcjB;AAED,6EAA6E;AAC7E,wBAAgB,cAAc,CAAC,IAAI,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAMtF;AAKD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAO9E;AAwED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,GAAG,IAAI,CAYxF;AA2CD,+EAA+E;AAC/E,qBAAa,kBAAmB,YAAW,cAAc;IAG3C,OAAO,CAAC,KAAK;IAFzB,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAQ;gBAEb,KAAK,EAAE,SAAS;IAE9B,YAAY,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;CAwB9D"}

package/dist/ai/crux.js

@@ -0,0 +1,219 @@
+import { recoverToolArgsFromContent, warnToolChoiceIgnored } from "./llm/recover-tool.js";
+function isTruncatedStop(reason) {
+    if (!reason)
+        return false;
+    const r = reason.toLowerCase();
+    return r === "length" || r === "max_tokens";
+}
+/**
+ * Classify an empty/unusable crux reply. `null` means at least one usable summary.
+ * With `requested`, a summary only counts when its id is one we asked for: enrich
+ * looks results up by node id, so a summary under any other id is never applied.
+ */
+export function classifyCruxMiss(res, parsed, requested) {
+    const finishReason = res.stopReason;
+    const wanted = requested ? new Set(requested) : undefined;
+    const matched = wanted ? parsed.filter((p) => wanted.has(p.id)) : parsed;
+    if (matched.some((p) => p.summary.trim()))
+        return null;
+    if (isTruncatedStop(finishReason))
+        return { kind: "truncated", finishReason };
+    if (parsed.length > 0 && matched.length === 0) {
+        return { kind: "id-mismatch", finishReason, returned: parsed.length, firstId: parsed[0].id };
+    }
+    if (parsed.length > 0)
+        return { kind: "empty-parsed", finishReason };
+    const emptyTools = res.toolCalls.length === 0;
+    const emptyText = !res.text?.trim();
+    if (emptyTools && emptyText)
+        return { kind: "empty-toolCalls", finishReason };
+    return { kind: "unparseable", finishReason };
+}
+/** Per-file error text: miss class + the provider's finish_reason (#235). */
+export function formatCruxMiss(kind, finishReason) {
+    const fr = finishReason == null || finishReason === "" ? "null" : finishReason;
+    if (kind === "id-mismatch") {
+        return `model returned summaries but no id matched a requested target [${kind}, finish_reason=${fr}]`;
+    }
+    return `model returned no usable symbol summaries [${kind}, finish_reason=${fr}]`;
+}
+/** Longest echoed id shown in an error; a whole echoed row can carry a long signature. */
+const MAX_SHOWN_ID_CHARS = 200;
+/**
+ * The model's text for an `id-mismatch`, kept apart from {@link formatCruxMiss}:
+ * the failure gate matches words like "quota" in the error message, and a
+ * returned id can carry any source text, so it must never reach the gate.
+ */
+export function formatCruxMissDetail(miss) {
+    if (miss?.kind !== "id-mismatch" || miss.firstId === undefined)
+        return "";
+    const id = miss.firstId.length > MAX_SHOWN_ID_CHARS
+        ? `${miss.firstId.slice(0, MAX_SHOWN_ID_CHARS)}…`
+        : miss.firstId;
+    return `first of ${miss.returned ?? 1} returned id(s): ${JSON.stringify(id)}`;
+}
+const SYSTEM_PROMPT = `You explain code definitions for a code graph that helps engineers navigate a codebase.
+
+You are given ONE source file with 1-based line numbers, and a list of TARGET definitions in it. Describe EVERY target via the record_symbols tool.
+
+Rules:
+- Return EXACTLY ONE entry for EVERY target id, using that id verbatim. The number of entries you return MUST equal the number of targets. Never omit a target: a reply missing any id is invalid and will be re-requested.
+- A trivial symbol is NOT an exception. You still return it — with a one-sentence summary and crux 0/0 (see below). "Skip" means "give it no crux span", NEVER "leave it out".
+- summary: ONE sentence — what the symbol is FOR at the business-logic level (the problem it solves or the rule it enforces), not a restatement of its signature.
+- crux_start / crux_end: FILE line numbers (as shown), inside that symbol's own line range. Pick the SINGLE most important contiguous span — the core branch, formula, guard, or state change — at most ~8 lines, and NEVER the whole function. When there is no single focal span (a trivial getter, a plain data holder, a one-line delegation, or logic spread evenly), use crux_start: 0 and crux_end: 0. That 0/0 IS the answer — do not drop the entry.`;
+const RECORD_TOOL = "record_symbols";
+const SYMBOLS_SCHEMA = {
+    type: "object",
+    properties: {
+        symbols: {
+            type: "array",
+            items: {
+                type: "object",
+                properties: {
+                    id: { type: "string" },
+                    summary: { type: "string" },
+                    crux_start: { type: "number" },
+                    crux_end: { type: "number" },
+                },
+                required: ["id", "summary", "crux_start", "crux_end"],
+            },
+        },
+    },
+    required: ["symbols"],
+};
+/** Cap the file text sent per request so one huge file can't blow the context. */
+const MAX_CODE_CHARS = 18_000;
+function numberLines(source) {
+    const clipped = source.length > MAX_CODE_CHARS ? `${source.slice(0, MAX_CODE_CHARS)}\n… (truncated)` : source;
+    return clipped
+        .split("\n")
+        .map((line, i) => `${i + 1}\t${line}`)
+        .join("\n");
+}
+/**
+ * `id=` is the LAST field of a target line, so the id ends where the line does.
+ * With the id first nothing terminated it, and models asked for the id
+ * "verbatim" copied the whole row — `a.cs#Level | variable | lines L58-L58 | sig`
+ * — into `id` (#259). {@link resolveTargetId} still repairs echoes of either layout.
+ */
+function userContent(input) {
+    const targets = input.nodes
+        .map((n) => `- ${n.kind} | lines L${n.startLine}-L${n.endLine}` +
+        (n.signature ? ` | ${n.signature}` : "") +
+        ` | id=${n.id}`)
+        .join("\n");
+    const n = input.nodes.length;
+    return `FILE: ${input.path}\n\n${numberLines(input.source)}\n\nTARGETS (${n} — return all ${n}, one entry per id):\n${targets}`;
+}
+/** The longest requested id `test` accepts, or null. */
+function longestMatch(requested, test) {
+    let best = null;
+    for (const id of requested)
+        if (test(id) && (best === null || id.length > best.length))
+            best = id;
+    return best;
+}
+/**
+ * Map an id the model returned onto one of the ids we asked for, or null.
+ *
+ * Models echo decorated target rows instead of the bare id (#259, #298, #486).
+ * Rather than cut the string at a guessed delimiter, every rule compares against
+ * the requested ids, so the result is always an id we asked for — never a
+ * fragment of a hallucinated one — and no rule assumes which characters an id
+ * may contain. In order:
+ *   1. exact match;
+ *   2. a requested id followed by ` | ` (the row echoed from the id onwards);
+ *   3. the same two with a leading `id=` removed;
+ *   4. a row ending in ` | id=<requested id>` (the current layout echoed whole).
+ * When several requested ids qualify, the longest wins.
+ */
+export function resolveTargetId(raw, requested) {
+    const id = raw.trim();
+    if (requested.includes(id))
+        return id;
+    const echoed = longestMatch(requested, (r) => id.startsWith(`${r} | `));
+    if (echoed)
+        return echoed;
+    if (id.startsWith("id=")) {
+        const bare = id.slice(3).trim();
+        if (requested.includes(bare))
+            return bare;
+        const bareEchoed = longestMatch(requested, (r) => bare.startsWith(`${r} | `));
+        if (bareEchoed)
+            return bareEchoed;
+    }
+    return longestMatch(requested, (r) => id.endsWith(` | id=${r}`));
+}
+/**
+ * Normalize the tool's parsed argument object into a {@link NodeCrux} list. Ids
+ * are resolved against `requested`; one that matches nothing keeps its raw text
+ * so {@link classifyCruxMiss} can report what the model actually sent.
+ */
+function parseResults(obj, requested) {
+    if (!obj || !Array.isArray(obj.symbols))
+        return [];
+    const num = (v) => (typeof v === "number" && Number.isFinite(v) ? Math.trunc(v) : 0);
+    return obj.symbols
+        .map((s) => s)
+        .filter((s) => typeof s.id === "string")
+        .map((s) => ({
+        id: resolveTargetId(s.id, requested) ?? s.id,
+        summary: typeof s.summary === "string" ? s.summary.trim() : "",
+        crux_start: num(s.crux_start),
+        crux_end: num(s.crux_end),
+    }));
+}
+/**
+ * Some OpenAI-compatible gateways ignore forced `tool_choice` and put the tool
+ * payload in `content` instead (plain `{symbols:…}`, fenced JSON, or an emulated
+ * `[{name, parameters}]` array). Without this recovery the meaning pass sees an
+ * empty `toolCalls` list, leaves every node `pending`, and `graft check` loops
+ * on "run --deep" forever (#172; same trigger as #129 for the crux path).
+ */
+function argsFromResponse(res) {
+    const call = res.toolCalls.find((c) => c.name === RECORD_TOOL) ?? res.toolCalls[0];
+    if (call?.args && typeof call.args === "object" && !Array.isArray(call.args)) {
+        return call.args;
+    }
+    const recovered = recoverToolArgsFromContent(res.text, {
+        toolNames: [RECORD_TOOL, "emit_json"],
+        payloadKey: "symbols",
+    });
+    if (!recovered)
+        warnToolChoiceIgnored("crux", res.text?.trim() ? "unparsed" : "empty");
+    return recovered;
+}
+/** Crux summarizer backed by any {@link ChatModel} via forced tool calling. */
+export class ChatCruxSummarizer {
+    model;
+    lastMiss = null;
+    constructor(model) {
+        this.model = model;
+    }
+    async describeFile(input) {
+        this.lastMiss = null;
+        if (input.nodes.length === 0)
+            return [];
+        const res = await this.model.create({
+            temperature: 0,
+            maxTokens: 8192,
+            tools: [
+                {
+                    name: RECORD_TOOL,
+                    description: "Record each target definition's purpose and crux line range.",
+                    parameters: SYMBOLS_SCHEMA,
+                },
+            ],
+            responseFormat: { kind: "tool", name: RECORD_TOOL },
+            messages: [
+                { role: "system", content: SYSTEM_PROMPT },
+                { role: "user", content: userContent(input) },
+            ],
+        });
+        const requested = input.nodes.map((n) => n.id);
+        const parsed = parseResults(argsFromResponse(res), requested);
+        this.lastMiss = classifyCruxMiss(res, parsed, requested);
+        return parsed;
+    }
+}
+//# sourceMappingURL=crux.js.map

package/dist/ai/crux.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"crux.js","sourceRoot":"","sources":["../../src/ai/crux.ts"],"names":[],"mappings":"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"}

package/dist/ai/failure.d.ts

@@ -0,0 +1,60 @@
+/**
+ * When to stop calling a provider that is failing (#127).
+ *
+ * Both LLM passes of `build --deep` — the per-file concept summaries
+ * (`context/build.ts`) and the per-file crux pass (`graph/enrich.ts`) — used to
+ * catch every error per file, keep going, and finish with a clean exit. On an
+ * 884-file repo behind a gateway whose token quota was spent that produced 1,617
+ * failed calls, a normal success footer, and a graph whose meaning tier was
+ * missing; the degradation surfaced days later as bad `ask` results.
+ *
+ * One gate, shared by both passes, so they agree on what "the provider stopped
+ * working" means and a caller can report it once.
+ *
+ * Content-quality misses (empty/unusable crux, #235) still count as failed files
+ * so they are not cached as success (#177), but they do not increment the
+ * consecutive-failure cutoff — the provider is answering, just not usefully for
+ * those files. Quota/auth stay immediately terminal (#127).
+ */
+/** Consecutive failures that end a pass. One flaky file is normal; five in a row is
+ * a provider that is not going to start working, and each further call is spend
+ * with no chance of a result. */
+export declare const MAX_CONSECUTIVE_FAILURES = 5;
+/**
+ * Errors no amount of retrying fixes: the key is wrong, or the account/quota is
+ * spent. Matched on the message because that is all a provider-neutral transport
+ * carries — over-matching costs a build that was going to fail anyway, while
+ * under-matching just falls back to the consecutive-failure cutoff.
+ */
+export declare function terminalReason(message: string): string | null;
+/**
+ * Failure bookkeeping for one LLM pass: how many units failed, how many were
+ * skipped once it gave up, and the human-readable reason it did.
+ *
+ * Single-threaded by construction — every mutation happens between awaits in the
+ * pass's own worker — so no locking is needed despite the concurrency above it.
+ */
+export declare class LlmFailureGate {
+    /** Units (files) whose call failed. */
+    failed: number;
+    /** Units never attempted because the pass had already given up. */
+    skipped: number;
+    /** Why the pass stopped, when it did. */
+    fatal?: string;
+    private consecutive;
+    /** True once the pass should stop issuing calls. */
+    get stopped(): boolean;
+    /**
+     * Record a failed unit; sets {@link fatal} when this failure is the last straw.
+     * Pass `{ quality: true }` for a content-quality miss (#235): counted, not fatal,
+     * unless the message is quota/auth (those still stop immediately).
+     */
+    record(message: string, opts?: {
+        quality?: boolean;
+    }): void;
+    /** Record a success — a failure run only counts while it is unbroken. */
+    succeeded(): void;
+    /** Record a unit that was not attempted because the pass had stopped. */
+    skip(): void;
+}
+//# sourceMappingURL=failure.d.ts.map

package/dist/ai/failure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"failure.d.ts","sourceRoot":"","sources":["../../src/ai/failure.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;iCAEiC;AACjC,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAE1C;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAS7D;AAED;;;;;;GAMG;AACH,qBAAa,cAAc;IACzB,uCAAuC;IACvC,MAAM,SAAK;IACX,mEAAmE;IACnE,OAAO,SAAK;IACZ,yCAAyC;IACzC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,WAAW,CAAK;IAExB,oDAAoD;IACpD,IAAI,OAAO,IAAI,OAAO,CAErB;IAED;;;;OAIG;IACH,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI;IAc3D,yEAAyE;IACzE,SAAS,IAAI,IAAI;IAIjB,yEAAyE;IACzE,IAAI,IAAI,IAAI;CAGb"}

package/dist/ai/failure.js

@@ -0,0 +1,86 @@
+/**
+ * When to stop calling a provider that is failing (#127).
+ *
+ * Both LLM passes of `build --deep` — the per-file concept summaries
+ * (`context/build.ts`) and the per-file crux pass (`graph/enrich.ts`) — used to
+ * catch every error per file, keep going, and finish with a clean exit. On an
+ * 884-file repo behind a gateway whose token quota was spent that produced 1,617
+ * failed calls, a normal success footer, and a graph whose meaning tier was
+ * missing; the degradation surfaced days later as bad `ask` results.
+ *
+ * One gate, shared by both passes, so they agree on what "the provider stopped
+ * working" means and a caller can report it once.
+ *
+ * Content-quality misses (empty/unusable crux, #235) still count as failed files
+ * so they are not cached as success (#177), but they do not increment the
+ * consecutive-failure cutoff — the provider is answering, just not usefully for
+ * those files. Quota/auth stay immediately terminal (#127).
+ */
+/** Consecutive failures that end a pass. One flaky file is normal; five in a row is
+ * a provider that is not going to start working, and each further call is spend
+ * with no chance of a result. */
+export const MAX_CONSECUTIVE_FAILURES = 5;
+/**
+ * Errors no amount of retrying fixes: the key is wrong, or the account/quota is
+ * spent. Matched on the message because that is all a provider-neutral transport
+ * carries — over-matching costs a build that was going to fail anyway, while
+ * under-matching just falls back to the consecutive-failure cutoff.
+ */
+export function terminalReason(message) {
+    const m = message.toLowerCase();
+    if (/quota|insufficient[_ ]funds|insufficient[_ ]quota|billing|payment required|402/.test(m)) {
+        return "the provider reports the quota/credit for this key is exhausted";
+    }
+    if (/\b401\b|\b403\b|unauthorized|invalid api key|invalid_api_key|authentication/.test(m)) {
+        return "the provider rejected the API key";
+    }
+    return null;
+}
+/**
+ * Failure bookkeeping for one LLM pass: how many units failed, how many were
+ * skipped once it gave up, and the human-readable reason it did.
+ *
+ * Single-threaded by construction — every mutation happens between awaits in the
+ * pass's own worker — so no locking is needed despite the concurrency above it.
+ */
+export class LlmFailureGate {
+    /** Units (files) whose call failed. */
+    failed = 0;
+    /** Units never attempted because the pass had already given up. */
+    skipped = 0;
+    /** Why the pass stopped, when it did. */
+    fatal;
+    consecutive = 0;
+    /** True once the pass should stop issuing calls. */
+    get stopped() {
+        return this.fatal !== undefined;
+    }
+    /**
+     * Record a failed unit; sets {@link fatal} when this failure is the last straw.
+     * Pass `{ quality: true }` for a content-quality miss (#235): counted, not fatal,
+     * unless the message is quota/auth (those still stop immediately).
+     */
+    record(message, opts) {
+        this.failed++;
+        const terminal = terminalReason(message);
+        if (terminal) {
+            this.fatal = `${terminal} — stopped after ${this.failed} failed file(s). First error: ${message}`;
+            return;
+        }
+        if (opts?.quality)
+            return;
+        this.consecutive++;
+        if (this.consecutive >= MAX_CONSECUTIVE_FAILURES) {
+            this.fatal = `${this.consecutive} files in a row failed, so the pass stopped rather than keep calling. Last error: ${message}`;
+        }
+    }
+    /** Record a success — a failure run only counts while it is unbroken. */
+    succeeded() {
+        this.consecutive = 0;
+    }
+    /** Record a unit that was not attempted because the pass had stopped. */
+    skip() {
+        this.skipped++;
+    }
+}
+//# sourceMappingURL=failure.js.map

package/dist/ai/failure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"failure.js","sourceRoot":"","sources":["../../src/ai/failure.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;iCAEiC;AACjC,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC;AAE1C;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,OAAe;IAC5C,MAAM,CAAC,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAChC,IAAI,gFAAgF,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7F,OAAO,iEAAiE,CAAC;IAC3E,CAAC;IACD,IAAI,6EAA6E,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;QAC1F,OAAO,mCAAmC,CAAC;IAC7C,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;GAMG;AACH,MAAM,OAAO,cAAc;IACzB,uCAAuC;IACvC,MAAM,GAAG,CAAC,CAAC;IACX,mEAAmE;IACnE,OAAO,GAAG,CAAC,CAAC;IACZ,yCAAyC;IACzC,KAAK,CAAU;IACP,WAAW,GAAG,CAAC,CAAC;IAExB,oDAAoD;IACpD,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,KAAK,KAAK,SAAS,CAAC;IAClC,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,OAAe,EAAE,IAA4B;QAClD,IAAI,CAAC,MAAM,EAAE,CAAC;QACd,MAAM,QAAQ,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;QACzC,IAAI,QAAQ,EAAE,CAAC;YACb,IAAI,CAAC,KAAK,GAAG,GAAG,QAAQ,oBAAoB,IAAI,CAAC,MAAM,iCAAiC,OAAO,EAAE,CAAC;YAClG,OAAO;QACT,CAAC;QACD,IAAI,IAAI,EAAE,OAAO;YAAE,OAAO;QAC1B,IAAI,CAAC,WAAW,EAAE,CAAC;QACnB,IAAI,IAAI,CAAC,WAAW,IAAI,wBAAwB,EAAE,CAAC;YACjD,IAAI,CAAC,KAAK,GAAG,GAAG,IAAI,CAAC,WAAW,qFAAqF,OAAO,EAAE,CAAC;QACjI,CAAC;IACH,CAAC;IAED,yEAAyE;IACzE,SAAS;QACP,IAAI,CAAC,WAAW,GAAG,CAAC,CAAC;IACvB,CAAC;IAED,yEAAyE;IACzE,IAAI;QACF,IAAI,CAAC,OAAO,EAAE,CAAC;IACjB,CAAC;CACF"}

package/dist/ai/llm/anthropic.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Native Anthropic transport. Wraps `@anthropic-ai/sdk` (the Messages API), so
+ * Claude is a first-class provider rather than something tunneled through an
+ * OpenAI-compatible endpoint.
+ *
+ * The Messages API differs from Chat Completions in ways this adapter absorbs so
+ * the rest of graft never sees them:
+ *   - `system` is a top-level parameter, not a message.
+ *   - tool results ride inside a USER turn, and all results answering one
+ *     assistant turn must be coalesced into a single user message.
+ *   - `max_tokens` is required (callers get a default).
+ *   - `temperature` is rejected by current models, so it is never forwarded.
+ *   - structured output is a forced tool (there is no `response_format`).
+ *   - assistant turns are replayed verbatim (via `providerRaw`) so thinking-block
+ *     signatures survive a multi-turn loop.
+ */
+import Anthropic from "@anthropic-ai/sdk";
+import type { ChatModel, ChatRequest, ChatResponse } from "./types.js";
+export interface AnthropicChatModelOptions {
+    apiKey: string;
+    model: string;
+    baseUrl?: string;
+    label?: string;
+    /** Inject a pre-built client (tests pass a stub; production omits it). */
+    client?: Anthropic;
+}
+export declare class AnthropicChatModel implements ChatModel {
+    readonly label: string;
+    private client;
+    private model;
+    constructor(opts: AnthropicChatModelOptions);
+    create(req: ChatRequest): Promise<ChatResponse>;
+    /** Reconstruct an assistant turn, replaying the original blocks when we made them. */
+    private assistantParam;
+    private fromResponse;
+}
+//# sourceMappingURL=anthropic.d.ts.map

package/dist/ai/llm/anthropic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"anthropic.d.ts","sourceRoot":"","sources":["../../../src/ai/llm/anthropic.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,SAAS,MAAM,mBAAmB,CAAC;AAE1C,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,YAAY,EAAsC,MAAM,YAAY,CAAC;AAM3G,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,MAAM,CAAC,EAAE,SAAS,CAAC;CACpB;AAKD,qBAAa,kBAAmB,YAAW,SAAS;IAClD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,MAAM,CAAY;IAC1B,OAAO,CAAC,KAAK,CAAS;gBAEV,IAAI,EAAE,yBAAyB;IAQrC,MAAM,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC;IAuDrD,sFAAsF;IACtF,OAAO,CAAC,cAAc;IAUtB,OAAO,CAAC,YAAY;CA4BrB"}