@venturewild/workspace 0.1.11 → 0.1.13

package/server/src/agent.mjs

@@ -1,386 +1,386 @@
-// AI agent subprocess wrapper.
-// AR-17: wrap, don't embed. We spawn `claude` and stream its output — we never
-// embed an SDK or run our own agent loop.
-//
-// The stream-json parser is the heart of this file. `claude -p --output-format
-// stream-json --include-partial-messages` emits NDJSON where each line is one of:
-//   - {type:"system",...}            session init / status — ignored
-//   - {type:"rate_limit_event",...}  ignored
-//   - {type:"stream_event",event:{}} the Anthropic streaming protocol, wrapped.
-//                                    This is our PRIMARY source: real-time text
-//                                    deltas, tool-call name + streamed input.
-//   - {type:"assistant",message:{}}  the completed message — REDUNDANT with the
-//                                    stream events, used only as a fallback when
-//                                    --include-partial-messages is off.
-//   - {type:"user",message:{}}       carries tool_result blocks.
-//   - {type:"result",...}            final cost + usage + status.
-
-import { spawn } from 'node:child_process';
-import { promisify } from 'node:util';
-import { execFile as execFileCb } from 'node:child_process';
-import { EventEmitter } from 'node:events';
-import os from 'node:os';
-import fs from 'node:fs';
-import { DEFAULT_AGENTS } from './config.mjs';
-
-const execFile = promisify(execFileCb);
-
-const PATH_LOOKUP_TIMEOUT_MS = 1500;
-
-// Where `claude` (and other user-installed CLIs) actually live on macOS/Linux.
-// The native installer drops it in ~/.local/bin; Homebrew uses /opt/homebrew/bin
-// (Apple Silicon) or /usr/local/bin; our no-sudo npm prefix is ~/.npm-global/bin.
-function toolDirs(home = os.homedir()) {
-  return [`${home}/.local/bin`, '/opt/homebrew/bin', '/usr/local/bin', `${home}/.npm-global/bin`];
-}
-
-// GUI / launchd-launched processes inherit a MINIMAL PATH that omits all of the
-// above and never reads ~/.zshrc — so a server started by the macOS always-on
-// LaunchAgent can't find `claude` (spawn ENOENT). Idempotently add the real tool
-// dirs so detection + spawn work regardless of how the process was launched.
-export function ensureToolPath(env = process.env, { platform = process.platform, home = os.homedir() } = {}) {
-  if (platform === 'win32') return env.PATH; // HKCU\Run inherits the full user PATH
-  const have = (env.PATH || '').split(':').filter(Boolean);
-  const add = toolDirs(home).filter((d) => !have.includes(d));
-  if (add.length) env.PATH = [...have, ...add].join(':');
-  return env.PATH;
-}
-
-async function isOnPath(binary) {
-  ensureToolPath(); // make sure the tool dirs are on PATH before we look
-  const probe = process.platform === 'win32' ? 'where.exe' : 'which';
-  try {
-    const { stdout } = await execFile(probe, [binary], { timeout: PATH_LOOKUP_TIMEOUT_MS });
-    const lines = stdout.split(/\r?\n/).filter(Boolean);
-    if (lines.length > 0) return lines[0].trim();
-  } catch { /* fall through to a direct probe */ }
-  // which/where can still miss a freshly-installed binary in a stripped launchd
-  // environment — probe the known install dirs directly and return an ABSOLUTE
-  // path, which spawn uses verbatim (no PATH needed at spawn time).
-  if (process.platform !== 'win32') {
-    for (const dir of toolDirs()) {
-      const candidate = `${dir}/${binary}`;
-      try { fs.accessSync(candidate, fs.constants.X_OK); return candidate; } catch { /* next */ }
-    }
-  }
-  return null;
-}
-
-export async function detectAgents(candidates = DEFAULT_AGENTS) {
-  const results = await Promise.all(
-    candidates.map(async (agent) => {
-      const resolved = await isOnPath(agent.binary);
-      return { ...agent, available: Boolean(resolved), resolvedPath: resolved };
-    }),
-  );
-  return results;
-}
-
-/** Flatten a tool_result `content` field (string | array of blocks) to text. */
-function flattenContent(content) {
-  if (typeof content === 'string') return content;
-  if (Array.isArray(content)) {
-    return content
-      .map((c) => (typeof c === 'string' ? c : c?.text || ''))
-      .join('');
-  }
-  return '';
-}
-
-/**
- * Build the argv for one `claude -p` turn. Extracted from `send()` so the
- * resume / mode / add-dir logic is unit-testable without spawning a process.
- *
- *   - `resumeSessionId` : carries the conversation forward. Claude Code
- *     rehydrates the prior turns from this id, so the agent remembers what
- *     was already said. Absent on the first turn of a conversation.
- *   - `mode` : 'plan' is read-only proposing; anything else is 'build', which
- *     can create/edit files + run commands (PRD C3 posture — the user's own
- *     machine, own agent, own API bill).
- */
-export function buildClaudeArgs(baseArgs, ctx = {}) {
-  const args = [...baseArgs];
-  if (ctx.resumeSessionId) args.push('--resume', ctx.resumeSessionId);
-  if (ctx.cwd) args.push('--add-dir', ctx.cwd);
-  args.push('--permission-mode', ctx.mode === 'plan' ? 'plan' : 'bypassPermissions');
-  return args;
-}
-
-/**
- * AgentSession streams one chat turn through a wrapped subprocess.
- *
- * Lifecycle per AR-17:
- *   - one process per user turn (`claude -p` prints + exits)
- *   - emits 'chunk' — a normalized event the UI understands (see below)
- *   - emits 'stderr' on stderr output
- *   - emits 'end' on process exit with code
- *   - emits 'error' on spawn / runtime error
- *
- * Chunk protocol (the only contract the browser depends on):
- *   { type:'text',        text }                       streamed assistant text
- *   { type:'thinking',    text }                       streamed extended-thinking
- *   { type:'tool-use',    id, name, input }            a completed tool call
- *   { type:'tool-result', id, content, isError }       that tool's result
- *   { type:'usage',       usage:{...,cost_usd}, ... }   final cost + token usage
- *   { type:'error',       message }                    a run-level failure
- */
-export class AgentSession extends EventEmitter {
-  constructor(agent, opts = {}) {
-    super();
-    this.agent = agent;
-    this.opts = opts;
-    this.proc = null;
-    this.closed = false;
-    // The claude session id seen on this turn. The server reads it after the
-    // turn ends and passes it to the next turn as --resume, so the agent
-    // actually remembers the conversation.
-    this.sessionId = null;
-    // stream-json parse state — fresh per session (one session per turn)
-    this._buffer = '';
-    this._sawStreamEvent = false;
-    this._blocks = new Map(); // content-block index -> { kind, id, name, jsonBuf }
-  }
-
-  send(prompt, ctx = {}) {
-    if (this.closed) throw new Error('session closed');
-    // claude gets the full resume/mode/add-dir treatment; other agents (and
-    // the test echo agent) run with their bare args.
-    const args =
-      this.agent.id === 'claude'
-        ? buildClaudeArgs(this.agent.args, ctx)
-        : [...this.agent.args];
-    // Prefer the resolved absolute path from detection; fall back to the bare
-    // name. claude ships a native binary, so shell:false spawns cleanly.
-    const command = this.agent.resolvedPath || this.agent.binary;
-    this.proc = spawn(command, args, {
-      cwd: ctx.cwd || this.opts.cwd || process.cwd(),
-      env: { ...process.env, ...(ctx.env || {}) },
-      shell: false,
-      stdio: ['pipe', 'pipe', 'pipe'],
-      windowsHide: true,
-    });
-
-    this.proc.stdout.setEncoding('utf8');
-    this.proc.stderr.setEncoding('utf8');
-
-    const streamFormat = this.agent.streamFormat || 'text';
-
-    this.proc.stdout.on('data', (chunk) => this._handleStdout(chunk, streamFormat));
-    this.proc.stderr.on('data', (chunk) => this.emit('stderr', chunk));
-    this.proc.on('error', (err) => this.emit('error', err));
-    this.proc.on('close', (code) => {
-      this.emit('end', { code });
-      this.proc = null;
-    });
-
-    try {
-      this.proc.stdin.write(prompt);
-      this.proc.stdin.end();
-    } catch (e) {
-      this.emit('error', e);
-    }
-  }
-
-  _handleStdout(chunk, streamFormat) {
-    if (streamFormat !== 'claude-stream-json') {
-      // Plain-text agents (and the test echo agent) stream straight through.
-      this.emit('chunk', { type: 'text', text: chunk });
-      return;
-    }
-    this._buffer += chunk;
-    const lines = this._buffer.split('\n');
-    this._buffer = lines.pop() || '';
-    for (const line of lines) {
-      const trimmed = line.trim();
-      if (!trimmed) continue;
-      let evt;
-      try {
-        evt = JSON.parse(trimmed);
-      } catch {
-        // Non-JSON noise on stdout (rare). Drop it — don't pollute the chat.
-        continue;
-      }
-      this._handleClaudeEvent(evt);
-    }
-  }
-
-  _handleClaudeEvent(evt) {
-    if (!evt || typeof evt !== 'object') return;
-    // Every claude stream-json line carries the session id (the `system` init
-    // line and the final `result` both do). Capturing it lets the next turn
-    // --resume this exact conversation.
-    if (typeof evt.session_id === 'string') this.sessionId = evt.session_id;
-    switch (evt.type) {
-      case 'stream_event':
-        this._sawStreamEvent = true;
-        this._handleStreamEvent(evt.event);
-        return;
-      case 'assistant':
-        // Redundant with stream_event when --include-partial-messages is on
-        // (it always is). Only the fallback path when partials are disabled.
-        if (!this._sawStreamEvent) this._handleAssistantFallback(evt.message);
-        return;
-      case 'user':
-        this._handleToolResults(evt.message);
-        return;
-      case 'result':
-        this._handleResult(evt);
-        return;
-      case 'error':
-        this.emit('chunk', {
-          type: 'error',
-          message: evt.message || evt.error?.message || 'agent error',
-        });
-        return;
-      default:
-        // system, rate_limit_event, anything new — ignored.
-        return;
-    }
-  }
-
-  /** The wrapped Anthropic streaming protocol — our real-time source. */
-  _handleStreamEvent(ev) {
-    if (!ev || typeof ev !== 'object') return;
-    switch (ev.type) {
-      case 'content_block_start': {
-        const cb = ev.content_block || {};
-        if (cb.type === 'tool_use') {
-          // Tool input arrives as input_json_delta fragments — buffer them
-          // until content_block_stop, then emit one complete tool-use chunk.
-          this._blocks.set(ev.index, {
-            kind: 'tool',
-            id: cb.id,
-            name: cb.name,
-            jsonBuf: '',
-          });
-        } else {
-          this._blocks.set(ev.index, { kind: cb.type || 'text' });
-        }
-        return;
-      }
-      case 'content_block_delta': {
-        const d = ev.delta || {};
-        if (d.type === 'text_delta' && d.text) {
-          this.emit('chunk', { type: 'text', text: d.text });
-        } else if (d.type === 'thinking_delta' && d.thinking) {
-          this.emit('chunk', { type: 'thinking', text: d.thinking });
-        } else if (d.type === 'input_json_delta') {
-          const blk = this._blocks.get(ev.index);
-          if (blk && blk.kind === 'tool') blk.jsonBuf += d.partial_json || '';
-        }
-        return;
-      }
-      case 'content_block_stop': {
-        const blk = this._blocks.get(ev.index);
-        if (blk && blk.kind === 'tool') {
-          let input = {};
-          try {
-            input = blk.jsonBuf ? JSON.parse(blk.jsonBuf) : {};
-          } catch {
-            input = { _raw: blk.jsonBuf };
-          }
-          this.emit('chunk', {
-            type: 'tool-use',
-            id: blk.id,
-            name: blk.name,
-            input,
-          });
-        }
-        this._blocks.delete(ev.index);
-        return;
-      }
-      default:
-        // message_start / message_delta / message_stop — no UI effect.
-        return;
-    }
-  }
-
-  /** Fallback for `--include-partial-messages` off: parse the whole message. */
-  _handleAssistantFallback(message) {
-    const content = message?.content;
-    if (typeof content === 'string') {
-      if (content) this.emit('chunk', { type: 'text', text: content });
-      return;
-    }
-    if (!Array.isArray(content)) return;
-    for (const block of content) {
-      if (block.type === 'text' && block.text) {
-        this.emit('chunk', { type: 'text', text: block.text });
-      } else if (block.type === 'thinking' && block.thinking) {
-        this.emit('chunk', { type: 'thinking', text: block.thinking });
-      } else if (block.type === 'tool_use') {
-        this.emit('chunk', {
-          type: 'tool-use',
-          id: block.id,
-          name: block.name,
-          input: block.input || {},
-        });
-      }
-    }
-  }
-
-  /** `user` events carry tool_result blocks — match them back to a tool card. */
-  _handleToolResults(message) {
-    const content = message?.content;
-    if (!Array.isArray(content)) return;
-    for (const block of content) {
-      if (block.type === 'tool_result') {
-        this.emit('chunk', {
-          type: 'tool-result',
-          id: block.tool_use_id,
-          content: flattenContent(block.content),
-          isError: block.is_error === true,
-        });
-      }
-    }
-  }
-
-  /** The final `result` event — authoritative cost + usage for the turn. */
-  _handleResult(evt) {
-    const u = evt.usage || {};
-    this.emit('chunk', {
-      type: 'usage',
-      usage: {
-        input_tokens: u.input_tokens || 0,
-        output_tokens: u.output_tokens || 0,
-        cache_read_input_tokens: u.cache_read_input_tokens || 0,
-        // cost_usd lives here so the ActivityBus can accumulate it directly.
-        cost_usd: typeof evt.total_cost_usd === 'number' ? evt.total_cost_usd : 0,
-      },
-      durationMs: evt.duration_ms,
-      numTurns: evt.num_turns,
-    });
-    if (evt.is_error || (evt.subtype && evt.subtype !== 'success')) {
-      this.emit('chunk', {
-        type: 'error',
-        message:
-          (typeof evt.result === 'string' && evt.result) ||
-          evt.subtype ||
-          'agent run failed',
-      });
-    }
-  }
-
-  cancel() {
-    if (this.proc && !this.proc.killed) {
-      try {
-        this.proc.kill();
-      } catch {}
-    }
-  }
-
-  close() {
-    this.closed = true;
-    this.cancel();
-  }
-}
-
-export function pickDefaultAgent(detected) {
-  // Prefer claude; fall back to first available; fall back to claude (assume
-  // it'll be installed — the UI shows an install hint when it isn't).
-  const claude = detected.find((a) => a.id === 'claude' && a.available);
-  if (claude) return claude;
-  const anyAvailable = detected.find((a) => a.available);
-  if (anyAvailable) return anyAvailable;
-  return detected[0] || DEFAULT_AGENTS[0];
-}
+// AI agent subprocess wrapper.
+// AR-17: wrap, don't embed. We spawn `claude` and stream its output — we never
+// embed an SDK or run our own agent loop.
+//
+// The stream-json parser is the heart of this file. `claude -p --output-format
+// stream-json --include-partial-messages` emits NDJSON where each line is one of:
+//   - {type:"system",...}            session init / status — ignored
+//   - {type:"rate_limit_event",...}  ignored
+//   - {type:"stream_event",event:{}} the Anthropic streaming protocol, wrapped.
+//                                    This is our PRIMARY source: real-time text
+//                                    deltas, tool-call name + streamed input.
+//   - {type:"assistant",message:{}}  the completed message — REDUNDANT with the
+//                                    stream events, used only as a fallback when
+//                                    --include-partial-messages is off.
+//   - {type:"user",message:{}}       carries tool_result blocks.
+//   - {type:"result",...}            final cost + usage + status.
+
+import { spawn } from 'node:child_process';
+import { promisify } from 'node:util';
+import { execFile as execFileCb } from 'node:child_process';
+import { EventEmitter } from 'node:events';
+import os from 'node:os';
+import fs from 'node:fs';
+import { DEFAULT_AGENTS } from './config.mjs';
+
+const execFile = promisify(execFileCb);
+
+const PATH_LOOKUP_TIMEOUT_MS = 1500;
+
+// Where `claude` (and other user-installed CLIs) actually live on macOS/Linux.
+// The native installer drops it in ~/.local/bin; Homebrew uses /opt/homebrew/bin
+// (Apple Silicon) or /usr/local/bin; our no-sudo npm prefix is ~/.npm-global/bin.
+function toolDirs(home = os.homedir()) {
+  return [`${home}/.local/bin`, '/opt/homebrew/bin', '/usr/local/bin', `${home}/.npm-global/bin`];
+}
+
+// GUI / launchd-launched processes inherit a MINIMAL PATH that omits all of the
+// above and never reads ~/.zshrc — so a server started by the macOS always-on
+// LaunchAgent can't find `claude` (spawn ENOENT). Idempotently add the real tool
+// dirs so detection + spawn work regardless of how the process was launched.
+export function ensureToolPath(env = process.env, { platform = process.platform, home = os.homedir() } = {}) {
+  if (platform === 'win32') return env.PATH; // HKCU\Run inherits the full user PATH
+  const have = (env.PATH || '').split(':').filter(Boolean);
+  const add = toolDirs(home).filter((d) => !have.includes(d));
+  if (add.length) env.PATH = [...have, ...add].join(':');
+  return env.PATH;
+}
+
+async function isOnPath(binary) {
+  ensureToolPath(); // make sure the tool dirs are on PATH before we look
+  const probe = process.platform === 'win32' ? 'where.exe' : 'which';
+  try {
+    const { stdout } = await execFile(probe, [binary], { timeout: PATH_LOOKUP_TIMEOUT_MS });
+    const lines = stdout.split(/\r?\n/).filter(Boolean);
+    if (lines.length > 0) return lines[0].trim();
+  } catch { /* fall through to a direct probe */ }
+  // which/where can still miss a freshly-installed binary in a stripped launchd
+  // environment — probe the known install dirs directly and return an ABSOLUTE
+  // path, which spawn uses verbatim (no PATH needed at spawn time).
+  if (process.platform !== 'win32') {
+    for (const dir of toolDirs()) {
+      const candidate = `${dir}/${binary}`;
+      try { fs.accessSync(candidate, fs.constants.X_OK); return candidate; } catch { /* next */ }
+    }
+  }
+  return null;
+}
+
+export async function detectAgents(candidates = DEFAULT_AGENTS) {
+  const results = await Promise.all(
+    candidates.map(async (agent) => {
+      const resolved = await isOnPath(agent.binary);
+      return { ...agent, available: Boolean(resolved), resolvedPath: resolved };
+    }),
+  );
+  return results;
+}
+
+/** Flatten a tool_result `content` field (string | array of blocks) to text. */
+function flattenContent(content) {
+  if (typeof content === 'string') return content;
+  if (Array.isArray(content)) {
+    return content
+      .map((c) => (typeof c === 'string' ? c : c?.text || ''))
+      .join('');
+  }
+  return '';
+}
+
+/**
+ * Build the argv for one `claude -p` turn. Extracted from `send()` so the
+ * resume / mode / add-dir logic is unit-testable without spawning a process.
+ *
+ *   - `resumeSessionId` : carries the conversation forward. Claude Code
+ *     rehydrates the prior turns from this id, so the agent remembers what
+ *     was already said. Absent on the first turn of a conversation.
+ *   - `mode` : 'plan' is read-only proposing; anything else is 'build', which
+ *     can create/edit files + run commands (PRD C3 posture — the user's own
+ *     machine, own agent, own API bill).
+ */
+export function buildClaudeArgs(baseArgs, ctx = {}) {
+  const args = [...baseArgs];
+  if (ctx.resumeSessionId) args.push('--resume', ctx.resumeSessionId);
+  if (ctx.cwd) args.push('--add-dir', ctx.cwd);
+  args.push('--permission-mode', ctx.mode === 'plan' ? 'plan' : 'bypassPermissions');
+  return args;
+}
+
+/**
+ * AgentSession streams one chat turn through a wrapped subprocess.
+ *
+ * Lifecycle per AR-17:
+ *   - one process per user turn (`claude -p` prints + exits)
+ *   - emits 'chunk' — a normalized event the UI understands (see below)
+ *   - emits 'stderr' on stderr output
+ *   - emits 'end' on process exit with code
+ *   - emits 'error' on spawn / runtime error
+ *
+ * Chunk protocol (the only contract the browser depends on):
+ *   { type:'text',        text }                       streamed assistant text
+ *   { type:'thinking',    text }                       streamed extended-thinking
+ *   { type:'tool-use',    id, name, input }            a completed tool call
+ *   { type:'tool-result', id, content, isError }       that tool's result
+ *   { type:'usage',       usage:{...,cost_usd}, ... }   final cost + token usage
+ *   { type:'error',       message }                    a run-level failure
+ */
+export class AgentSession extends EventEmitter {
+  constructor(agent, opts = {}) {
+    super();
+    this.agent = agent;
+    this.opts = opts;
+    this.proc = null;
+    this.closed = false;
+    // The claude session id seen on this turn. The server reads it after the
+    // turn ends and passes it to the next turn as --resume, so the agent
+    // actually remembers the conversation.
+    this.sessionId = null;
+    // stream-json parse state — fresh per session (one session per turn)
+    this._buffer = '';
+    this._sawStreamEvent = false;
+    this._blocks = new Map(); // content-block index -> { kind, id, name, jsonBuf }
+  }
+
+  send(prompt, ctx = {}) {
+    if (this.closed) throw new Error('session closed');
+    // claude gets the full resume/mode/add-dir treatment; other agents (and
+    // the test echo agent) run with their bare args.
+    const args =
+      this.agent.id === 'claude'
+        ? buildClaudeArgs(this.agent.args, ctx)
+        : [...this.agent.args];
+    // Prefer the resolved absolute path from detection; fall back to the bare
+    // name. claude ships a native binary, so shell:false spawns cleanly.
+    const command = this.agent.resolvedPath || this.agent.binary;
+    this.proc = spawn(command, args, {
+      cwd: ctx.cwd || this.opts.cwd || process.cwd(),
+      env: { ...process.env, ...(ctx.env || {}) },
+      shell: false,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      windowsHide: true,
+    });
+
+    this.proc.stdout.setEncoding('utf8');
+    this.proc.stderr.setEncoding('utf8');
+
+    const streamFormat = this.agent.streamFormat || 'text';
+
+    this.proc.stdout.on('data', (chunk) => this._handleStdout(chunk, streamFormat));
+    this.proc.stderr.on('data', (chunk) => this.emit('stderr', chunk));
+    this.proc.on('error', (err) => this.emit('error', err));
+    this.proc.on('close', (code) => {
+      this.emit('end', { code });
+      this.proc = null;
+    });
+
+    try {
+      this.proc.stdin.write(prompt);
+      this.proc.stdin.end();
+    } catch (e) {
+      this.emit('error', e);
+    }
+  }
+
+  _handleStdout(chunk, streamFormat) {
+    if (streamFormat !== 'claude-stream-json') {
+      // Plain-text agents (and the test echo agent) stream straight through.
+      this.emit('chunk', { type: 'text', text: chunk });
+      return;
+    }
+    this._buffer += chunk;
+    const lines = this._buffer.split('\n');
+    this._buffer = lines.pop() || '';
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      let evt;
+      try {
+        evt = JSON.parse(trimmed);
+      } catch {
+        // Non-JSON noise on stdout (rare). Drop it — don't pollute the chat.
+        continue;
+      }
+      this._handleClaudeEvent(evt);
+    }
+  }
+
+  _handleClaudeEvent(evt) {
+    if (!evt || typeof evt !== 'object') return;
+    // Every claude stream-json line carries the session id (the `system` init
+    // line and the final `result` both do). Capturing it lets the next turn
+    // --resume this exact conversation.
+    if (typeof evt.session_id === 'string') this.sessionId = evt.session_id;
+    switch (evt.type) {
+      case 'stream_event':
+        this._sawStreamEvent = true;
+        this._handleStreamEvent(evt.event);
+        return;
+      case 'assistant':
+        // Redundant with stream_event when --include-partial-messages is on
+        // (it always is). Only the fallback path when partials are disabled.
+        if (!this._sawStreamEvent) this._handleAssistantFallback(evt.message);
+        return;
+      case 'user':
+        this._handleToolResults(evt.message);
+        return;
+      case 'result':
+        this._handleResult(evt);
+        return;
+      case 'error':
+        this.emit('chunk', {
+          type: 'error',
+          message: evt.message || evt.error?.message || 'agent error',
+        });
+        return;
+      default:
+        // system, rate_limit_event, anything new — ignored.
+        return;
+    }
+  }
+
+  /** The wrapped Anthropic streaming protocol — our real-time source. */
+  _handleStreamEvent(ev) {
+    if (!ev || typeof ev !== 'object') return;
+    switch (ev.type) {
+      case 'content_block_start': {
+        const cb = ev.content_block || {};
+        if (cb.type === 'tool_use') {
+          // Tool input arrives as input_json_delta fragments — buffer them
+          // until content_block_stop, then emit one complete tool-use chunk.
+          this._blocks.set(ev.index, {
+            kind: 'tool',
+            id: cb.id,
+            name: cb.name,
+            jsonBuf: '',
+          });
+        } else {
+          this._blocks.set(ev.index, { kind: cb.type || 'text' });
+        }
+        return;
+      }
+      case 'content_block_delta': {
+        const d = ev.delta || {};
+        if (d.type === 'text_delta' && d.text) {
+          this.emit('chunk', { type: 'text', text: d.text });
+        } else if (d.type === 'thinking_delta' && d.thinking) {
+          this.emit('chunk', { type: 'thinking', text: d.thinking });
+        } else if (d.type === 'input_json_delta') {
+          const blk = this._blocks.get(ev.index);
+          if (blk && blk.kind === 'tool') blk.jsonBuf += d.partial_json || '';
+        }
+        return;
+      }
+      case 'content_block_stop': {
+        const blk = this._blocks.get(ev.index);
+        if (blk && blk.kind === 'tool') {
+          let input = {};
+          try {
+            input = blk.jsonBuf ? JSON.parse(blk.jsonBuf) : {};
+          } catch {
+            input = { _raw: blk.jsonBuf };
+          }
+          this.emit('chunk', {
+            type: 'tool-use',
+            id: blk.id,
+            name: blk.name,
+            input,
+          });
+        }
+        this._blocks.delete(ev.index);
+        return;
+      }
+      default:
+        // message_start / message_delta / message_stop — no UI effect.
+        return;
+    }
+  }
+
+  /** Fallback for `--include-partial-messages` off: parse the whole message. */
+  _handleAssistantFallback(message) {
+    const content = message?.content;
+    if (typeof content === 'string') {
+      if (content) this.emit('chunk', { type: 'text', text: content });
+      return;
+    }
+    if (!Array.isArray(content)) return;
+    for (const block of content) {
+      if (block.type === 'text' && block.text) {
+        this.emit('chunk', { type: 'text', text: block.text });
+      } else if (block.type === 'thinking' && block.thinking) {
+        this.emit('chunk', { type: 'thinking', text: block.thinking });
+      } else if (block.type === 'tool_use') {
+        this.emit('chunk', {
+          type: 'tool-use',
+          id: block.id,
+          name: block.name,
+          input: block.input || {},
+        });
+      }
+    }
+  }
+
+  /** `user` events carry tool_result blocks — match them back to a tool card. */
+  _handleToolResults(message) {
+    const content = message?.content;
+    if (!Array.isArray(content)) return;
+    for (const block of content) {
+      if (block.type === 'tool_result') {
+        this.emit('chunk', {
+          type: 'tool-result',
+          id: block.tool_use_id,
+          content: flattenContent(block.content),
+          isError: block.is_error === true,
+        });
+      }
+    }
+  }
+
+  /** The final `result` event — authoritative cost + usage for the turn. */
+  _handleResult(evt) {
+    const u = evt.usage || {};
+    this.emit('chunk', {
+      type: 'usage',
+      usage: {
+        input_tokens: u.input_tokens || 0,
+        output_tokens: u.output_tokens || 0,
+        cache_read_input_tokens: u.cache_read_input_tokens || 0,
+        // cost_usd lives here so the ActivityBus can accumulate it directly.
+        cost_usd: typeof evt.total_cost_usd === 'number' ? evt.total_cost_usd : 0,
+      },
+      durationMs: evt.duration_ms,
+      numTurns: evt.num_turns,
+    });
+    if (evt.is_error || (evt.subtype && evt.subtype !== 'success')) {
+      this.emit('chunk', {
+        type: 'error',
+        message:
+          (typeof evt.result === 'string' && evt.result) ||
+          evt.subtype ||
+          'agent run failed',
+      });
+    }
+  }
+
+  cancel() {
+    if (this.proc && !this.proc.killed) {
+      try {
+        this.proc.kill();
+      } catch {}
+    }
+  }
+
+  close() {
+    this.closed = true;
+    this.cancel();
+  }
+}
+
+export function pickDefaultAgent(detected) {
+  // Prefer claude; fall back to first available; fall back to claude (assume
+  // it'll be installed — the UI shows an install hint when it isn't).
+  const claude = detected.find((a) => a.id === 'claude' && a.available);
+  if (claude) return claude;
+  const anyAvailable = detected.find((a) => a.available);
+  if (anyAvailable) return anyAvailable;
+  return detected[0] || DEFAULT_AGENTS[0];
+}