@pivanov/claude-wire 0.0.2 → 0.0.4

package/dist/process.js

@@ -2,25 +2,55 @@ import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { BINARY } from "./constants.js";
-import { assertPositiveNumber, errorMessage, KnownError, ProcessError } from "./errors.js";
-import { fileExists, spawnProcess, whichSync } from "./runtime.js";
+import { errorMessage, KnownError, ProcessError } from "./errors.js";
+import { isExecutableNonEmpty, spawnProcess, whichSync } from "./runtime.js";
+import { assertPositiveNumber } from "./validation.js";
 import { writer } from "./writer.js";
+// Swallow ESRCH/EPIPE-style throws from kill()/write() when the child is
+// already gone. Every call site had the same try/catch -- keeping it in one
+// place stops future adders from forgetting the guard.
+export const safeKill = (proc, signal) => {
+    try {
+        proc.kill(signal);
+    }
+    catch {
+        // already dead
+    }
+};
+export const safeWrite = (proc, line) => {
+    try {
+        proc.write(line);
+        return true;
+    }
+    catch {
+        // stdin closed / process died -- caller surfaces the error via the read path
+        return false;
+    }
+};
+// Resolves the `claude` CLI binary path. POSIX-only today: uses `which` and
+// `$HOME`-rooted common install paths. Windows users running under WSL get
+// the Linux layout, which works; native Windows is not supported yet.
 const resolveBinaryPath = () => {
     const found = whichSync("claude");
     if (found) {
         return found;
     }
     for (const p of BINARY.commonPaths) {
-        if (fileExists(p)) {
+        if (isExecutableNonEmpty(p)) {
             return p;
         }
     }
     return BINARY.name;
 };
-const ALIAS_PATTERN = /(?:alias\s+claude\s*=|export\s+).*CLAUDE_CONFIG_DIR=["']?\$?(?:HOME|\{HOME\}|~)\/?([^\s"']+?)["']?(?:\s|\/|$)/;
+// Rejects lines whose first non-whitespace char is `#` so commented-out
+// aliases/exports don't silently apply. /m anchors to each line in rc files.
+export const ALIAS_PATTERN = /^(?!\s*#).*?(?:alias\s+claude\s*=|export\s+).*CLAUDE_CONFIG_DIR=["']?\$?(?:HOME|\{HOME\}|~)\/?([^\s"']+?)["']?(?:\s|$)/m;
 const resolveConfigDirFromAlias = () => {
     const home = homedir();
-    const rcFiles = [".zshrc", ".bashrc", ".zprofile", ".bash_profile", ".aliases"];
+    // .zshenv is the one file zsh sources for NON-interactive shells, so
+    // users who export CLAUDE_CONFIG_DIR for cron/CI-like contexts often
+    // put it there. Include it alongside the interactive-shell rc files.
+    const rcFiles = [".zshenv", ".zshrc", ".bashrc", ".zprofile", ".bash_profile", ".aliases"];
     for (const rcFile of rcFiles) {
         try {
             const content = readFileSync(join(home, rcFile), "utf-8");
@@ -36,7 +66,17 @@ const resolveConfigDirFromAlias = () => {
     return undefined;
 };
 let cached;
-export const resetBinaryCache = () => {
+/**
+ * Clears the cached resolved environment (binary path + alias-detected
+ * `CLAUDE_CONFIG_DIR`). Call this when either has changed mid-process -- for
+ * example after installing the Claude CLI during a test run, or when a long-
+ * running daemon updates the user's shell rc file. The next `spawnClaude()`
+ * will re-resolve from scratch.
+ *
+ * Normal applications should never need this; the cache is populated once at
+ * first use and kept for the process lifetime.
+ */
+export const resetResolvedEnvCache = () => {
     cached = undefined;
 };
 const resolve = () => {
@@ -50,18 +90,23 @@ const resolve = () => {
 };
 export const buildArgs = (options, binaryPath) => {
     const args = [binaryPath, "-p", "--output-format", "stream-json", "--input-format", "stream-json"];
-    if (options.verbose !== false) {
-        args.push("--verbose");
-    }
-    if (options.model) {
-        args.push("--model", options.model);
-    }
-    if (options.systemPrompt) {
-        args.push("--system-prompt", options.systemPrompt);
-    }
-    if (options.appendSystemPrompt) {
-        args.push("--append-system-prompt", options.appendSystemPrompt);
-    }
+    const flag = (cond, name) => {
+        if (cond) {
+            args.push(name);
+        }
+    };
+    const kv = (value, name) => {
+        if (value) {
+            args.push(name, value);
+        }
+    };
+    // Default ON: the translator's block-dedup relies on --verbose emitting
+    // cumulative assistant content. Consumers must explicitly pass `false`
+    // to opt out (`undefined` still yields --verbose).
+    flag(options.verbose !== false, "--verbose");
+    kv(options.model, "--model");
+    kv(options.systemPrompt, "--system-prompt");
+    kv(options.appendSystemPrompt, "--append-system-prompt");
     if (options.allowedTools) {
         if (options.allowedTools.length === 0) {
             args.push("--tools", "");
@@ -76,82 +121,79 @@ export const buildArgs = (options, binaryPath) => {
     if (options.maxBudgetUsd !== undefined) {
         args.push("--max-budget-usd", String(options.maxBudgetUsd));
     }
-    if (options.resume) {
-        args.push("--resume", options.resume);
-    }
-    if (options.mcpConfig) {
-        args.push("--mcp-config", options.mcpConfig);
-    }
-    if (options.continueSession) {
-        args.push("--continue");
-    }
-    if (options.permissionMode) {
-        args.push("--permission-mode", options.permissionMode);
-    }
+    kv(options.resume, "--resume");
+    kv(options.mcpConfig, "--mcp-config");
+    flag(options.continueSession, "--continue");
+    kv(options.permissionMode, "--permission-mode");
     if (options.addDirs && options.addDirs.length > 0) {
         for (const dir of options.addDirs) {
             args.push("--add-dir", dir);
         }
     }
-    if (options.effort) {
-        args.push("--effort", options.effort);
-    }
-    if (options.includeHookEvents) {
-        args.push("--include-hook-events");
-    }
-    if (options.includePartialMessages) {
-        args.push("--include-partial-messages");
-    }
-    if (options.bare) {
-        args.push("--bare");
-    }
-    if (options.jsonSchema) {
-        args.push("--json-schema", options.jsonSchema);
-    }
-    if (options.forkSession) {
-        args.push("--fork-session");
-    }
-    if (options.noSessionPersistence) {
-        args.push("--no-session-persistence");
-    }
-    if (options.sessionId) {
-        args.push("--session-id", options.sessionId);
-    }
+    kv(options.effort, "--effort");
+    flag(options.includeHookEvents, "--include-hook-events");
+    flag(options.includePartialMessages, "--include-partial-messages");
+    flag(options.bare, "--bare");
+    kv(options.jsonSchema, "--json-schema");
+    flag(options.forkSession, "--fork-session");
+    flag(options.noSessionPersistence, "--no-session-persistence");
+    kv(options.sessionId, "--session-id");
     if (options.settingSources !== undefined) {
         args.push("--setting-sources", options.settingSources);
     }
-    if (options.disableSlashCommands) {
-        args.push("--disable-slash-commands");
-    }
+    flag(options.disableSlashCommands, "--disable-slash-commands");
     return args;
 };
+// Priority (lowest → highest): baseEnv < alias-detected config <
+// user's explicit `options.env` < explicit `options.configDir`. User
+// input always outranks the alias heuristic. Returns undefined when no
+// override is needed, so spawnProcess can pass the parent env through.
+export const buildSpawnEnv = (baseEnv, aliasConfigDir, options) => {
+    const needsEnv = aliasConfigDir || options.configDir || options.env;
+    if (!needsEnv) {
+        return undefined;
+    }
+    const spawnEnv = { ...baseEnv };
+    if (aliasConfigDir) {
+        spawnEnv.CLAUDE_CONFIG_DIR = aliasConfigDir;
+    }
+    if (options.env) {
+        Object.assign(spawnEnv, options.env);
+    }
+    if (options.configDir) {
+        spawnEnv.CLAUDE_CONFIG_DIR = options.configDir;
+    }
+    return spawnEnv;
+};
 export const spawnClaude = (options) => {
     assertPositiveNumber(options.maxBudgetUsd, "maxBudgetUsd");
     const resolved = resolve();
     const args = buildArgs(options, resolved.binaryPath);
     try {
-        const needsEnv = resolved.aliasConfigDir || options.configDir || options.env;
-        let spawnEnv;
-        if (needsEnv) {
-            spawnEnv = { ...process.env };
-            if (options.env) {
-                Object.assign(spawnEnv, options.env);
-            }
-            if (resolved.aliasConfigDir) {
-                spawnEnv.CLAUDE_CONFIG_DIR = resolved.aliasConfigDir;
-            }
-            if (options.configDir) {
-                spawnEnv.CLAUDE_CONFIG_DIR = options.configDir;
-            }
-        }
+        const spawnEnv = buildSpawnEnv(process.env, resolved.aliasConfigDir, options);
         const rawProc = spawnProcess(args, { cwd: options.cwd, env: spawnEnv });
         rawProc.exited.catch(() => { });
+        // Tear the child down when the caller's signal aborts. Without this,
+        // a signal that fires BEFORE stdout emits anything leaves the reader
+        // loop to eventually notice -- the child keeps running in the meantime.
+        // Register FIRST, then re-check `aborted`: closes the gap where abort
+        // could fire between the check and listener attach. `once: true` lets
+        // the listener be GC'd after firing.
+        if (options.signal) {
+            const onAbort = () => {
+                safeKill(rawProc);
+            };
+            options.signal.addEventListener("abort", onAbort, { once: true });
+            if (options.signal.aborted) {
+                safeKill(rawProc);
+            }
+        }
         const claudeProc = {
             write: (msg) => {
                 rawProc.stdin.write(msg);
             },
-            kill: () => {
-                rawProc.kill();
+            kill: (signal) => {
+                rawProc.kill(signal);
             },
             exited: rawProc.exited,
             stdout: rawProc.stdout,

package/dist/reader.d.ts

@@ -2,12 +2,21 @@ import type { ITranslator } from "./parser/translator.js";
 import type { IClaudeProcess } from "./process.js";
 import type { IToolHandlerInstance } from "./tools/handler.js";
 import type { TRelayEvent } from "./types/events.js";
+import type { TWarn } from "./warnings.js";
 export interface IReaderOptions {
     reader: ReadableStreamDefaultReader<Uint8Array>;
     translator: ITranslator;
     toolHandler?: IToolHandlerInstance;
     proc?: IClaudeProcess;
     signal?: AbortSignal;
+    onWarning?: TWarn;
 }
+export interface IStderrDrain {
+    chunks: string[];
+    done: Promise<void>;
+    text: () => string;
+}
+export declare const drainStderr: (proc: {
+    stderr: ReadableStream<Uint8Array>;
+}) => IStderrDrain;
 export declare function readNdjsonEvents(opts: IReaderOptions): AsyncGenerator<TRelayEvent>;
-export type { TRelayEvent };

package/dist/reader.js

@@ -2,22 +2,89 @@ 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 = [];
+    const stderrReader = proc.stderr.getReader();
+    const decoder = new TextDecoder();
+    const done = (async () => {
+        try {
+            while (true) {
+                const { done: isDone, value } = await stderrReader.read();
+                if (isDone) {
+                    break;
+                }
+                chunks.push(decoder.decode(value, { stream: true }));
+            }
+        }
+        catch {
+            // process exited
+        }
+        finally {
+            // Flush any trailing partial multibyte sequence.
+            const tail = decoder.decode();
+            if (tail) {
+                chunks.push(tail);
+            }
+            stderrReader.releaseLock();
+        }
+    })().catch(() => { });
+    return {
+        chunks,
+        done,
+        text: () => chunks.join("").trim(),
+    };
+};
 export async function* readNdjsonEvents(opts) {
     const { reader, translator, signal } = opts;
     const decoder = new TextDecoder();
     let buffer = "";
     let timeoutId;
     let turnComplete = false;
+    let abortReject;
+    const abortPromise = new Promise((_, reject) => {
+        abortReject = reject;
+    });
+    // Swallow unhandled rejection if nothing ever races against this promise.
+    abortPromise.catch(() => { });
+    // 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);
+        }
+        timeoutId = setTimeout(() => {
+            timeoutReject?.(new TimeoutError(`No data received within ${TIMEOUTS.defaultAbortMs}ms`));
+        }, TIMEOUTS.defaultAbortMs);
+    };
     const abortHandler = signal
         ? () => {
+            abortReject?.(new AbortError());
             if (opts.proc) {
-                try {
-                    opts.proc.write('{"type":"abort"}\n');
-                }
-                catch {
-                    // stdin closed
-                }
-                opts.proc.kill();
+                safeWrite(opts.proc, writer.abort());
+                safeKill(opts.proc);
             }
         }
         : undefined;
@@ -32,20 +99,19 @@ export async function* readNdjsonEvents(opts) {
             if (signal?.aborted) {
                 throw new AbortError();
             }
-            const timeoutPromise = new Promise((_, reject) => {
-                timeoutId = setTimeout(() => {
-                    reject(new TimeoutError(`No data received within ${TIMEOUTS.defaultAbortMs}ms`));
-                }, TIMEOUTS.defaultAbortMs);
-            });
-            const readResult = await Promise.race([reader.read(), timeoutPromise]);
-            clearTimeout(timeoutId);
+            resetReadTimeout();
+            const readResult = await Promise.race([reader.read(), timeoutPromise, abortPromise]);
             const { done, value } = readResult;
             if (done) {
                 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() ?? "";
@@ -54,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;
@@ -72,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

@@ -1,6 +1,7 @@
 import { execFileSync, spawn as nodeSpawn } from "node:child_process";
 import { accessSync, constants, statSync } from "node:fs";
 import { Readable } from "node:stream";
+import { ProcessError } from "./errors.js";
 const isBun = typeof globalThis.Bun !== "undefined";
 export const spawnProcess = (args, opts) => {
     if (isBun) {
@@ -29,16 +30,10 @@ export const whichSync = (name) => {
         return undefined;
     }
 };
-export const fileExists = (path) => {
-    if (isBun) {
-        try {
-            accessSync(path, constants.X_OK);
-            return statSync(path).size > 0;
-        }
-        catch {
-            return false;
-        }
-    }
+// 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;
@@ -66,50 +61,27 @@ const spawnBun = (args, opts) => {
         },
         stdout: proc.stdout,
         stderr: proc.stderr,
-        kill: () => {
-            proc.kill();
+        kill: (signal) => {
+            proc.kill(signal);
         },
         exited: proc.exited,
         pid: proc.pid,
     };
 };
-const nodeReadableToWeb = (readable) => {
-    return new ReadableStream({
-        start(controller) {
-            let closed = false;
-            readable.on("data", (chunk) => {
-                if (!closed) {
-                    controller.enqueue(new Uint8Array(chunk));
-                }
-            });
-            readable.on("end", () => {
-                if (!closed) {
-                    closed = true;
-                    controller.close();
-                }
-            });
-            readable.on("error", (err) => {
-                if (!closed) {
-                    closed = true;
-                    controller.error(err);
-                }
-            });
-        },
-        cancel() {
-            readable.destroy();
-        },
-    });
-};
+const toWeb = (readable) => Readable.toWeb(readable);
 const spawnNode = (args, opts) => {
     const [cmd, ...rest] = args;
     if (!cmd) {
-        throw new Error("No command specified");
+        throw new ProcessError("No command specified");
     }
     const child = nodeSpawn(cmd, rest, {
         cwd: opts.cwd,
         stdio: ["pipe", "pipe", "pipe"],
         env: opts.env,
     });
+    if (child.pid === undefined) {
+        throw new ProcessError(`Failed to spawn ${cmd}: no PID assigned`);
+    }
     const exited = new Promise((resolve, reject) => {
         child.on("exit", (code) => {
             resolve(code ?? 1);
@@ -119,18 +91,21 @@ const spawnNode = (args, opts) => {
     return {
         stdin: {
             write: (data) => {
-                child.stdin?.write(data);
+                if (!child.stdin || child.stdin.destroyed) {
+                    throw new ProcessError("Cannot write: stdin is not writable");
+                }
+                child.stdin.write(data);
             },
             end: () => {
                 child.stdin?.end();
             },
         },
-        stdout: child.stdout ? nodeReadableToWeb(child.stdout) : new ReadableStream(),
-        stderr: child.stderr ? nodeReadableToWeb(child.stderr) : new ReadableStream(),
-        kill: () => {
-            child.kill();
+        stdout: child.stdout ? toWeb(child.stdout) : new ReadableStream(),
+        stderr: child.stderr ? toWeb(child.stderr) : new ReadableStream(),
+        kill: (signal) => {
+            child.kill(signal);
         },
         exited,
-        pid: child.pid ?? 0,
+        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;