codehere 0.6.2 → 0.7.0

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

@@ -15,6 +15,8 @@
  */
 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';
@@ -51,11 +53,16 @@ function scanForKnownError(text) {
     }
     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',
-    '--include-partial-messages',
-    '--include-hook-events',
     '--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
@@ -183,13 +190,21 @@ export function spawnClaudeCode(prompt, options = {}) {
     }
     let child;
     try {
-        child = spawn('claude', ['-p', finalPrompt, ...HEADLESS_FLAGS, ...(options.extraArgs ?? [])], {
+        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
@@ -219,6 +234,16 @@ export function spawnClaudeCode(prompt, options = {}) {
             },
         };
     }
+    // ── 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
@@ -228,7 +253,9 @@ export function spawnClaudeCode(prompt, options = {}) {
     // headless API can't replay).
     let claudeSessionId;
     child.stdout?.on('data', (chunk) => {
-        stdoutBuf += chunk.toString('utf-8');
+        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();
@@ -254,12 +281,14 @@ export function spawnClaudeCode(prompt, options = {}) {
     // ── 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

package/dist/infrastructure/orchestration/codex-adapter.js

@@ -16,10 +16,12 @@
 import { spawn, execFileSync } from 'child_process';
 import { EventEmitter } from 'events';
 import { randomUUID } from 'crypto';
+import { startRecording } from './cassette-recorder.js';
 import { ProgressAggregator } from './progress-aggregator.js';
 import { snapshotCwd, extractArtifacts } from './artifacts-extractor.js';
 import { applyMemoryPrefix } from './memory-injector.js';
 import { mirrorToolCallToAudit } from '../hooks/mirror-tool-call-to-audit.js';
+import { resolveAgentSpawn } from './mocks/resolve-agent-spawn.js';
 const HEADLESS_FLAGS = [
     'exec',
     '--json',
@@ -98,37 +100,158 @@ export function spawnCodex(prompt, options = {}) {
         }
         // Collect text for test-summary parsing (Layer 3). Codex surfaces command
         // output via item.completed.aggregated_output and agent messages via item.text.
+        //
+        // v0.7 CRIT-1 fix — extended item subtypes parsed:
+        //   - command_execution (Bash) — existing, mirrored to audit
+        //   - agent_message (assistant text) — existing
+        //   - file_change (Edit/Write batch) — NEW, mirrored as Edit per file
+        //   - mcp_tool_call (MCP servers) — NEW, mirrored as Tool with server prefix
+        //   - collab_tool_call (SUBAGENT FAN-OUT, multi-agent v2 GA 2026-05-18) — NEW
+        //     · spawn_agent / send_input / wait / close_agent / resume_agent
+        //     · mirrored to audit as "Subagent" toolName so /history shows the
+        //       child-spawn activity. Without this, multi-agent Codex tasks fall
+        //       silently through (audit + cost claim breach per CRIT-1).
+        //     · Token usage of children remains UNDER-REPORTED in this fix —
+        //       child usage lives on a separate app-server stream we don't yet
+        //       subscribe to. Disclosed honestly in docs/contracts/00-FINDINGS.md.
+        //   - todo_list — NEW, fed through as a synthetic 'todo' tool call (lets
+        //     ProgressAggregator surface plan changes for PM Layer 2 UX parity)
+        //   - web_search — NEW, mirrored as WebSearch tool
+        //   - reasoning — NOT mirrored (private CoT trace; not an action)
+        //   - error (item) — NEW, surfaced as codehere:error for non-fatal errors
         if (event.type === 'item.completed') {
             const item = event.data?.item;
-            if (item?.type === 'command_execution' && item.aggregated_output)
-                textAccum += item.aggregated_output + '\n';
-            if (item?.type === 'agent_message' && item.text)
-                textAccum += item.text + '\n';
-            // #110 slice 2 — mirror tool calls to the audit log so codex
-            // gets the same audit-trail surface as Claude's per-tool hook.
-            // Post-hoc only (no block); pre-tool intercept is a future slice.
-            if (item?.type === 'command_execution' && typeof item.command === 'string' && item.command) {
+            if (!item?.type) {
+                // unknown shape — let it pass for textAccum below
+            }
+            else if (item.type === 'command_execution') {
+                if (item.aggregated_output)
+                    textAccum += item.aggregated_output + '\n';
+                if (typeof item.command === 'string' && item.command) {
+                    mirrorToolCallToAudit({
+                        sessionId,
+                        agent: 'codex',
+                        toolName: 'Bash',
+                        toolInput: item.command,
+                        cwd,
+                    });
+                }
+            }
+            else if (item.type === 'agent_message') {
+                if (item.text)
+                    textAccum += item.text + '\n';
+            }
+            else if (item.type === 'file_change') {
+                // One audit entry per changed file. Codehere-cased toolName per
+                // /history filter convention (matches Claude Edit/Write rows).
+                for (const change of item.changes ?? []) {
+                    const path = String(change.path ?? '');
+                    const kind = String(change.kind ?? 'update');
+                    if (!path)
+                        continue;
+                    const toolName = kind === 'add' ? 'Write' : kind === 'delete' ? 'Delete' : 'Edit';
+                    mirrorToolCallToAudit({
+                        sessionId,
+                        agent: 'codex',
+                        toolName,
+                        toolInput: path,
+                        cwd,
+                    });
+                }
+            }
+            else if (item.type === 'mcp_tool_call') {
+                const server = String(item.server ?? '');
+                const tool = String(item.tool ?? 'mcp');
                 mirrorToolCallToAudit({
                     sessionId,
                     agent: 'codex',
-                    toolName: 'Bash',
-                    toolInput: item.command,
+                    toolName: `MCP.${server}.${tool}`,
+                    toolInput: typeof item.arguments === 'string' ? item.arguments : JSON.stringify(item.arguments ?? {}).slice(0, 500),
                     cwd,
                 });
             }
+            else if (item.type === 'collab_tool_call') {
+                // SUBAGENT FAN-OUT — the v0.7 fix that closes CRIT-1's audit gap.
+                // Mirror every collab call to the audit log so /history shows the
+                // subagent activity. Tool naming convention: "Subagent.<tool>".
+                const collabTool = String(item.tool ?? 'collab');
+                const receivers = (item.receiver_thread_ids ?? []).join(',');
+                const promptExcerpt = item.prompt ? String(item.prompt).slice(0, 200) : '';
+                const auditPayload = JSON.stringify({
+                    tool: collabTool,
+                    sender: item.sender_thread_id,
+                    receivers,
+                    prompt: promptExcerpt,
+                    agents_states: item.agents_states ?? {},
+                }).slice(0, 1000);
+                mirrorToolCallToAudit({
+                    sessionId,
+                    agent: 'codex',
+                    toolName: `Subagent.${collabTool}`,
+                    toolInput: auditPayload,
+                    cwd,
+                });
+            }
+            else if (item.type === 'todo_list') {
+                // Feed into textAccum for Final Report visibility. Future v0.8: wire
+                // into ProgressAggregator for PM Layer 2 parity with Claude TodoWrite.
+                const items = (item.items ?? []).map((t) => `- [${t.completed ? 'x' : ' '}] ${t.text ?? ''}`).join('\n');
+                if (items)
+                    textAccum += `Todo list:\n${items}\n`;
+            }
+            else if (item.type === 'web_search') {
+                mirrorToolCallToAudit({
+                    sessionId,
+                    agent: 'codex',
+                    toolName: 'WebSearch',
+                    toolInput: String(item.query ?? ''),
+                    cwd,
+                });
+            }
+            else if (item.type === 'error') {
+                // Non-fatal item-level error (distinct from top-level `error` + `turn.failed`).
+                // Don't flip errorEmitted — caller may still complete successfully.
+                if (item.message)
+                    textAccum += `[error] ${item.message}\n`;
+            }
+            // reasoning: intentionally not mirrored (private trace, not an action)
         }
         // Accumulate token usage across all turns (one turn.completed per turn).
+        // v0.7 MED-3 parity — also sum reasoning_output_tokens into outputTokens.
         if (event.type === 'turn.completed') {
             const u = event.data?.usage;
             if (u) {
                 const acc = usageSnapshot ?? { inputTokens: 0, outputTokens: 0 };
                 acc.inputTokens += Number(u.input_tokens ?? 0);
                 acc.outputTokens += Number(u.output_tokens ?? 0);
+                // Reasoning tokens billed at output rate per OpenAI pricing — fold in.
+                if (u.reasoning_output_tokens)
+                    acc.outputTokens += Number(u.reasoning_output_tokens);
                 if (u.cached_input_tokens)
                     acc.cacheReadTokens = (acc.cacheReadTokens ?? 0) + Number(u.cached_input_tokens);
                 usageSnapshot = acc;
             }
         }
+        // v0.7 MED-1 — explicit handler for turn.failed. Previously caught only by
+        // the catch-all stringify scan below (load-bearing accident). Now the
+        // canonical wire surface for API errors is parsed directly.
+        if (event.type === 'turn.failed' && !errorEmitted) {
+            const errObj = event.data?.error;
+            const message = String(errObj?.message ?? '');
+            if (message) {
+                const hit = scanForKnownError(message);
+                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);
+                }
+            }
+        }
         if (!errorEmitted) {
             const data = event.data;
             let text = '';
@@ -139,7 +262,9 @@ export function spawnCodex(prompt, options = {}) {
                 text = data.line;
             }
             else if (data && typeof data === 'object') {
-                // Catch-all: scan any string fields for known error patterns
+                // Catch-all (kept for stream-level `error` events + any future shape we
+                // don't have an explicit handler for). MED-1's explicit turn.failed
+                // handler above runs first; this is the safety net.
                 text = JSON.stringify(data);
             }
             if (text) {
@@ -163,7 +288,8 @@ export function spawnCodex(prompt, options = {}) {
         // Codex expects the prompt via stdin when stdin is piped; passing as argv
         // while stdin is 'ignore' causes codex to hang waiting for EOF → exit 0
         // with no task run. Pipe stdin, write prompt, close.
-        child = spawn('codex', [...HEADLESS_FLAGS, ...(options.extraArgs ?? [])], {
+        const sp = resolveAgentSpawn('codex', 'codex', [...HEADLESS_FLAGS, ...(options.extraArgs ?? [])]);
+        child = spawn(sp.command, sp.args, {
             cwd,
             env: spawnEnv,
             stdio: ['pipe', 'pipe', 'pipe'],
@@ -205,9 +331,14 @@ export function spawnCodex(prompt, options = {}) {
     // multi-turn continuity. Same pattern as claude-code-adapter capturing
     // session_id from the init event for `claude --resume`.
     let codexThreadId;
+    // Organic cassette recording (S2b · capture-first plan) · no-op unless
+    // CODEHERE_RECORD_CASSETTES=1, so zero overhead by default.
+    const recorder = startRecording({ adapter: 'codex', sessionId, prompt: finalPrompt, cwd });
     let stdoutBuf = '';
     child.stdout?.on('data', (chunk) => {
-        stdoutBuf += chunk.toString('utf-8');
+        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();
@@ -228,12 +359,14 @@ export function spawnCodex(prompt, options = {}) {
     });
     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';
         // PM events BEFORE 'exit' — see claude-code-adapter for rationale

package/dist/infrastructure/orchestration/context-handoff.js

@@ -52,7 +52,7 @@ function loadAllPacks(cwd) {
  *   2. Same workspace, any pack (most recent)
  *   3. Fallback: no handoff
  */
-export function loadHandoffContext(cwd, { fromSessionId, maxAgeMs = DEFAULT_MAX_AGE_MS, minNodes = DEFAULT_MIN_NODES } = {}) {
+export function loadHandoffContext(cwd, { maxAgeMs = DEFAULT_MAX_AGE_MS, minNodes = DEFAULT_MIN_NODES } = {}) {
     const now = Date.now();
     const packs = loadAllPacks(cwd);
     // Filter by age
@@ -92,10 +92,11 @@ export function enrichPromptWithHandoff(prompt, handoff) {
     if (!handoff)
         return prompt;
     const handoffLine = `[handoff: agent=${handoff.agent}, pack=${handoff.packId}, ${handoff.nodeCount} nodes, ${handoff.edgeCount} edges]`;
-    const preview = handoff.payloadPreview ? ` ${handoff.payloadPreview.slice(0, 800)}` : '';
+    const preview = handoff.payloadPreview ? handoff.payloadPreview.slice(0, 800) : '';
     return [
         `[Previous session context — ${handoffLine}]`,
         `This workspace has recent structural context from a prior session.`,
+        ...(preview ? [`Recent context: ${preview}`] : []),
         `For details, refer to the knowledge graph at the workspace root.`,
         `---`,
         prompt,

package/dist/infrastructure/orchestration/control/codex-control-surface.js

@@ -0,0 +1,99 @@
+/**
+ * CodexControlSurface · drives a running codex session via the app-server
+ * JSON-RPC protocol (newline-delimited over stdio). inject() = `turn/steer`,
+ * which pushes a message into the running turn.
+ *
+ * Under CODEHERE_MOCK=1 it spawns the mock app-server (zero API, no rate-limit);
+ * otherwise the real `codex app-server`. The protocol is identical — the real
+ * handshake was verified 2026-05-25; the mock lets us build + test the inject
+ * path without spending tokens or waiting on the rate-limit.
+ */
+import { spawn } from 'child_process';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { isMockMode } from '../mocks/resolve-agent-spawn.js';
+function serverSpawn() {
+    if (isMockMode()) {
+        // Env override lets tests point at the compiled dist mock (import.meta.url
+        // is the src .ts under vitest, where the .js sibling doesn't exist).
+        const mockPath = process.env.CODEHERE_MOCK_CODEX_SERVER ||
+            join(dirname(fileURLToPath(import.meta.url)), '..', 'mocks', 'mock-codex-app-server.js');
+        return { command: process.execPath, args: [mockPath] };
+    }
+    return { command: 'codex', args: ['app-server'] };
+}
+export class CodexControlSurface {
+    agentId = 'codex';
+    proc = null;
+    buf = '';
+    nextId = 1;
+    pending = new Map();
+    listeners = [];
+    threadId = '';
+    start() {
+        if (this.proc)
+            return;
+        const { command, args } = serverSpawn();
+        this.proc = spawn(command, args, { stdio: ['pipe', 'pipe', 'inherit'] });
+        this.proc.stdout?.on('data', (d) => this.onData(d.toString()));
+    }
+    onData(chunk) {
+        this.buf += chunk;
+        let nl;
+        while ((nl = this.buf.indexOf('\n')) >= 0) {
+            const line = this.buf.slice(0, nl).trim();
+            this.buf = this.buf.slice(nl + 1);
+            if (!line)
+                continue;
+            let m;
+            try {
+                m = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            if (typeof m.id === 'number' && this.pending.has(m.id)) {
+                this.pending.get(m.id)(m.result ?? m.error);
+                this.pending.delete(m.id);
+            }
+            else if (m.method) {
+                const evt = { method: m.method, params: m.params };
+                for (const cb of this.listeners)
+                    cb(evt);
+            }
+        }
+    }
+    rpc(method, params) {
+        this.start();
+        return new Promise((resolve) => {
+            const id = this.nextId++;
+            this.pending.set(id, resolve);
+            this.proc.stdin?.write(JSON.stringify({ jsonrpc: '2.0', id, method, params }) + '\n');
+        });
+    }
+    async open(prompt) {
+        await this.rpc('initialize', { clientInfo: { name: 'codehere', version: '0.6.2' } });
+        const th = (await this.rpc('thread/start', { cwd: process.cwd() }));
+        this.threadId = String(th?.thread_id ?? '');
+        // Fire the initial turn (don't await — it streams; inject() steers it).
+        void this.rpc('turn/start', { thread_id: this.threadId, input: prompt });
+        return { threadId: this.threadId };
+    }
+    async inject(message) {
+        const r = (await this.rpc('turn/steer', { thread_id: this.threadId, input: message }));
+        return { accepted: r?.accepted === true };
+    }
+    onEvent(cb) {
+        this.listeners.push(cb);
+    }
+    close() {
+        try {
+            this.proc?.kill();
+        }
+        catch {
+            /* best-effort */
+        }
+        this.proc = null;
+    }
+}
+//# sourceMappingURL=codex-control-surface.js.map

package/dist/infrastructure/orchestration/control/control-surface.js

@@ -0,0 +1,15 @@
+/**
+ * ControlSurface · the vendor-neutral "drive another agent" abstraction.
+ *
+ * The POC (agent/test/evidence/poc/control-channel/) proved the cross-agent
+ * finding: each agent exposes a DIFFERENT control surface (codex app-server
+ * turn/steer · claude --channels · etc.), so codehere's control layer is one
+ * interface implemented per-adapter — exactly the adapter pattern codehere
+ * already uses for spawning.
+ *
+ * `inject(message)` is the core primitive: push a message INTO a running agent
+ * session (the remote-control headline). Today: codex app-server. Next: claude
+ * channel.
+ */
+export {};
+//# sourceMappingURL=control-surface.js.map

package/dist/infrastructure/orchestration/gemini-adapter.js

@@ -29,6 +29,7 @@
  * Kills the process group (negative pid) so subagents under gemini exit too.
  */
 import { spawn, execFile, execFileSync } from 'child_process';
+import { startRecording } from './cassette-recorder.js';
 import { promisify } from 'util';
 const execFileAsync = promisify(execFile);
 import { EventEmitter } from 'events';
@@ -37,6 +38,7 @@ import { existsSync } from 'fs';
 import { homedir } from 'os';
 import { join } from 'path';
 import { ProgressAggregator } from './progress-aggregator.js';
+import { resolveAgentSpawn } from './mocks/resolve-agent-spawn.js';
 import { applyMemoryPrefix } from './memory-injector.js';
 import { mirrorToolCallToAudit } from '../hooks/mirror-tool-call-to-audit.js';
 import { snapshotCwd, extractArtifacts } from './artifacts-extractor.js';
@@ -247,7 +249,8 @@ export function spawnGemini(prompt, options = {}) {
     };
     let child;
     try {
-        child = spawn('gemini', ['-p', finalPrompt, ...HEADLESS_FLAGS, ...(options.extraArgs ?? [])], {
+        const sp = resolveAgentSpawn('gemini', 'gemini', ['-p', finalPrompt, ...HEADLESS_FLAGS, ...(options.extraArgs ?? [])], finalPrompt);
+        child = spawn(sp.command, sp.args, {
             cwd,
             env: spawnEnv,
             stdio: ['ignore', 'pipe', 'pipe'],
@@ -292,8 +295,13 @@ export function spawnGemini(prompt, options = {}) {
     // 'latest', NOT the UUID itself). See parseGeminiSessionIndexForUuid +
     // the appendMessage block below.
     let geminiSessionUuid = null;
+    // Organic cassette recording (S2b · capture-first plan) · no-op unless
+    // CODEHERE_RECORD_CASSETTES=1, so zero overhead by default.
+    const recorder = startRecording({ adapter: 'gemini', sessionId, prompt: finalPrompt, cwd });
     child.stdout?.on('data', (chunk) => {
-        stdoutBuf += chunk.toString('utf-8');
+        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();
@@ -314,6 +322,7 @@ export function spawnGemini(prompt, options = {}) {
     });
     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 } });
@@ -322,6 +331,7 @@ export function spawnGemini(prompt, options = {}) {
     // Use `close` (after all stdio has drained), not `exit` (which can fire while
     // unread stdout is still in-flight). Flush any final un-newlined buffered line.
     child.on('close', (code, signal) => {
+        recorder.onExit(code ?? -1, signal);
         if (stdoutBuf.trim()) {
             const line = stdoutBuf.trim();
             stdoutBuf = '';