@pivanov/claude-wire 0.0.3 → 0.1.0

package/dist/process.d.ts

@@ -1,7 +1,7 @@
 import type { IClaudeOptions } from "./types/options.js";
 export interface IClaudeProcess {
     write: (message: string) => void;
-    kill: () => void;
+    kill: (signal?: NodeJS.Signals | number) => void;
     exited: Promise<number>;
     stdout: ReadableStream<Uint8Array>;
     stderr: ReadableStream<Uint8Array>;
@@ -10,8 +10,20 @@ export interface IClaudeProcess {
 export interface ISpawnOptions extends IClaudeOptions {
     prompt?: string;
 }
+export declare const safeKill: (proc: Pick<IClaudeProcess, "kill">, signal?: NodeJS.Signals | number) => void;
+export declare const safeWrite: (proc: Pick<IClaudeProcess, "write">, line: string) => boolean;
 export declare const ALIAS_PATTERN: RegExp;
-export declare const resolveConfigDirFromAlias: () => string | undefined;
-export declare const resetBinaryCache: () => void;
+/**
+ * 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 declare const resetResolvedEnvCache: () => void;
 export declare const buildArgs: (options: ISpawnOptions, binaryPath: string) => string[];
+export declare const buildSpawnEnv: (baseEnv: Record<string, string | undefined>, aliasConfigDir: string | undefined, options: Pick<ISpawnOptions, "configDir" | "env">) => Record<string, string | undefined> | undefined;
 export declare const spawnClaude: (options: ISpawnOptions) => IClaudeProcess;

package/dist/process.js

@@ -2,16 +2,41 @@ 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;
         }
     }
@@ -20,9 +45,12 @@ const resolveBinaryPath = () => {
 // 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;
-export const resolveConfigDirFromAlias = () => {
+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");
@@ -38,7 +66,17 @@ export 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 = () => {
@@ -62,6 +100,9 @@ export const buildArgs = (options, binaryPath) => {
             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");
@@ -103,36 +144,56 @@ export const buildArgs = (options, binaryPath) => {
     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) {
-            // Priority (lowest → highest): process.env < alias-detected config <
-            // user's explicit `options.env` < explicit `options.configDir`. User
-            // input always outranks the alias heuristic.
-            spawnEnv = { ...process.env };
-            if (resolved.aliasConfigDir) {
-                spawnEnv.CLAUDE_CONFIG_DIR = resolved.aliasConfigDir;
-            }
-            if (options.env) {
-                Object.assign(spawnEnv, options.env);
-            }
-            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,16 +2,19 @@ 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>;

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,37 @@
-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>;
+    askJson: <T>(prompt: string, schema: import("./json.js").TSchemaInput<T>, options?: IAskOptions) => Promise<import("./json.js").IJsonResult<T>>;
     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;