jeo-code 0.7.31 → 0.7.33

package/src/agent/debug-session.ts

@@ -0,0 +1,435 @@
+/**
+ * In-process CDP (V8 Inspector Protocol) client driving a spawned `node --inspect-brk`
+ * process (gjc `debug` parity, Node.js JavaScript/TypeScript ONLY).
+ *
+ * Scope, stated honestly:
+ *  - Targets `node` specifically. Bun's own inspector speaks the WebKit Inspector
+ *    Protocol dialect (Bun docs: "Bun speaks the WebKit Inspector Protocol"), and
+ *    empirical testing here showed its `Debugger.paused`/resume sequencing does NOT
+ *    behave like Node's — so Bun is NOT supported rather than silently half-working.
+ *  - No DAP wire protocol, no other languages, no remote/attach mode — this speaks
+ *    the underlying V8 protocol directly against a locally-spawned `node` process.
+ *  - One debug session at a time, matching the tool's "one active session" model.
+ *    `launch()` terminates any previous session first.
+ *
+ * Flow: `launch()` spawns `node --inspect-brk=0 <program> <args>`, connects over
+ * WebSocket, enables the Debugger/Runtime domains, and resumes through Node's own
+ * "Break on start" pause via `Runtime.runIfWaitingForDebugger` — the session is left
+ * PAUSED there so the caller can set breakpoints before the first line of real user
+ * code runs, then call `continue`.
+ */
+import * as path from "node:path";
+
+interface CdpLocation {
+  scriptId: string;
+  lineNumber: number;
+  columnNumber?: number;
+}
+
+interface CdpScope {
+  type: string;
+  object: { objectId?: string; description?: string };
+}
+
+interface CdpCallFrame {
+  callFrameId: string;
+  functionName: string;
+  location: CdpLocation;
+  scopeChain: CdpScope[];
+}
+
+interface PausedState {
+  callFrames: CdpCallFrame[];
+  reason: string;
+}
+
+/** Outcome of waiting for the next debug-relevant event: a real pause, the process
+ *  actually exiting, or the script's execution context finishing while Node keeps
+ *  the (now idle) process alive waiting for the debugger — see the
+ *  `Runtime.executionContextDestroyed` handling in `handleMessage`. */
+type WaitResult = PausedState | { exited: true; code: number | null } | { finished: true };
+
+interface BreakpointRecord {
+  id: string;
+  file: string;
+  line: number;
+  condition?: string;
+}
+
+function escapeRegex(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+const CONNECT_TIMEOUT_MS = 10_000;
+const PAUSE_TIMEOUT_MS = 15_000;
+const MAX_OUTPUT_CHARS = 20_000;
+
+export class DebugSession {
+  private proc: Bun.Subprocess<"ignore", "pipe", "pipe"> | undefined;
+  private ws: WebSocket | undefined;
+  private nextId = 1;
+  private pending = new Map<number, { resolve: (v: any) => void; reject: (e: any) => void }>();
+  private paused: PausedState | undefined;
+  private exitCode: number | null | undefined;
+  private outputBuf = "";
+  private scriptUrls = new Map<string, string>(); // scriptId -> url
+  private breakpoints = new Map<string, BreakpointRecord>(); // cdp breakpointId -> record
+  private pausedWaiters: Array<(p: WaitResult) => void> = [];
+
+  get isActive(): boolean {
+    return !!this.proc && this.exitCode === undefined;
+  }
+
+  get isPaused(): boolean {
+    return !!this.paused;
+  }
+
+  private appendOutput(chunk: string): void {
+    this.outputBuf += chunk;
+    if (this.outputBuf.length > MAX_OUTPUT_CHARS) {
+      this.outputBuf = "…[truncated]…\n" + this.outputBuf.slice(this.outputBuf.length - MAX_OUTPUT_CHARS);
+    }
+  }
+
+  output(): string {
+    return this.outputBuf;
+  }
+
+  private async drain(stream: ReadableStream<Uint8Array>): Promise<void> {
+    const reader = stream.getReader();
+    const decoder = new TextDecoder();
+    try {
+      while (true) {
+        const { value, done } = await reader.read();
+        if (done) break;
+        this.appendOutput(decoder.decode(value, { stream: true }));
+      }
+    } catch {
+      // stream torn down on terminate — nothing further to drain
+    }
+  }
+
+  private send(method: string, params: Record<string, any> = {}): Promise<any> {
+    if (!this.ws) return Promise.reject(new Error("No active debug session."));
+    const id = this.nextId++;
+    return new Promise((resolve, reject) => {
+      this.pending.set(id, { resolve, reject });
+      this.ws!.send(JSON.stringify({ id, method, params }));
+    });
+  }
+
+  private handleMessage(raw: string): void {
+    let msg: any;
+    try {
+      msg = JSON.parse(raw);
+    } catch {
+      return;
+    }
+    if (msg.id !== undefined && this.pending.has(msg.id)) {
+      const p = this.pending.get(msg.id)!;
+      this.pending.delete(msg.id);
+      if (msg.error) p.reject(new Error(msg.error.message ?? JSON.stringify(msg.error)));
+      else p.resolve(msg.result);
+      return;
+    }
+    if (msg.method === "Debugger.scriptParsed") {
+      this.scriptUrls.set(msg.params.scriptId, msg.params.url);
+    } else if (msg.method === "Debugger.paused") {
+      this.paused = { callFrames: msg.params.callFrames, reason: msg.params.reason };
+      const waiters = this.pausedWaiters.splice(0);
+      for (const w of waiters) w(this.paused);
+    } else if (msg.method === "Debugger.resumed") {
+      this.paused = undefined;
+    } else if (msg.method === "Debugger.breakpointResolved") {
+      const rec = this.breakpoints.get(msg.params.breakpointId);
+      if (rec) this.scriptUrls.set(msg.params.location.scriptId, this.scriptUrls.get(msg.params.location.scriptId) ?? rec.file);
+    } else if (msg.method === "Runtime.executionContextDestroyed") {
+      // Node keeps the process alive after the script finishes while a debugger is
+      // attached (it waits to be told to exit) — proc.exited would hang forever, so
+      // this event is the real "the script is done" signal. Settle any waiter with
+      // `finished`, then kill the now-idle process ourselves; nothing further to debug.
+      const waiters = this.pausedWaiters.splice(0);
+      for (const w of waiters) w({ finished: true });
+      void this.terminate();
+    }
+  }
+
+  /** Resolve on the next `Debugger.paused`, OR immediately if the process has already
+   *  exited (so a `continue`/`step` after the last breakpoint doesn't hang forever). */
+  private waitForPausedOrExit(): Promise<WaitResult> {
+    if (this.exitCode !== undefined) return Promise.resolve({ exited: true, code: this.exitCode });
+    return new Promise((resolve) => {
+      let done = false;
+      const settle = (v: WaitResult) => {
+        if (done) return;
+        done = true;
+        resolve(v);
+      };
+      this.pausedWaiters.push(settle);
+      this.proc?.exited.then((code) => settle({ exited: true, code }));
+      setTimeout(() => settle({ exited: true, code: null }), PAUSE_TIMEOUT_MS);
+    });
+  }
+
+  async launch(program: string, args: string[], cwd: string): Promise<{ success: boolean; output: string; error?: string }> {
+    await this.terminate();
+
+    let proc: Bun.Subprocess<"ignore", "pipe", "pipe">;
+    try {
+      proc = Bun.spawn(["node", "--inspect-brk=0", program, ...args], { cwd, stdin: "ignore", stdout: "pipe", stderr: "pipe" });
+    } catch (err: any) {
+      return { success: false, output: "", error: `Failed to spawn 'node': ${err.message}` };
+    }
+    this.proc = proc;
+    this.exitCode = undefined;
+    this.outputBuf = "";
+    this.scriptUrls.clear();
+    this.breakpoints.clear();
+    this.paused = undefined;
+    void proc.exited.then((code) => { if (this.proc === proc) this.exitCode = code; });
+    void this.drain(proc.stdout);
+
+    const url = await this.waitForInspectorUrl(proc.stderr);
+    if (!url) {
+      await this.terminate();
+      return { success: false, output: "", error: "node did not print an inspector WebSocket URL in time — is 'node' installed and on PATH?" };
+    }
+
+    try {
+      const ws = new WebSocket(url);
+      this.ws = ws;
+      // Guard against a STALE socket delivering buffered messages after a newer
+      // session has replaced `this.ws` (e.g. a killed process's socket flushing its
+      // last frames concurrently with the next `launch()`) — without this, a
+      // straggler event would mutate the singleton's live session state from a dead
+      // session's listener closure.
+      ws.addEventListener("message", (ev) => { if (this.ws === ws) this.handleMessage(ev.data as string); });
+      await new Promise<void>((resolve, reject) => {
+        const t = setTimeout(() => reject(new Error("Timed out connecting to the inspector WebSocket.")), CONNECT_TIMEOUT_MS);
+        ws.addEventListener("open", () => { clearTimeout(t); resolve(); }, { once: true });
+        ws.addEventListener("error", () => { clearTimeout(t); reject(new Error("Inspector WebSocket connection failed.")); }, { once: true });
+      });
+      await this.send("Debugger.enable");
+      await this.send("Runtime.enable");
+      await this.send("Runtime.runIfWaitingForDebugger");
+    } catch (err: any) {
+      await this.terminate();
+      return { success: false, output: "", error: err.message };
+    }
+
+    const settled = await this.waitForPausedOrExit();
+    if ("exited" in settled) {
+      return { success: false, output: "", error: `Program exited (code ${settled.code}) before an initial breakpoint could be established.` };
+    }
+    if ("finished" in settled) {
+      return { success: false, output: "", error: "The program finished before an initial breakpoint could be established." };
+    }
+    return {
+      success: true,
+      output: `Launched 'node ${program} ${args.join(" ")}'. Paused at program start (${settled.reason}). ` +
+        `Set breakpoints, then 'continue' to run.`,
+    };
+  }
+
+  private async waitForInspectorUrl(stderr: ReadableStream<Uint8Array>): Promise<string | undefined> {
+    const reader = stderr.getReader();
+    const decoder = new TextDecoder();
+    let buf = "";
+    const deadline = Date.now() + CONNECT_TIMEOUT_MS;
+    try {
+      while (Date.now() < deadline) {
+        const { value, done } = await Promise.race([
+          reader.read(),
+          new Promise<{ value: undefined; done: false }>((r) => setTimeout(() => r({ value: undefined, done: false }), 200)),
+        ]);
+        if (done) break;
+        if (value) {
+          const text = decoder.decode(value, { stream: true });
+          buf += text;
+          this.appendOutput(text);
+          const m = /ws:\/\/\S+/.exec(buf);
+          if (m) return m[0];
+        }
+      }
+    } finally {
+      reader.releaseLock();
+      // Keep draining the rest of stderr into captured output after url discovery.
+      void this.drain(stderr).catch(() => {});
+    }
+    return undefined;
+  }
+
+  async setBreakpoint(file: string, line1: number, cwd: string, condition?: string): Promise<{ success: boolean; output: string; error?: string }> {
+    if (!this.isActive) return { success: false, output: "", error: "No active debug session. Launch one first." };
+    const absPath = path.resolve(cwd, file);
+    try {
+      const res = await this.send("Debugger.setBreakpointByUrl", {
+        lineNumber: line1 - 1,
+        urlRegex: escapeRegex(absPath),
+        condition,
+      });
+      this.breakpoints.set(res.breakpointId, { id: res.breakpointId, file: absPath, line: line1, condition });
+      const resolvedNote = res.locations?.length ? "" : " (not yet resolved — script not loaded yet, will resolve once it is)";
+      return { success: true, output: `Breakpoint ${res.breakpointId} set at ${file}:${line1}${resolvedNote}.` };
+    } catch (err: any) {
+      return { success: false, output: "", error: err.message };
+    }
+  }
+
+  async removeBreakpoint(id: string): Promise<{ success: boolean; output: string; error?: string }> {
+    if (!this.isActive) return { success: false, output: "", error: "No active debug session." };
+    if (!this.breakpoints.has(id)) return { success: false, output: "", error: `Unknown breakpoint id '${id}'.` };
+    try {
+      await this.send("Debugger.removeBreakpoint", { breakpointId: id });
+      this.breakpoints.delete(id);
+      return { success: true, output: `Breakpoint ${id} removed.` };
+    } catch (err: any) {
+      return { success: false, output: "", error: err.message };
+    }
+  }
+
+  private async resumeLike(method: string, label: string): Promise<{ success: boolean; output: string; error?: string }> {
+    if (!this.isActive) return { success: false, output: "", error: "No active debug session." };
+    if (!this.isPaused) return { success: false, output: "", error: `Cannot '${label}': the session is not paused.` };
+    try {
+      await this.send(method);
+    } catch (err: any) {
+      return { success: false, output: "", error: err.message };
+    }
+    const settled = await this.waitForPausedOrExit();
+    if ("exited" in settled) {
+      return { success: true, output: `Program exited (code ${settled.code}).` };
+    }
+    if ("finished" in settled) {
+      return { success: true, output: "Program finished (execution completed)." };
+    }
+    return { success: true, output: this.formatPaused(settled) };
+  }
+
+  continue(): Promise<{ success: boolean; output: string; error?: string }> {
+    return this.resumeLike("Debugger.resume", "continue");
+  }
+
+  stepOver(): Promise<{ success: boolean; output: string; error?: string }> {
+    return this.resumeLike("Debugger.stepOver", "step_over");
+  }
+
+  stepIn(): Promise<{ success: boolean; output: string; error?: string }> {
+    return this.resumeLike("Debugger.stepInto", "step_in");
+  }
+
+  stepOut(): Promise<{ success: boolean; output: string; error?: string }> {
+    return this.resumeLike("Debugger.stepOut", "step_out");
+  }
+
+  async pause(): Promise<{ success: boolean; output: string; error?: string }> {
+    if (!this.isActive) return { success: false, output: "", error: "No active debug session." };
+    if (this.isPaused) return { success: true, output: this.formatPaused(this.paused!) };
+    try {
+      await this.send("Debugger.pause");
+    } catch (err: any) {
+      return { success: false, output: "", error: err.message };
+    }
+    const settled = await this.waitForPausedOrExit();
+    if ("exited" in settled) return { success: true, output: `Program exited (code ${settled.code}).` };
+    if ("finished" in settled) return { success: true, output: "Program finished (execution completed)." };
+    return { success: true, output: this.formatPaused(settled) };
+  }
+
+  async evaluate(expression: string, frameIndex = 0): Promise<{ success: boolean; output: string; error?: string }> {
+    if (!this.isActive) return { success: false, output: "", error: "No active debug session." };
+    try {
+      let result: any;
+      if (this.isPaused) {
+        const frame = this.paused!.callFrames[frameIndex];
+        if (!frame) return { success: false, output: "", error: `No stack frame at index ${frameIndex}.` };
+        result = await this.send("Debugger.evaluateOnCallFrame", { callFrameId: frame.callFrameId, expression });
+      } else {
+        result = await this.send("Runtime.evaluate", { expression });
+      }
+      if (result.exceptionDetails) {
+        return { success: false, output: "", error: this.describeRemoteObject(result.result) };
+      }
+      return { success: true, output: this.describeRemoteObject(result.result) };
+    } catch (err: any) {
+      return { success: false, output: "", error: err.message };
+    }
+  }
+
+  private describeRemoteObject(obj: any): string {
+    if (!obj) return "undefined";
+    if (obj.type === "object" && obj.subtype === "error") return obj.description ?? "Error";
+    if (obj.value !== undefined) return typeof obj.value === "string" ? obj.value : JSON.stringify(obj.value);
+    return obj.description ?? obj.className ?? obj.type ?? "undefined";
+  }
+
+  private formatPaused(p: PausedState): string {
+    const lines = [`Paused (${p.reason}):`];
+    p.callFrames.slice(0, 10).forEach((f, i) => lines.push(`  #${i} ${this.frameLabel(f)}`));
+    return lines.join("\n");
+  }
+
+  private frameLabel(f: CdpCallFrame): string {
+    const url = this.scriptUrls.get(f.location.scriptId) ?? f.location.scriptId;
+    return `${f.functionName || "(anonymous)"} (${url}:${f.location.lineNumber + 1})`;
+  }
+
+  stackTrace(): { success: boolean; output: string; error?: string } {
+    if (!this.isActive) return { success: false, output: "", error: "No active debug session." };
+    if (!this.isPaused) return { success: false, output: "", error: "The session is not paused." };
+    return { success: true, output: this.formatPaused(this.paused!) };
+  }
+
+  scopes(frameIndex = 0): { success: boolean; output: string; error?: string; scopes?: { type: string; objectId?: string }[] } {
+    if (!this.isActive) return { success: false, output: "", error: "No active debug session." };
+    if (!this.isPaused) return { success: false, output: "", error: "The session is not paused." };
+    const frame = this.paused!.callFrames[frameIndex];
+    if (!frame) return { success: false, output: "", error: `No stack frame at index ${frameIndex}.` };
+    const scopes = frame.scopeChain.map((s) => ({ type: s.type, objectId: s.object.objectId }));
+    return { success: true, output: scopes.map((s) => s.objectId ? `${s.type}: ${s.objectId}` : `${s.type} (no variables)`).join("\n"), scopes };
+  }
+
+  async variables(objectId: string): Promise<{ success: boolean; output: string; error?: string }> {
+    if (!this.isActive) return { success: false, output: "", error: "No active debug session." };
+    try {
+      const res = await this.send("Runtime.getProperties", { objectId, ownProperties: true });
+      const lines = (res.result ?? [])
+        .filter((p: any) => p.enumerable !== false)
+        .map((p: any) => `${p.name} = ${this.describeRemoteObject(p.value)}`);
+      return { success: true, output: lines.length ? lines.join("\n") : "(no properties)" };
+    } catch (err: any) {
+      return { success: false, output: "", error: err.message };
+    }
+  }
+
+  threads(): { success: boolean; output: string } {
+    return { success: true, output: this.isActive ? "1 thread: main (node is single-threaded here)" : "No active debug session." };
+  }
+
+  async terminate(): Promise<{ success: boolean; output: string }> {
+    const wasActive = this.isActive;
+    try {
+      this.ws?.close();
+    } catch { /* best-effort */ }
+    this.ws = undefined;
+    if (this.proc) {
+      try {
+        this.proc.kill();
+      } catch { /* best-effort */ }
+    }
+    this.proc = undefined;
+    this.paused = undefined;
+    this.pending.clear();
+    const waiters = this.pausedWaiters.splice(0);
+    for (const w of waiters) w({ exited: true, code: this.exitCode ?? null });
+    return { success: true, output: wasActive ? "Debug session terminated." : "No active debug session." };
+  }
+}
+
+/** Process-wide singleton — one active debug session (gjc `debug` tool parity). */
+export const debugSession = new DebugSession();
+
+// Safety net: never leave a debugged `node` process running past the CLI's own exit.
+process.on("exit", () => {
+  void debugSession.terminate();
+});

package/src/agent/debug-tool.ts

@@ -0,0 +1,89 @@
+/**
+ * `debug` tool — Node.js debugging via the in-process CDP client in
+ * `debug-session.ts` (gjc `debug` parity, Node.js JS/TS ONLY — no Bun target, no
+ * DAP wire protocol, no other languages; see that file's header for the full scope
+ * statement). MUTATING: runs arbitrary user code as a real OS process, so it is
+ * excluded from read-only subagent roles the same way `bash`/`computer` are.
+ */
+import type { ToolHandler } from "./engine";
+import type { ToolResult } from "./tools";
+import { debugSession } from "./debug-session";
+
+/** One-line protocol description appended to the launch system prompt. */
+export const DEBUG_TOOL_PROTOCOL_LINE =
+  `debug {action, ...} — Node.js debugging (one active session; 'launch' replaces any previous one). ` +
+  `launch {program, args?, cwd?} spawns 'node --inspect-brk' and pauses at program start; set_breakpoint ` +
+  `{file, line, condition?} / remove_breakpoint {id}; continue / step_over / step_in / step_out / pause resume ` +
+  `or step and report the next pause (or program exit); evaluate {expression, frame?}; stack_trace; scopes ` +
+  `{frame?} (lists 'type: objectId'); variables {object_id}; threads; output (captured stdout/stderr so far); ` +
+  `terminate.`;
+
+function err(message: string): ToolResult {
+  return { success: false, output: "", error: message };
+}
+
+export function createDebugTool(): ToolHandler {
+  return async (args: Record<string, any>, cwd: string): Promise<ToolResult> => {
+    const action = String(args.action ?? "").trim().toLowerCase();
+
+    if (action === "launch") {
+      const program = typeof args.program === "string" ? args.program.trim() : "";
+      if (!program) return err(`debug {action:"launch"} requires a non-empty "program".`);
+      const scriptArgs = Array.isArray(args.args) ? args.args.map((a: unknown) => String(a)) : [];
+      const resolvedCwd = typeof args.cwd === "string" && args.cwd.trim() ? args.cwd : cwd;
+      return debugSession.launch(program, scriptArgs, resolvedCwd);
+    }
+
+    if (action === "set_breakpoint") {
+      const file = typeof args.file === "string" ? args.file.trim() : "";
+      if (!file) return err(`debug {action:"set_breakpoint"} requires a non-empty "file".`);
+      const line = typeof args.line === "number" ? args.line : parseInt(String(args.line ?? ""), 10);
+      if (!Number.isFinite(line) || line < 1) return err(`debug {action:"set_breakpoint"} requires a positive integer "line".`);
+      const condition = typeof args.condition === "string" && args.condition.trim() ? args.condition : undefined;
+      return debugSession.setBreakpoint(file, line, cwd, condition);
+    }
+
+    if (action === "remove_breakpoint") {
+      const id = typeof args.id === "string" ? args.id.trim() : "";
+      if (!id) return err(`debug {action:"remove_breakpoint"} requires a non-empty "id".`);
+      return debugSession.removeBreakpoint(id);
+    }
+
+    if (action === "continue") return debugSession.continue();
+    if (action === "step_over") return debugSession.stepOver();
+    if (action === "step_in") return debugSession.stepIn();
+    if (action === "step_out") return debugSession.stepOut();
+    if (action === "pause") return debugSession.pause();
+
+    if (action === "evaluate") {
+      const expression = typeof args.expression === "string" ? args.expression : "";
+      if (!expression.trim()) return err(`debug {action:"evaluate"} requires a non-empty "expression".`);
+      const frame = typeof args.frame === "number" ? args.frame : 0;
+      return debugSession.evaluate(expression, frame);
+    }
+
+    if (action === "stack_trace") return debugSession.stackTrace();
+
+    if (action === "scopes") {
+      const frame = typeof args.frame === "number" ? args.frame : 0;
+      const res = debugSession.scopes(frame);
+      return { success: res.success, output: res.output, error: res.error };
+    }
+
+    if (action === "variables") {
+      const objectId = typeof args.object_id === "string" ? args.object_id
+        : typeof args.objectId === "string" ? args.objectId : "";
+      if (!objectId) return err(`debug {action:"variables"} requires a non-empty "object_id" (from a prior 'scopes' call).`);
+      return debugSession.variables(objectId);
+    }
+
+    if (action === "threads") return debugSession.threads();
+    if (action === "output") return { success: true, output: debugSession.output() || "(no output yet)" };
+    if (action === "terminate") return debugSession.terminate();
+
+    return err(
+      `Unknown debug action '${action}'. Use launch | set_breakpoint | remove_breakpoint | continue | ` +
+      `step_over | step_in | step_out | pause | evaluate | stack_trace | scopes | variables | threads | output | terminate.`,
+    );
+  };
+}

package/src/agent/engine.ts

@@ -15,6 +15,13 @@ import { nativeToolSchemasFor, normalizeNativeToolName } from "./tool-schemas";
 import { readTool, writeTool, editTool, bashTool, findTool, searchTool, lsTool, mkdirTool, deleteTool, type ToolResult } from "./tools";
 import { webSearchTool, setWebSearchActiveModel } from "./web-search";
 import { executeComputerAction } from "../commands/computer";
+import { computerSupervisor } from "./computer-supervisor";
+import { createAstGrepTool } from "./ast-grep-tool";
+import { createAstEditTool } from "./ast-edit-tool";
+import { createLspTool } from "./lsp-tool";
+import { createLspRenameTool } from "./lsp-rename-tool";
+import { createDebugTool } from "./debug-tool";
+import { createBrowserTool } from "./browser-tool";
 import { isRateLimitError, waitAbortable } from "../util/retry";
 import { isContextOverflowError, isRefusalError, friendlyProviderError } from "../util/provider-error";
 import { runPreToolHooks, runPostTurnHooksForBatch } from "./hooks";
@@ -82,7 +89,22 @@ export const DEFAULT_TOOLS: Record<string, ToolHandler> = {
   mkdir: (a, cwd) => mkdirTool(a.dirPath ?? a.path ?? a.dir, cwd),
   delete: (a, cwd) => deleteTool(a.path ?? a.filePath ?? a.targetPath ?? a.dirPath, cwd, !!(a.recursive ?? a.r)),
   web_search: (a, cwd) => webSearchTool(a, cwd),
-  computer: (a) => executeComputerAction(a as any),
+  // Interactive-loop parity with the one-shot `jeo computer` CLI (see
+  // src/commands/computer.ts's runComputerCommand): arm the fail-closed
+  // supervisor and refresh its heartbeat immediately before EVERY call, so the
+  // kill-switch/heartbeat gate inside executeComputerAction passes for an
+  // actively-invoked tool call — it is never "always on" between calls.
+  computer: (a) => {
+    computerSupervisor.setKillSwitchLive(true);
+    computerSupervisor.heartbeat();
+    return executeComputerAction(a as any);
+  },
+  ast_grep: createAstGrepTool(),
+  ast_edit: createAstEditTool(),
+  lsp: createLspTool(),
+  lsp_rename: createLspRenameTool(),
+  debug: createDebugTool(),
+  browser: createBrowserTool(),
 };
 /** Tool-protocol description injected into the system prompt. */
 export const TOOL_PROTOCOL = [
@@ -98,7 +120,13 @@ export const TOOL_PROTOCOL = [
   "9. delete {path, recursive?}          — remove a file (or directory with recursive:true)",
   "10. web_search {query, recency?, limit?} — search the web (Anthropic-native: synthesized answer + sources + citations)",
   "11. computer {action, x?, y?, text?, key?, deltaX?, deltaY?, duration?, actions?} — execute desktop automation actions (screenshot, click, double_click, move, drag, scroll, type, keypress, wait, batch)",
-  "12. done   {reason?}                  — call when the task is fully implemented AND verified",
+  "12. ast_grep {pattern, paths} — structural TypeScript/JavaScript search: $NAME captures one node (repeats must match identical code), $_ is a wildcard node, $$$NAME/$$$ capture/ignore zero-or-more sibling nodes in a list (call args, statements, class members, ...)",
+  "13. ast_edit {pattern, replacement, paths} — structural TypeScript/JavaScript rewrite; same pattern metavariables, 'replacement' substitutes $NAME/$$$NAME with captured text (empty replacement deletes matches)",
+  "14. lsp {action, file, line?, symbol?} — TypeScript/JavaScript language-service queries (definition/references/hover/symbols/diagnostics); 'symbol' resolves the column on 'line' (append #N for the Nth occurrence)",
+  "15. lsp_rename {file, line, symbol?, new_name, apply?} — cross-file TypeScript/JavaScript rename (apply defaults true; apply:false previews only)",
+  "16. debug {action, ...} — Node.js debugging (launch/set_breakpoint/continue/step_over/step_in/step_out/pause/evaluate/stack_trace/scopes/variables/threads/output/terminate); one active session, 'launch' spawns 'node --inspect-brk' and pauses at start",
+  "17. browser {action:\"open\"|\"close\"|\"run\"|\"act\", name?, url?, actions?} — headless Chromium automation (Playwright); 'act' runs structured steps (navigate/click/type/fill/select/press/scroll/back/wait/observe/extract/screenshot) addressing elements by numeric id from 'observe' or a CSS selector; 'run' executes JS with page/browser/tab/display/assert/wait in scope",
+  "18. done   {reason?}                  — call when the task is fully implemented AND verified",
   "",
   "Reply with STRICT JSON only — no code fences. You MAY include an optional leading",
   '"reasoning" string (one short sentence on your plan) before "tool":',
@@ -120,9 +148,11 @@ export const READONLY_TOOL_PROTOCOL = [
   "1. read   {filePath, lineRange?}      — read a file (lineRange: \"a-b\", \"a-\", \"a\", \"a+n\", or multi \"a-b,c-d\")",
   "2. find   {globPattern}               — find files by name",
   "3. search {pattern, globPattern?, ignoreCase?} — grep for a pattern",
-  "4. ls     {dirPath}                   — list a directory's entries",
-  "5. web_search {query, recency?, limit?} — search the web (answer + sources + citations)",
-  "6. done   {reason?}                   — call when your review/analysis is complete",
+  "4. ast_grep {pattern, paths} — structural TypeScript/JavaScript search ($NAME/$_/$$$NAME metavariables — see ast_grep for full syntax)",
+  "5. lsp {action, file, line?, symbol?} — TypeScript/JavaScript definition/references/hover/symbols/diagnostics (read-only; cross-file rename is not available to this role)",
+  "6. ls     {dirPath}                   — list a directory's entries",
+  "7. web_search {query, recency?, limit?} — search the web (answer + sources + citations)",
+  "8. done   {reason?}                   — call when your review/analysis is complete",
   "",
   "Reply with STRICT JSON only — no prose, no code fences:",
   '{ "tool": "<name>", "arguments": { ... } }',
@@ -441,6 +471,13 @@ export async function runAgentLoop(history: Message[], opts: AgentLoopOptions):
   let lastMutationSeq = 0;
   let lastVerificationSeq = 0;
   let donePushbackUsed = false;
+  // Abuse guard for the done-pushback escape hatch: the "second done always
+  // passes" latch below is meant for turns where verification is genuinely
+  // not applicable (docs/config-only changes) — not for a model that just
+  // resends `done` immediately with zero intervening action. Reset to false
+  // when the first pushback fires; any executed tool step (even read-only)
+  // sets it back to true, so the escape hatch requires at least one attempt.
+  let sawActionSincePushback = true;
   // Caller-owned done gate (onBeforeDone) — also strictly once per turn.
   let beforeDoneNudgeUsed = false;
   // F1 (round 4): the run-command of the most recent post-turn hook FAILURE whose
@@ -806,12 +843,32 @@ export async function runAgentLoop(history: Message[], opts: AgentLoopOptions):
         verificationStale: sawMutation && lastMutationSeq > lastVerificationSeq,
         pendingHookFailure,
       });
-      if (doneGate.block && !donePushbackUsed) {
-        donePushbackUsed = true; // second done always passes — escape hatch
-        pushAssistantTurn(history, responseText, reasonBuf, artifactBuf);
-        history.push({ role: "user", content: doneGate.message });
-        step++;
-        continue;
+      if (doneGate.block) {
+        if (!donePushbackUsed) {
+          donePushbackUsed = true;
+          sawActionSincePushback = false; // require a real attempt before the 2nd done is honored
+          pushAssistantTurn(history, responseText, reasonBuf, artifactBuf);
+          history.push({ role: "user", content: doneGate.message });
+          step++;
+          continue;
+        }
+        if (!sawActionSincePushback) {
+          // Abuse guard: the model re-sent `done` immediately with zero intervening
+          // tool calls — not the intended "verification genuinely not applicable"
+          // escape hatch. Bounce once more instead of silently accepting it.
+          pushAssistantTurn(history, responseText, reasonBuf, artifactBuf);
+          history.push({
+            role: "user",
+            content:
+              `${doneGate.message}\n\nYou called 'done' again without taking any further action. ` +
+              `Either run the relevant verification (test/build/lint) or take another concrete step, ` +
+              `then call done — do not resend 'done' unchanged.`,
+          });
+          step++;
+          continue;
+        }
+        // donePushbackUsed && sawActionSincePushback: the model made at least one
+        // real attempt since the pushback — honor the escape hatch.
       }
       // Caller-owned done gate (e.g. stale-todo reconciliation): ONE bounded
       // bounce, then any later done passes — field case: a 28-step turn ended
@@ -1173,7 +1230,10 @@ export async function runAgentLoop(history: Message[], opts: AgentLoopOptions):
     // here, so this always holds the last REAL execution's results.
     lastResults = results;
     // Executed tool step = progress: the stall budget clocks time WITHOUT this.
-    if (results.some(r => r.executed)) lastProgressAt = Date.now();
+    if (results.some(r => r.executed)) {
+      lastProgressAt = Date.now();
+      sawActionSincePushback = true; // any real step after a pushback re-enables the done escape hatch
+    }
     step++;
   }