myshell-tools 1.0.0 → 2.0.0

package/dist/providers/codex-parse.d.ts

@@ -0,0 +1,32 @@
+/**
+ * src/providers/codex-parse.ts — stateful JSONL parser for `codex exec --json`.
+ *
+ * STATEFUL MODULE: codex streams assistant text across multiple `agent_message`
+ * items and the final `turn.completed` event does NOT repeat the full text, so
+ * we accumulate text in a closure and surface the complete value in `done`.
+ *
+ * Pure in all other respects: no I/O, no execa, no side effects. The factory
+ * function `createCodexParser()` returns a closure that is hermetic and
+ * fixture-testable.
+ *
+ * Codex `codex exec --json` event schema (JSONL, one object per line):
+ *  - thread.started / turn.started      → emit nothing
+ *  - item.completed (agent_message)     → text event + accumulate to buffer
+ *  - item.completed (reasoning)         → reasoning event (if text present)
+ *  - item.completed (command_execution / file_change / mcp_tool_call) → tool event
+ *  - turn.completed                     → usage event + done event (no costUsd)
+ *  - turn.failed / error                → error event
+ *  - unknown / malformed JSON           → emit nothing (never throw)
+ */
+import type { ProviderEvent } from './port.js';
+/**
+ * Create a stateful parser for `codex exec --json` stdout.
+ *
+ * Returns a function that accepts one JSONL line at a time and returns 0 or
+ * more {@link ProviderEvent}s. The closure accumulates agent_message text so
+ * that `done.text` contains the full concatenated assistant reply.
+ *
+ * The returned parser never throws — malformed JSON or unknown event types
+ * silently return [].
+ */
+export declare function createCodexParser(): (line: string) => ProviderEvent[];

package/dist/providers/codex-parse.js

@@ -0,0 +1,145 @@
+/**
+ * src/providers/codex-parse.ts — stateful JSONL parser for `codex exec --json`.
+ *
+ * STATEFUL MODULE: codex streams assistant text across multiple `agent_message`
+ * items and the final `turn.completed` event does NOT repeat the full text, so
+ * we accumulate text in a closure and surface the complete value in `done`.
+ *
+ * Pure in all other respects: no I/O, no execa, no side effects. The factory
+ * function `createCodexParser()` returns a closure that is hermetic and
+ * fixture-testable.
+ *
+ * Codex `codex exec --json` event schema (JSONL, one object per line):
+ *  - thread.started / turn.started      → emit nothing
+ *  - item.completed (agent_message)     → text event + accumulate to buffer
+ *  - item.completed (reasoning)         → reasoning event (if text present)
+ *  - item.completed (command_execution / file_change / mcp_tool_call) → tool event
+ *  - turn.completed                     → usage event + done event (no costUsd)
+ *  - turn.failed / error                → error event
+ *  - unknown / malformed JSON           → emit nothing (never throw)
+ */
+import { classifyError } from './errors.js';
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function mapUsage(u) {
+    const base = {
+        inputTokens: u.input_tokens ?? 0,
+        outputTokens: u.output_tokens ?? 0,
+    };
+    // exactOptionalPropertyTypes: only include cachedInputTokens when it is a
+    // number — omit the key entirely otherwise.
+    if (typeof u.cached_input_tokens === 'number') {
+        return { ...base, cachedInputTokens: u.cached_input_tokens };
+    }
+    return base;
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Create a stateful parser for `codex exec --json` stdout.
+ *
+ * Returns a function that accepts one JSONL line at a time and returns 0 or
+ * more {@link ProviderEvent}s. The closure accumulates agent_message text so
+ * that `done.text` contains the full concatenated assistant reply.
+ *
+ * The returned parser never throws — malformed JSON or unknown event types
+ * silently return [].
+ */
+export function createCodexParser() {
+    let accumulatedText = '';
+    return function parseCodexLine(line) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            return [];
+        let parsed;
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch {
+            return [];
+        }
+        if (typeof parsed !== 'object' || parsed === null)
+            return [];
+        const obj = parsed;
+        const eventType = obj['type'];
+        // -----------------------------------------------------------------------
+        // thread.started / turn.started — emit nothing
+        // -----------------------------------------------------------------------
+        if (eventType === 'thread.started' || eventType === 'turn.started') {
+            return [];
+        }
+        // -----------------------------------------------------------------------
+        // item.completed — dispatch on item.type
+        // -----------------------------------------------------------------------
+        if (eventType === 'item.completed') {
+            const ev = parsed;
+            const item = ev.item;
+            if (typeof item !== 'object' || item === null)
+                return [];
+            const itemType = item.type;
+            if (itemType === 'agent_message') {
+                const msg = item;
+                const delta = typeof msg.text === 'string' ? msg.text : '';
+                accumulatedText += delta;
+                return [{ type: 'text', delta }];
+            }
+            if (itemType === 'reasoning') {
+                const r = item;
+                if (typeof r.text === 'string' && r.text.length > 0) {
+                    return [{ type: 'reasoning', delta: r.text }];
+                }
+                return [];
+            }
+            if (itemType === 'command_execution' ||
+                itemType === 'file_change' ||
+                itemType === 'mcp_tool_call') {
+                const act = item;
+                const toolEvent = typeof act.detail === 'string'
+                    ? { type: 'tool', name: itemType, phase: 'end', detail: act.detail }
+                    : { type: 'tool', name: itemType, phase: 'end' };
+                return [toolEvent];
+            }
+            // Unknown item type — emit nothing
+            return [];
+        }
+        // -----------------------------------------------------------------------
+        // turn.completed — emit usage + done (no costUsd)
+        // -----------------------------------------------------------------------
+        if (eventType === 'turn.completed') {
+            const ev = parsed;
+            const usage = ev.usage !== undefined && ev.usage !== null
+                ? mapUsage(ev.usage)
+                : { inputTokens: 0, outputTokens: 0 };
+            return [
+                { type: 'usage', usage },
+                {
+                    type: 'done',
+                    text: accumulatedText,
+                    usage,
+                    raw: parsed,
+                },
+            ];
+        }
+        // -----------------------------------------------------------------------
+        // turn.failed — emit error
+        // -----------------------------------------------------------------------
+        if (eventType === 'turn.failed') {
+            const ev = parsed;
+            const message = ev.error?.message ?? 'turn failed';
+            return [{ type: 'error', error: classifyError(message, 1) }];
+        }
+        // -----------------------------------------------------------------------
+        // error — emit error
+        // -----------------------------------------------------------------------
+        if (eventType === 'error') {
+            const ev = parsed;
+            const message = ev.message ?? 'unknown error';
+            return [{ type: 'error', error: classifyError(message, 1) }];
+        }
+        // Unknown event type — emit nothing
+        return [];
+    };
+}
+//# sourceMappingURL=codex-parse.js.map

package/dist/providers/codex-parse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codex-parse.js","sourceRoot":"","sources":["../../src/providers/codex-parse.ts"],"names":[],"mappings":"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"}

package/dist/providers/codex.d.ts

@@ -0,0 +1,44 @@
+/**
+ * src/providers/codex.ts — Codex CLI adapter implementing the Provider port.
+ *
+ * Spawns `codex exec --json -m <model> --sandbox <level>` via execa v9,
+ * delivers the prompt via STDIN (never as an argv argument), and streams
+ * parsed ProviderEvents to the caller as they arrive.
+ *
+ * Sandbox mapping:
+ *  read-only        → '--sandbox read-only'
+ *  workspace-write  → '--sandbox workspace-write'
+ *  full-access      → '--sandbox danger-full-access'
+ *
+ * Authentication note:
+ *  Auth state is OPTIMISTIC at detect() time — we cannot cheaply probe it.
+ *  The real auth state surfaces at run time: an unauthenticated run produces
+ *  a stderr/event that classifyError() maps to category 'auth'.
+ *
+ * costUsd note:
+ *  Codex does NOT report a USD cost. The `done` event therefore omits
+ *  `costUsd` entirely. The orchestrator will fall back to pricing-table
+ *  estimation from the usage tokens — this is the documented behaviour.
+ *
+ * Execa v9 streaming:
+ *  We use `for await (const line of subprocess)` which iterates over stdout
+ *  lines as strings. Confirmed from execa types: the subprocess IS an
+ *  AsyncIterable<string>.
+ */
+import type { Provider, SandboxLevel } from './port.js';
+/**
+ * Map the abstract {@link SandboxLevel} to the concrete `--sandbox` argument
+ * that the Codex CLI accepts.
+ *
+ * NEVER default to 'danger-full-access' — always require the caller to opt in
+ * explicitly by passing SandboxLevel 'full-access'.
+ */
+export declare function toSandboxArg(level: SandboxLevel): string;
+/**
+ * Create a Codex provider adapter.
+ *
+ * @param opts.bin - Override the binary name/path (default: `'codex'`).
+ */
+export declare function createCodexProvider(opts?: {
+    bin?: string;
+}): Provider;

package/dist/providers/codex.js

@@ -0,0 +1,124 @@
+/**
+ * src/providers/codex.ts — Codex CLI adapter implementing the Provider port.
+ *
+ * Spawns `codex exec --json -m <model> --sandbox <level>` via execa v9,
+ * delivers the prompt via STDIN (never as an argv argument), and streams
+ * parsed ProviderEvents to the caller as they arrive.
+ *
+ * Sandbox mapping:
+ *  read-only        → '--sandbox read-only'
+ *  workspace-write  → '--sandbox workspace-write'
+ *  full-access      → '--sandbox danger-full-access'
+ *
+ * Authentication note:
+ *  Auth state is OPTIMISTIC at detect() time — we cannot cheaply probe it.
+ *  The real auth state surfaces at run time: an unauthenticated run produces
+ *  a stderr/event that classifyError() maps to category 'auth'.
+ *
+ * costUsd note:
+ *  Codex does NOT report a USD cost. The `done` event therefore omits
+ *  `costUsd` entirely. The orchestrator will fall back to pricing-table
+ *  estimation from the usage tokens — this is the documented behaviour.
+ *
+ * Execa v9 streaming:
+ *  We use `for await (const line of subprocess)` which iterates over stdout
+ *  lines as strings. Confirmed from execa types: the subprocess IS an
+ *  AsyncIterable<string>.
+ */
+import { execa } from 'execa';
+import { detectProvider } from './detect.js';
+import { classifyError } from './errors.js';
+import { createCodexParser } from './codex-parse.js';
+// ---------------------------------------------------------------------------
+// Sandbox argument mapping
+// ---------------------------------------------------------------------------
+/**
+ * Map the abstract {@link SandboxLevel} to the concrete `--sandbox` argument
+ * that the Codex CLI accepts.
+ *
+ * NEVER default to 'danger-full-access' — always require the caller to opt in
+ * explicitly by passing SandboxLevel 'full-access'.
+ */
+export function toSandboxArg(level) {
+    switch (level) {
+        case 'read-only':
+            return 'read-only';
+        case 'workspace-write':
+            return 'workspace-write';
+        case 'full-access':
+            return 'danger-full-access';
+    }
+}
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+/**
+ * Create a Codex provider adapter.
+ *
+ * @param opts.bin - Override the binary name/path (default: `'codex'`).
+ */
+export function createCodexProvider(opts) {
+    const bin = opts?.bin ?? 'codex';
+    return {
+        id: 'codex',
+        detect() {
+            return detectProvider('codex');
+        },
+        async *run(req, signal) {
+            const args = [
+                'exec',
+                '--json',
+                '-m',
+                req.model,
+                '--sandbox',
+                toSandboxArg(req.sandbox),
+            ];
+            // Spawn with reject:false so we always get the result object (never throws).
+            // cancelSignal wires our AbortSignal directly to execa's termination path.
+            const subprocess = execa(bin, args, {
+                cwd: req.cwd,
+                input: req.prompt, // deliver prompt via STDIN, not argv
+                cancelSignal: signal,
+                timeout: req.timeoutMs,
+                reject: false,
+            });
+            // One parser instance per run — holds the accumulated text closure.
+            const parseCodexLine = createCodexParser();
+            let emittedTerminal = false;
+            // Stream stdout line by line.
+            // execa v9: the subprocess itself is an AsyncIterable that yields one
+            // string per stdout line (from types/subprocess/subprocess.d.ts).
+            try {
+                for await (const line of subprocess) {
+                    const events = parseCodexLine(line);
+                    for (const ev of events) {
+                        yield ev;
+                        if (ev.type === 'done' || ev.type === 'error') {
+                            emittedTerminal = true;
+                        }
+                    }
+                }
+            }
+            catch {
+                // Iteration errors (e.g. stream abort) are handled below via the result.
+            }
+            // Wait for the subprocess to fully exit and collect the result.
+            const result = await subprocess;
+            if (!emittedTerminal) {
+                if (result.isCanceled) {
+                    yield {
+                        type: 'error',
+                        error: classifyError('cancelled', 1),
+                    };
+                }
+                else if (result.failed || (result.exitCode !== undefined && result.exitCode !== 0)) {
+                    yield {
+                        type: 'error',
+                        error: classifyError(typeof result.stderr === 'string' ? result.stderr : '', result.exitCode ?? 1),
+                    };
+                }
+            }
+        },
+    };
+}
+//# sourceMappingURL=codex.js.map

package/dist/providers/codex.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codex.js","sourceRoot":"","sources":["../../src/providers/codex.ts"],"names":[],"mappings":"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"}

package/dist/providers/detect.d.ts

@@ -0,0 +1,49 @@
+/**
+ * src/providers/detect.ts
+ *
+ * Provider-detection logic.
+ *
+ * Claude detection is REAL: spawns `claude --version` to probe installation.
+ * Codex detection is REAL: spawns `codex --version` to probe installation.
+ * Authentication is OPTIMISTIC for both — we cannot cheaply probe auth state
+ * without spending API quota. The real auth state surfaces at run time and is
+ * classified by errors.ts (category 'auth').
+ */
+export interface ProviderStatus {
+    readonly id: 'claude' | 'codex';
+    readonly installed: boolean;
+    readonly version: string | null;
+    readonly authenticated: boolean;
+    readonly binaryPath: string | null;
+    readonly availableModels: readonly string[];
+}
+export interface EnvironmentStatus {
+    readonly claude: ProviderStatus;
+    readonly codex: ProviderStatus;
+    readonly hasAnyProvider: boolean;
+    readonly platform: NodeJS.Platform;
+}
+/**
+ * Detect whether a provider CLI is installed and (optimistically) usable.
+ *
+ * For 'claude': runs `claude --version` to confirm the binary is present and
+ * executable. Authentication is reported as `true` optimistically — we cannot
+ * cheaply probe auth state without spending API quota. If the user is not
+ * authenticated, the real auth failure surfaces at run time via classifyError()
+ * (category 'auth').
+ *
+ * For 'codex': runs `codex --version` to confirm the binary is present and
+ * executable. Authentication is reported as `true` optimistically for the same
+ * reason — real auth failures surface at run time via classifyError().
+ */
+export declare function detectProvider(id: 'claude' | 'codex'): Promise<ProviderStatus>;
+/**
+ * Detect the full environment — both providers — in parallel.
+ *
+ * Stub: delegates to detectProvider for each provider ID.
+ */
+export declare function detectEnvironment(): Promise<EnvironmentStatus>;
+/**
+ * Return the shell command a user should run to install the given provider.
+ */
+export declare function getInstallCommand(id: 'claude' | 'codex'): string;

package/dist/providers/detect.js

@@ -0,0 +1,125 @@
+/**
+ * src/providers/detect.ts
+ *
+ * Provider-detection logic.
+ *
+ * Claude detection is REAL: spawns `claude --version` to probe installation.
+ * Codex detection is REAL: spawns `codex --version` to probe installation.
+ * Authentication is OPTIMISTIC for both — we cannot cheaply probe auth state
+ * without spending API quota. The real auth state surfaces at run time and is
+ * classified by errors.ts (category 'auth').
+ */
+import { execa } from 'execa';
+// ---------------------------------------------------------------------------
+// Internal factory
+// ---------------------------------------------------------------------------
+function notDetected(id) {
+    return {
+        id,
+        installed: false,
+        version: null,
+        authenticated: false,
+        binaryPath: null,
+        availableModels: [],
+    };
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Detect whether a provider CLI is installed and (optimistically) usable.
+ *
+ * For 'claude': runs `claude --version` to confirm the binary is present and
+ * executable. Authentication is reported as `true` optimistically — we cannot
+ * cheaply probe auth state without spending API quota. If the user is not
+ * authenticated, the real auth failure surfaces at run time via classifyError()
+ * (category 'auth').
+ *
+ * For 'codex': runs `codex --version` to confirm the binary is present and
+ * executable. Authentication is reported as `true` optimistically for the same
+ * reason — real auth failures surface at run time via classifyError().
+ */
+export async function detectProvider(id) {
+    if (id === 'claude') {
+        try {
+            const result = await execa('claude', ['--version'], {
+                reject: false,
+                timeout: 10_000,
+            });
+            if (result.exitCode === 0) {
+                return {
+                    id: 'claude',
+                    installed: true,
+                    version: result.stdout.trim(),
+                    binaryPath: 'claude',
+                    availableModels: ['opus', 'sonnet', 'haiku'],
+                    /**
+                     * Authentication is OPTIMISTIC: we assume the user is authenticated
+                     * if the binary is installed. The real auth state surfaces at run
+                     * time when classifyError() maps an auth-related stderr to 'auth'.
+                     */
+                    authenticated: true,
+                };
+            }
+        }
+        catch {
+            // Binary not found or spawn error — fall through to notDetected
+        }
+        return notDetected('claude');
+    }
+    // codex: run `codex --version` to probe installation
+    try {
+        const result = await execa('codex', ['--version'], {
+            reject: false,
+            timeout: 10_000,
+        });
+        if (result.exitCode === 0) {
+            return {
+                id: 'codex',
+                installed: true,
+                version: result.stdout.trim(),
+                binaryPath: 'codex',
+                availableModels: ['gpt-5.5', 'gpt-5.4', 'gpt-5.4-mini'],
+                /**
+                 * Authentication is OPTIMISTIC: we assume the user is authenticated
+                 * if the binary is installed. The real auth state surfaces at run
+                 * time when classifyError() maps an auth-related stderr to 'auth'.
+                 */
+                authenticated: true,
+            };
+        }
+    }
+    catch {
+        // Binary not found or spawn error — fall through to notDetected
+    }
+    return notDetected('codex');
+}
+/**
+ * Detect the full environment — both providers — in parallel.
+ *
+ * Stub: delegates to detectProvider for each provider ID.
+ */
+export async function detectEnvironment() {
+    const [claude, codex] = await Promise.all([
+        detectProvider('claude'),
+        detectProvider('codex'),
+    ]);
+    return {
+        claude,
+        codex,
+        hasAnyProvider: claude.installed || codex.installed,
+        platform: process.platform,
+    };
+}
+/**
+ * Return the shell command a user should run to install the given provider.
+ */
+export function getInstallCommand(id) {
+    switch (id) {
+        case 'claude':
+            return 'npm install -g @anthropic-ai/claude-code';
+        case 'codex':
+            return 'npm install -g @openai/codex';
+    }
+}
+//# sourceMappingURL=detect.js.map

package/dist/providers/detect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect.js","sourceRoot":"","sources":["../../src/providers/detect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC;AAsB9B,8EAA8E;AAC9E,mBAAmB;AACnB,8EAA8E;AAE9E,SAAS,WAAW,CAAC,EAAsB;IACzC,OAAO;QACL,EAAE;QACF,SAAS,EAAE,KAAK;QAChB,OAAO,EAAE,IAAI;QACb,aAAa,EAAE,KAAK;QACpB,UAAU,EAAE,IAAI;QAChB,eAAe,EAAE,EAAE;KACpB,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,EAAsB;IAEtB,IAAI,EAAE,KAAK,QAAQ,EAAE,CAAC;QACpB,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,QAAQ,EAAE,CAAC,WAAW,CAAC,EAAE;gBAClD,MAAM,EAAE,KAAK;gBACb,OAAO,EAAE,MAAM;aAChB,CAAC,CAAC;YAEH,IAAI,MAAM,CAAC,QAAQ,KAAK,CAAC,EAAE,CAAC;gBAC1B,OAAO;oBACL,EAAE,EAAE,QAAQ;oBACZ,SAAS,EAAE,IAAI;oBACf,OAAO,EAAG,MAAM,CAAC,MAAiB,CAAC,IAAI,EAAE;oBACzC,UAAU,EAAE,QAAQ;oBACpB,eAAe,EAAE,CAAC,MAAM,EAAE,QAAQ,EAAE,OAAO,CAAC;oBAC5C;;;;uBAIG;oBACH,aAAa,EAAE,IAAI;iBACpB,CAAC;YACJ,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,gEAAgE;QAClE,CAAC;QAED,OAAO,WAAW,CAAC,QAAQ,CAAC,CAAC;IAC/B,CAAC;IAED,qDAAqD;IACrD,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,OAAO,EAAE,CAAC,WAAW,CAAC,EAAE;YACjD,MAAM,EAAE,KAAK;YACb,OAAO,EAAE,MAAM;SAChB,CAAC,CAAC;QAEH,IAAI,MAAM,CAAC,QAAQ,KAAK,CAAC,EAAE,CAAC;YAC1B,OAAO;gBACL,EAAE,EAAE,OAAO;gBACX,SAAS,EAAE,IAAI;gBACf,OAAO,EAAG,MAAM,CAAC,MAAiB,CAAC,IAAI,EAAE;gBACzC,UAAU,EAAE,OAAO;gBACnB,eAAe,EAAE,CAAC,SAAS,EAAE,SAAS,EAAE,cAAc,CAAC;gBACvD;;;;mBAIG;gBACH,aAAa,EAAE,IAAI;aACpB,CAAC;QACJ,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,gEAAgE;IAClE,CAAC;IAED,OAAO,WAAW,CAAC,OAAO,CAAC,CAAC;AAC9B,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB;IACrC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QACxC,cAAc,CAAC,QAAQ,CAAC;QACxB,cAAc,CAAC,OAAO,CAAC;KACxB,CAAC,CAAC;IAEH,OAAO;QACL,MAAM;QACN,KAAK;QACL,cAAc,EAAE,MAAM,CAAC,SAAS,IAAI,KAAK,CAAC,SAAS;QACnD,QAAQ,EAAE,OAAO,CAAC,QAAQ;KAC3B,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,EAAsB;IACtD,QAAQ,EAAE,EAAE,CAAC;QACX,KAAK,QAAQ;YACX,OAAO,0CAA0C,CAAC;QACpD,KAAK,OAAO;YACV,OAAO,8BAA8B,CAAC;IAC1C,CAAC;AACH,CAAC"}

package/dist/providers/errors.d.ts

@@ -0,0 +1,49 @@
+/**
+ * errors.ts — Error types, classification, backoff calculation, and message
+ * formatting for provider CLI operations.
+ *
+ * Pure module: no child_process, no fs, no console.log. All functions return
+ * data; callers decide how to display or act on it.
+ */
+export type ErrorCategory = 'auth' | 'rate-limit' | 'timeout' | 'network' | 'model' | 'permission' | 'unknown';
+export interface CliError {
+    category: ErrorCategory;
+    recoverable: boolean;
+    message: string;
+    suggestion: string;
+}
+export interface BackoffOptions {
+    /** Base delay in milliseconds for attempt 0. Defaults to 1000. */
+    baseMs?: number;
+    /** Multiplier applied each attempt. Defaults to 2. */
+    multiplier?: number;
+    /** Maximum delay in milliseconds. Defaults to 30_000. */
+    maxMs?: number;
+    /** Jitter fraction (0–1) applied as random ±fraction of the computed delay. Defaults to 0.15. */
+    jitter?: number;
+}
+/**
+ * Calculate how long to wait before the next retry attempt.
+ *
+ * Returns a value in milliseconds. With jitter the actual value will be within
+ * `[(1 - jitter) * delay, (1 + jitter) * delay]` where `delay` is the pure
+ * exponential value capped at `maxMs`.
+ *
+ * @param attempt - Zero-based attempt index (0 = first retry).
+ */
+export declare function calculateBackoff(attempt: number, opts?: BackoffOptions): number;
+/**
+ * Classify a CLI failure into a structured {@link CliError}.
+ *
+ * @param stderr   - The stderr output from the CLI process (may be empty).
+ * @param exitCode - The numeric exit code of the process.
+ */
+export declare function classifyError(stderr: string, exitCode: number): CliError;
+/**
+ * Format a {@link CliError} into a human-readable string suitable for display.
+ * Does not include ANSI codes so it works in any context.
+ *
+ * @param error    - A classified CLI error.
+ * @param provider - Optional provider name for contextual detail (e.g. `'claude'`).
+ */
+export declare function formatErrorMessage(error: CliError, provider?: string): string;