@pivanov/claude-wire 0.0.2 → 0.0.4

package/dist/types/options.d.ts

@@ -1,20 +1,33 @@
 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>;
 }
 export interface IClaudeOptions {
     cwd?: string;
     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`
+     * and kills the process when `total_cost_usd` exceeds this value. `0` means
+     * "disallow any spend" (useful for tests).
+     */
     maxCostUsd?: number;
+    /**
+     * CLI-level budget forwarded as `--max-budget-usd`. Enforced by the Claude
+     * binary itself, independent of {@link IClaudeOptions.maxCostUsd}. Either
+     * can fire first; set both for belt-and-suspenders.
+     */
     maxBudgetUsd?: number;
     onCostUpdate?: (cost: TCostSnapshot) => void;
     signal?: AbortSignal;
@@ -34,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.2",
+  "version": "0.0.4",
   "description": "Run Claude Code programmatically. Typed SDK for spawning, streaming, and controlling the CLI.",
   "type": "module",
   "engines": {