atom-agent 1.0.0 → 1.1.0

package/dist/adapters.js

@@ -262,6 +262,58 @@ 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();
@@ -275,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)
@@ -299,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 {

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.)`);
+}