@pivanov/claude-wire 0.0.3 → 0.0.4

package/dist/reader.js

@@ -2,6 +2,7 @@ import { LIMITS, TIMEOUTS } from "./constants.js";
 import { AbortError, ClaudeError, TimeoutError } from "./errors.js";
 import { parseLine } from "./parser/ndjson.js";
 import { dispatchToolDecision } from "./pipeline.js";
+import { safeKill, safeWrite } from "./process.js";
 import { writer } from "./writer.js";
 export const drainStderr = (proc) => {
     const chunks = [];
@@ -29,7 +30,11 @@ export const drainStderr = (proc) => {
             stderrReader.releaseLock();
         }
     })().catch(() => { });
-    return { chunks, done };
+    return {
+        chunks,
+        done,
+        text: () => chunks.join("").trim(),
+    };
 };
 export async function* readNdjsonEvents(opts) {
     const { reader, translator, signal } = opts;
@@ -43,13 +48,29 @@ export async function* readNdjsonEvents(opts) {
     });
     // Swallow unhandled rejection if nothing ever races against this promise.
     abortPromise.catch(() => { });
-    // Single resettable timeout shared across all iterations — avoids leaking
+    // Single resettable timeout shared across all iterations -- avoids leaking
     // a new Promise + setTimeout per read loop.
     let timeoutReject;
     const timeoutPromise = new Promise((_, reject) => {
         timeoutReject = reject;
     });
     timeoutPromise.catch(() => { });
+    // Shared per-raw-event dispatch. Used by both the main read loop and the
+    // trailing-buffer flush so the translate → tool-dispatch → yield sequence
+    // lives in one place. `!turnComplete` guards dispatch so we don't approve
+    // or deny a tool call the CLI emits after it already said it's done.
+    const processRaw = async function* (raw) {
+        const translated = translator.translate(raw);
+        for (const event of translated) {
+            if (event.type === "tool_use" && !turnComplete && opts.toolHandler && opts.proc) {
+                await dispatchToolDecision(opts.proc, opts.toolHandler, event, opts.onWarning);
+            }
+            yield event;
+            if (event.type === "turn_complete") {
+                turnComplete = true;
+            }
+        }
+    };
     const resetReadTimeout = () => {
         if (timeoutId) {
             clearTimeout(timeoutId);
@@ -62,13 +83,8 @@ export async function* readNdjsonEvents(opts) {
         ? () => {
             abortReject?.(new AbortError());
             if (opts.proc) {
-                try {
-                    opts.proc.write(writer.abort());
-                }
-                catch {
-                    // stdin closed
-                }
-                opts.proc.kill();
+                safeWrite(opts.proc, writer.abort());
+                safeKill(opts.proc);
             }
         }
         : undefined;
@@ -90,8 +106,12 @@ export async function* readNdjsonEvents(opts) {
                 break;
             }
             buffer += decoder.decode(value, { stream: true });
+            // The limit applies to the accumulated buffer (which contains at most
+            // one in-progress line plus any already-split lines being held), so
+            // a single oversize line trips the same guard. Name is legacy -- the
+            // check is effectively "no NDJSON message may grow past this size".
             if (buffer.length > LIMITS.ndjsonMaxLineChars) {
-                throw new ClaudeError(`NDJSON buffer exceeded ${LIMITS.ndjsonMaxLineChars} chars`);
+                throw new ClaudeError(`NDJSON buffer exceeded ${LIMITS.ndjsonMaxLineChars} chars (single line or accumulated pending lines)`);
             }
             const lines = buffer.split("\n");
             buffer = lines.pop() ?? "";
@@ -100,16 +120,7 @@ export async function* readNdjsonEvents(opts) {
                 if (!raw) {
                     continue;
                 }
-                const events = translator.translate(raw);
-                for (const event of events) {
-                    if (event.type === "tool_use" && opts.toolHandler && opts.proc) {
-                        await dispatchToolDecision(opts.proc, opts.toolHandler, event);
-                    }
-                    yield event;
-                    if (event.type === "turn_complete") {
-                        turnComplete = true;
-                    }
-                }
+                yield* processRaw(raw);
             }
             if (turnComplete) {
                 break;
@@ -118,16 +129,7 @@ export async function* readNdjsonEvents(opts) {
         if (buffer.trim()) {
             const raw = parseLine(buffer);
             if (raw) {
-                const events = translator.translate(raw);
-                for (const event of events) {
-                    if (event.type === "tool_use" && opts.toolHandler && opts.proc && !turnComplete) {
-                        await dispatchToolDecision(opts.proc, opts.toolHandler, event);
-                    }
-                    yield event;
-                    if (event.type === "turn_complete") {
-                        turnComplete = true;
-                    }
-                }
+                yield* processRaw(raw);
             }
         }
     }

package/dist/runtime.d.ts

@@ -1,18 +1,19 @@
-export interface IRawProcess {
+interface IRawProcess {
     stdin: {
         write: (data: string) => void;
         end: () => void;
     };
     stdout: ReadableStream<Uint8Array>;
     stderr: ReadableStream<Uint8Array>;
-    kill: () => void;
+    kill: (signal?: NodeJS.Signals | number) => void;
     exited: Promise<number>;
     pid: number;
 }
-export interface ISpawnOpts {
+interface ISpawnOpts {
     cwd?: string;
     env?: Record<string, string | undefined>;
 }
 export declare const spawnProcess: (args: string[], opts: ISpawnOpts) => IRawProcess;
 export declare const whichSync: (name: string) => string | undefined;
-export declare const fileExists: (path: string) => boolean;
+export declare const isExecutableNonEmpty: (path: string) => boolean;
+export {};

package/dist/runtime.js

@@ -30,7 +30,10 @@ export const whichSync = (name) => {
         return undefined;
     }
 };
-export const fileExists = (path) => {
+// Used to vet candidate `claude` binary paths -- a zero-byte stub or a
+// non-executable regular file both count as "not a usable binary" here.
+// Name reflects behavior: this is NOT a generic fs.exists check.
+export const isExecutableNonEmpty = (path) => {
     try {
         accessSync(path, constants.X_OK);
         return statSync(path).size > 0;
@@ -58,8 +61,8 @@ const spawnBun = (args, opts) => {
         },
         stdout: proc.stdout,
         stderr: proc.stderr,
-        kill: () => {
-            proc.kill();
+        kill: (signal) => {
+            proc.kill(signal);
         },
         exited: proc.exited,
         pid: proc.pid,
@@ -99,8 +102,8 @@ const spawnNode = (args, opts) => {
         },
         stdout: child.stdout ? toWeb(child.stdout) : new ReadableStream(),
         stderr: child.stderr ? toWeb(child.stderr) : new ReadableStream(),
-        kill: () => {
-            child.kill();
+        kill: (signal) => {
+            child.kill(signal);
         },
         exited,
         pid: child.pid,

package/dist/session.d.ts

@@ -1,8 +1,36 @@
-import type { ISessionOptions } from "./types/options.js";
+import type { IAskOptions, ISessionOptions } from "./types/options.js";
 import type { TAskResult } from "./types/results.js";
 export interface IClaudeSession extends AsyncDisposable {
-    ask: (prompt: string) => Promise<TAskResult>;
+    ask: (prompt: string, options?: IAskOptions) => Promise<TAskResult>;
     close: () => Promise<void>;
     sessionId: string | undefined;
 }
+/**
+ * Creates a multi-turn Claude session backed by a single long-lived CLI
+ * process. Each `ask()` sends a user prompt and resolves with `TAskResult`
+ * for that turn. Calls are serialized -- a second `ask()` waits for the
+ * first to complete. Use `close()` (or `await using`) to free the process.
+ *
+ * ### Retry behavior
+ * Each `ask()` automatically retries transient failures -- process crashes
+ * matching SIGKILL/SIGTERM/SIGPIPE exit codes, `ECONNRESET`, `ECONNREFUSED`,
+ * `ETIMEDOUT`, `EHOSTUNREACH`, `ENETUNREACH`, `EAI_AGAIN`, Anthropic
+ * `overloaded_error` / 529s, broken-pipe / "socket hang up" messages, etc.
+ * (see `isTransientError`). Backoff is `500ms → 1s → 2s`; the budget is
+ * `LIMITS.maxRespawnAttempts` (currently 3) and is shared across a single
+ * `ask()`. When the budget is exhausted the session throws
+ * `KnownError("retry-exhausted")` and marks itself closed.
+ *
+ * Fatal errors -- `KnownError` and `BudgetExceededError` -- also close the
+ * session. Any subsequent `ask()` on a closed session rejects with
+ * `ClaudeError("Session is closed")`. All other errors (abort, timeout,
+ * non-transient `ProcessError`) propagate without closing, and the caller
+ * may decide whether to retry at a higher level.
+ *
+ * ### Observability
+ * - `onCostUpdate(snapshot)` -- fires after every `turn_complete`.
+ * - `onRetry(attempt, error)` -- fires each time a transient failure triggers
+ *   a respawn inside one `ask()`. Attempt is 1-indexed.
+ * - `onWarning(message, cause)` -- routes all library-emitted warnings.
+ */
 export declare const createSession: (options?: ISessionOptions) => IClaudeSession;

package/dist/session.js

@@ -1,41 +1,90 @@
-import { LIMITS, RESPAWN_BACKOFF_MS, TIMEOUTS } from "./constants.js";
+import { withTimeout } from "./async.js";
+import { LIMITS, MAX_BACKOFF_INDEX, RESPAWN_BACKOFF_MS, TIMEOUTS } from "./constants.js";
 import { createCostTracker } from "./cost.js";
-import { AbortError, BudgetExceededError, ClaudeError, isTransientError, KnownError, ProcessError, TimeoutError } from "./errors.js";
+import { AbortError, BudgetExceededError, ClaudeError, isTransientError, KnownError, processExitedEarly, TimeoutError } from "./errors.js";
 import { createTranslator } from "./parser/translator.js";
-import { buildResult } from "./pipeline.js";
-import { spawnClaude } from "./process.js";
-import { drainStderr, readNdjsonEvents } from "./reader.js";
+import { applyTurnComplete, buildResult, startPipeline } from "./pipeline.js";
+import { safeKill, safeWrite } from "./process.js";
+import { readNdjsonEvents } from "./reader.js";
 import { createToolHandler } from "./tools/handler.js";
 import { writer } from "./writer.js";
-const gracefulKill = async (p) => {
-    p.kill();
-    let timer;
-    let timedOut = false;
+// Two-stage termination: SIGTERM first, escalate to SIGKILL after the
+// graceful-exit timeout. A stuck child (e.g. blocked on a syscall that
+// ignores SIGTERM) would otherwise survive the "graceful" path and leak.
+// The sentinel value distinguishes "exited on time" from "timeout fired"
+// without a side-channel boolean.
+// Compose two optional AbortSignals into one. If either fires, the
+// returned signal aborts. Returns undefined when both inputs are undefined.
+const composeSignals = (a, b) => {
+    if (!a && !b) {
+        return undefined;
+    }
+    if (!a) {
+        return b;
+    }
+    if (!b) {
+        return a;
+    }
+    const ctrl = new AbortController();
+    const abort = () => ctrl.abort();
+    a.addEventListener("abort", abort, { once: true });
+    b.addEventListener("abort", abort, { once: true });
+    if (a.aborted || b.aborted) {
+        ctrl.abort();
+    }
+    return ctrl.signal;
+};
+// Fire both session-level and per-ask onRetry, swallowing throws from either.
+const fireRetry = (attempt, error, sessionLevel, askLevel) => {
     try {
-        await Promise.race([
-            p.exited,
-            new Promise((r) => {
-                timer = setTimeout(() => {
-                    timedOut = true;
-                    r();
-                }, TIMEOUTS.gracefulExitMs);
-            }),
-        ]);
+        sessionLevel?.(attempt, error);
     }
-    finally {
-        if (timer) {
-            clearTimeout(timer);
-        }
+    catch {
+        // observer threw -- retry still happens
     }
-    if (timedOut) {
-        try {
-            p.kill();
-        }
-        catch {
-            // already dead
-        }
+    try {
+        askLevel?.(attempt, error);
+    }
+    catch {
+        // observer threw -- retry still happens
     }
 };
+const KILL_TIMED_OUT = Symbol("kill-timed-out");
+const gracefulKill = async (p) => {
+    safeKill(p, "SIGTERM");
+    const outcome = await withTimeout(p.exited, TIMEOUTS.gracefulExitMs, () => KILL_TIMED_OUT);
+    if (outcome === KILL_TIMED_OUT) {
+        safeKill(p, "SIGKILL");
+    }
+};
+/**
+ * Creates a multi-turn Claude session backed by a single long-lived CLI
+ * process. Each `ask()` sends a user prompt and resolves with `TAskResult`
+ * for that turn. Calls are serialized -- a second `ask()` waits for the
+ * first to complete. Use `close()` (or `await using`) to free the process.
+ *
+ * ### Retry behavior
+ * Each `ask()` automatically retries transient failures -- process crashes
+ * matching SIGKILL/SIGTERM/SIGPIPE exit codes, `ECONNRESET`, `ECONNREFUSED`,
+ * `ETIMEDOUT`, `EHOSTUNREACH`, `ENETUNREACH`, `EAI_AGAIN`, Anthropic
+ * `overloaded_error` / 529s, broken-pipe / "socket hang up" messages, etc.
+ * (see `isTransientError`). Backoff is `500ms → 1s → 2s`; the budget is
+ * `LIMITS.maxRespawnAttempts` (currently 3) and is shared across a single
+ * `ask()`. When the budget is exhausted the session throws
+ * `KnownError("retry-exhausted")` and marks itself closed.
+ *
+ * Fatal errors -- `KnownError` and `BudgetExceededError` -- also close the
+ * session. Any subsequent `ask()` on a closed session rejects with
+ * `ClaudeError("Session is closed")`. All other errors (abort, timeout,
+ * non-transient `ProcessError`) propagate without closing, and the caller
+ * may decide whether to retry at a higher level.
+ *
+ * ### Observability
+ * - `onCostUpdate(snapshot)` -- fires after every `turn_complete`.
+ * - `onRetry(attempt, error)` -- fires each time a transient failure triggers
+ *   a respawn inside one `ask()`. Attempt is 1-indexed.
+ * - `onWarning(message, cause)` -- routes all library-emitted warnings.
+ */
 export const createSession = (options = {}) => {
     let proc;
     let currentSessionId;
@@ -46,6 +95,7 @@ export const createSession = (options = {}) => {
     const costTracker = createCostTracker({
         maxCostUsd: options.maxCostUsd,
         onCostUpdate: options.onCostUpdate,
+        onWarning: options.onWarning,
     });
     const toolHandler = options.tools ? createToolHandler(options.tools) : undefined;
     let inFlight;
@@ -61,9 +111,11 @@ export const createSession = (options = {}) => {
         }
         reader = undefined;
     };
-    let lastStderrChunks = [];
-    let lastDrainDone;
-    const getStderrText = () => lastStderrChunks.join("").trim();
+    // Drain handle from the most recent spawn. Stored as a whole so we
+    // can call `.text()` (shared helper on IStderrDrain) instead of
+    // reimplementing chunks.join/trim at every use site.
+    let lastStderrDrain;
+    const getStderrText = () => lastStderrDrain?.text() ?? "";
     const killProc = () => {
         if (proc) {
             proc.kill();
@@ -75,20 +127,27 @@ export const createSession = (options = {}) => {
     const spawnFresh = (prompt, resumeId) => {
         if (consecutiveCrashes >= LIMITS.maxRespawnAttempts) {
             killProc();
-            throw new ProcessError(`Process crashed ${consecutiveCrashes} times, giving up`);
+            // Typed code so consumers can pattern-match on
+            // `KnownError && err.code === "retry-exhausted"` without parsing strings.
+            throw new KnownError("retry-exhausted", `Process crashed ${consecutiveCrashes} times, giving up`);
         }
         costOffsets = costTracker.snapshot();
         killProc();
         translator.reset();
+        // Respawn always overrides caller-supplied options.resume with the live
+        // session id when one is available: mid-session recovery must resume the
+        // same conversation, not whatever static id was passed at construction.
         const spawnOpts = resumeId ? { prompt, ...options, resume: resumeId } : { prompt, ...options };
-        proc = spawnClaude(spawnOpts);
-        reader = proc.stdout.getReader();
-        const drain = drainStderr(proc);
-        lastStderrChunks = drain.chunks;
-        lastDrainDone = drain.done;
+        const pipeline = startPipeline(spawnOpts);
+        proc = pipeline.proc;
+        reader = pipeline.reader;
+        lastStderrDrain = pipeline.stderr;
     };
     const respawnBackoff = async () => {
-        const idx = Math.min(consecutiveCrashes, RESPAWN_BACKOFF_MS.length) - 1;
+        // consecutiveCrashes starts at 1 for the first retry; idx points
+        // into RESPAWN_BACKOFF_MS and clamps to the last defined entry for
+        // any crash count beyond the table length.
+        const idx = Math.min(consecutiveCrashes, MAX_BACKOFF_INDEX) - 1;
         const delay = idx >= 0 ? RESPAWN_BACKOFF_MS[idx] : 0;
         if (delay) {
             await new Promise((r) => setTimeout(r, delay));
@@ -106,14 +165,14 @@ export const createSession = (options = {}) => {
             toolHandler,
             proc,
             signal,
+            onWarning: options.onWarning,
         })) {
             if (event.type === "session_meta") {
                 currentSessionId = event.sessionId;
             }
             events.push(event);
             if (event.type === "turn_complete") {
-                costTracker.update(costOffsets.totalUsd + (event.costUsd ?? 0), costOffsets.inputTokens + (event.inputTokens ?? 0), costOffsets.outputTokens + (event.outputTokens ?? 0));
-                costTracker.checkBudget();
+                applyTurnComplete(event, costTracker, costOffsets);
                 gotTurnComplete = true;
                 break;
             }
@@ -122,46 +181,49 @@ export const createSession = (options = {}) => {
             if (signal?.aborted) {
                 throw new AbortError();
             }
-            // stdout closed → process is dying. Race `exited` against a short
-            // timeout so a zombie/unreaped child doesn't hang us. If exited doesn't
-            // resolve in time we leave exitCode undefined (→ non-transient).
+            // stdout closed → process is dying. Wait briefly for exited so we
+            // can attach an exit code to the error; if it doesn't resolve in
+            // time, force-kill and leave exitCode undefined (→ non-transient).
             let exitCode;
             if (proc) {
                 const live = proc;
-                exitCode = await Promise.race([
-                    live.exited,
-                    new Promise((r) => setTimeout(() => r(undefined), TIMEOUTS.gracefulExitMs)),
-                ]);
+                exitCode = await withTimeout(live.exited, TIMEOUTS.gracefulExitMs);
                 if (exitCode === undefined) {
                     live.kill();
                 }
             }
-            if (lastDrainDone) {
-                await Promise.race([lastDrainDone, new Promise((r) => setTimeout(r, 500))]);
+            if (lastStderrDrain) {
+                await withTimeout(lastStderrDrain.done, TIMEOUTS.stderrDrainGraceMs);
             }
-            const stderrMsg = getStderrText();
-            throw new ProcessError(stderrMsg || "Process exited without completing the turn", exitCode);
+            throw processExitedEarly(getStderrText(), exitCode);
         }
         return events;
     };
-    const doAsk = async (prompt) => {
+    const doAsk = async (prompt, askOpts) => {
         if (!proc) {
             spawnFresh(prompt, currentSessionId);
         }
-        else {
+        else if (!safeWrite(proc, writer.user(prompt))) {
+            // stdin write failed -- process probably died. Try to respawn.
+            // spawnFresh can itself throw ProcessError synchronously when the
+            // respawn cap is already hit; surface as an Error like the retry
+            // loop below would, instead of a raw synchronous throw.
+            consecutiveCrashes++;
+            translator.reset();
             try {
-                proc.write(writer.user(prompt));
-            }
-            catch {
-                consecutiveCrashes++;
-                translator.reset();
                 spawnFresh(prompt, currentSessionId);
             }
+            catch (respawnError) {
+                killProc();
+                throw respawnError;
+            }
         }
+        // Compose per-ask signal with session-level signal: either firing aborts.
+        const effectiveSignal = composeSignals(options.signal, askOpts?.signal);
         let events;
         while (true) {
             try {
-                events = await readUntilTurnComplete(options.signal);
+                events = await readUntilTurnComplete(effectiveSignal);
                 break;
             }
             catch (error) {
@@ -175,6 +237,9 @@ export const createSession = (options = {}) => {
                     throw error;
                 }
                 consecutiveCrashes++;
+                // Fire both session-level and per-ask onRetry. Both are safe-invoked
+                // so a throwing observer doesn't prevent the retry.
+                fireRetry(consecutiveCrashes, error, options.onRetry, askOpts?.onRetry);
                 await respawnBackoff();
                 spawnFresh(prompt, currentSessionId);
                 // Loop to retry; stops when budget exhausted or turn completes.
@@ -194,7 +259,7 @@ export const createSession = (options = {}) => {
         return buildResult(events, costTracker, currentSessionId);
     };
     let closed = false;
-    const ask = (prompt) => {
+    const ask = (prompt, askOpts) => {
         if (closed) {
             return Promise.reject(new ClaudeError("Session is closed"));
         }
@@ -209,7 +274,7 @@ export const createSession = (options = {}) => {
             if (closed) {
                 throw new ClaudeError("Session is closed");
             }
-            return doAsk(prompt);
+            return doAsk(prompt, askOpts);
         })
             .catch((error) => {
             if (error instanceof KnownError || error instanceof BudgetExceededError) {
@@ -225,16 +290,11 @@ export const createSession = (options = {}) => {
         if (inFlight) {
             // Cap the wait: a stuck reader.read() inside the queued ask would
             // otherwise hang close() forever before gracefulKill gets a chance.
-            await Promise.race([inFlight.catch(() => { }), new Promise((r) => setTimeout(r, TIMEOUTS.gracefulExitMs))]);
+            await withTimeout(inFlight.catch(() => { }), TIMEOUTS.gracefulExitMs);
             inFlight = undefined;
         }
         if (proc) {
-            try {
-                proc.write(writer.abort());
-            }
-            catch {
-                // stdin may already be closed
-            }
+            safeWrite(proc, writer.abort());
             await gracefulKill(proc);
             proc = undefined;
         }