@axplusb/kepler 1.0.10 → 2.0.0

package/src/core/tool-executor.mjs

@@ -28,6 +28,7 @@ import { execSync } from 'node:child_process';
 export function createToolExecutor({
     projectRegistry = new ProjectRegistry(),
     skillsLoader = new SkillsLoader().load(process.cwd()),
+    checkpoints = null,
 } = {}) {
     const occRegistry = createToolRegistry();
     const skillTool = occRegistry.get('Skill');
@@ -132,6 +133,30 @@ export function createToolExecutor({
         return parts.length ? `\n--- Verify ---\n${parts.join('\n')}` : '';
     }
 
+    // ── Solution nudge after exploration ───────────────────────
+    // After the agent has read enough code, nudge it to formulate
+    // a solution based on the goal — not to blindly edit, but to
+    // synthesize what it learned into a fix approach.
+    let _codeReadsCount = 0;
+    let _hasEdited = false;
+
+    function solutionNudge(filePath) {
+        const ext = path.extname(filePath).toLowerCase();
+        const isCode = ['.py', '.js', '.ts', '.tsx', '.mjs', '.go', '.rs', '.java', '.rb'].includes(ext);
+        if (!isCode || _hasEdited) return '';
+
+        _codeReadsCount++;
+        if (_codeReadsCount < 4) return '';
+
+        // Only nudge once at threshold, not every read after
+        if (_codeReadsCount === 4) {
+            return '\n\n--- You have explored enough code to formulate a solution. ' +
+                'Based on what you have read, determine the fix and apply it. ' +
+                'If the approach is unclear, call plan() with your findings. ---';
+        }
+        return '';
+    }
+
     // ── Tool mapping table ──────────────────────────────────────
 
     const toolMap = {
@@ -258,10 +283,11 @@ export function createToolExecutor({
             });
             const output = typeof result === 'string' ? result : String(result);
             const content = output.replace(/^\s*\d+[→\t]/gm, '');
+            const actNudge = solutionNudge(filePath);
             return {
                 success: !isError(output),
                 content,
-                output: output + nudge,
+                output: output + nudge + actNudge,
                 _tool: 'read_file',
                 _output_type: 'file_content',
             };
@@ -284,6 +310,10 @@ export function createToolExecutor({
                     await occRegistry.call('Read', { file_path: filePath, limit: 1 });
                 }
             } catch { /* file may not exist yet */ }
+            // Checkpoint before overwrite so /undo can restore the previous content.
+            if (checkpoints && fs.existsSync(filePath)) {
+                try { checkpoints.save(filePath); } catch { /* best effort */ }
+            }
             const result = await occRegistry.call('Write', {
                 file_path: filePath,
                 content: args.content,
@@ -380,6 +410,11 @@ export function createToolExecutor({
                 await occRegistry.call('Read', { file_path: filePath, limit: 1 });
             } catch { /* best effort */ }
 
+            // Checkpoint before edit so /undo can restore the previous content.
+            if (checkpoints) {
+                try { checkpoints.save(filePath); } catch { /* best effort */ }
+            }
+
             let result;
             try {
                 result = await occRegistry.call('Edit', {
@@ -418,6 +453,7 @@ print('OK: replaced')
 
             const wrapped = wrapResult(result, 'edit_file');
             updateProjectIndex(filePath);
+            _hasEdited = true;
 
             // Auto-lint the edited file
             const lintOutput = autoLint(filePath);
@@ -484,9 +520,16 @@ print('OK: replaced')
                 }
             } catch { /* rg not found or no results */ }
 
-            // Layer 2: BM25 — semantic relevance (finds related code even without exact match)
+            // Layer 2: Symbol search — AST-extracted functions/classes with signatures
             if (project?.retriever) {
                 if (!project.retriever.index) project.retriever.loadIndex();
+                const symbols = project.retriever.searchSymbols(query, 5);
+                if (symbols.length > 0) {
+                    const symOutput = project.retriever.formatSymbolResults(symbols);
+                    parts.push(`## Symbols (functions/classes)\n${symOutput}`);
+                }
+
+                // Layer 3: BM25 chunks — broader context when symbols aren't enough
                 const chunks = project.retriever.retrieve(query, 5);
                 if (chunks.length > 0) {
                     const bm25Output = chunks.map(c => {
@@ -609,7 +652,7 @@ print('OK: replaced')
             return { success: true, files: results, _tool: 'read_files' };
         },
 
-        // 9. delete_file + safety check
+        // 9. delete_file + safety check + checkpoint for undo
         delete_file: async (args) => {
             try {
                 const filePath = resolvePath(args.file_path || args.path, args);
@@ -617,6 +660,9 @@ print('OK: replaced')
                 if (!delCheck.safe) {
                     return { success: false, output: `🛡️ BLOCKED: ${delCheck.reason}`, _tool: 'delete_file', _blocked: true };
                 }
+                if (checkpoints) {
+                    try { checkpoints.save(filePath); } catch { /* best effort */ }
+                }
                 fs.unlinkSync(filePath);
                 updateProjectIndex(filePath);
                 return { success: true, message: `Deleted ${args.path}`, _tool: 'delete_file' };

package/src/onboarding/preflight.mjs

@@ -0,0 +1,274 @@
+/**
+ * Preflight diagnostic — Mission Control (PRD-055 §9).
+ *
+ * Prints a non-blocking summary of the runtime environment before the REPL
+ * starts so the user can see what is and is not aligned:
+ *
+ *   🔭 Kepler v1.0.4 · initializing orbit
+ *
+ *     [✓] Auth token
+ *     [✓] OpenRouter key
+ *     [✓] Backend  http://127.0.0.1:8000
+ *     [✓] Git repository  main · clean
+ *     [⚠] Linter (ruff) not found → /install ruff to enable lint_check
+ *     [✓] Project map  142 files, Python + TypeScript
+ *
+ *   All systems aligned. What are we building today?
+ *
+ * Checks are non-blocking. A failure shows a one-line next-step hint.
+ *
+ * Exposed via `runPreflight()` (called from REPL startup) and `/preflight`
+ * (registered as a slash command).
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { execSync } from 'node:child_process';
+import http from 'node:http';
+import https from 'node:https';
+import { URL } from 'node:url';
+import { paint } from '../ui/palette.mjs';
+import { icons } from '../ui/icons.mjs';
+import { term } from '../ui/term.mjs';
+
+const OK   = (s) => `${paint.state.success('[✓]')} ${s}`;
+const WARN = (s) => `${paint.state.warn('[⚠]')} ${s}`;
+const FAIL = (s) => `${paint.state.danger('[✗]')} ${s}`;
+
+// ── Individual checks (each returns { status, label, hint? }) ──────────
+
+function checkAuthToken(auth) {
+  const creds = auth.loadCredentials();
+  if (creds.token) return { status: 'ok', label: `Auth token` };
+  return { status: 'warn', label: 'Auth token missing', hint: '/login to sign in' };
+}
+
+function checkProviderKey(auth) {
+  const creds = auth.loadCredentials();
+  if (creds.openRouterKey) return { status: 'ok', label: 'OpenRouter key' };
+  if (creds.anthropicKey)  return { status: 'ok', label: 'Anthropic key' };
+  if (creds.openaiKey)     return { status: 'ok', label: 'OpenAI key' };
+  if (creds.googleKey)     return { status: 'ok', label: 'Google key' };
+  return { status: 'warn', label: 'No model provider key configured', hint: 'set OPENROUTER_API_KEY or run /config' };
+}
+
+async function checkBackend(auth, { timeoutMs = 1500 } = {}) {
+  const creds = auth.loadCredentials();
+  const url = creds.backendUrl;
+  if (!url) return { status: 'warn', label: 'Backend not configured' };
+  try {
+    const reachable = await ping(url, timeoutMs);
+    if (reachable) return { status: 'ok', label: `Backend  ${shorten(url, 48)}` };
+    return { status: 'warn', label: `Backend  ${shorten(url, 48)}`, hint: 'unreachable — check network or start backend' };
+  } catch {
+    return { status: 'warn', label: `Backend  ${shorten(url, 48)}`, hint: 'unreachable' };
+  }
+}
+
+function checkGit(cwd) {
+  if (!hasGitDir(cwd)) return { status: 'warn', label: 'Not a git repository', hint: '`git init` to enable diff / checkpoints' };
+  try {
+    const branch = execSync('git rev-parse --abbrev-ref HEAD 2>/dev/null', { cwd, encoding: 'utf-8' }).trim();
+    const status = execSync('git status --porcelain 2>/dev/null', { cwd, encoding: 'utf-8' });
+    const dirty = status.split('\n').filter(Boolean).length;
+    const summary = dirty > 0
+      ? `${branch} · ${paint.state.warn(`${dirty} dirty`)}`
+      : `${branch} · clean`;
+    return { status: 'ok', label: `Git repository  ${summary}` };
+  } catch {
+    return { status: 'warn', label: 'Git repository present but unreadable' };
+  }
+}
+
+function checkLinters(cwd) {
+  const present = [];
+  const missing = [];
+  for (const [name, kind] of LINTERS) {
+    if (which(name)) present.push({ name, kind });
+    else if (projectUses(cwd, kind)) missing.push({ name, kind });
+  }
+  if (present.length === 0 && missing.length === 0) {
+    return { status: 'ok', label: 'Linters  none required' };
+  }
+  if (missing.length === 0) {
+    return { status: 'ok', label: `Linters  ${present.map(p => p.name).join(', ')}` };
+  }
+  const hint = missing.map(m => `/install ${m.name} to enable lint_check for ${m.kind}`).join(' · ');
+  return { status: 'warn', label: `Linter (${missing.map(m => m.name).join(', ')}) not found`, hint };
+}
+
+const LINTERS = [
+  ['ruff',    'python'],
+  ['eslint',  'javascript'],
+  ['tsc',     'typescript'],
+  ['cargo',   'rust'],
+];
+
+function projectUses(cwd, kind) {
+  try {
+    const files = fs.readdirSync(cwd);
+    switch (kind) {
+      case 'python':     return files.some(f => /\.py$/.test(f)) || files.includes('pyproject.toml') || files.includes('requirements.txt');
+      case 'javascript': return files.includes('package.json');
+      case 'typescript': return files.includes('tsconfig.json');
+      case 'rust':       return files.includes('Cargo.toml');
+      default:           return false;
+    }
+  } catch { return false; }
+}
+
+function checkProjectMap(cwd) {
+  try {
+    const counts = quickFileCount(cwd, { max: 5000 });
+    if (!counts.total) return { status: 'warn', label: 'Project map  no files indexed yet' };
+    const langs = topLanguages(counts.byExt, 2);
+    const langStr = langs.length ? langs.join(' + ') : 'mixed';
+    return { status: 'ok', label: `Project map  ${counts.total} files, ${langStr}` };
+  } catch {
+    return { status: 'warn', label: 'Project map  unreadable' };
+  }
+}
+
+// ── Helpers ─────────────────────────────────────────────────────────────
+
+function shorten(s, n) {
+  const str = String(s || '');
+  return str.length <= n ? str : str.slice(0, n - 1) + '…';
+}
+
+function hasGitDir(cwd) {
+  let dir = cwd;
+  for (let i = 0; i < 6; i++) {
+    if (fs.existsSync(path.join(dir, '.git'))) return true;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return false;
+}
+
+function which(name) {
+  try {
+    execSync(`command -v ${name}`, { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] });
+    return true;
+  } catch { return false; }
+}
+
+function ping(url, timeoutMs) {
+  return new Promise((resolve) => {
+    let u;
+    try { u = new URL(url); } catch { resolve(false); return; }
+    const lib = u.protocol === 'https:' ? https : http;
+    const req = lib.request({
+      hostname: u.hostname,
+      port: u.port || (u.protocol === 'https:' ? 443 : 80),
+      path: u.pathname || '/',
+      method: 'GET',
+      timeout: timeoutMs,
+    }, (res) => {
+      // Any response means the host is reachable, even 404.
+      res.resume();
+      resolve(true);
+    });
+    req.on('error', () => resolve(false));
+    req.on('timeout', () => { try { req.destroy(); } catch {} resolve(false); });
+    req.end();
+  });
+}
+
+const EXT_TO_LANG = {
+  '.py': 'Python', '.ts': 'TypeScript', '.tsx': 'TypeScript', '.js': 'JavaScript',
+  '.jsx': 'JavaScript', '.mjs': 'JavaScript', '.go': 'Go', '.rs': 'Rust',
+  '.java': 'Java', '.rb': 'Ruby', '.php': 'PHP', '.swift': 'Swift', '.kt': 'Kotlin',
+  '.c': 'C', '.cc': 'C++', '.cpp': 'C++', '.h': 'C/C++', '.hpp': 'C++',
+};
+
+function topLanguages(byExt, n) {
+  const ranked = Object.entries(byExt)
+    .map(([ext, count]) => [EXT_TO_LANG[ext], count])
+    .filter(([lang]) => lang)
+    .reduce((acc, [lang, count]) => { acc.set(lang, (acc.get(lang) || 0) + count); return acc; }, new Map());
+  return [...ranked.entries()]
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, n)
+    .map(([lang]) => lang);
+}
+
+function quickFileCount(cwd, { max = 5000 } = {}) {
+  // Shallow walk: skip node_modules, .git, dist, build, .venv, __pycache__.
+  const SKIP = new Set(['node_modules', '.git', 'dist', 'build', '.next', '.venv', 'venv', '__pycache__', '.kepler', '.terraform']);
+  const byExt = {};
+  let total = 0;
+  const stack = [cwd];
+  while (stack.length && total < max) {
+    const dir = stack.pop();
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); }
+    catch { continue; }
+    for (const e of entries) {
+      if (e.name.startsWith('.') && e.name !== '.kepler') continue;
+      if (SKIP.has(e.name)) continue;
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) stack.push(full);
+      else if (e.isFile()) {
+        total++;
+        const ext = path.extname(e.name).toLowerCase();
+        if (ext) byExt[ext] = (byExt[ext] || 0) + 1;
+        if (total >= max) break;
+      }
+    }
+  }
+  return { total, byExt };
+}
+
+// ── Renderer ────────────────────────────────────────────────────────────
+
+function formatRow(check) {
+  switch (check.status) {
+    case 'ok':   return `  ${OK(paint.text.primary(check.label))}`;
+    case 'warn': return `  ${WARN(paint.text.primary(check.label))}` +
+                        (check.hint ? `  ${paint.text.dim('→ ' + check.hint)}` : '');
+    case 'fail': return `  ${FAIL(paint.text.primary(check.label))}` +
+                        (check.hint ? `  ${paint.text.dim('→ ' + check.hint)}` : '');
+    default:     return `  ${paint.text.dim(check.label)}`;
+  }
+}
+
+/**
+ * Run the preflight diagnostic. Writes to stderr and resolves with the
+ * collected check results.
+ *
+ * @param {object} opts
+ * @param {object} opts.auth        — TarangAuth instance
+ * @param {string} opts.cwd         — working directory
+ * @param {string} opts.version     — package version string
+ * @param {boolean} [opts.silent]   — if true, do not write (useful for tests)
+ */
+export async function runPreflight({ auth, cwd, version, silent = false } = {}) {
+  const t = term();
+  const write = (s) => { if (!silent) process.stderr.write(s); };
+
+  const header = `${icons.search} ${paint.bold(paint.brand.primary('Kepler v' + (version || '?')))} ${paint.text.dim('· initializing orbit')}`;
+  write('\n' + header + '\n\n');
+
+  const checks = [];
+  checks.push(checkAuthToken(auth));
+  checks.push(checkProviderKey(auth));
+  checks.push(await checkBackend(auth));
+  checks.push(checkGit(cwd));
+  checks.push(checkLinters(cwd));
+  checks.push(checkProjectMap(cwd));
+
+  for (const c of checks) write(formatRow(c) + '\n');
+
+  const fails = checks.filter(c => c.status === 'fail').length;
+  const warns = checks.filter(c => c.status === 'warn').length;
+  const tail = fails === 0 && warns === 0
+    ? paint.state.success('All systems aligned.')
+    : fails > 0
+        ? paint.state.danger(`${fails} blocker${fails === 1 ? '' : 's'}, ${warns} warning${warns === 1 ? '' : 's'} — see hints above.`)
+        : paint.state.warn(`${warns} warning${warns === 1 ? '' : 's'} — non-blocking.`);
+
+  write('\n  ' + tail + '\n\n');
+  return checks;
+}

package/src/state/orbit.mjs

@@ -0,0 +1,263 @@
+/**
+ * Orbit state machine — Mission Control (PRD-055 §5.2).
+ *
+ * The "orbit" is the current phase of the session. The status bar reads
+ * from this module; the REPL pushes events into it. It is intentionally a
+ * pure state machine — no I/O, no side effects, no globals. Each REPL
+ * creates one instance.
+ *
+ *   const orbit = createOrbit();
+ *   orbit.on('change', state => statusBar.render(state));
+ *   orbit.onEvent({ type: 'tool_call', data: { tool: 'edit_file' } });
+ *
+ * States (PRD §5.2):
+ *   IDLE        — waiting for user input
+ *   DISCOVERY   — first message until first plan or edit
+ *   PLANNING    — preflight plan running OR plan() sub-agent active
+ *   EXECUTION   — write/edit/shell tools firing
+ *   ALIGNMENT   — tests / validators running
+ *   AWAITING    — approval required
+ *   PAUSED      — user pressed `p`
+ *
+ * Transitions are derived from existing backend SSE events. We never
+ * teach the backend about orbits; the CLI infers them from tool activity.
+ */
+
+// Tool families used for orbit inference. Mirrors src/ui/icons.mjs but
+// scoped to the few orbits actually need.
+const PLANNING_TOOLS = new Set(['plan']);
+const EXECUTION_TOOLS = new Set(['edit_file', 'write_file', 'write_project', 'shell', 'delete_file']);
+const ALIGNMENT_TOOLS = new Set(['run_tests', 'validate_build', 'lint_check', 'validate_file', 'validate_structure', 'git_diff', 'git_status']);
+const RESEARCH_TOOLS  = new Set(['search_code', 'search_files', 'grep', 'read_file', 'read_files', 'list_files', 'analyze_code', 'get_project_overview', 'explore']);
+
+export const ORBITS = Object.freeze({
+  IDLE:      'IDLE',
+  DISCOVERY: 'DISCOVERY',
+  PLANNING:  'PLANNING',
+  EXECUTION: 'EXECUTION',
+  ALIGNMENT: 'ALIGNMENT',
+  AWAITING:  'AWAITING',
+  PAUSED:    'PAUSED',
+});
+
+/**
+ * @returns the snapshot consumed by the status bar.
+ */
+function snapshot(s) {
+  return {
+    orbit:           s.orbit,
+    task:            s.task || '',
+    turn:            s.turn,
+    maxTurn:         s.maxTurn,
+    cost:            s.cost,
+    activeTool:      s.activeTool || '',
+    subAgents:       s.subAgents,
+    paused:          s.paused,
+    awaitingTier:    s.awaitingTier || null,
+    awaitingTool:    s.awaitingTool || '',
+  };
+}
+
+export function createOrbit() {
+  const state = {
+    orbit:        ORBITS.IDLE,
+    task:         '',
+    turn:         0,
+    maxTurn:      0,
+    cost:         0,
+    activeTool:   '',
+    subAgents:    0,           // count of currently-active sub-agents
+    paused:       false,
+    awaitingTool: '',
+    awaitingTier: null,
+    _hasEdited:   false,       // for DISCOVERY → EXECUTION transition
+    _resumeOrbit: null,        // remembered orbit when paused
+  };
+
+  const listeners = new Set();
+
+  function emit() {
+    const snap = snapshot(state);
+    for (const fn of listeners) {
+      try { fn(snap); } catch {}
+    }
+  }
+
+  function setOrbit(next) {
+    if (state.paused && next !== ORBITS.PAUSED && next !== ORBITS.IDLE) {
+      // While paused, remember the orbit that would have applied but stay paused.
+      state._resumeOrbit = next;
+      return;
+    }
+    if (state.orbit === next) return;
+    state.orbit = next;
+    emit();
+  }
+
+  function inferOrbitFromTool(toolName) {
+    if (state.paused) return null;
+    if (state.subAgents > 0 && PLANNING_TOOLS.has(toolName)) return ORBITS.PLANNING;
+    if (PLANNING_TOOLS.has(toolName)) return ORBITS.PLANNING;
+    if (EXECUTION_TOOLS.has(toolName)) {
+      state._hasEdited = true;
+      return ORBITS.EXECUTION;
+    }
+    if (ALIGNMENT_TOOLS.has(toolName)) return ORBITS.ALIGNMENT;
+    if (RESEARCH_TOOLS.has(toolName)) {
+      // Stay in DISCOVERY until first edit; afterwards research stays in
+      // current orbit (EXECUTION) so the status doesn't flicker back.
+      return state._hasEdited ? null : ORBITS.DISCOVERY;
+    }
+    return null;
+  }
+
+  return {
+    state: () => snapshot(state),
+
+    on(event, fn) {
+      if (event !== 'change') return () => {};
+      listeners.add(fn);
+      return () => listeners.delete(fn);
+    },
+
+    // ── Inbound events from the REPL ──────────────────────────────────
+
+    onUserInput(text) {
+      // First user message of the session OR a new turn opens DISCOVERY.
+      state.turn++;
+      state.task = (text || '').replace(/\s+/g, ' ').trim().slice(0, 80);
+      state._hasEdited = false;
+      state.activeTool = '';
+      setOrbit(ORBITS.DISCOVERY);
+    },
+
+    onMaxTurn(n) {
+      if (typeof n === 'number' && n > 0) {
+        state.maxTurn = n;
+        emit();
+      }
+    },
+
+    onTask(text) {
+      if (!text) return;
+      state.task = String(text).replace(/\s+/g, ' ').trim().slice(0, 80);
+      emit();
+    },
+
+    onCost(value) {
+      if (typeof value === 'number' && Number.isFinite(value)) {
+        state.cost = value;
+        emit();
+      }
+    },
+
+    onToolCall(toolName) {
+      state.activeTool = toolName || '';
+      const next = inferOrbitFromTool(toolName);
+      if (next) setOrbit(next);
+      else emit();
+    },
+
+    onToolResult() {
+      state.activeTool = '';
+      emit();
+    },
+
+    onSubAgentStart() {
+      state.subAgents = Math.max(0, state.subAgents) + 1;
+      setOrbit(ORBITS.PLANNING);
+    },
+
+    onSubAgentEnd() {
+      state.subAgents = Math.max(0, state.subAgents - 1);
+      // Fall back to whatever the parent was doing — we don't track that
+      // precisely, so go to EXECUTION if an edit has happened, else
+      // DISCOVERY. The next tool_call event will refine.
+      if (state.subAgents === 0) {
+        setOrbit(state._hasEdited ? ORBITS.EXECUTION : ORBITS.DISCOVERY);
+      } else {
+        emit();
+      }
+    },
+
+    onApprovalRequired({ tool, tier } = {}) {
+      state.awaitingTool = tool || '';
+      state.awaitingTier = tier || null;
+      setOrbit(ORBITS.AWAITING);
+    },
+
+    onApprovalResolved() {
+      state.awaitingTool = '';
+      state.awaitingTier = null;
+      // Drop back to the inferred orbit for the active tool, or EXECUTION
+      // if we have an active tool but can't classify, or IDLE.
+      const inferred = inferOrbitFromTool(state.activeTool) || (state._hasEdited ? ORBITS.EXECUTION : ORBITS.DISCOVERY);
+      setOrbit(inferred);
+    },
+
+    onComplete({ cost } = {}) {
+      if (typeof cost === 'number') state.cost = cost;
+      state.activeTool = '';
+      setOrbit(ORBITS.IDLE);
+    },
+
+    onPause() {
+      if (state.paused) return;
+      state.paused = true;
+      state._resumeOrbit = state.orbit;
+      state.orbit = ORBITS.PAUSED;
+      emit();
+    },
+
+    onResume() {
+      if (!state.paused) return;
+      state.paused = false;
+      const resume = state._resumeOrbit || ORBITS.IDLE;
+      state._resumeOrbit = null;
+      state.orbit = resume;
+      emit();
+    },
+
+    /**
+     * Generic event router so the REPL can feed raw SSE events without a
+     * giant switch in this module. Returns true if the event was handled.
+     */
+    onEvent(event) {
+      if (!event || !event.type) return false;
+      const { type, data } = event;
+      switch (type) {
+        case 'tool_call':
+        case 'tool_request':
+          this.onToolCall(data?.tool || '');
+          return true;
+        case 'tool_result':
+        case 'tool_done':
+          this.onToolResult();
+          return true;
+        case 'sub_agent_start':
+          this.onSubAgentStart();
+          return true;
+        case 'sub_agent_complete':
+          this.onSubAgentEnd();
+          return true;
+        case 'approval_required':
+          this.onApprovalRequired({ tool: data?.tool, tier: data?.tier });
+          return true;
+        case 'approval_granted':
+        case 'approval_denied':
+          this.onApprovalResolved();
+          return true;
+        case 'complete': {
+          const usage = data?.usage || {};
+          this.onComplete({ cost: usage.total_cost_usd ?? usage.cost_usd });
+          return true;
+        }
+        case 'plan_created':
+          this.onTask(data?.title || data?.task || '');
+          return true;
+        default:
+          return false;
+      }
+    },
+  };
+}