lazyclaw 6.3.0 → 6.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lazyclaw",
-  "version": "6.3.0",
+  "version": "6.4.0",
   "description": "Lazy, elegant terminal CLI for chatting with Claude / OpenAI / Gemini / Ollama, orchestrating multi-step LLM workflows, and running multi-agent Slack teams with cross-task memory. Banner-on-launch, slash-command ghost autocomplete, persistent sessions, local HTTP gateway.",
   "keywords": [
     "claude",
@@ -35,6 +35,7 @@
     "lint:size": "node scripts/lint-file-size.mjs",
     "lint:pack": "node scripts/check-pack.mjs",
     "test:bench": "node scripts/bench-providers.mjs",
+    "test:bench:cli": "node scripts/bench-claude-cli.mjs",
     "test:bench:index": "node --test tests/index_store.bench.mjs",
     "test:perf": "node --test tests/phaseH-perf.test.mjs tests/index_store.bench.mjs",
     "migrate:v5": "node scripts/migrate-v5.mjs"
@@ -68,6 +69,7 @@
     "sandbox/",
     "skills_install.mjs",
     "skills_curator.mjs",
+    "skills/",
     "cron.mjs",
     "loop-engine.mjs",
     "loops.mjs",

package/providers/anthropic.mjs

@@ -47,6 +47,63 @@ class RateLimitError extends Error {
   }
 }
 
+class TimeoutError extends Error {
+  constructor(idleMs) {
+    super(`anthropic: idle timeout — no stream activity for ${idleMs}ms`);
+    this.name = 'TimeoutError';
+    this.code = 'TIMEOUT';
+    this.idleMs = idleMs;
+  }
+}
+
+const DEFAULT_IDLE_TIMEOUT_MS = 120000;
+
+// Resolve the IDLE (inter-chunk) timeout once per request: opts override
+// wins, then env LAZYCLAW_REQUEST_TIMEOUT_MS (positive int), else 120s.
+function resolveIdleTimeoutMs(opts) {
+  if (Number.isFinite(opts?.idleTimeoutMs) && opts.idleTimeoutMs > 0) return opts.idleTimeoutMs;
+  const raw = parseInt(process.env.LAZYCLAW_REQUEST_TIMEOUT_MS ?? '', 10);
+  if (Number.isFinite(raw) && raw > 0) return raw;
+  return DEFAULT_IDLE_TIMEOUT_MS;
+}
+
+// Wrap a chunk iterator with an IDLE timeout: abort only when NO chunk has
+// arrived for idleMs (the timer resets on every received chunk, and also
+// guards the connect/first-byte phase). This is NOT a total-duration cap,
+// so a long but healthy generation that streams steadily is never aborted.
+// `controller` is aborted on idle expiry so the real connection tears down;
+// the caller's signal is forwarded into the same controller upstream.
+async function* iterateWithIdleTimeout(body, idleMs, controller) {
+  const iterator = iterateBody(body)[Symbol.asyncIterator]();
+  try {
+    while (true) {
+      let timer;
+      const idle = new Promise((_, reject) => {
+        timer = setTimeout(() => {
+          controller.abort();
+          reject(new TimeoutError(idleMs));
+        }, idleMs);
+      });
+      let step;
+      try {
+        step = await Promise.race([iterator.next(), idle]);
+      } finally {
+        clearTimeout(timer);
+      }
+      if (step.done) return;
+      yield step.value;
+    }
+  } finally {
+    // Best-effort, NON-awaited cleanup: on idle abort the underlying reader
+    // may be suspended on a read that never settles, so awaiting return()
+    // would re-hang us. We aborted the controller (tearing down the real
+    // connection) already; just nudge the iterator and move on.
+    if (typeof iterator.return === 'function') {
+      try { Promise.resolve(iterator.return()).catch(() => {}); } catch { /* ignore */ }
+    }
+  }
+}
+
 class ApiError extends Error {
   constructor(status, body) {
     super(`anthropic api ${status}: ${body.slice(0, 200)}`);
@@ -134,7 +191,7 @@ export const anthropicProvider = {
     const fetchFn = opts.fetch || globalThis.fetch;
     if (!fetchFn) throw new Error('anthropic: no fetch implementation available');
 
-    const model = opts.model || 'claude-opus-4-7';
+    const model = opts.model || 'claude-opus-4-8';
     const apiMessages = messages
       .filter(m => m.role === 'user' || m.role === 'assistant')
       .map(m => ({ role: m.role, content: String(m.content ?? '') }));
@@ -198,6 +255,21 @@ export const anthropicProvider = {
     // surfaces immediately rather than waiting for the next chunk.
     if (opts.signal?.aborted) throw new AbortError('aborted before request');
 
+    // Compose the caller's signal with an internal controller that the idle
+    // timeout aborts. The composed signal goes to fetch so a stalled
+    // connection (or a user cancel) tears down the real socket.
+    const idleMs = resolveIdleTimeoutMs(opts);
+    const idleController = new AbortController();
+    const fetchSignal = opts.signal
+      ? (typeof AbortSignal.any === 'function'
+          ? AbortSignal.any([opts.signal, idleController.signal])
+          : idleController.signal)
+      : idleController.signal;
+    const forwardCallerAbort = () => idleController.abort();
+    if (opts.signal && typeof AbortSignal.any !== 'function') {
+      opts.signal.addEventListener('abort', forwardCallerAbort, { once: true });
+    }
+
     const res = await fetchFn('https://api.anthropic.com/v1/messages', {
       method: 'POST',
       headers: {
@@ -206,7 +278,7 @@ export const anthropicProvider = {
         'anthropic-version': ANTHROPIC_VERSION,
       },
       body: JSON.stringify(body),
-      signal: opts.signal,
+      signal: fetchSignal,
     });
 
     if (!res.ok) {
@@ -232,7 +304,25 @@ export const anthropicProvider = {
     // We collect both and emit a single opts.onUsage call right before
     // we return on message_stop.
     let usage = null;
-    for await (const chunk of iterateBody(res.body)) {
+    let lastStop = null;
+    // Fire onUsage + (if truncated) onTruncated EXACTLY ONCE — from message_stop
+    // or, if the stream ends without it after usage was captured, the post-loop
+    // flush. stop_reason 'max_tokens' is Anthropic's hard output-cut signal.
+    let finalized = false;
+    const finalize = () => {
+      if (finalized) return;
+      finalized = true;
+      if (usage && typeof opts.onUsage === 'function') {
+        try { opts.onUsage(usage); } catch { /* never let a callback abort */ }
+      }
+      if (lastStop === 'max_tokens' && typeof opts.onTruncated === 'function') {
+        try { opts.onTruncated('max_tokens'); } catch { /* ditto */ }
+      }
+    };
+    try {
+    for await (const chunk of iterateWithIdleTimeout(res.body, idleMs, idleController)) {
+      // A user cancel surfaces as an idle-controller abort too; map it back
+      // to ABORT so it stays distinguishable from a TIMEOUT.
       if (opts.signal?.aborted) throw new AbortError('aborted mid-stream');
       buffer += typeof chunk === 'string' ? chunk : decoder.decode(chunk, { stream: true });
       let consumed = 0;
@@ -254,6 +344,7 @@ export const anthropicProvider = {
         } else if (frame.event === 'message_delta' && frame.data) {
           try {
             const obj = JSON.parse(frame.data);
+            if (obj?.delta?.stop_reason) lastStop = obj.delta.stop_reason;
             const u = obj?.usage;
             if (u && usage) {
               // message_delta carries the final output_tokens — overwrite
@@ -307,9 +398,7 @@ export const anthropicProvider = {
             }
           } catch { /* skip malformed */ }
         } else if (frame.event === 'message_stop') {
-          if (usage && typeof opts.onUsage === 'function') {
-            try { opts.onUsage(usage); } catch { /* never let a callback abort */ }
-          }
+          finalize();
           return;
         } else if (frame.event === 'error' && frame.data) {
           let parsed = null;
@@ -320,6 +409,12 @@ export const anthropicProvider = {
       }
       if (consumed > 0) buffer = buffer.slice(consumed);
     }
+    } finally {
+      if (opts.signal && typeof AbortSignal.any !== 'function') {
+        opts.signal.removeEventListener('abort', forwardCallerAbort);
+      }
+    }
+    finalize();   // flush captured usage/truncation if the stream ended without message_stop
     // Flush any pending bytes the streaming decoder was still holding.
     const tail = decoder.decode();
     if (tail) buffer += tail;

package/providers/cache.mjs

@@ -47,7 +47,15 @@ function hashKey(messages, model, opts) {
     messages,
     model: model || null,
     thinking: opts?.thinking || null,
-    system: opts?.system || null,
+    // The system prompt can arrive three ways: opts.system, the static/volatile
+    // split (opts.systemStatic / opts.systemVolatile — what the REPL caller
+    // uses), or an embedded role:system message. Fold ALL of them into the key
+    // so two calls that differ only in their static system can't collide and
+    // serve one another's cached reply. (When system lives in messages it is
+    // already in the key via `messages`; the explicit field is belt-and-suspenders.)
+    system: opts?.system || (Array.isArray(messages) ? messages.find?.((m) => m?.role === 'system')?.content : null) || null,
+    systemStatic: opts?.systemStatic || null,
+    systemVolatile: opts?.systemVolatile || null,
     tools: opts?.tools || null,
     toolChoice: opts?.toolChoice || null,
   };

package/providers/claude_cli.mjs

@@ -19,6 +19,7 @@
 
 import { spawn } from 'node:child_process';
 import { spawnSandboxed } from '../sandbox.mjs';
+import { classifyCliExit } from './cli_error.mjs';
 
 class AbortError extends Error {
   constructor(message = 'aborted') {
@@ -40,7 +41,12 @@ class CliExitError extends Error {
   constructor(code, signal, stderr) {
     super(`claude CLI exited ${code ?? signal}: ${String(stderr).slice(0, 400)}`);
     this.name = 'ClaudeCliExitError';
-    this.code = 'CLI_EXIT';
+    // A transient upstream throttle (claude's "Server temporarily limiting
+    // requests", overload, 429/5xx) maps to a retriable RATE_LIMIT so
+    // withRateLimitRetry retries it; a genuine usage cap stays CLI_EXIT.
+    const cls = classifyCliExit(stderr);
+    this.code = cls.code;
+    if (cls.retryAfterMs !== undefined) this.retryAfterMs = cls.retryAfterMs;
     this.exitCode = code;
     this.signal = signal;
     this.stderr = stderr;
@@ -51,12 +57,15 @@ class CliExitError extends Error {
 // form `claude --model` actually accepts. The Python dashboard ran into
 // the same issue (FF1) — passing the full id silently hangs the CLI.
 const _CLI_MODEL_ALIASES = {
+  'claude-fable-5':       'fable',
+  'claude-opus-4-8':      'opus',
   'claude-opus-4-7':      'opus',
   'claude-opus-4-6':      'opus',
   'claude-sonnet-4-6':    'sonnet',
   'claude-sonnet-4-5':    'sonnet',
   'claude-haiku-4-5':     'haiku',
   'claude-haiku-4-5-20251001': 'haiku',
+  fable: 'fable',
   opus: 'opus',
   sonnet: 'sonnet',
   haiku: 'haiku',
@@ -107,6 +116,37 @@ function extractTextDelta(obj) {
   return '';
 }
 
+// Build the `claude` argv. By DEFAULT lazyclaw runs claude LEAN: lazyclaw
+// supplies its own system prompt, so claude must NOT inherit the user's global
+// CLAUDE.md / skills / hooks / MCP servers. Loading them made every turn pull
+// ~180k tokens (measured) and let Claude Code act on the user's personal config
+// instead of lazyclaw's prompt — slow and off-task. `--setting-sources ''`
+// loads none of user/project/local; `--strict-mcp-config` (no --mcp-config)
+// loads no MCP servers. Pass opts.lean=false to restore the full environment.
+export function buildArgs(prompt, opts = {}) {
+  const args = [
+    '-p', prompt,
+    '--output-format', 'stream-json',
+    '--include-partial-messages',
+    '--verbose',
+  ];
+  if (opts.lean !== false) {
+    args.push('--setting-sources', '', '--strict-mcp-config');
+  }
+  // Bound Claude Code's internal autonomous agent loop. A plain chat/worker
+  // completion is ONE turn with NO built-in tools — without this a single
+  // question can trigger Claude Code's full Read/Grep/Bash exploration loop
+  // (measured 6-11 internal model calls, 90-126s) instead of just answering.
+  // Callers that genuinely want agentic behavior raise maxTurns and pass a
+  // tools whitelist (the agentic/team path uses the tool-use adapter instead).
+  const maxTurns = opts.maxTurns == null ? 1 : opts.maxTurns;
+  if (maxTurns > 0) args.push('--max-turns', String(maxTurns));
+  args.push('--tools', opts.tools == null ? '' : String(opts.tools));
+  const modelAlias = resolveModelAlias(opts.model);
+  if (modelAlias) args.push('--model', modelAlias);
+  return args;
+}
+
 export const claudeCliProvider = {
   name: 'claude-cli',
   /**
@@ -122,17 +162,39 @@ export const claudeCliProvider = {
    */
   async *sendMessage(messages, opts = {}) {
     const bin = opts.bin || 'claude';
+
+    // Opt-in persistent stream-json session: reuse ONE warm `claude` per
+    // conversation (the harness boots once, not every turn). Send only the NEW
+    // user turn — the session holds prior context server-side. We must NOT fall
+    // back to a fresh one-shot spawn once a chunk has been yielded (that would
+    // re-run the turn), so only fall through on a PRE-yield failure.
+    if (opts.persistent && opts.sessionKey) {
+      const last = [...messages].reverse().find((m) => m && m.role === 'user');
+      if (last && String(last.content).trim()) {
+        const { getSession } = await import('./claude_cli_session.mjs');
+        const session = getSession(opts.sessionKey, {
+          bin, model: opts.model, cwd: opts.cwd, lean: opts.lean,
+          maxTurns: opts.maxTurns, tools: opts.tools,
+          system: opts.sessionSystem || opts.system || messages.find((m) => m.role === 'system')?.content,
+        });
+        let yielded = false;
+        try {
+          for await (const chunk of session.send(String(last.content), { signal: opts.signal, onUsage: opts.onUsage })) {
+            yielded = true;
+            yield chunk;
+          }
+          return;
+        } catch (err) {
+          if (yielded || err?.code === 'ABORT') throw err; // can't re-run mid-stream
+          // pre-yield session failure → fall through to the one-shot spawn below
+        }
+      }
+    }
+
     const prompt = buildPrompt(messages, opts.system || messages.find(m => m.role === 'system')?.content);
     if (!prompt) return;
 
-    const args = [
-      '-p', prompt,
-      '--output-format', 'stream-json',
-      '--include-partial-messages',
-      '--verbose',
-    ];
-    const modelAlias = resolveModelAlias(opts.model);
-    if (modelAlias) args.push('--model', modelAlias);
+    const args = buildArgs(prompt, opts);
 
     if (opts.signal?.aborted) throw new AbortError('aborted before spawn');
 
@@ -188,6 +250,34 @@ export const claudeCliProvider = {
       });
     });
 
+    // Accumulate per-turn usage from `assistant` events. The streaming `result`
+    // event reports ZERO token usage (verified on claude 2.1.185), so reading it
+    // dropped input/output counts to 0; the truthful per-turn usage rides the
+    // `assistant` message event. Emit on the result event (which carries cost),
+    // summing across assistant events so a multi-turn run reports its total.
+    const _usage = { input: 0, output: 0, cacheCreate: 0, cacheRead: 0, saw: false };
+    const _accumulateUsage = (obj) => {
+      if (obj?.type === 'assistant' && obj.message?.usage) {
+        const u = obj.message.usage;
+        _usage.input += u.input_tokens || 0;
+        _usage.output += u.output_tokens || 0;
+        _usage.cacheCreate += u.cache_creation_input_tokens || 0;
+        _usage.cacheRead += u.cache_read_input_tokens || 0;
+        _usage.saw = true;
+      }
+      if (obj?.type === 'result' && typeof opts.onUsage === 'function') {
+        try {
+          opts.onUsage({
+            inputTokens: _usage.saw ? _usage.input : (obj.usage?.input_tokens || 0),
+            outputTokens: _usage.saw ? _usage.output : (obj.usage?.output_tokens || 0),
+            cacheCreationInputTokens: _usage.cacheCreate,
+            cacheReadInputTokens: _usage.cacheRead,
+            totalCostUsd: obj.total_cost_usd || 0,
+          });
+        } catch (_) { /* never fail the stream on a usage callback */ }
+      }
+    };
+
     try {
       for await (const chunk of proc.stdout) {
         if (opts.signal?.aborted) throw new AbortError('aborted mid-stream');
@@ -201,26 +291,17 @@ export const claudeCliProvider = {
           try { obj = JSON.parse(line); } catch { continue; }
           const text = extractTextDelta(obj);
           if (text) yield text;
-          if (obj?.type === 'result') {
-            // Last event of a successful run carries usage + cost.
-            if (typeof opts.onUsage === 'function') {
-              try {
-                opts.onUsage({
-                  inputTokens:  obj.usage?.input_tokens || 0,
-                  outputTokens: obj.usage?.output_tokens || 0,
-                  totalCostUsd: obj.total_cost_usd || 0,
-                });
-              } catch (_) { /* never fail the stream on usage callback */ }
-            }
-          }
+          _accumulateUsage(obj);
         }
       }
-      // Drain trailing buffered line.
+      // Drain trailing buffered line — handle usage too, so a result line that
+      // isn't newline-terminated still reports tokens + cost.
       if (buffer.trim()) {
         try {
           const obj = JSON.parse(buffer.trim());
           const text = extractTextDelta(obj);
           if (text) yield text;
+          _accumulateUsage(obj);
         } catch (_) { /* incomplete tail — drop */ }
       }
       // Wait for either a clean exit or an async spawn error. On ENOENT
@@ -245,3 +326,4 @@ export const claudeCliProvider = {
 };
 
 export { CliMissingError, CliExitError, AbortError, resolveModelAlias, buildPrompt };
+// buildArgs is also exported at its definition (lean-flag seam).

package/providers/claude_cli_session.mjs

@@ -0,0 +1,166 @@
+// Persistent claude stream-json session.
+//
+// lazyclaw's default claude-cli path spawns a fresh `claude -p` per turn, so the
+// Claude Code agent harness cold-boots and re-loads its base context EVERY turn
+// (measured ~1.6-2.7s + ~24k tokens per spawn). Claude Code also supports a
+// realtime streaming-input mode (`--input-format stream-json`): keep ONE child
+// alive per conversation, write each user turn as a JSON line to its stdin, read
+// the reply from stdout. The harness boots ONCE per session and stays warm — the
+// same way the Hermes upstream stays fast on the same $0 Pro subscription.
+// Measured here: turn 1 ~4.4s, turn 2 ~2.2s (boot amortized).
+//
+// Lifecycle: sessions are keyed by a conversation id, serialise one turn at a
+// time, evict on child exit/crash (next getSession respawns), kill on abort
+// (so a half-generated turn can't leak into the next), and idle-timeout teardown.
+// Callers keep the existing one-shot providers/claude_cli.mjs path as the
+// fallback for stateless calls and when this mode is unavailable.
+
+import { spawn } from 'node:child_process';
+import { resolveModelAlias, AbortError } from './claude_cli.mjs';
+
+const SESSIONS = new Map();
+const DEFAULT_IDLE_MS = 5 * 60_000;
+
+function extractTextDelta(obj) {
+  if (!obj || typeof obj !== 'object' || obj.type !== 'stream_event') return '';
+  const ev = obj.event || {};
+  if (ev.type === 'content_block_delta' && ev.delta && ev.delta.type === 'text_delta' && typeof ev.delta.text === 'string') {
+    return ev.delta.text;
+  }
+  return '';
+}
+
+class ClaudeSession {
+  constructor(key, opts = {}) {
+    this.key = key;
+    this.opts = opts;
+    this.idleMs = opts.idleMs || DEFAULT_IDLE_MS;
+    this._spawn = opts._spawn || spawn;
+    this.busy = false;
+    this.alive = true;
+    this.buffer = '';
+    this._spawnChild();
+  }
+
+  _spawnChild() {
+    const o = this.opts;
+    const args = [
+      '--print', '--input-format', 'stream-json', '--output-format', 'stream-json',
+      '--include-partial-messages', '--verbose',
+    ];
+    if (o.lean !== false) args.push('--setting-sources', '', '--strict-mcp-config');
+    const mt = o.maxTurns == null ? 1 : o.maxTurns;
+    if (mt > 0) args.push('--max-turns', String(mt));
+    args.push('--tools', o.tools == null ? '' : String(o.tools));
+    const model = resolveModelAlias(o.model);
+    if (model) args.push('--model', model);
+    if (o.system && String(o.system).trim()) args.push('--append-system-prompt', String(o.system));
+
+    this.proc = this._spawn(o.bin || process.env.LAZYCLAW_CLAUDE_BIN || 'claude', args, {
+      cwd: o.cwd || process.cwd(),
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    try { this.proc.stdout.setEncoding('utf8'); } catch { /* fake child in tests */ }
+    const evict = () => {
+      this.alive = false;
+      clearTimeout(this._idle);
+      if (SESSIONS.get(this.key) === this) SESSIONS.delete(this.key);
+    };
+    this.proc.on('exit', evict);
+    this.proc.on('error', evict);
+    this._touch();
+  }
+
+  _touch() {
+    clearTimeout(this._idle);
+    this._idle = setTimeout(() => this.close(), this.idleMs);
+    if (this._idle && typeof this._idle.unref === 'function') this._idle.unref();
+  }
+
+  // Stream one turn. Yields text deltas until the matching `result` event.
+  async *send(userText, { signal, onUsage } = {}) {
+    if (this.busy) throw new Error('claude session busy — sends must be serialised per session');
+    if (!this.alive) throw new Error('claude session is not alive');
+    this.busy = true;
+    this._touch();
+
+    const queue = [];
+    let done = false;
+    let error = null;
+    let wake = null;
+    const wait = () => new Promise((r) => { wake = r; });
+    const onData = (d) => {
+      this.buffer += d;
+      let nl;
+      while ((nl = this.buffer.indexOf('\n')) >= 0) {
+        const line = this.buffer.slice(0, nl).trim();
+        this.buffer = this.buffer.slice(nl + 1);
+        if (!line) continue;
+        let obj;
+        try { obj = JSON.parse(line); } catch { continue; }
+        const t = extractTextDelta(obj);
+        if (t) { queue.push(t); if (wake) wake(); }
+        if (obj.type === 'result') {
+          if (typeof onUsage === 'function' && obj.usage) {
+            try {
+              onUsage({
+                inputTokens: obj.usage.input_tokens || 0,
+                outputTokens: obj.usage.output_tokens || 0,
+                totalCostUsd: obj.total_cost_usd || 0,
+              });
+            } catch { /* never fail a turn on a usage callback */ }
+          }
+          done = true; if (wake) wake();
+        }
+      }
+    };
+    const onExit = () => { if (!error) error = new Error('claude session exited mid-turn'); done = true; if (wake) wake(); };
+    this.proc.stdout.on('data', onData);
+    this.proc.once('exit', onExit);
+
+    let aborted = false;
+    try {
+      this.proc.stdin.write(JSON.stringify({ type: 'user', message: { role: 'user', content: String(userText) } }) + '\n');
+      for (;;) {
+        if (queue.length) { yield queue.shift(); continue; }
+        if (done) break;
+        if (signal && signal.aborted) { aborted = true; error = new AbortError('aborted mid-session'); break; }
+        await wait();
+      }
+      if (error) throw error;
+    } finally {
+      this.proc.stdout.off('data', onData);
+      this.proc.off('exit', onExit);
+      this.busy = false;
+      this._touch();
+      // Abort mid-turn leaves a half-generated reply in the pipe; drop the warm
+      // session so the next turn starts clean rather than reading stale output.
+      if (aborted) this.close();
+    }
+  }
+
+  close() {
+    this.alive = false;
+    clearTimeout(this._idle);
+    if (SESSIONS.get(this.key) === this) SESSIONS.delete(this.key);
+    try { if (this.proc && !this.proc.killed) this.proc.kill('SIGTERM'); } catch { /* already gone */ }
+  }
+}
+
+// Return the live session for `key`, spawning one if none is alive. A warm
+// session fixes its system prompt at spawn (--append-system-prompt), so if the
+// caller's system changes mid-conversation (e.g. plan-mode toggled), the warm
+// session is stale — evict and respawn rather than answer with the old system.
+export function getSession(key, opts = {}) {
+  const existing = SESSIONS.get(key);
+  if (existing && existing.alive) {
+    if ((existing.opts.system || '') === (opts.system || '')) return existing;
+    existing.close();
+  }
+  const s = new ClaudeSession(key, opts);
+  SESSIONS.set(key, s);
+  return s;
+}
+
+export function closeAllSessions() { for (const s of [...SESSIONS.values()]) s.close(); }
+export function _resetSessions() { closeAllSessions(); SESSIONS.clear(); }

package/providers/cli_error.mjs

@@ -0,0 +1,38 @@
+// Classify a non-zero CLI-provider exit by its stderr.
+//
+// claude-cli / codex-cli / gemini-cli all surface upstream throttling by
+// exiting non-zero with the throttle text on stderr — e.g. claude's
+// "Server temporarily limiting requests (not your usage limit)", an
+// overloaded_error, or a bare HTTP 429/5xx. Those are transient: the same
+// call usually succeeds shortly, so they should map to a RETRIABLE error code
+// (RATE_LIMIT) that withRateLimitRetry retries before the first chunk.
+//
+// A genuine, durable cap — a subscription usage limit, out of credits, quota
+// exceeded — must NOT be retried: retrying just burns the same wall and fails
+// again, so it keeps the non-retriable CLI_EXIT code and surfaces fast.
+//
+// Subtlety: the transient throttle text literally contains the words "usage
+// limit" ("...not your usage limit..."), so the durable-cap pattern is phrased
+// to require the "reached"/"exceeded"/"out of" wording a real cap uses — it
+// must not fire on the transient throttle.
+
+// Durable caps — never retry. Each alternative carries the cap-specific
+// wording so the bare phrase "usage limit" inside the transient text can't
+// match.
+const DURABLE_CAP = /usage limit reached|reached your (?:usage|plan|monthly|account|daily) limit|out of credits|quota (?:has been )?exceeded|insufficient (?:\w+ )?credits?|please upgrade|upgrade your plan/i;
+
+// Transient throttle / overload — retry after a short pause.
+const TRANSIENT = /temporarily limiting|limiting requests|overloaded|rate.?limited?|too many requests|\b(?:429|500|502|503|504|529)\b|please try again|service unavailable/i;
+
+const DEFAULT_CLI_RETRY_AFTER_MS = 3000;
+
+/**
+ * @param {unknown} stderr  Captured stderr from the failed CLI invocation.
+ * @returns {{ code: 'RATE_LIMIT' | 'CLI_EXIT', retriable: boolean, retryAfterMs?: number }}
+ */
+export function classifyCliExit(stderr) {
+  const s = String(stderr ?? '');
+  if (DURABLE_CAP.test(s)) return { code: 'CLI_EXIT', retriable: false };
+  if (TRANSIENT.test(s)) return { code: 'RATE_LIMIT', retriable: true, retryAfterMs: DEFAULT_CLI_RETRY_AFTER_MS };
+  return { code: 'CLI_EXIT', retriable: false };
+}