atom-agent 0.3.0 → 1.1.0

package/dist/adapters.js

@@ -24,6 +24,7 @@ function parseArgsObject(raw) {
         return {};
     }
 }
+import { ephemeralBreakpoint, assemblePrefix } from "./prompt-cache.js";
 export function buildAnthropicBody(history, model, opts) {
     const systems = [];
     const messages = [];
@@ -83,15 +84,37 @@ export function buildAnthropicBody(history, model, opts) {
     // Compaction path (includeTools:false) omits `tools` + `tool_choice`
     // entirely — asserted in tests as "no `tools` key".
     if (includeTools) {
-        body.tools = toolDefs().map((t) => ({
+        const defs = toolDefs().map((t) => ({
             name: t.function.name,
             description: t.function.description,
             input_schema: t.function.parameters,
         }));
+        // Stable-prefix boundary (prompt-cache architecture): the env tail below
+        // decides. With a split, the stable block + full tools array are
+        // breakpointed (system head, then last tool — the two long-lived cache
+        // entries); without one, the legacy string shape is preserved exactly.
+        const joined = systems.join("\n\n");
+        const prefix = systems.length > 0 ? assemblePrefix({ systemContent: joined }) : null;
+        const dynamicTail = prefix?.dynamicSystem ?? null;
+        const stableHead = prefix && dynamicTail !== null ? prefix.stableSystem : "";
+        if (prefix !== null && dynamicTail !== null && stableHead.trim().length > 0) {
+            body.system = [
+                { type: "text", text: stableHead, cache_control: ephemeralBreakpoint() },
+                { type: "text", text: dynamicTail },
+            ];
+            if (defs.length > 0) {
+                defs[defs.length - 1].cache_control = ephemeralBreakpoint();
+            }
+        }
+        else if (systems.length > 0) {
+            body.system = joined;
+        }
+        body.tools = defs;
         body.tool_choice = { type: "auto" };
     }
-    if (systems.length > 0)
+    else if (systems.length > 0) {
         body.system = systems.join("\n\n");
+    }
     return body;
 }
 export function anthropicHeaders(apiKey) {
@@ -226,10 +249,71 @@ export function buildGeminiBody(history, _model, opts) {
         body.generationConfig = { maxOutputTokens: Math.floor(opts.maxOutputTokens) };
     }
     if (systems.length > 0) {
-        body.system_instruction = { parts: [{ text: systems.join("\n\n") }] };
+        // Stable-prefix split (prompt-cache architecture): a trailing env block
+        // becomes its own part so the stable head stays byte-identical across
+        // POSTs for implicit prefix caching. No env tail → the legacy single
+        // part, byte-identical to before.
+        const joined = systems.join("\n\n");
+        const prefix = assemblePrefix({ systemContent: joined });
+        body.system_instruction =
+            prefix.dynamicSystem !== null && prefix.stableSystem.trim().length > 0
+                ? { parts: [{ text: prefix.stableSystem }, { text: prefix.dynamicSystem }] }
+                : { parts: [{ text: joined }] };
     }
     return body;
 }
+// ---- SSE stall timeout (live-proven: a 200-OK stream can stop emitting
+// bytes mid-generation — e.g. free-tier routers stalling on tool-heavy
+// requests — and hang the turn until the socket dies minutes later) ----
+//
+// Every `reader.read()` / iterator step races this clock; silence longer
+// than the budget fails the turn LOUDLY with a permanent Truncated-stream
+// error (same contract as a dead connection: the caller rolls back, the App
+// keeps the streamed partial, the user resends). The clock resets on every
+// received chunk — slow models are fine, dead sockets are not.
+//
+// Budget: env ATOM_STALL_TIMEOUT_MS when a finite value > 0 (max-clamped to
+// 5min; an explicitly tiny value is the operator's choice, and lets tests
+// use millisecond budgets), else the 60s default. The hung read is left to
+// settle — callers cancel/release the reader on the way out as before.
+export const DEFAULT_SSE_STALL_TIMEOUT_MS = 60_000;
+export const MAX_SSE_STALL_TIMEOUT_MS = 300_000;
+export function sseStallTimeoutMs() {
+    const raw = process.env.ATOM_STALL_TIMEOUT_MS;
+    if (raw !== undefined) {
+        const n = Number(raw.trim());
+        if (Number.isFinite(n) && n > 0)
+            return Math.min(Math.floor(n), MAX_SSE_STALL_TIMEOUT_MS);
+    }
+    return DEFAULT_SSE_STALL_TIMEOUT_MS;
+}
+export function isStallError(e) {
+    return e instanceof Error && e.message.startsWith("Truncated stream from model (stall:");
+}
+export async function readWithStall(read, ms) {
+    const limit = typeof ms === "number" && Number.isFinite(ms) && ms > 0 ? Math.floor(ms) : sseStallTimeoutMs();
+    let timer = null;
+    try {
+        const pending = read();
+        const timeout = new Promise((_, reject) => {
+            timer = setTimeout(() => {
+                reject(new Error(`Truncated stream from model (stall: no bytes for ${limit}ms before [DONE]).`));
+            }, limit);
+            // An unref'd timer must never hold the process open for a settled read.
+            try {
+                timer.unref?.();
+            }
+            catch {
+                // ignore — environments without unref (browsers) proceed regardless
+            }
+        });
+        return await Promise.race([pending, timeout]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
 async function collectSSEText(res) {
     const body = res.body;
     const decoder = new TextDecoder();
@@ -243,9 +327,20 @@ async function collectSSEText(res) {
                 for (;;) {
                     let chunk;
                     try {
-                        chunk = await reader.read();
+                        chunk = await readWithStall(() => reader.read());
                     }
                     catch (e) {
+                        if (isStallError(e)) {
+                            // Free the dead socket on the way out, then surface the stall
+                            // unchanged (permanent Truncated contract — never retried).
+                            try {
+                                await reader.cancel?.();
+                            }
+                            catch {
+                                // ignore cancel errors
+                            }
+                            throw e;
+                        }
                         throw new Error(`Truncated stream from model (connection aborted: ${e instanceof Error ? e.message : String(e)}).`);
                     }
                     if (chunk.done)
@@ -267,11 +362,26 @@ async function collectSSEText(res) {
             }
         }
         else if (typeof body[Symbol.asyncIterator] === "function") {
-            for await (const v of body) {
-                rawText +=
-                    typeof v === "string"
-                        ? v
-                        : decoder.decode(v, { stream: true });
+            const it = body[Symbol.asyncIterator]();
+            try {
+                for (;;) {
+                    const step = await readWithStall(() => it.next());
+                    if (step.done)
+                        break;
+                    const v = step.value;
+                    rawText +=
+                        typeof v === "string"
+                            ? v
+                            : decoder.decode(v, { stream: true });
+                }
+            }
+            finally {
+                try {
+                    await it.return?.();
+                }
+                catch {
+                    // ignore — the stream is over either way
+                }
             }
         }
         else {
@@ -318,7 +428,7 @@ function finiteCount(value) {
         ? Math.floor(value)
         : undefined;
 }
-function openAIUsage(prompt, completion) {
+function openAIUsage(prompt, completion, cache) {
     const out = {};
     const p = finiteCount(prompt);
     if (p !== undefined)
@@ -328,6 +438,14 @@ function openAIUsage(prompt, completion) {
         out.completion_tokens = c;
     if (p !== undefined && c !== undefined)
         out.total_tokens = p + c;
+    // Provider-reported cache counters ride alongside (Anthropic
+    // cache_read/_creation, Gemini cachedContentTokenCount) — present-only.
+    const read = finiteCount(cache?.read);
+    if (read !== undefined)
+        out.cacheReadTokens = read;
+    const write = finiteCount(cache?.write);
+    if (write !== undefined)
+        out.cacheWriteTokens = write;
     return out.prompt_tokens !== undefined ||
         out.completion_tokens !== undefined ||
         out.total_tokens !== undefined
@@ -406,7 +524,10 @@ export async function readAnthropicSSEMessage(res, opts) {
             const msg = o["message"];
             const u = msg?.["usage"];
             if (u) {
-                const hit = openAIUsage(u["input_tokens"], u["output_tokens"]);
+                const hit = openAIUsage(u["input_tokens"], u["output_tokens"], {
+                    read: u["cache_read_input_tokens"],
+                    write: u["cache_creation_input_tokens"],
+                });
                 const merged = mergeUsage(usage, hit, { recomputeTotal: true });
                 if (merged !== undefined)
                     usage = merged;
@@ -488,7 +609,10 @@ export async function readAnthropicSSEMessage(res, opts) {
             const inputSrc = u?.["input_tokens"] !== undefined ? u["input_tokens"] : o["input_tokens"];
             const outputSrc = u?.["output_tokens"] !== undefined ? u["output_tokens"] : o["output_tokens"];
             if (u !== undefined || o["input_tokens"] !== undefined || o["output_tokens"] !== undefined) {
-                const hit = openAIUsage(inputSrc, outputSrc);
+                const hit = openAIUsage(inputSrc, outputSrc, {
+                    read: u?.["cache_read_input_tokens"] ?? o["cache_read_input_tokens"],
+                    write: u?.["cache_creation_input_tokens"] ?? o["cache_creation_input_tokens"],
+                });
                 const merged = mergeUsage(usage, hit, { recomputeTotal: true });
                 if (merged !== undefined)
                     usage = merged;
@@ -607,7 +731,10 @@ export function parseAnthropicJson(data) {
     };
     const u = o["usage"];
     if (u) {
-        const hit = openAIUsage(u["input_tokens"], u["output_tokens"]);
+        const hit = openAIUsage(u["input_tokens"], u["output_tokens"], {
+            read: u["cache_read_input_tokens"],
+            write: u["cache_creation_input_tokens"],
+        });
         if (hit)
             result.usage = hit;
     }
@@ -712,7 +839,9 @@ export async function readGeminiSSEMessage(res, opts) {
         }
         const um = o["usageMetadata"];
         if (um) {
-            const hit = openAIUsage(um["promptTokenCount"], um["candidatesTokenCount"]);
+            const hit = openAIUsage(um["promptTokenCount"], um["candidatesTokenCount"], {
+                read: um["cachedContentTokenCount"],
+            });
             const total = finiteCount(um["totalTokenCount"]);
             const merged = mergeUsage(usage, hit, { total });
             if (merged !== undefined)
@@ -802,7 +931,9 @@ export function parseGeminiJson(data) {
     };
     const um = o["usageMetadata"];
     if (um) {
-        const hit = openAIUsage(um["promptTokenCount"], um["candidatesTokenCount"]);
+        const hit = openAIUsage(um["promptTokenCount"], um["candidatesTokenCount"], {
+            read: um["cachedContentTokenCount"],
+        });
         const total = finiteCount(um["totalTokenCount"]);
         const merged = mergeUsage(undefined, hit, { total });
         if (merged !== undefined)

package/dist/agent/gates.js

@@ -0,0 +1,153 @@
+// Turn-end gates: the runtime-enforced finish conditions every turn must
+// satisfy before final text ends it (todo completion, verification). Pure
+// functions over an explicit context — no loop state, no I/O, no UI.
+// Moved verbatim from src/zen.ts; zen.ts re-exports the stable surface.
+import { getTodos } from "../tools.js";
+// Todo-completion guard: the turn may not end with final text while todos
+// are open. With budget left, record the attempt and feed back a guard
+// message as a user follow-up so the model must continue with tool calls or
+// explicitly resolve the todos. With the step budget spent, end with an
+// explicit blocked statement naming the unfinished items instead.
+export function todoCompletionGate(finalText, ctx) {
+    const open = getTodos().filter((t) => t.status !== "completed");
+    if (open.length === 0)
+        return { action: "pass" };
+    const items = open.map((t, i) => `${i + 1}. [${t.status}] ${t.content}`).join("\n");
+    if (ctx.step >= ctx.maxSteps) {
+        return {
+            action: "end",
+            finalText: `${finalText}${finalText ? "\n" : ""}(blocked: ${open.length} open todo(s) — resolve with todo_update/todowrite before ending the turn:\n${items})`,
+        };
+    }
+    return {
+        action: "continue",
+        assistantText: finalText,
+        followUp: `(todo guard: ${open.length} open todo(s) — do not end the turn with final text. Continue with tool calls, or resolve them with todo_update/todowrite:\n${items})`,
+    };
+}
+// Task 7 verification gate: code files were written but no test/typecheck/
+// build command has PASSED since. The turn CONTINUES (never ends on a mere
+// report — the system prompt forbids unverified finishes, so the runtime
+// must not terminate while just labeling): the attempt is recorded and a
+// verification follow-up re-enters the loop, exactly like the todo guard.
+// Two bounded exits: spent step budget, or MAX_VERIFY_ROUNDS nag cycles
+// without a passing run — both end with an explicit labeled statement naming
+// what is unverified and why the loop stopped. Turns with no code writes
+// (questions, docs, explanations, read-only work) are unaffected.
+export const MAX_VERIFY_ROUNDS = 3;
+// Source-code extensions whose writes require a passing verification run.
+// Curated heuristic boundary (not a parser): docs, configs, data, and
+// extensionless files never arm the gate, so a README edit finishes clean.
+// Case-insensitive; dotfiles and trailing dots never match.
+const CODE_EXTENSIONS = new Set([
+    "ts", "tsx", "mts", "cts", "js", "jsx", "mjs", "cjs",
+    "py", "pyw", "rb", "go", "rs", "java", "kt", "kts",
+    "swift", "c", "h", "cpp", "hpp", "cc", "cxx", "cs",
+    "php", "scala", "sh", "bash", "lua", "r", "dart",
+    "vue", "svelte", "astro", "sql", "pl", "pm",
+]);
+export function isCodePath(p) {
+    if (typeof p !== "string" || p.length === 0)
+        return false;
+    const base = p.split(/[\\/]/).pop() ?? "";
+    const dot = base.lastIndexOf(".");
+    if (dot <= 0 || dot === base.length - 1)
+        return false;
+    return CODE_EXTENSIONS.has(base.slice(dot + 1).toLowerCase());
+}
+function verifyFilesLabel(paths) {
+    if (paths.length === 0)
+        return "changed files";
+    const shown = paths.slice(0, 5);
+    const extra = paths.length - shown.length;
+    return shown.join(", ") + (extra > 0 ? ` (+${extra} more)` : "");
+}
+export function verificationGate(finalText, ctx) {
+    const needs = ctx.needsVerification ?? ctx.filesWritten;
+    if (!needs || ctx.verifiedAfterWrite)
+        return { action: "pass" };
+    const files = verifyFilesLabel(ctx.unverifiedPaths ?? []);
+    if (ctx.step >= ctx.maxSteps) {
+        return {
+            action: "end",
+            finalText: `${finalText}${finalText ? "\n" : ""}(blocked: turn budget spent (${ctx.maxSteps} tool steps) with ${files} still unverified — run the verification and report its pass/fail lines, or name why it cannot run.)`,
+        };
+    }
+    if ((ctx.verifyRounds ?? 0) >= MAX_VERIFY_ROUNDS) {
+        return {
+            action: "end",
+            finalText: `${finalText}${finalText ? "\n" : ""}(unverified: ${files} changed without a passing verification run — verification was requested ${MAX_VERIFY_ROUNDS}× and never ran. Run \`npm test\` and \`npm run typecheck\` and report their pass/fail lines, or name the blocker explicitly.)`,
+        };
+    }
+    return {
+        action: "continue",
+        assistantText: finalText,
+        followUp: `(verification required: ${files} changed since the last passing check. Run the repo's verification (e.g. \`npm test\`, \`npm run typecheck\`) and report pass/fail before finishing — final text ends the turn only after a check passes.)`,
+    };
+}
+export const TURN_END_GATES = [todoCompletionGate, verificationGate];
+export function evaluateTurnEnd(finalText, ctx, gates = TURN_END_GATES) {
+    for (let i = 0; i < gates.length; i++) {
+        const gate = gates[i];
+        const decision = gate(finalText, ctx);
+        if (decision.action === "pass")
+            continue;
+        if (decision.action === "continue") {
+            // Which gate continued (the loop bounds verification nag cycles):
+            // the verification gate by name, anything else by function name.
+            const via = gate === verificationGate ? "verification" : gate.name || `gate-${i}`;
+            return { kind: "continue", assistantText: decision.assistantText, followUp: decision.followUp, via };
+        }
+        return { kind: "end", finalText: decision.finalText };
+    }
+    return { kind: "end", finalText };
+}
+// Task 7 verification gate: a bash command counts as a verification run
+// when it names a common test/typecheck/build entry point. This is a word
+// heuristic, not a parser — a miss only appends a non-blocking
+// informational flag (never stops the turn), and the list is pinned by
+// tests/loop-verification-gate.test.ts.
+export function isVerificationCommand(command) {
+    return /\b(vitest|jest|mocha|pytest|typecheck|tsc|verify|check|build|tests?)\b/i.test(command);
+}
+// Explicit verification outcome: the bash executor's JSON envelope carries
+// exitCode. 0 = the check passed (evidence); non-zero = it ran and FAILED
+// (not evidence — the gate stays armed so the model sees the failure and
+// fixes forward). Unparseable results (custom executors, test fakes
+// returning plain strings) keep the legacy conservative behavior: a
+// reporting runner counts as a pass. Never throws.
+export function bashExitCode(result) {
+    try {
+        const v = JSON.parse(result);
+        if (typeof v === "object" && v !== null) {
+            const code = v["exitCode"];
+            if (typeof code === "number" && Number.isFinite(code))
+                return Math.floor(code);
+        }
+    }
+    catch {
+        // non-JSON runners keep legacy behavior (see caller)
+    }
+    return null;
+}
+// Current open todo texts (content + activeForm) via the shared getTodos
+// read path — no duplicated state. Completed items never pin (their echoes
+// are stale context). Never throws: on any failure there is simply nothing
+// todo-pinned and truncation falls back to task-prompt + latest-turn pinning.
+// Exported so manager-based trimmers (App submit) pin the same live todos.
+export function openTodoNeedles() {
+    try {
+        const open = getTodos().filter((t) => t.status !== "completed");
+        const out = [];
+        for (const t of open) {
+            if (typeof t.content === "string" && t.content.length > 0)
+                out.push(t.content);
+            if (typeof t.activeForm === "string" && t.activeForm.length > 0)
+                out.push(t.activeForm);
+        }
+        return out;
+    }
+    catch {
+        return [];
+    }
+}

package/dist/agent/loop-guard.js

@@ -0,0 +1,184 @@
+// Loop-guard: repetition/runaway detection + error-streak recovery for the
+// agentic loop. Pure state machines, no I/O, never throw.
+//
+// Why this exists: maxSteps (30 tool rounds) is the ultimate backstop, but
+// a model stuck calling `read <same path>` 30 times burns 30 POSTs before it
+// trips. The guard spots the pattern early (consecutive identical signatures)
+// and the loop nudges the model toward a different approach with a bounded
+// follow-up — then stops hard if the pattern survives the nudges. Error
+// streaks get the same treatment: ending on 3+ unaddressed `Error:` results
+// is almost always premature, so the loop asks for a fix-forward attempt
+// before accepting final text.
+//
+// Defaults preserve the pinned maxSteps contract: repetition intervention is
+// OPT-IN (maxRepeatedCalls set by the caller; unset = track-only for stats),
+// because the existing suites pin "always same call → 31 POSTs → stopped
+// notice". Error-streak recovery defaults to 3 (single errors still end
+// normally — the model may be reporting a blocker).
+//
+// All thresholds clamp to sane minima; every method is safe to call with any
+// input.
+// Tools whose identical repeats are legitimate polling, never runaway:
+// bash_output re-polls the same taskId while a background task runs (each
+// poll can return growing output). Excluded calls still break other tools'
+// consecutive streaks — a poll between two identical reads means the reads
+// were not consecutive.
+export const POLLING_TOOLS = new Set(["bash_output"]);
+export class RepetitionGuard {
+    maxConsecutive;
+    maxTotal;
+    maxNudges;
+    consecutiveSig = null;
+    consecutiveCount = 0;
+    totals = new Map();
+    nudges = 0;
+    excluded;
+    hits = 0;
+    constructor(opts = {}) {
+        const mc = opts.maxRepeatedCalls;
+        this.maxConsecutive =
+            typeof mc === "number" && Number.isFinite(mc) ? Math.max(2, Math.floor(mc)) : null;
+        const mt = opts.maxTotalRepeats;
+        this.maxTotal =
+            typeof mt === "number" && Number.isFinite(mt)
+                ? Math.max(2, Math.floor(mt))
+                : this.maxConsecutive !== null
+                    ? this.maxConsecutive * 3
+                    : null;
+        const mn = opts.maxNudges;
+        this.maxNudges =
+            typeof mn === "number" && Number.isFinite(mn) ? Math.max(1, Math.floor(mn)) : 2;
+        this.excluded = new Set(POLLING_TOOLS);
+        try {
+            if (opts.excludedTools) {
+                for (const t of opts.excludedTools) {
+                    if (typeof t === "string" && t.length > 0)
+                        this.excluded.add(t);
+                }
+            }
+        }
+        catch {
+            // custom exclusions are best-effort; defaults still apply
+        }
+    }
+    isExcluded(toolName) {
+        return typeof toolName === "string" && this.excluded.has(toolName);
+    }
+    note(signature, toolName) {
+        const sig = typeof signature === "string" ? signature : String(signature ?? "");
+        const name = typeof toolName === "string" && toolName.length > 0
+            ? toolName
+            : sig.includes(" ")
+                ? sig.slice(0, sig.indexOf(" "))
+                : sig;
+        // Polling tools never count: they still break other tools' streaks (a
+        // poll between two identical reads means the reads were not consecutive).
+        if (this.isExcluded(name)) {
+            this.resetStreak();
+            return { signature: sig, consecutive: 0, total: this.totals.get(sig) ?? 0, intervened: false, excluded: true };
+        }
+        const total = (this.totals.get(sig) ?? 0) + 1;
+        this.totals.set(sig, total);
+        if (this.consecutiveSig === sig)
+            this.consecutiveCount += 1;
+        else {
+            this.consecutiveSig = sig;
+            this.consecutiveCount = 1;
+        }
+        const intervened = this.shouldIntervene();
+        if (intervened)
+            this.hits += 1;
+        return { signature: sig, consecutive: this.consecutiveCount, total, intervened, excluded: false };
+    }
+    shouldIntervene() {
+        if (this.maxConsecutive === null)
+            return false;
+        if (this.consecutiveCount >= this.maxConsecutive)
+            return true;
+        if (this.maxTotal !== null && this.consecutiveSig !== null) {
+            if ((this.totals.get(this.consecutiveSig) ?? 0) >= this.maxTotal)
+                return true;
+        }
+        return false;
+    }
+    // Nudge budget: true while guidance follow-ups remain (each consumes one).
+    // When exhausted the caller stops hard — the pattern survived coaching.
+    consumeNudge() {
+        if (this.nudges >= this.maxNudges)
+            return false;
+        this.nudges += 1;
+        return true;
+    }
+    get nudgeCount() {
+        return this.nudges;
+    }
+    get hitCount() {
+        return this.hits;
+    }
+    resetStreak() {
+        this.consecutiveSig = null;
+        this.consecutiveCount = 0;
+    }
+}
+export function repetitionFollowUp(signature, consecutive) {
+    const short = signature.length > 160 ? `${signature.slice(0, 160)}…` : signature;
+    return (`(loop guard: the identical tool call repeated ${consecutive}× consecutively (${short}). ` +
+        `The current approach is not making progress — try a different tool, different arguments, ` +
+        `or report the blocker with its evidence instead of retrying the same call.)`);
+}
+export function repetitionStopNotice(signature, consecutive) {
+    const short = signature.length > 160 ? `${signature.slice(0, 160)}…` : signature;
+    return (`(stopped: identical tool call repeated ${consecutive}× (${short}) — ` +
+        `loop-guard halted the runaway instead of burning the remaining tool budget.)`);
+}
+// Error-streak tracker: consecutive `Error:` results. The loop asks whether
+// final text should be accepted (streak < threshold → yes) or nudged once
+// (streak >= threshold → continue, bounded per turn by the caller).
+export class ErrorStreakTracker {
+    threshold;
+    streak = 0;
+    nudges = 0;
+    constructor(threshold) {
+        this.threshold =
+            typeof threshold === "number" && Number.isFinite(threshold) && threshold > 0
+                ? Math.floor(threshold)
+                : threshold === 0
+                    ? 0
+                    : 3;
+    }
+    get enabled() {
+        return this.threshold > 0;
+    }
+    noteResult(isError) {
+        if (isError)
+            this.streak += 1;
+        else
+            this.streak = 0;
+    }
+    noteResults(results) {
+        for (const e of results)
+            this.noteResult(e === true);
+    }
+    get current() {
+        return this.streak;
+    }
+    // True when final text should be held for a fix-forward attempt. Consumes
+    // one nudge per true (the caller bounds total nudges per turn).
+    shouldHoldFinal(maxNudgesPerTurn) {
+        if (!this.enabled || this.streak < this.threshold)
+            return false;
+        if (this.nudges >= maxNudgesPerTurn)
+            return false;
+        this.nudges += 1;
+        return true;
+    }
+    reset() {
+        this.streak = 0;
+    }
+}
+export function errorStreakFollowUp(streak) {
+    return (`(recovery: the last ${streak} tool result(s) were errors and the turn tried to end. ` +
+        `Do not end on unaddressed failures — read the error text, fix the arguments or replan ` +
+        `around the failure, and continue with tool calls. If it cannot be fixed, end by naming ` +
+        `the blocker with its evidence.)`);
+}