jeo-code 0.7.31 → 0.7.32

package/src/agent/ast-match.ts

@@ -0,0 +1,241 @@
+/**
+ * Structural AST pattern matcher for TypeScript/JavaScript (gjc `ast_grep`/`ast_edit`
+ * parity, scoped to TS/JS/TSX/JSX — jeo-code has zero native dependencies, so this is
+ * a pure-TS reimplementation of ast-grep's metavariable matching against the
+ * `typescript` compiler API's AST, NOT the real ast-grep binary and NOT multi-language.
+ *
+ * Pattern syntax (matches the `ast_grep`/`ast_edit` tool contract):
+ *  - `$NAME`  — capture exactly ONE node; two occurrences of the same name in a
+ *    pattern must match IDENTICAL source text (e.g. `assertEqual($A, $A)`).
+ *  - `$_`     — wildcard, matches exactly one node without binding a capture.
+ *  - `$$$NAME`/`$$$` — capture/ignore ZERO OR MORE sibling nodes in a LIST position
+ *    (call arguments, array/object elements, statement lists, class members,
+ *    named-import specifiers, parameter lists, ...). At most one `$$$`-style
+ *    metavariable per list is supported.
+ *
+ * Implementation notes:
+ *  - `ts.Node.forEachChild(cbNode, cbNodeArray)` is used to enumerate a node's
+ *    children in canonical source order, distinguishing single-child "slots" from
+ *    list ("NodeArray") slots — this is what lets `$$$` bind a variable-length
+ *    span instead of a single node.
+ *  - A metavariable identifier is frequently parsed WRAPPED in a structural node
+ *    rather than standing bare — e.g. `($$$ARGS)` is a lone `ParameterDeclaration`
+ *    whose `.name` is the identifier, `{ $$$IMPORTS }` is a lone `ImportSpecifier`,
+ *    `: $_` is a `TypeReferenceNode`, `{ $$$BODY }` is a `Block` containing one
+ *    `ExpressionStatement`. `unwrapBareWrapper()` sees through these SPECIFIC,
+ *    well-known "no extra shape" wrappers so metavariable detection is not
+ *    accidentally defeated by the parser's own AST shape.
+ *  - Structural comparison otherwise requires the SAME `SyntaxKind` and recurses
+ *    slot-by-slot. A pattern is allowed to OMIT trailing optional slots the
+ *    candidate has (e.g. no `else` branch, no return type) and to be missing a
+ *    LEADING/MIDDLE list-shaped slot the candidate has (typically `modifiers`/
+ *    `decorators`, e.g. matching un-exported AND exported declarations with the
+ *    same pattern) — up to a small bounded number of skipped candidate slots.
+ */
+import * as ts from "typescript";
+
+export type MetaKind = "single" | "multi" | "wild" | "wildmulti";
+export interface Meta { kind: MetaKind; name: string }
+
+function unwrapBareWrapper(node: ts.Node): ts.Node | null {
+  if (ts.isParameter(node) && ts.isIdentifier(node.name) && !node.type && !node.initializer
+      && !node.questionToken && !node.dotDotDotToken && (!node.modifiers || node.modifiers.length === 0)) {
+    return node.name;
+  }
+  if (ts.isImportSpecifier(node) && !node.propertyName && !node.isTypeOnly) return node.name;
+  if (ts.isExportSpecifier(node) && !node.propertyName && !node.isTypeOnly) return node.name;
+  if (ts.isBindingElement(node) && !node.propertyName && !node.initializer && !node.dotDotDotToken && ts.isIdentifier(node.name)) return node.name;
+  if (ts.isTypeReferenceNode(node) && ts.isIdentifier(node.typeName) && !node.typeArguments) return node.typeName;
+  if (ts.isExpressionStatement(node)) return node.expression;
+  if (ts.isShorthandPropertyAssignment(node) && !node.objectAssignmentInitializer) return node.name;
+  return null;
+}
+
+/** Classify a (possibly wrapper-unwrapped) node as a metavariable, or `null` for
+ *  an ordinary AST node that must be matched structurally. */
+export function metaOf(node: ts.Node): Meta | null {
+  const inner = unwrapBareWrapper(node);
+  if (inner) return metaOf(inner);
+  if (!ts.isIdentifier(node)) return null;
+  const t = node.text;
+  if (t === "$_") return { kind: "wild", name: "_" };
+  if (t === "$$$") return { kind: "wildmulti", name: "_" };
+  const m3 = /^\$\$\$([A-Za-z_][A-Za-z0-9_]*)$/.exec(t);
+  if (m3) return { kind: "multi", name: m3[1]! };
+  const m1 = /^\$([A-Za-z_][A-Za-z0-9_]*)$/.exec(t);
+  if (m1) return { kind: "single", name: m1[1]! };
+  return null;
+}
+
+export interface Bindings {
+  single: Map<string, string>;
+  multi: Map<string, string[]>;
+}
+
+function newBindings(): Bindings {
+  return { single: new Map(), multi: new Map() };
+}
+
+type Slot = { kind: "node"; node: ts.Node } | { kind: "list"; nodes: readonly ts.Node[] };
+
+function slotsOf(node: ts.Node): Slot[] {
+  const out: Slot[] = [];
+  node.forEachChild(
+    child => { out.push({ kind: "node", node: child }); return undefined; },
+    arr => { out.push({ kind: "list", nodes: arr }); return undefined; },
+  );
+  return out;
+}
+
+function leafText(node: ts.Node): string | undefined {
+  if (ts.isIdentifier(node) || ts.isPrivateIdentifier(node)) return node.text;
+  if (ts.isStringLiteralLike(node)) return node.text;
+  if (ts.isNumericLiteral(node) || ts.isBigIntLiteral(node)) return node.text;
+  return undefined;
+}
+
+/** How many candidate-only slots (e.g. `export`/decorators the pattern omitted) a
+ *  single structural comparison may skip over before giving up. */
+const MAX_SLOT_SKIPS = 2;
+
+function matchNode(pattern: ts.Node, patternSf: ts.SourceFile, candidate: ts.Node, candidateSf: ts.SourceFile, b: Bindings): boolean {
+  const meta = metaOf(pattern);
+  if (meta) {
+    if (meta.kind === "wild") return true;
+    if (meta.kind === "single") {
+      const text = candidate.getText(candidateSf).trim();
+      const prev = b.single.get(meta.name);
+      if (prev !== undefined) return prev === text;
+      b.single.set(meta.name, text);
+      return true;
+    }
+    // `$$$NAME`/`$$$` reached outside a list slot (unusual pattern shape) — fall back
+    // to treating it as a single capture of the whole candidate rather than failing.
+    const text = candidate.getText(candidateSf).trim();
+    if (meta.kind === "multi") {
+      const prev = b.multi.get(meta.name);
+      if (prev !== undefined) return prev.join(" ") === text;
+      b.multi.set(meta.name, [text]);
+    }
+    return true;
+  }
+  if (pattern.kind !== candidate.kind) return false;
+  const lt = leafText(pattern);
+  if (lt !== undefined) return lt === leafText(candidate);
+
+  const pSlots = slotsOf(pattern);
+  const cSlots = slotsOf(candidate);
+  let pi = 0, ci = 0, skips = 0;
+  while (pi < pSlots.length) {
+    const ps = pSlots[pi]!;
+    if (ci >= cSlots.length) return false;
+    const cs = cSlots[ci]!;
+    if (ps.kind === cs.kind) {
+      const ok = ps.kind === "list"
+        ? matchList(ps.nodes, patternSf, (cs as { kind: "list"; nodes: readonly ts.Node[] }).nodes, candidateSf, b)
+        : matchNode((ps as { kind: "node"; node: ts.Node }).node, patternSf, (cs as { kind: "node"; node: ts.Node }).node, candidateSf, b);
+      if (!ok) {
+        if (skips < MAX_SLOT_SKIPS && ci + 1 < cSlots.length) { skips++; ci++; continue; }
+        return false;
+      }
+      pi++; ci++;
+      continue;
+    }
+    // Slot-KIND mismatch (list vs single) at this relative position — most commonly a
+    // `modifiers`/`decorators` list the candidate has and the pattern omitted. Skip the
+    // candidate slot and retry the SAME pattern slot against the next one.
+    if (skips < MAX_SLOT_SKIPS) { skips++; ci++; continue; }
+    return false;
+  }
+  return true; // trailing extra candidate slots are fine — unspecified optional parts
+}
+
+function matchList(patternNodes: readonly ts.Node[], patternSf: ts.SourceFile, candidateNodes: readonly ts.Node[], candidateSf: ts.SourceFile, b: Bindings): boolean {
+  const idx = patternNodes.findIndex(n => { const m = metaOf(n); return m?.kind === "multi" || m?.kind === "wildmulti"; });
+  if (idx === -1) {
+    if (patternNodes.length !== candidateNodes.length) return false;
+    for (let i = 0; i < patternNodes.length; i++) {
+      if (!matchNode(patternNodes[i]!, patternSf, candidateNodes[i]!, candidateSf, b)) return false;
+    }
+    return true;
+  }
+  const prefixLen = idx;
+  const suffixLen = patternNodes.length - idx - 1;
+  if (candidateNodes.length < prefixLen + suffixLen) return false;
+  for (let i = 0; i < prefixLen; i++) {
+    if (!matchNode(patternNodes[i]!, patternSf, candidateNodes[i]!, candidateSf, b)) return false;
+  }
+  for (let i = 0; i < suffixLen; i++) {
+    if (!matchNode(patternNodes[patternNodes.length - 1 - i]!, patternSf, candidateNodes[candidateNodes.length - 1 - i]!, candidateSf, b)) return false;
+  }
+  const middle = candidateNodes.slice(prefixLen, candidateNodes.length - suffixLen);
+  const meta = metaOf(patternNodes[idx]!)!;
+  if (meta.kind === "multi") {
+    const texts = middle.map(n => n.getText(candidateSf).trim());
+    const prev = b.multi.get(meta.name);
+    if (prev !== undefined) return prev.join(",") === texts.join(",");
+    b.multi.set(meta.name, texts);
+  }
+  return true;
+}
+
+/** Parse a pattern string to a single matchable node. Multi-statement snippets are
+ *  rejected with a clear error — wrap them in a block/valid context instead (same
+ *  discipline as real ast-grep). A bare expression statement is unwrapped to its
+ *  expression so `$A && $A()` matches an Expression, not only an ExpressionStatement. */
+export function parsePattern(src: string): { node: ts.Node; sf: ts.SourceFile } {
+  const sf = ts.createSourceFile("__pattern__.tsx", src, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+  if (sf.statements.length !== 1) {
+    throw new Error(`pattern must parse to exactly one top-level statement (got ${sf.statements.length}) — wrap multi-statement snippets in a block or valid context`);
+  }
+  let node: ts.Node = sf.statements[0]!;
+  if (ts.isExpressionStatement(node)) node = node.expression;
+  return { node, sf };
+}
+
+export interface MatchCaptures {
+  single: Record<string, string>;
+  multi: Record<string, string[]>;
+}
+
+export interface MatchResult {
+  node: ts.Node;
+  captures: MatchCaptures;
+}
+
+/** Find every non-overlapping-by-construction match of `patternSrc` in `sourceFile`.
+ *  A fast prefilter only attempts nodes whose `SyntaxKind` equals the pattern's root
+ *  kind (unless the pattern root is itself a bare metavariable). */
+export function findMatches(patternSrc: string, sourceFile: ts.SourceFile): MatchResult[] {
+  const { node: patternNode, sf: patternSf } = parsePattern(patternSrc);
+  const patternIsBareMeta = metaOf(patternNode) !== null;
+  const out: MatchResult[] = [];
+  const visit = (node: ts.Node) => {
+    if (patternIsBareMeta || node.kind === patternNode.kind) {
+      const b = newBindings();
+      if (matchNode(patternNode, patternSf, node, sourceFile, b)) {
+        out.push({ node, captures: { single: Object.fromEntries(b.single), multi: Object.fromEntries(b.multi) } });
+      }
+    }
+    node.forEachChild(visit);
+  };
+  sourceFile.forEachChild(visit);
+  return out;
+}
+
+/** Render a replacement template, substituting `$NAME`/`$$$NAME` with their bound
+ *  capture text (multi-captures join with ", "). An unbound metavariable (including
+ *  `$_`/`$$$`, which never bind) is left as literal text in the output. */
+export function renderReplacement(template: string, captures: MatchCaptures): string {
+  return template.replace(/\$\$\$([A-Za-z_][A-Za-z0-9_]*)|\$([A-Za-z_][A-Za-z0-9_]*)/g, (whole, multiName?: string, singleName?: string) => {
+    if (multiName !== undefined) {
+      const vals = captures.multi[multiName];
+      return vals !== undefined ? vals.join(", ") : whole;
+    }
+    if (singleName !== undefined) {
+      const val = captures.single[singleName];
+      return val !== undefined ? val : whole;
+    }
+    return whole;
+  });
+}

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();
+});