myshell-tools 1.0.0 → 2.0.0-alpha.0

package/dist/infra/session.d.ts

@@ -0,0 +1,28 @@
+/**
+ * src/infra/session.ts — SessionWriter implementation and session reader.
+ *
+ * Sessions are persisted as JSONL files under `.myshell-tools/sessions/current.jsonl`.
+ * Each call to `append` writes a single line atomically using `atomicAppendJSONL`.
+ * `readSession` re-hydrates a session from the JSONL file, skipping any malformed
+ * lines so a partial write can never break a resume.
+ */
+import type { SessionEntry, SessionWriter } from '../core/types.js';
+/**
+ * Create a SessionWriter for the given working directory and session id.
+ *
+ * @param opts.cwd - The project working directory (parent of `.myshell-tools/`).
+ * @param opts.id  - A unique session identifier (typically a UUID).
+ */
+export declare function createSessionWriter(opts: {
+    cwd: string;
+    id: string;
+}): SessionWriter;
+/**
+ * Read all SessionEntry records from the current session JSONL file.
+ *
+ * Returns an empty array if the file does not exist. Malformed lines (e.g.
+ * caused by a partial write) are silently skipped.
+ *
+ * @param cwd - The project working directory.
+ */
+export declare function readSession(cwd: string): Promise<SessionEntry[]>;

package/dist/infra/session.js

@@ -0,0 +1,61 @@
+/**
+ * src/infra/session.ts — SessionWriter implementation and session reader.
+ *
+ * Sessions are persisted as JSONL files under `.myshell-tools/sessions/current.jsonl`.
+ * Each call to `append` writes a single line atomically using `atomicAppendJSONL`.
+ * `readSession` re-hydrates a session from the JSONL file, skipping any malformed
+ * lines so a partial write can never break a resume.
+ */
+import { mkdir, readFile } from 'node:fs/promises';
+import { atomicAppendJSONL } from './atomic.js';
+import { getSessionsDir, getSessionFile } from './paths.js';
+/**
+ * Create a SessionWriter for the given working directory and session id.
+ *
+ * @param opts.cwd - The project working directory (parent of `.myshell-tools/`).
+ * @param opts.id  - A unique session identifier (typically a UUID).
+ */
+export function createSessionWriter(opts) {
+    const { cwd, id } = opts;
+    return {
+        id,
+        async append(entry) {
+            await mkdir(getSessionsDir(cwd), { recursive: true });
+            await atomicAppendJSONL(getSessionFile(cwd), entry);
+        },
+    };
+}
+/**
+ * Read all SessionEntry records from the current session JSONL file.
+ *
+ * Returns an empty array if the file does not exist. Malformed lines (e.g.
+ * caused by a partial write) are silently skipped.
+ *
+ * @param cwd - The project working directory.
+ */
+export async function readSession(cwd) {
+    let raw;
+    try {
+        raw = await readFile(getSessionFile(cwd), 'utf8');
+    }
+    catch (err) {
+        const nodeErr = err;
+        if (nodeErr.code === 'ENOENT')
+            return [];
+        throw err;
+    }
+    const entries = [];
+    for (const line of raw.split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0)
+            continue;
+        try {
+            entries.push(JSON.parse(trimmed));
+        }
+        catch {
+            // Skip malformed lines
+        }
+    }
+    return entries;
+}
+//# sourceMappingURL=session.js.map

package/dist/infra/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../src/infra/session.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAEnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE5D;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAiC;IACnE,MAAM,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,IAAI,CAAC;IAEzB,OAAO;QACL,EAAE;QAEF,KAAK,CAAC,MAAM,CAAC,KAAmB;YAC9B,MAAM,KAAK,CAAC,cAAc,CAAC,GAAG,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YACtD,MAAM,iBAAiB,CAAC,cAAc,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC;QACtD,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,GAAW;IAC3C,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,QAAQ,CAAC,cAAc,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC;IACpD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,OAAO,GAAG,GAA4B,CAAC;QAC7C,IAAI,OAAO,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,EAAE,CAAC;QACzC,MAAM,GAAG,CAAC;IACZ,CAAC;IAED,MAAM,OAAO,GAAmB,EAAE,CAAC;IACnC,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACnC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QAC5B,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,SAAS;QACnC,IAAI,CAAC;YACH,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAiB,CAAC,CAAC;QACpD,CAAC;QAAC,MAAM,CAAC;YACP,uBAAuB;QACzB,CAAC;IACH,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/interface/render.d.ts

@@ -0,0 +1,27 @@
+/**
+ * src/interface/render.ts — Human-readable event stream renderer.
+ *
+ * Consumes the AsyncIterable<CoreEvent> produced by orchestrate() and writes
+ * a clean, truthful transcript to an OutputSink. All displayed values come
+ * directly from CoreEvent data — no fabricated metrics, no hardcoded strings.
+ *
+ * Honesty Contract: confidence is rendered as a computed percentage or the
+ * literal word "unrated" when null. No digit-% literals appear in this file.
+ */
+import type { CoreEvent } from '../core/types.js';
+export interface OutputSink {
+    write(s: string): void;
+    readonly color: boolean;
+    readonly isTty: boolean;
+}
+/**
+ * Iterate events from orchestrate() and write a human-readable, truthful
+ * transcript to the OutputSink. Returns the success flag and the final event
+ * once the stream is exhausted.
+ */
+export declare function renderStream(events: AsyncIterable<CoreEvent>, out: OutputSink): Promise<{
+    success: boolean;
+    final?: Extract<CoreEvent, {
+        type: 'final';
+    }>;
+}>;

package/dist/interface/render.js

@@ -0,0 +1,134 @@
+/**
+ * src/interface/render.ts — Human-readable event stream renderer.
+ *
+ * Consumes the AsyncIterable<CoreEvent> produced by orchestrate() and writes
+ * a clean, truthful transcript to an OutputSink. All displayed values come
+ * directly from CoreEvent data — no fabricated metrics, no hardcoded strings.
+ *
+ * Honesty Contract: confidence is rendered as a computed percentage or the
+ * literal word "unrated" when null. No digit-% literals appear in this file.
+ */
+import { bold, cyan, dim, green, red, yellow } from '../ui/theme.js';
+import { createSpinner } from '../ui/spinner.js';
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/**
+ * Render a confidence value as a computed percentage string or 'unrated'.
+ * No digit-% literal is used here — the percentage is always interpolated
+ * from the real numeric value.
+ */
+function renderConfidence(confidence, color) {
+    if (confidence === null)
+        return dim('unrated', color);
+    const pct = Math.round(confidence * 100);
+    const str = `${pct}%`;
+    if (pct >= 80)
+        return green(str, color);
+    if (pct >= 50)
+        return yellow(str, color);
+    return red(str, color);
+}
+// ---------------------------------------------------------------------------
+// renderStream
+// ---------------------------------------------------------------------------
+/**
+ * Iterate events from orchestrate() and write a human-readable, truthful
+ * transcript to the OutputSink. Returns the success flag and the final event
+ * once the stream is exhausted.
+ */
+export async function renderStream(events, out) {
+    const c = out.color;
+    let finalEvent;
+    // Spinner is only used in TTY mode; we create one per tier-start and stop it
+    // when the first real output arrives or when tier-done fires.
+    const spinner = createSpinner(out);
+    let spinnerActive = false;
+    function stopSpinner() {
+        if (spinnerActive) {
+            spinner.stop();
+            spinnerActive = false;
+        }
+    }
+    for await (const ev of events) {
+        switch (ev.type) {
+            case 'classified': {
+                const cl = ev.classification;
+                out.write(cyan(`Classified: ${cl.tier} tier, ${cl.risk} risk`, c) +
+                    ` — ${cl.rationale}\n`);
+                break;
+            }
+            case 'tier-start': {
+                out.write(bold(`▶ ${ev.tier.toUpperCase()} (${ev.provider}/${ev.model}) attempt ${ev.attempt}`, c) +
+                    `\n`);
+                // Start spinner while waiting for the first provider output.
+                if (out.isTty) {
+                    spinner.start(`${ev.tier.toUpperCase()} (${ev.provider}/${ev.model}) working…`);
+                    spinnerActive = true;
+                }
+                break;
+            }
+            case 'provider-event': {
+                const pe = ev.event;
+                if (pe.type === 'text') {
+                    // First real output — clear the spinner line.
+                    stopSpinner();
+                    // Stream the real model output verbatim.
+                    out.write(pe.delta);
+                }
+                else if (pe.type === 'tool') {
+                    stopSpinner();
+                    out.write(dim(`[tool] ${pe.name} ${pe.phase}`, c) + `\n`);
+                }
+                else if (pe.type === 'reasoning') {
+                    stopSpinner();
+                    out.write(dim(pe.delta, c));
+                }
+                // 'usage', 'done', 'error' are handled via tier-done / final
+                break;
+            }
+            case 'tier-done': {
+                stopSpinner();
+                const confidenceStr = renderConfidence(ev.confidence, c);
+                const costStr = `$${ev.costUsd.toFixed(4)}`;
+                const successMark = ev.success ? green('✓', c) : red('✗', c);
+                out.write(`\n${successMark} ${bold('tier done', c)} — ` +
+                    `confidence: ${confidenceStr}, ` +
+                    `cost: ${costStr}, ` +
+                    `duration: ${ev.durationMs}ms\n`);
+                break;
+            }
+            case 'escalate': {
+                out.write(yellow(`↑ Escalating ${ev.from} → ${ev.to}: ${ev.reason}`, c) + `\n`);
+                break;
+            }
+            case 'notice': {
+                const prefix = ev.level === 'error' ? red('[error]', c) :
+                    ev.level === 'warn' ? yellow('[warn]', c) :
+                        dim('[info]', c);
+                out.write(`${prefix} ${ev.message}\n`);
+                break;
+            }
+            case 'final': {
+                finalEvent = ev;
+                const successLabel = ev.success
+                    ? bold(green('Success', c), c)
+                    : bold(red('Failed', c), c);
+                const costStr = `$${ev.totalCostUsd.toFixed(4)}`;
+                out.write(`\n${successLabel} — ` +
+                    `tier: ${ev.tier}, ` +
+                    `cost: ${costStr}, ` +
+                    `attempts: ${ev.attempts}, ` +
+                    `session: ${ev.sessionId}\n`);
+                break;
+            }
+        }
+    }
+    // Safety: ensure spinner is stopped if stream ended without a terminal event.
+    stopSpinner();
+    if (finalEvent !== undefined) {
+        return { success: finalEvent.success, final: finalEvent };
+    }
+    return { success: false };
+}
+//# sourceMappingURL=render.js.map

package/dist/interface/render.js.map

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

package/dist/interface/repl.d.ts

@@ -0,0 +1,23 @@
+/**
+ * src/interface/repl.ts — interactive REPL for myshell-tools.
+ *
+ * Presents a `myshell-tools> ` prompt, dispatching each line as a task via runTask().
+ * Built-in commands: /exit, /quit, /help.
+ *
+ * SIGINT behaviour:
+ *   - If a task is in flight → abort it and keep the REPL alive.
+ *   - If idle → close the readline interface and resolve.
+ *
+ * Never calls process.exit() — that responsibility belongs exclusively to
+ * src/cli.ts.
+ */
+import type { OrchestrateDeps } from '../core/types.js';
+import type { OutputSink } from './render.js';
+/**
+ * Start an interactive REPL session. Resolves when the user exits or when the
+ * readline interface is closed.
+ *
+ * @param deps - Injected orchestration dependencies.
+ * @param out  - Where rendered output is written.
+ */
+export declare function startRepl(deps: OrchestrateDeps, out: OutputSink): Promise<void>;

package/dist/interface/repl.js

@@ -0,0 +1,90 @@
+/**
+ * src/interface/repl.ts — interactive REPL for myshell-tools.
+ *
+ * Presents a `myshell-tools> ` prompt, dispatching each line as a task via runTask().
+ * Built-in commands: /exit, /quit, /help.
+ *
+ * SIGINT behaviour:
+ *   - If a task is in flight → abort it and keep the REPL alive.
+ *   - If idle → close the readline interface and resolve.
+ *
+ * Never calls process.exit() — that responsibility belongs exclusively to
+ * src/cli.ts.
+ */
+import readline from 'node:readline';
+import { runTask } from './run.js';
+const REPL_HELP = `\
+Available commands:
+  /help     Show this help message
+  /exit     Exit the REPL
+  /quit     Exit the REPL
+  <task>    Run a task (any other non-empty line)
+`;
+/**
+ * Start an interactive REPL session. Resolves when the user exits or when the
+ * readline interface is closed.
+ *
+ * @param deps - Injected orchestration dependencies.
+ * @param out  - Where rendered output is written.
+ */
+export async function startRepl(deps, out) {
+    return new Promise((resolve) => {
+        const rl = readline.createInterface({
+            input: process.stdin,
+            output: process.stdout,
+            prompt: 'myshell-tools> ',
+            terminal: out.isTty,
+        });
+        // Track the in-flight AbortController so SIGINT can cancel it.
+        let currentAc = null;
+        rl.on('SIGINT', () => {
+            if (currentAc !== null) {
+                // Task in flight — abort it, keep the REPL alive.
+                currentAc.abort();
+                out.write('\n[warn] Task cancelled.\n');
+                rl.prompt();
+            }
+            else {
+                // Idle — close and resolve.
+                out.write('\n');
+                rl.close();
+            }
+        });
+        rl.on('close', () => {
+            resolve();
+        });
+        rl.on('line', (rawLine) => {
+            const line = rawLine.trim();
+            if (line.length === 0) {
+                rl.prompt();
+                return;
+            }
+            if (line === '/exit' || line === '/quit') {
+                rl.close();
+                return;
+            }
+            if (line === '/help') {
+                out.write(REPL_HELP);
+                rl.prompt();
+                return;
+            }
+            // Pause readline while the task runs to avoid interleaved output.
+            rl.pause();
+            const ac = new AbortController();
+            currentAc = ac;
+            runTask(line, deps, out, ac.signal).then(() => {
+                currentAc = null;
+                rl.resume();
+                rl.prompt();
+            }).catch((err) => {
+                currentAc = null;
+                const msg = err instanceof Error ? err.message : String(err);
+                out.write(`[error] ${msg}\n`);
+                rl.resume();
+                rl.prompt();
+            });
+        });
+        rl.prompt();
+    });
+}
+//# sourceMappingURL=repl.js.map

package/dist/interface/repl.js.map

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

package/dist/interface/run.d.ts

@@ -0,0 +1,20 @@
+/**
+ * src/interface/run.ts — single-task runner for the CLI `run` command.
+ *
+ * Bridges the orchestration core to the terminal output: calls orchestrate(),
+ * pipes the event stream through renderStream(), and returns a numeric exit
+ * code so that src/cli.ts — the only file allowed to call process.exit() —
+ * can terminate the process appropriately.
+ */
+import type { OrchestrateDeps } from '../core/types.js';
+import type { OutputSink } from './render.js';
+/**
+ * Run a single task end-to-end, rendering every CoreEvent to the OutputSink.
+ *
+ * @param task   - The raw user task description.
+ * @param deps   - Injected orchestration dependencies.
+ * @param out    - Where rendered output is written.
+ * @param signal - AbortSignal; abort to cancel the in-flight task.
+ * @returns      0 on success, 1 on failure or error.
+ */
+export declare function runTask(task: string, deps: OrchestrateDeps, out: OutputSink, signal: AbortSignal): Promise<number>;

package/dist/interface/run.js

@@ -0,0 +1,31 @@
+/**
+ * src/interface/run.ts — single-task runner for the CLI `run` command.
+ *
+ * Bridges the orchestration core to the terminal output: calls orchestrate(),
+ * pipes the event stream through renderStream(), and returns a numeric exit
+ * code so that src/cli.ts — the only file allowed to call process.exit() —
+ * can terminate the process appropriately.
+ */
+import { orchestrate } from '../core/orchestrate.js';
+import { renderStream } from './render.js';
+/**
+ * Run a single task end-to-end, rendering every CoreEvent to the OutputSink.
+ *
+ * @param task   - The raw user task description.
+ * @param deps   - Injected orchestration dependencies.
+ * @param out    - Where rendered output is written.
+ * @param signal - AbortSignal; abort to cancel the in-flight task.
+ * @returns      0 on success, 1 on failure or error.
+ */
+export async function runTask(task, deps, out, signal) {
+    try {
+        const result = await renderStream(orchestrate(task, deps, signal), out);
+        return result.success ? 0 : 1;
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        out.write(`[error] ${msg}\n`);
+        return 1;
+    }
+}
+//# sourceMappingURL=run.js.map

package/dist/interface/run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../../src/interface/run.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAErD,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAC3B,IAAY,EACZ,IAAqB,EACrB,GAAe,EACf,MAAmB;IAEnB,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC,WAAW,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,EAAE,GAAG,CAAC,CAAC;QACxE,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAChC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC7D,GAAG,CAAC,KAAK,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;QAC9B,OAAO,CAAC,CAAC;IACX,CAAC;AACH,CAAC"}

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

@@ -0,0 +1,24 @@
+/**
+ * src/providers/claude-parse.ts — pure JSONL parser for `claude -p --output-format stream-json`.
+ *
+ * PURE MODULE: no I/O, no execa, no side effects. All logic is a function from
+ * string → ProviderEvent[]. This is the hermetic, fixture-tested heart of the
+ * Claude adapter.
+ *
+ * Stream-json schema (matched from the captured fixture):
+ *  - rate_limit_event           → emit nothing
+ *  - system/init                → emit nothing
+ *  - assistant                  → text/tool events per content[] item
+ *  - result/success             → usage event + done event
+ *  - result/is_error or !success → usage event + error event
+ *  - unparseable line           → emit nothing (skip)
+ */
+import type { ProviderEvent } from './port.js';
+/**
+ * Parse a single JSONL line from `claude --output-format stream-json` stdout.
+ *
+ * Returns 0 or more {@link ProviderEvent}s. Returns an empty array for:
+ *  - Lines that fail JSON.parse
+ *  - Event types we intentionally ignore (rate_limit_event, system/init)
+ */
+export declare function parseClaudeLine(line: string): ProviderEvent[];

package/dist/providers/claude-parse.js

@@ -0,0 +1,113 @@
+/**
+ * src/providers/claude-parse.ts — pure JSONL parser for `claude -p --output-format stream-json`.
+ *
+ * PURE MODULE: no I/O, no execa, no side effects. All logic is a function from
+ * string → ProviderEvent[]. This is the hermetic, fixture-tested heart of the
+ * Claude adapter.
+ *
+ * Stream-json schema (matched from the captured fixture):
+ *  - rate_limit_event           → emit nothing
+ *  - system/init                → emit nothing
+ *  - assistant                  → text/tool events per content[] item
+ *  - result/success             → usage event + done event
+ *  - result/is_error or !success → usage event + error event
+ *  - unparseable line           → emit nothing (skip)
+ */
+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 if it is a
+    // number — omit the key entirely otherwise.
+    if (typeof u.cache_read_input_tokens === 'number') {
+        return { ...base, cachedInputTokens: u.cache_read_input_tokens };
+    }
+    return base;
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Parse a single JSONL line from `claude --output-format stream-json` stdout.
+ *
+ * Returns 0 or more {@link ProviderEvent}s. Returns an empty array for:
+ *  - Lines that fail JSON.parse
+ *  - Event types we intentionally ignore (rate_limit_event, system/init)
+ */
+export function parseClaudeLine(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'];
+    // -------------------------------------------------------------------------
+    // rate_limit_event / system — emit nothing
+    // -------------------------------------------------------------------------
+    if (eventType === 'rate_limit_event' || eventType === 'system') {
+        return [];
+    }
+    // -------------------------------------------------------------------------
+    // assistant — emit text/tool events per content[] item
+    // Do NOT emit usage from assistant events (it's intermediate).
+    // -------------------------------------------------------------------------
+    if (eventType === 'assistant') {
+        const ev = parsed;
+        const events = [];
+        for (const item of ev.message.content) {
+            if (item.type === 'text') {
+                const textItem = item;
+                events.push({ type: 'text', delta: textItem.text });
+            }
+            else if (item.type === 'tool_use') {
+                const toolItem = item;
+                events.push({ type: 'tool', name: toolItem.name, phase: 'start' });
+            }
+            // Other content types: ignore
+        }
+        return events;
+    }
+    // -------------------------------------------------------------------------
+    // result — emit usage event + done or error event
+    // -------------------------------------------------------------------------
+    if (eventType === 'result') {
+        const ev = parsed;
+        const events = [];
+        const usage = ev.usage ? mapUsage(ev.usage) : { inputTokens: 0, outputTokens: 0 };
+        // Always emit usage first
+        events.push({ type: 'usage', usage });
+        const isFailure = ev.is_error === true || ev.subtype !== 'success';
+        if (isFailure) {
+            const errorText = String(ev.result ?? ev.subtype ?? 'unknown error');
+            events.push({ type: 'error', error: classifyError(errorText, 1) });
+        }
+        else {
+            const resultText = ev.result ?? '';
+            const doneEvent = {
+                type: 'done',
+                text: resultText,
+                usage,
+                ...(typeof ev.total_cost_usd === 'number' ? { costUsd: ev.total_cost_usd } : {}),
+                raw: parsed,
+            };
+            events.push(doneEvent);
+        }
+        return events;
+    }
+    // Unknown event type — emit nothing
+    return [];
+}
+//# sourceMappingURL=claude-parse.js.map

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

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

package/dist/providers/claude.d.ts

@@ -0,0 +1,45 @@
+/**
+ * src/providers/claude.ts — Claude CLI adapter implementing the Provider port.
+ *
+ * Spawns `claude -p --output-format stream-json --verbose` via execa v9,
+ * delivers the prompt via STDIN (never as an argv argument), and streams
+ * parsed ProviderEvents to the caller as they arrive.
+ *
+ * Sandbox enforcement note (Phase-4 item):
+ *  The `req.sandbox` level is accepted but NOT yet translated into Claude CLI
+ *  flags. Default headless `claude -p` is inherently safe — tool calls that
+ *  would require elevated permissions are auto-denied by the Claude CLI. Full
+ *  sandbox→flag mapping (e.g. `--allowedTools` restrictions) is deferred to
+ *  Phase 4. Do NOT pass `--dangerously-skip-permissions` or any
+ *  permission-bypass flag here.
+ *
+ * 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 that classifyError() maps to category 'auth'.
+ *
+ * Execa v9 streaming:
+ *  We use `subprocess[Symbol.asyncIterator]()` (i.e. `for await … of subprocess`)
+ *  which by default iterates over stdout lines as strings. Confirmed from
+ *  types/subprocess/subprocess.d.ts: the subprocess IS an AsyncIterable that
+ *  yields one string per stdout line.
+ */
+import type { Provider } from './port.js';
+/**
+ * Map a concrete model id to a CLI-safe alias so a stale full id never 404s.
+ *
+ * Patterns:
+ *  - claude-opus-*   → 'opus'
+ *  - claude-sonnet-* → 'sonnet'
+ *  - claude-haiku-*  → 'haiku'
+ *  - anything else   → returned unchanged
+ */
+export declare function toClaudeModelArg(model: string): string;
+/**
+ * Create a Claude provider adapter.
+ *
+ * @param opts.bin - Override the binary name/path (default: `'claude'`).
+ */
+export declare function createClaudeProvider(opts?: {
+    bin?: string;
+}): Provider;