atom-agent 1.0.0 → 1.2.0

package/dist/adapters.js

@@ -262,10 +262,80 @@ export function buildGeminiBody(history, _model, opts) {
     }
     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();
     let rawText = "";
+    // Data-silence tracking (mirrors zen.readSSEMessage): queue comments and
+    // keep-alives carry bytes but no model output, so only chunks containing a
+    // `data:` line start refresh the clock. The tail window catches a marker
+    // split across chunk boundaries.
+    let lastDataAt = Date.now();
+    let tail = "";
+    const noteChunk = (chunkText) => {
+        const joined = tail + chunkText;
+        if (/(?:^|\n)data:/.test(joined))
+            lastDataAt = Date.now();
+        tail = joined.slice(-8);
+    };
+    const throwIfDataStalled = () => {
+        const budget = sseStallTimeoutMs();
+        if (Date.now() - lastDataAt > budget) {
+            throw new Error(`Truncated stream from model (stall: no output for ${budget}ms — queued or stalled upstream; resend to retry).`);
+        }
+    };
     if (body == null)
         return { rawText, events: [] };
     try {
@@ -275,18 +345,31 @@ 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)
                         break;
                     const v = chunk.value;
-                    rawText +=
-                        typeof v === "string"
-                            ? v
-                            : decoder.decode(v, { stream: true });
+                    const textPart = typeof v === "string"
+                        ? v
+                        : decoder.decode(v, { stream: true });
+                    rawText += textPart;
+                    noteChunk(textPart);
+                    throwIfDataStalled();
                 }
             }
             finally {
@@ -299,11 +382,28 @@ async function collectSSEText(res) {
             }
         }
         else if (typeof body[Symbol.asyncIterator] === "function") {
-            for await (const v of body) {
-                rawText +=
-                    typeof v === "string"
+            const it = body[Symbol.asyncIterator]();
+            try {
+                for (;;) {
+                    const step = await readWithStall(() => it.next());
+                    if (step.done)
+                        break;
+                    const v = step.value;
+                    const textPart = typeof v === "string"
                         ? v
                         : decoder.decode(v, { stream: true });
+                    rawText += textPart;
+                    noteChunk(textPart);
+                    throwIfDataStalled();
+                }
+            }
+            finally {
+                try {
+                    await it.return?.();
+                }
+                catch {
+                    // ignore — the stream is over either way
+                }
             }
         }
         else {

package/dist/agent/gates.js

@@ -19,6 +19,15 @@ export function todoCompletionGate(finalText, ctx) {
             finalText: `${finalText}${finalText ? "\n" : ""}(blocked: ${open.length} open todo(s) — resolve with todo_update/todowrite before ending the turn:\n${items})`,
         };
     }
+    // Guard cycles are bounded (like the verification gate): a model that
+    // keeps answering without resolving todos ends with a blocked statement
+    // instead of looping forever. Normal flows resolve within a round or two.
+    if ((ctx.todoRounds ?? 0) >= MAX_TODO_ROUNDS) {
+        return {
+            action: "end",
+            finalText: `${finalText}${finalText ? "\n" : ""}(blocked: ${open.length} open todo(s) remain after ${MAX_TODO_ROUNDS} guard rounds — resolve with todo_update/todowrite before ending the turn:\n${items})`,
+        };
+    }
     return {
         action: "continue",
         assistantText: finalText,
@@ -30,11 +39,15 @@ export function todoCompletionGate(finalText, ctx) {
 // 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
+// Two bounded exits: an explicit step budget spent, or MAX_VERIFY_ROUNDS nag
 // 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;
+// Todo-guard continues before the turn ends blocked: a model that keeps
+// answering final text without resolving open todos is sent back at most
+// this many times. Mirrors MAX_VERIFY_ROUNDS so no gate can spin forever.
+export const MAX_TODO_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.

package/dist/agent/loop-guard.js

@@ -0,0 +1,182 @@
+// Loop-guard: repetition/runaway detection + error-streak recovery for the
+// agentic loop. Pure state machines, no I/O, never throw.
+//
+// Why this exists: turns are uncapped by default, so a model stuck calling
+// `read <same path>` forever burns POSTs without end. 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.
+//
+// Repetition intervention is OPT-IN (maxRepeatedCalls set by the caller;
+// unset = track-only for stats). 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.)`);
+}