myshell-tools 1.0.0 → 2.0.0-alpha.0

package/dist/providers/claude.js

@@ -0,0 +1,122 @@
+/**
+ * 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 { execa } from 'execa';
+import { detectProvider } from './detect.js';
+import { classifyError } from './errors.js';
+import { parseClaudeLine } from './claude-parse.js';
+// ---------------------------------------------------------------------------
+// Model alias mapping
+// ---------------------------------------------------------------------------
+/**
+ * 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 function toClaudeModelArg(model) {
+    if (model.startsWith('claude-opus'))
+        return 'opus';
+    if (model.startsWith('claude-sonnet'))
+        return 'sonnet';
+    if (model.startsWith('claude-haiku'))
+        return 'haiku';
+    return model;
+}
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+/**
+ * Create a Claude provider adapter.
+ *
+ * @param opts.bin - Override the binary name/path (default: `'claude'`).
+ */
+export function createClaudeProvider(opts) {
+    const bin = opts?.bin ?? 'claude';
+    return {
+        id: 'claude',
+        detect() {
+            return detectProvider('claude');
+        },
+        async *run(req, signal) {
+            const args = [
+                '-p',
+                '--output-format',
+                'stream-json',
+                '--verbose',
+                '--model',
+                toClaudeModelArg(req.model),
+            ];
+            // 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,
+            });
+            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 = parseClaudeLine(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=claude.js.map

package/dist/providers/claude.js.map

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

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