@pivanov/claude-wire 0.0.3 → 0.0.4

package/dist/stream.js

@@ -1,68 +1,99 @@
+import { withTimeout } from "./async.js";
+import { TIMEOUTS } from "./constants.js";
 import { createCostTracker } from "./cost.js";
-import { AbortError, ClaudeError, ProcessError } from "./errors.js";
+import { AbortError, ClaudeError, ProcessError, processExitedEarly } from "./errors.js";
 import { createTranslator } from "./parser/translator.js";
-import { buildResult, extractText } from "./pipeline.js";
-import { spawnClaude } from "./process.js";
-import { drainStderr, readNdjsonEvents } from "./reader.js";
+import { applyTurnComplete, buildResult, extractText, startPipeline } from "./pipeline.js";
+import { readNdjsonEvents } from "./reader.js";
 import { createToolHandler } from "./tools/handler.js";
+// Enforced exclusivity between iterating the stream and consuming via
+// text()/cost()/result(). Sharing the base message keeps the two throw
+// sites from drifting apart over time.
+const MIX_ITER_CONSUME = "Cannot mix for-await iteration with text()/cost()/result() on the same stream -- use one or the other.";
 export const createStream = (prompt, options = {}) => {
-    if (options.signal?.aborted) {
-        throw new AbortError();
-    }
+    // Abort check happens inside `ensureSpawned` -- at factory time we only
+    // capture config. A pre-aborted signal surfaces on the first access
+    // (iterate / text / cost / result), which is when spawn would happen.
     const translator = createTranslator();
     const toolHandler = options.tools ? createToolHandler(options.tools) : undefined;
     const costTracker = createCostTracker({
         maxCostUsd: options.maxCostUsd,
         onCostUpdate: options.onCostUpdate,
+        onWarning: options.onWarning,
     });
     let proc;
     let stderr;
+    let stdoutReader;
     let cachedGenerator;
     const ensureSpawned = () => {
         if (!proc) {
             if (options.signal?.aborted) {
                 throw new AbortError();
             }
-            proc = spawnClaude({ prompt, ...options });
-            stderr = drainStderr(proc);
+            // Shared boot: spawnClaude → getReader → drainStderr in one call.
+            // Matches session.ts so future refactors can't let the two drift.
+            const pipeline = startPipeline({ prompt, ...options });
+            proc = pipeline.proc;
+            stdoutReader = pipeline.reader;
+            stderr = pipeline.stderr;
         }
         return proc;
     };
     const generate = async function* () {
         const p = ensureSpawned();
-        const stdoutReader = p.stdout.getReader();
+        // ensureSpawned always populates stdoutReader alongside proc. Typed
+        // assertion so consumers can treat it as non-null below.
+        const currentReader = stdoutReader;
         let turnComplete = false;
         try {
             for await (const event of readNdjsonEvents({
-                reader: stdoutReader,
+                reader: currentReader,
                 translator,
                 toolHandler,
                 proc: p,
                 signal: options.signal,
+                onWarning: options.onWarning,
             })) {
                 if (event.type === "turn_complete") {
-                    costTracker.update(event.costUsd ?? 0, event.inputTokens ?? 0, event.outputTokens ?? 0);
-                    costTracker.checkBudget();
+                    applyTurnComplete(event, costTracker);
                     turnComplete = true;
                 }
                 yield event;
             }
             if (!turnComplete) {
-                const exitCode = await p.exited;
+                // Don't wait forever on p.exited -- a stuck child that never closes
+                // stdout would hang the generator. Cap at gracefulExitMs, then
+                // force-kill so cleanup() isn't left waiting too.
+                const exitCode = await withTimeout(p.exited, TIMEOUTS.gracefulExitMs);
+                if (exitCode === undefined) {
+                    p.kill();
+                }
+                // Give stderr a brief chance to drain so the thrown error carries
+                // the CLI's actual complaint instead of an empty string. Uniform
+                // across all three branches below so users never get "no context".
+                if (stderr) {
+                    await withTimeout(stderr.done, TIMEOUTS.stderrDrainGraceMs);
+                }
+                const stderrText = stderr ? stderr.text() : "";
+                if (exitCode === undefined) {
+                    throw processExitedEarly(stderrText);
+                }
                 if (exitCode !== 0) {
-                    if (stderr) {
-                        await stderr.done;
-                    }
-                    const stderrText = stderr ? stderr.chunks.join("").trim() : "";
                     const exitMsg = stderrText || `Claude process exited with code ${exitCode}`;
                     throw new ProcessError(exitMsg, exitCode);
                 }
-                throw new ProcessError("Process exited without completing the turn");
+                throw processExitedEarly(stderrText);
             }
         }
         finally {
-            stdoutReader.releaseLock();
+            currentReader.releaseLock();
             p.kill();
+            // Let stderr catch up so any trailing lines aren't silently dropped --
+            // session's error path does the same via withTimeout. Capped so a
+            // stuck drain can't hold up consumer cleanup.
+            if (stderr) {
+                await withTimeout(stderr.done, TIMEOUTS.stderrDrainGraceMs);
+            }
         }
     };
     const bufferedEvents = [];
@@ -70,7 +101,7 @@ export const createStream = (prompt, options = {}) => {
     const ensureConsumed = () => {
         if (!consumePromise) {
             if (cachedGenerator) {
-                throw new ClaudeError("Cannot call text()/cost()/result() after iterating with for-await. Use one or the other.");
+                throw new ClaudeError(MIX_ITER_CONSUME);
             }
             const gen = generate();
             cachedGenerator = gen;
@@ -96,9 +127,13 @@ export const createStream = (prompt, options = {}) => {
         return buildResult(bufferedEvents, costTracker, sessionId);
     };
     const cleanup = () => {
-        // Always kill if a proc was ever spawned — the generator's finally may not
-        // have run yet (e.g., iterator created but never ticked). Redundant kill
-        // on an already-exited process is a harmless ESRCH.
+        // One-shot kill: streams are single-turn, so unlike session.gracefulKill
+        // there's no second ask() to worry about leaving the child stranded for.
+        // SIGTERM is sufficient -- a stuck child would be the CLI's bug, and we
+        // wouldn't gain anything by blocking cleanup() on a SIGKILL escalation.
+        // Always kill if a proc was ever spawned -- the generator's finally may
+        // not have run yet (e.g., iterator created but never ticked). Redundant
+        // kill on an already-exited process is a harmless ESRCH.
         if (proc) {
             proc.kill();
         }
@@ -106,7 +141,7 @@ export const createStream = (prompt, options = {}) => {
     return {
         [Symbol.asyncIterator]: () => {
             if (consumePromise) {
-                throw new ClaudeError("Cannot iterate after calling text()/cost()/result(). Use one or the other.");
+                throw new ClaudeError(MIX_ITER_CONSUME);
             }
             cachedGenerator ??= generate();
             return cachedGenerator;

package/dist/tools/handler.d.ts

@@ -2,6 +2,7 @@ import type { TToolUseEvent } from "../types/events.js";
 import type { IToolHandler } from "../types/options.js";
 export type TToolDecision = "approve" | "deny" | {
     result: string;
+    isError?: boolean;
 };
 export interface IToolHandlerInstance {
     decide: (tool: TToolUseEvent) => Promise<TToolDecision>;

package/dist/tools/registry.d.ts

@@ -1,2 +1,4 @@
-export declare const BUILT_IN_TOOLS: Set<string>;
-export declare const isBuiltInTool: (name: string) => boolean;
+export declare const BUILT_IN_TOOL_NAMES: readonly ["Read", "Write", "Edit", "Bash", "Glob", "Grep", "Agent", "NotebookEdit", "WebFetch", "WebSearch", "TaskCreate", "TaskUpdate", "TaskGet", "TaskList", "TaskStop", "TaskOutput", "ToolSearch", "Monitor", "EnterPlanMode", "ExitPlanMode", "SendMessage", "LSP", "AskUserQuestion", "Skill", "CronCreate", "CronDelete", "CronList", "RemoteTrigger", "TeamCreate", "TeamDelete", "EnterWorktree", "ExitWorktree", "ScheduleWakeup"];
+export type TBuiltInToolName = (typeof BUILT_IN_TOOL_NAMES)[number];
+export declare const BUILT_IN_TOOLS: ReadonlySet<TBuiltInToolName>;
+export declare const isBuiltInTool: (name: string) => name is TBuiltInToolName;

package/dist/tools/registry.js

@@ -1,6 +1,10 @@
 // Best-effort snapshot of known Claude Code tools. May not be exhaustive.
 // For the authoritative list, check session_meta.tools from a live session.
-export const BUILT_IN_TOOLS = new Set([
+//
+// Declared as a literal tuple so `TBuiltInToolName` is the exact union of
+// known names -- lets callers narrow `allowedTools` / `disallowedTools`
+// arrays at compile time instead of accepting any string[].
+export const BUILT_IN_TOOL_NAMES = [
     "Read",
     "Write",
     "Edit",
@@ -11,8 +15,6 @@ export const BUILT_IN_TOOLS = new Set([
     "NotebookEdit",
     "WebFetch",
     "WebSearch",
-    "TodoRead",
-    "TodoWrite",
     "TaskCreate",
     "TaskUpdate",
     "TaskGet",
@@ -36,7 +38,8 @@ export const BUILT_IN_TOOLS = new Set([
     "EnterWorktree",
     "ExitWorktree",
     "ScheduleWakeup",
-]);
+];
+export const BUILT_IN_TOOLS = new Set(BUILT_IN_TOOL_NAMES);
 export const isBuiltInTool = (name) => {
     return BUILT_IN_TOOLS.has(name);
 };

package/dist/types/options.d.ts

@@ -1,9 +1,11 @@
 import type { TToolDecision } from "../tools/handler.js";
+import type { TBuiltInToolName } from "../tools/registry.js";
 import type { TToolUseEvent } from "./events.js";
 import type { TCostSnapshot } from "./results.js";
+export type TToolName = TBuiltInToolName | (string & {});
 export interface IToolHandler {
-    allowed?: string[];
-    blocked?: string[];
+    allowed?: TToolName[];
+    blocked?: TToolName[];
     onToolUse?: (tool: TToolUseEvent) => Promise<TToolDecision>;
     onError?: (error: unknown, tool: TToolUseEvent) => TToolDecision | Promise<TToolDecision>;
 }
@@ -12,8 +14,8 @@ export interface IClaudeOptions {
     model?: "opus" | "sonnet" | "haiku" | (string & {});
     systemPrompt?: string;
     appendSystemPrompt?: string;
-    allowedTools?: string[];
-    disallowedTools?: string[];
+    allowedTools?: TToolName[];
+    disallowedTools?: TToolName[];
     tools?: IToolHandler;
     /**
      * SDK-side budget limit, evaluated after each turn. Throws `BudgetExceededError`
@@ -45,8 +47,43 @@ export interface IClaudeOptions {
     forkSession?: boolean;
     noSessionPersistence?: boolean;
     sessionId?: string;
-    settingSources?: string;
+    settingSources?: "project" | "user" | "local" | "all" | "" | (string & {});
     disableSlashCommands?: boolean;
+    /**
+     * Called for every library-emitted warning (user-callback threw, malformed
+     * tool decision, etc.). Set this to route warnings to your telemetry or
+     * silence them with `() => {}`. When omitted, warnings go to `console.warn`
+     * prefixed with `[claude-wire]`.
+     */
+    onWarning?: (message: string, cause?: unknown) => void;
 }
 export interface ISessionOptions extends IClaudeOptions {
+    /**
+     * Fires each time a transient failure triggers a respawn inside a single
+     * `ask()`. `attempt` is 1-indexed. The error is the one that caused the
+     * retry (e.g. `ProcessError` with a SIGKILL exit code). Use this to
+     * surface retry activity in UI/telemetry; the SDK still handles the retry.
+     *
+     * Can also be passed per-ask via `session.ask(prompt, { onRetry })` for
+     * request-scoped correlation. Both fire if both are set.
+     */
+    onRetry?: (attempt: number, error: unknown) => void;
+}
+/**
+ * Per-ask options passed to `session.ask(prompt, options?)`. Override or
+ * supplement session-level callbacks for a single call -- useful for
+ * request-scoped logging/correlation in daemon-style consumers.
+ */
+export interface IAskOptions {
+    /**
+     * Per-ask retry observer. Fires alongside the session-level `onRetry` when
+     * both are set, so callers can attach request-scoped context (request id,
+     * trace span, user id) without reaching outside the callback.
+     */
+    onRetry?: (attempt: number, error: unknown) => void;
+    /**
+     * Per-ask abort signal. Aborts this ask only (the session stays alive).
+     * Composes with the session-level `signal` -- either firing aborts the ask.
+     */
+    signal?: AbortSignal;
 }

package/dist/types/protocol.d.ts

@@ -3,7 +3,7 @@ export type TModelUsageEntry = {
     outputTokens: number;
     cacheReadInputTokens?: number;
     cacheCreationInputTokens?: number;
-    contextWindow: number;
+    contextWindow?: number;
 };
 export type TClaudeContentType = "text" | "thinking" | "tool_use" | "tool_result" | (string & {});
 export type TClaudeContent = {
@@ -32,11 +32,7 @@ export type TClaudeEvent = {
     model?: string;
     tools?: string[];
     duration_ms?: number;
-    duration_api_ms?: number;
-    cost_usd?: number;
     total_cost_usd?: number;
     is_error?: boolean;
-    num_turns?: number;
     modelUsage?: Record<string, TModelUsageEntry>;
-    usage?: unknown;
 };

package/dist/validation.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Rejects non-finite values and negatives. Zero is intentionally allowed
+ * so callers can express "disallow any spend" (useful in tests).
+ */
+export declare const assertPositiveNumber: (value: number | undefined, name: string) => void;
+/**
+ * Rejects empty strings. Used on writer payloads where an empty value
+ * would produce a malformed JSON line on the CLI's stdin.
+ */
+export declare const requireNonEmpty: (value: string, name: string) => void;

package/dist/validation.js

@@ -0,0 +1,23 @@
+import { ClaudeError } from "./errors.js";
+// Boundary validators -- throw ClaudeError with a stable message shape so
+// callers (SDK tests, consumer apps) can pattern-match on field name.
+// Both helpers are cheap; performance-sensitive paths should still prefer
+// type-level guards, but runtime checks catch undeclared-undefined drift.
+/**
+ * Rejects non-finite values and negatives. Zero is intentionally allowed
+ * so callers can express "disallow any spend" (useful in tests).
+ */
+export const assertPositiveNumber = (value, name) => {
+    if (value !== undefined && (!Number.isFinite(value) || value < 0)) {
+        throw new ClaudeError(`${name} must be a finite non-negative number`);
+    }
+};
+/**
+ * Rejects empty strings. Used on writer payloads where an empty value
+ * would produce a malformed JSON line on the CLI's stdin.
+ */
+export const requireNonEmpty = (value, name) => {
+    if (!value) {
+        throw new ClaudeError(`${name} must be a non-empty string`);
+    }
+};

package/dist/warnings.d.ts

@@ -0,0 +1,2 @@
+export type TWarn = (message: string, cause?: unknown) => void;
+export declare const createWarn: (onWarning?: TWarn) => TWarn;

package/dist/warnings.js

@@ -0,0 +1,24 @@
+// One-line library-warning emitter. Consumers set `onWarning` on
+// IClaudeOptions to route warnings anywhere; when unset we fall back to
+// `console.warn` so behavior is unchanged for casual users.
+const DEFAULT = (message, cause) => {
+    if (cause === undefined) {
+        console.warn(`[claude-wire] ${message}`);
+    }
+    else {
+        console.warn(`[claude-wire] ${message}`, cause);
+    }
+};
+export const createWarn = (onWarning) => {
+    return onWarning
+        ? (message, cause) => {
+            try {
+                onWarning(message, cause);
+            }
+            catch {
+                // A user hook that itself throws shouldn't take down the stream.
+                DEFAULT(message, cause);
+            }
+        }
+        : DEFAULT;
+};

package/dist/writer.d.ts

@@ -2,6 +2,15 @@ export declare const writer: {
     user: (content: string) => string;
     approve: (toolUseId: string) => string;
     deny: (toolUseId: string) => string;
-    toolResult: (toolUseId: string, content: string) => string;
+    /**
+     * Send a tool result in response to a `tool_use` event. Pass
+     * `{ isError: true }` to mark the result as a tool-side error -- the model
+     * will see it as an error and can react (retry, apologize, pick another
+     * tool) rather than treating it as success. The protocol supports the
+     * flag natively; without it, results are assumed successful.
+     */
+    toolResult: (toolUseId: string, content: string, options?: {
+        isError?: boolean;
+    }) => string;
     abort: () => string;
 };

package/dist/writer.js

@@ -1,10 +1,5 @@
-import { ClaudeError } from "./errors.js";
+import { requireNonEmpty } from "./validation.js";
 const ABORT_LINE = `${JSON.stringify({ type: "abort" })}\n`;
-const requireNonEmpty = (value, name) => {
-    if (!value) {
-        throw new ClaudeError(`${name} must be a non-empty string`);
-    }
-};
 export const writer = {
     user: (content) => {
         requireNonEmpty(content, "content");
@@ -18,9 +13,20 @@ export const writer = {
         requireNonEmpty(toolUseId, "toolUseId");
         return `${JSON.stringify({ type: "deny", tool_use_id: toolUseId })}\n`;
     },
-    toolResult: (toolUseId, content) => {
+    /**
+     * Send a tool result in response to a `tool_use` event. Pass
+     * `{ isError: true }` to mark the result as a tool-side error -- the model
+     * will see it as an error and can react (retry, apologize, pick another
+     * tool) rather than treating it as success. The protocol supports the
+     * flag natively; without it, results are assumed successful.
+     */
+    toolResult: (toolUseId, content, options) => {
         requireNonEmpty(toolUseId, "toolUseId");
-        return `${JSON.stringify({ type: "tool_result", tool_use_id: toolUseId, content })}\n`;
+        const payload = { type: "tool_result", tool_use_id: toolUseId, content };
+        if (options?.isError) {
+            payload.is_error = true;
+        }
+        return `${JSON.stringify(payload)}\n`;
     },
     abort: () => ABORT_LINE,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pivanov/claude-wire",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "description": "Run Claude Code programmatically. Typed SDK for spawning, streaming, and controlling the CLI.",
   "type": "module",
   "engines": {