codehere 0.8.0 → 1.0.2

package/dist/infrastructure/orchestration/cassette-recorder.js

@@ -1,120 +0,0 @@
-/**
- * cassette-recorder · organic instrumentation for S2b of the capture-first plan.
- *
- * What it does:
- *   When CODEHERE_RECORD_CASSETTES=1 is set, every adapter spawn writes the
- *   raw stdout/stderr byte stream + exit to a JSONL cassette under
- *   ~/.codehere/cassettes/<adapter>/<scenario>-<ISO>.jsonl. The schema matches
- *   the locked L3b format (agent/src/testing/cassette.ts) so the same loader
- *   + replay infrastructure works on captures from real production sessions.
- *
- * Why this exists:
- *   Per chat 2026-05-23 (path 3 hybrid), we agreed cassettes accumulate from
- *   the founder's normal use rather than from dedicated capture sessions
- *   requiring fresh API keys. This module is the "accumulates" mechanism.
- *
- * Design choices:
- *   - OFF by default. Zero overhead when the env var is unset. The 5 adapters
- *     all call `startRecording()`, but it returns a no-op recorder if the
- *     env var isn't set, so the per-chunk hooks become free function calls.
- *   - Best-effort writes. A failed cassette never breaks the spawn path.
- *   - No PII scrubbing here · the user is recording their own sessions on
- *     their own machine. If we ever publish cassettes externally, scrubbing
- *     belongs in an export tool, not in the recorder.
- *   - One cassette per session (no append between sessions). Easier to reason
- *     about lifecycle, easier to discard / re-run, easier to ship in a PR.
- */
-import { appendFileSync, mkdirSync } from 'fs';
-import { homedir } from 'os';
-import { dirname, join } from 'path';
-const ENV_FLAG = 'CODEHERE_RECORD_CASSETTES';
-const NULL_RECORDER = {
-    enabled: false,
-    path: '',
-    onStdout() { },
-    onStderr() { },
-    onExit() { },
-};
-export function startRecording(opts) {
-    if (process.env[ENV_FLAG] !== '1')
-        return NULL_RECORDER;
-    const outDir = opts.outDir ?? join(process.env.CODEHERE_HOME || homedir(), '.codehere', 'cassettes', opts.adapter);
-    const scenario = `organic-${opts.sessionId.slice(0, 8)}`;
-    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
-    const path = join(outDir, `${scenario}-${stamp}.jsonl`);
-    try {
-        mkdirSync(dirname(path), { recursive: true });
-    }
-    catch {
-        return NULL_RECORDER;
-    }
-    const start = Date.now();
-    const header = {
-        t: 0,
-        meta: {
-            adapter: opts.adapter,
-            scenario,
-            captured_at: new Date().toISOString(),
-            binary_version: opts.binary_version ?? 'unknown',
-            origin: 'real',
-            prompt: opts.prompt,
-            cwd_hint: hintCwd(opts.cwd),
-            schema: 1,
-        },
-    };
-    try {
-        appendFileSync(path, JSON.stringify(header) + '\n', 'utf-8');
-    }
-    catch {
-        return NULL_RECORDER;
-    }
-    let sealed = false;
-    return {
-        enabled: true,
-        path,
-        onStdout(chunk) {
-            if (sealed)
-                return;
-            writeEvent(path, { t: Date.now() - start, stream: 'stdout', data: chunk });
-        },
-        onStderr(chunk) {
-            if (sealed)
-                return;
-            writeEvent(path, { t: Date.now() - start, stream: 'stderr', data: chunk });
-        },
-        onExit(exit_code, signal) {
-            if (sealed)
-                return;
-            sealed = true;
-            writeEvent(path, { t: Date.now() - start, exit_code, signal });
-        },
-    };
-}
-/* ──────────────────────────────────────────────────────────────────────── */
-/* Internals                                                                 */
-/* ──────────────────────────────────────────────────────────────────────── */
-function writeEvent(path, payload) {
-    try {
-        appendFileSync(path, JSON.stringify(payload) + '\n', 'utf-8');
-    }
-    catch {
-        // best-effort · never break the spawn path
-    }
-}
-function hintCwd(cwd) {
-    if (!cwd)
-        return '.';
-    const home = homedir();
-    if (cwd === home)
-        return '~';
-    if (cwd.startsWith(home + '/'))
-        return '~/' + cwd.slice(home.length + 1);
-    return cwd;
-}
-/** Probe used by tests + the future status command. */
-export function isRecordingEnabled() {
-    return process.env[ENV_FLAG] === '1';
-}
-/** Returns the env flag name so callers can document it consistently. */
-export const RECORD_ENV_FLAG = ENV_FLAG;
-//# sourceMappingURL=cassette-recorder.js.map

package/dist/infrastructure/orchestration/claude-code-adapter.js

@@ -1,478 +0,0 @@
-/**
- * Claude Code adapter — F1 foundation of the PM layer (v0.3).
- *
- * Wraps `claude -p "<task>" --output-format=stream-json …` as a subprocess
- * and exposes a tight interface: spawn, subscribe to events, kill.
- *
- * Deep module: everything about process management, stream parsing, line
- * buffering, SIGTERM→SIGKILL escalation, and late-joiner replay is hidden
- * behind four exported names (TaskSession type, spawnClaudeCode, TaskEvent,
- * TaskStatus). Callers never see a child_process handle.
- *
- * Safety note: spawned sessions inherit the user's global PreToolUse hook
- * via ~/.claude/settings.json automatically — we do NOT re-wire it here.
- * That's F0 doing its job for free.
- */
-import { spawn } from 'child_process';
-import { execFileSync } from 'child_process';
-import { startRecording } from './cassette-recorder.js';
-import { resolveAgentSpawn } from './mocks/resolve-agent-spawn.js';
-import { EventEmitter } from 'events';
-import { randomUUID } from 'crypto';
-import { ProgressAggregator } from './progress-aggregator.js';
-import { snapshotCwd, extractArtifacts } from './artifacts-extractor.js';
-import { applyMemoryPrefix } from './memory-injector.js';
-// Runtime-error fingerprints → structured codehere:error events with recovery hints.
-// Matched against any stderr line or assistant-text content we see on the stream.
-const ERROR_PATTERNS = [
-    {
-        code: 'credit_low',
-        regex: /credit balance is too low/i,
-        message: 'Your Claude API account has no credits.',
-        recovery: 'codehere tries to use your Claude Code subscription by default. If you are seeing this, ' +
-            'ANTHROPIC_API_KEY is still being used somehow. Unset it in your shell (e.g. remove from ~/.zshrc), ' +
-            'or top up at console.anthropic.com.',
-    },
-    {
-        code: 'auth_invalid',
-        regex: /invalid api key|authentication.*failed|not authenticated|401 unauth/i,
-        message: 'Claude Code auth was rejected.',
-        recovery: 'Run `claude` in a terminal, sign in, then retry the task.',
-    },
-    {
-        code: 'rate_limit',
-        regex: /rate.?limit(ed)?|429|too many requests/i,
-        message: 'Claude rate-limited the request.',
-        recovery: 'Wait a minute and retry. If this persists, check your Claude usage dashboard.',
-    },
-];
-function scanForKnownError(text) {
-    for (const p of ERROR_PATTERNS) {
-        if (p.regex.test(text))
-            return { code: p.code, message: p.message, recovery: p.recovery };
-    }
-    return null;
-}
-// v0.7 MED-2 fix — dropped `--include-partial-messages` and
-// `--include-hook-events` from the headless flags. Per docs/contracts/claude-code.md
-// §7 the adapter doesn't consume partial-message deltas (only full assistant
-// blocks) and doesn't surface hook events in any UI. Both flags inflated
-// stream volume + token cost without benefit. If we later need either
-// (e.g., to wire a hook visualization in v0.8), re-add with explicit
-// parsing intent.
-const HEADLESS_FLAGS = [
-    '--output-format',
-    'stream-json',
-    '--verbose',
-    // Pre-grant common tools so -p mode doesn't dead-end at interactive permission
-    // prompts we cannot surface to the user. Safety is still enforced by codehere's
-    // PreToolUse hook (F0) on every tool call — that's the real gate.
-    '--allowedTools',
-    'Bash',
-    'Edit',
-    'Write',
-    'Read',
-    'Grep',
-    'Glob',
-    'MultiEdit',
-    'NotebookEdit',
-];
-export function spawnClaudeCode(prompt, options = {}) {
-    const sessionId = randomUUID();
-    const startedAt = Date.now();
-    const emitter = new EventEmitter();
-    const buffer = [];
-    let statusValue = 'running';
-    let killRequested = false;
-    // PM UX Layer 2+3 state. Shared helper modules; per-session instances.
-    const cwd = options.cwd ?? process.cwd();
-    // F3 Task 8 — inject project memory (AGENTS.md + lessons + repo_map slice)
-    // into the prompt prefix unless the caller opted out. Pure, side-effect-
-    // free; returns unchanged prompt + record=undefined when there's no
-    // .codehere/ at cwd.
-    const injected = applyMemoryPrefix(prompt, cwd, options);
-    const finalPrompt = injected.prompt;
-    const snapshot = snapshotCwd(cwd);
-    const aggregator = new ProgressAggregator('claude-code');
-    let stepsSnapshot = [];
-    let artifactsSnapshot;
-    let textAccum = ''; // accumulates assistant text + result summary for test-count parsing
-    let usageSnapshot; // token accumulator (principle #7)
-    let errorEmitted = false;
-    const emit = (event) => {
-        buffer.push(event);
-        emitter.emit('event', event);
-        // Layer 2: feed aggregator; on step change, emit synthetic snapshot event.
-        if (aggregator.ingest(event)) {
-            stepsSnapshot = aggregator.steps.map((s) => ({ ...s }));
-            const snapEvt = { type: 'codehere:steps', timestamp: Date.now(), data: { steps: stepsSnapshot } };
-            buffer.push(snapEvt);
-            emitter.emit('event', snapEvt);
-        }
-        // Accumulate text for test-summary parsing (Layer 3).
-        if (event.type === 'assistant') {
-            const msg = event.data?.message;
-            if (msg?.content) {
-                for (const b of msg.content) {
-                    if (b.type === 'text' && b.text)
-                        textAccum += b.text + '\n';
-                }
-            }
-        }
-        else if (event.type === 'result') {
-            const d = event.data;
-            if (d?.result)
-                textAccum += d.result + '\n';
-            // Claude Code's stream-json `result` event is the final summary — carries
-            // the full session's usage totals. One event per session; overwrite, don't sum.
-            if (d?.usage) {
-                usageSnapshot = {
-                    inputTokens: Number(d.usage.input_tokens ?? 0),
-                    outputTokens: Number(d.usage.output_tokens ?? 0),
-                    cacheReadTokens: d.usage.cache_read_input_tokens ? Number(d.usage.cache_read_input_tokens) : undefined,
-                    cacheCreationTokens: d.usage.cache_creation_input_tokens
-                        ? Number(d.usage.cache_creation_input_tokens)
-                        : undefined,
-                };
-            }
-        }
-        else if (event.type === 'user') {
-            const msg = event.data?.message;
-            if (msg?.content) {
-                for (const b of msg.content) {
-                    if (b.type === 'tool_result') {
-                        const raw = Array.isArray(b.content)
-                            ? b.content.map((c) => c.text ?? '').join('')
-                            : String(b.content ?? '');
-                        textAccum += raw + '\n';
-                    }
-                }
-            }
-        }
-        // F1b: scan for known failure patterns once per session
-        if (!errorEmitted) {
-            const data = event.data;
-            let text = '';
-            if (event.type === 'stderr' && data && typeof data.line === 'string') {
-                text = data.line;
-            }
-            else if (event.type === 'assistant' && data && typeof data === 'object') {
-                const msg = data.message;
-                if (msg?.content) {
-                    text = msg.content.map((b) => (b.type === 'text' ? (b.text ?? '') : '')).join(' ');
-                }
-            }
-            else if (event.type === 'result' && data && typeof data.result === 'string') {
-                text = String(data.result ?? '');
-            }
-            if (text) {
-                const hit = scanForKnownError(text);
-                if (hit) {
-                    errorEmitted = true;
-                    const errEvent = {
-                        type: 'codehere:error',
-                        timestamp: Date.now(),
-                        data: { code: hit.code, message: hit.message, recovery: hit.recovery },
-                    };
-                    buffer.push(errEvent);
-                    emitter.emit('event', errEvent);
-                }
-            }
-        }
-    };
-    const preferSubscription = options.preferSubscription !== false;
-    const spawnEnv = { ...process.env, ...(options.env ?? {}) };
-    if (preferSubscription) {
-        // Force keychain/OAuth path — matches what the user's interactive `claude` uses.
-        delete spawnEnv.ANTHROPIC_API_KEY;
-        delete spawnEnv.ANTHROPIC_AUTH_TOKEN;
-        delete spawnEnv.CLAUDE_API_KEY;
-    }
-    let child;
-    try {
-        const sp = resolveAgentSpawn('claude-code', 'claude', [
-            '-p',
-            finalPrompt,
-            ...HEADLESS_FLAGS,
-            ...(options.extraArgs ?? []),
-        ]);
-        child = spawn(sp.command, sp.args, {
-            cwd,
-            env: spawnEnv,
-            stdio: ['ignore', 'pipe', 'pipe'],
-        });
-    }
-    catch (err) {
-        // Recorder is short-circuit no-op when CODEHERE_RECORD_CASSETTES != '1'
-        // so the spawn-failure path doesn't even pay the closure cost.
-        statusValue = 'error';
-        const msg = err instanceof Error ? err.message : String(err);
-        // Emit synchronously so subscribers added immediately after see it
-        queueMicrotask(() => emit({ type: 'error', timestamp: Date.now(), data: { message: msg } }));
-        return {
-            sessionId,
-            startedAt,
-            prompt,
-            agent: 'claude-code',
-            get status() {
-                return statusValue;
-            },
-            get steps() {
-                return stepsSnapshot;
-            },
-            get artifacts() {
-                return artifactsSnapshot;
-            },
-            subscribe(handler) {
-                for (const e of buffer)
-                    handler(e);
-                emitter.on('event', handler);
-                return () => emitter.off('event', handler);
-            },
-            kill() {
-                /* already not running */
-            },
-        };
-    }
-    // ── Organic cassette recording (S2b · capture-first plan) ─────────────────
-    // No-op unless CODEHERE_RECORD_CASSETTES=1 · zero overhead by default.
-    // Captures the raw byte stream + exit so a future replay can reproduce
-    // this exact session through the mock adapter without a live agent call.
-    const recorder = startRecording({
-        adapter: 'claude-code',
-        sessionId,
-        prompt: finalPrompt,
-        cwd,
-    });
-    // ── stdout: newline-delimited JSON from `--output-format stream-json` ────────
-    let stdoutBuf = '';
-    // Iter 13 — capture the claude-internal session_id from the init event so
-    // appendMessage can use `--resume <session-id>` (reliable) instead of `-c`
-    // (which picks "most recent in cwd" and can collide with other concurrent
-    // claude sessions OR with conversations containing thinking blocks the
-    // headless API can't replay).
-    let claudeSessionId;
-    child.stdout?.on('data', (chunk) => {
-        const text = chunk.toString('utf-8');
-        recorder.onStdout(text);
-        stdoutBuf += text;
-        let idx;
-        while ((idx = stdoutBuf.indexOf('\n')) >= 0) {
-            const line = stdoutBuf.slice(0, idx).trim();
-            stdoutBuf = stdoutBuf.slice(idx + 1);
-            if (!line)
-                continue;
-            try {
-                const data = JSON.parse(line);
-                if (claudeSessionId === undefined &&
-                    data.type === 'system' &&
-                    data.subtype === 'init' &&
-                    typeof data.session_id === 'string') {
-                    claudeSessionId = data.session_id;
-                }
-                emit({ type: data.type ?? 'message', timestamp: Date.now(), data });
-            }
-            catch {
-                // Non-JSON stdout line — preserve so callers can see raw output
-                emit({ type: 'stdout', timestamp: Date.now(), data: { line } });
-            }
-        }
-    });
-    // ── stderr: Claude prints debug/errors here; forward raw ─────────────────────
-    child.stderr?.on('data', (chunk) => {
-        const text = chunk.toString('utf-8');
-        recorder.onStderr(text);
-        for (const line of text.split('\n')) {
-            if (line.trim())
-                emit({ type: 'stderr', timestamp: Date.now(), data: { line } });
-        }
-    });
-    child.on('exit', (code, signal) => {
-        recorder.onExit(code ?? -1, signal);
-        statusValue =
-            killRequested || signal !== null ? 'killed' : errorEmitted ? 'error' : code === 0 ? 'completed' : 'error';
-        // Emit synthetic PM events BEFORE 'exit' so the client has time to render
-        // them before its onmessage handler closes the SSE stream in response to exit.
-        // (Client must close on exit to avoid leaking connections — but close() cancels
-        //  pending messages, so order matters.)
-        // Layer 2: flip any still-active steps to done/failed so the UI stops spinning.
-        if (aggregator.finalize(statusValue === 'completed' ? 'completed' : statusValue === 'killed' ? 'killed' : 'error')) {
-            stepsSnapshot = aggregator.steps.map((s) => ({ ...s }));
-            emit({ type: 'codehere:steps', timestamp: Date.now(), data: { steps: stepsSnapshot } });
-        }
-        // Layer 3: on clean completion, extract artifacts (git diff + trust + tests + tokens) and announce.
-        if (statusValue === 'completed') {
-            try {
-                artifactsSnapshot = { ...extractArtifacts(snapshot, textAccum), usage: usageSnapshot };
-                emit({ type: 'codehere:artifacts', timestamp: Date.now(), data: artifactsSnapshot });
-            }
-            catch {
-                /* best-effort; don't break exit path */
-            }
-        }
-        emit({
-            type: 'exit',
-            timestamp: Date.now(),
-            data: { code, signal, status: statusValue, durationMs: Date.now() - startedAt },
-        });
-    });
-    child.on('error', (err) => {
-        statusValue = 'error';
-        emit({ type: 'error', timestamp: Date.now(), data: { message: err.message } });
-    });
-    return {
-        sessionId,
-        startedAt,
-        prompt,
-        agent: 'claude-code',
-        canAppendMessage: true,
-        memoryInjection: injected.record,
-        get status() {
-            return statusValue;
-        },
-        get steps() {
-            return stepsSnapshot;
-        },
-        get artifacts() {
-            return artifactsSnapshot;
-        },
-        subscribe(handler) {
-            for (const e of buffer)
-                handler(e);
-            emitter.on('event', handler);
-            return () => emitter.off('event', handler);
-        },
-        kill() {
-            if (statusValue !== 'running')
-                return;
-            killRequested = true;
-            child.kill('SIGTERM');
-            // Escalate if it doesn't die in 3s
-            setTimeout(() => {
-                if (statusValue === 'running') {
-                    try {
-                        child.kill('SIGKILL');
-                    }
-                    catch {
-                        /* already dead */
-                    }
-                }
-            }, 3000);
-        },
-        /**
-         * Iter 12 (with iter-13 fix) — follow-up message to a completed session.
-         *
-         * Iter 12 used `claude -p "<text>" -c` which picks "most recent
-         * conversation in current directory". Iter 13 dogfood proved this
-         * fragile: in a cwd with multiple concurrent claude sessions OR with
-         * conversations containing thinking blocks, -c either picks the wrong
-         * session or hits an API-replay error ("Invalid signature in thinking
-         * block"). Fix: capture the claude session_id from this session's init
-         * event (above) and use `--resume <session-id>` for follow-ups —
-         * unambiguous and replay-safe.
-         *
-         * Scope: still one-shot Q&A. No streaming. Returns assistant's response
-         * text. If we never captured a session_id (init event never fired —
-         * shouldn't happen in healthy claude runs), reject explicitly.
-         */
-        appendMessage(text) {
-            const startedAt = Date.now();
-            return new Promise((resolve, reject) => {
-                if (!claudeSessionId) {
-                    reject(new Error('Cannot reply: original claude session_id was never captured (init event missed)'));
-                    return;
-                }
-                let stdout = '';
-                let stderr = '';
-                // Route follow-ups through the mock seam too — under CODEHERE_MOCK=1 this
-                // hits the mock REPL, not the real binary. (Was a real-spend leak:
-                // appendMessage spawned `claude` directly regardless of mock mode.)
-                const sp2 = resolveAgentSpawn('claude-code', 'claude', ['-p', text, '--resume', claudeSessionId, ...HEADLESS_FLAGS], text);
-                const followup = spawn(sp2.command, sp2.args, {
-                    cwd,
-                    env: spawnEnv,
-                    stdio: ['ignore', 'pipe', 'pipe'],
-                });
-                followup.on('error', (err) => reject(err));
-                followup.stdout?.on('data', (chunk) => {
-                    stdout += chunk.toString('utf-8');
-                });
-                followup.stderr?.on('data', (chunk) => {
-                    stderr += chunk.toString('utf-8');
-                });
-                followup.on('exit', (code) => {
-                    if (code !== 0) {
-                        reject(new Error(`claude -c exited ${code}: ${stderr.slice(0, 200)}`));
-                        return;
-                    }
-                    // Parse stream-json — extract assistant message text from the
-                    // 'assistant' typed lines and the final 'result' line.
-                    const lines = stdout.split('\n').filter((l) => l.trim());
-                    const fragments = [];
-                    for (const line of lines) {
-                        try {
-                            const obj = JSON.parse(line);
-                            if (obj.type === 'assistant' && obj.message?.content) {
-                                for (const block of obj.message.content) {
-                                    if (block.type === 'text' && block.text)
-                                        fragments.push(block.text);
-                                }
-                            }
-                            else if (obj.type === 'result' && typeof obj.result === 'string') {
-                                fragments.push(obj.result);
-                            }
-                        }
-                        catch {
-                            // Non-JSON line — skip
-                        }
-                    }
-                    // Dedupe trivially: if 'result' contained the same text as the
-                    // last assistant block, take just one. Conservative: prefer 'result'
-                    // if present (it's the final summary), else join assistants.
-                    const result = fragments.length ? fragments[fragments.length - 1] : '(no response captured)';
-                    resolve({ result, durationMs: Date.now() - startedAt });
-                });
-            });
-        },
-    };
-}
-// ── AgentAdapter implementation ─────────────────────────────────────────────
-export const ClaudeCodeAdapter = {
-    id: 'claude-code',
-    label: 'Claude Code',
-    description: 'Good default for editing code, running tests, and shell commands. Strongest safety net: codehere can stop risky actions before they run, not just record them after.',
-    processPattern: /(?:^|\/)claude(?:\s|$)/,
-    isInstalled() {
-        try {
-            const out = execFileSync('which', ['claude'], { encoding: 'utf-8', timeout: 2000 });
-            return out.trim().length > 0;
-        }
-        catch {
-            return false;
-        }
-    },
-    spawn(prompt, options) {
-        return spawnClaudeCode(prompt, options);
-    },
-    checkReadiness() {
-        const installed = this.isInstalled();
-        if (!installed) {
-            return {
-                id: this.id,
-                label: this.label,
-                state: 'needs_install',
-                installed: false,
-                installHint: {
-                    command: 'npm install -g @anthropic-ai/claude-code',
-                    url: 'https://docs.claude.com/en/docs/claude-code/setup',
-                },
-            };
-        }
-        // Claude Code supports BOTH subscription (OAuth via keychain) and API key.
-        // "Ready" if either path works. We can't verify subscription without
-        // calling the API, so we treat any Claude Code install as ready by default —
-        // runtime F1b error-fingerprints catch real auth failures after spawn.
-        return { id: this.id, label: this.label, state: 'ready', installed: true };
-    },
-};
-//# sourceMappingURL=claude-code-adapter.js.map