jeo-code 0.7.31 → 0.7.33

package/src/agent/goal-tool.ts

@@ -0,0 +1,57 @@
+/**
+ * `goal` tool — lets the agent explicitly set/read/clear the session's natural-
+ * language stop condition, mirroring gjc's own `goal` tool. Wraps the existing
+ * file-persisted GoalState (src/agent/goal-verifier.ts) that the human-typed
+ * `/goal <condition>` slash command already writes to and that the engine's
+ * per-`done` verifier (src/commands/launch.ts, verifyGoal) already reads from —
+ * this tool just gives the MODEL the same lever, not a new state store.
+ */
+import type { ToolHandler } from "./engine";
+import type { ToolResult } from "./tools";
+import { readGoalState, writeGoalState, clearGoalState, type GoalState } from "./goal-verifier";
+
+/** One-line protocol description appended to the launch system prompt. */
+export const GOAL_TOOL_PROTOCOL_LINE =
+  `goal {action:"set", condition} sets a natural-language stop condition for this session — ` +
+  `it is auto-verified against the conversation every time you call done, and a NOT_MET/IMPOSSIBLE ` +
+  `verdict blocks your reply and tells you what's missing. goal {action:"get"} shows the current ` +
+  `condition and its latest verdict. goal {action:"clear"} removes it.`;
+
+function formatState(state: GoalState | null): string {
+  if (!state) return `No goal set for this session. Set one with goal {action:"set", condition}.`;
+  const last = state.verdicts[state.verdicts.length - 1];
+  const verdictLine = last
+    ? `Last verdict: ${last.verdict}${last.gap ? ` — ${last.gap}` : ""}`
+    : "No verdicts yet (verified on your next done call).";
+  return `Goal: "${state.condition}" (set ${new Date(state.setAt).toLocaleTimeString()})\n${verdictLine}`;
+}
+
+export function createGoalTool(): ToolHandler {
+  return async (args: Record<string, any>, cwd: string): Promise<ToolResult> => {
+    const action = String(args.action ?? "get").trim().toLowerCase();
+
+    if (action === "set") {
+      const condition = typeof args.condition === "string" ? args.condition.trim() : "";
+      if (!condition) {
+        return { success: false, output: "", error: `goal {action:"set"} requires a non-empty 'condition'.` };
+      }
+      await writeGoalState({ condition, setAt: Date.now(), verdicts: [] }, cwd);
+      return {
+        success: true,
+        output: `Goal set: "${condition}". It will be auto-verified against the conversation each time you call done.`,
+      };
+    }
+
+    if (action === "clear") {
+      await clearGoalState(cwd);
+      return { success: true, output: "Goal cleared." };
+    }
+
+    if (action === "get") {
+      const state = await readGoalState(cwd);
+      return { success: true, output: formatState(state) };
+    }
+
+    return { success: false, output: "", error: `Unknown goal action '${action}'. Use set | get | clear.` };
+  };
+}

package/src/agent/irc-tool.ts

@@ -0,0 +1,71 @@
+/**
+ * `irc` tool — lets the PARENT list running DETACHED subagents as "peers" and send
+ * a live message to one or all of them (gjc `irc` parity, scoped to an in-process
+ * registry: no separate peer directory, no channels — a running detached subagent
+ * IS a peer). Built entirely on `SubagentRegistry.running()` / `.steer()`; this file
+ * holds no state of its own.
+ *
+ * Delivery mechanism is identical to `subagent {action:"steer"}` — a pushed message
+ * sits in that subagent's registry inbox until its own agent loop drains it between
+ * steps (see `subagent-registry.ts` steer()/steerDrainFor()). "send to all" simply
+ * loops registry.steer() over every currently running id.
+ */
+import type { ToolHandler } from "./engine";
+import type { ToolResult } from "./tools";
+import type { SubagentRegistry, SubagentRecord } from "./subagent-registry";
+
+/** One-line protocol description appended to the launch system prompt. */
+export const IRC_TOOL_PROTOCOL_LINE =
+  `irc {action:"list"|"send", to?, message?} — live peer messaging with DETACHED ` +
+  `subagents started with task{detached:true}. 'list' shows running subagents as peers; ` +
+  `'send' delivers {to, message} to one running peer (to: its id) or every running peer ` +
+  `(to:"all"), picked up before its next step.`;
+
+function peerLine(rec: SubagentRecord): string {
+  return `- ${rec.id} (${rec.role}) · ${rec.task}`;
+}
+
+export function createIrcTool(registry: SubagentRegistry): ToolHandler {
+  return async (args: Record<string, any>, _cwd: string): Promise<ToolResult> => {
+    const action = String(args.action ?? "list").trim().toLowerCase();
+
+    if (action === "list") {
+      const peers = registry.running();
+      if (peers.length === 0) {
+        return { success: true, output: "No running subagent peers. Launch one with task {detached:true}." };
+      }
+      return { success: true, output: peers.map(peerLine).join("\n") };
+    }
+
+    if (action === "send") {
+      const message = typeof args.message === "string" ? args.message : typeof args.text === "string" ? args.text : "";
+      const to = typeof args.to === "string" ? args.to.trim() : "";
+      if (!message.trim()) {
+        return { success: false, output: "", error: "irc 'send' requires a non-empty 'message' (or 'text')." };
+      }
+      if (!to) {
+        return { success: false, output: "", error: "irc 'send' requires a 'to' target: a running subagent id, or \"all\"." };
+      }
+
+      if (to === "all") {
+        const peers = registry.running();
+        let sent = 0;
+        for (const peer of peers) {
+          if (registry.steer(peer.id, message)) sent++;
+        }
+        if (sent === 0) {
+          return { success: false, output: "", error: "No running subagent peers to send to." };
+        }
+        return { success: true, output: `Sent to ${sent} running peer(s).` };
+      }
+
+      const ok = registry.steer(to, message);
+      if (!ok) {
+        return { success: false, output: "", error: `No running subagent peer '${to}'.` };
+      }
+      return { success: true, output: `Sent to ${to}.` };
+    }
+
+    return { success: false, output: "", error: `Unknown irc action '${action}'. Use list | send.` };
+  };
+}

package/src/agent/job-registry.ts

@@ -0,0 +1,163 @@
+/**
+ * In-process registry for BACKGROUND shell processes (gjc `job`/async-bash parity,
+ * scoped down to one runtime). Unlike the synchronous `bash` tool, `start()` spawns
+ * a real parallel OS process via `Bun.spawn` and returns immediately — the parent
+ * can keep working and later list / tail / await / cancel it via the `job` control
+ * tool while stdout/stderr drain into a bounded buffer in the background.
+ *
+ * Lifecycle is bounded to the turn that created the registry — `cancelAll()` on
+ * turn teardown guarantees no background process leaks into the next turn.
+ */
+
+export type JobStatus = "running" | "exited" | "killed" | "failed";
+
+export interface JobRecord {
+  /** Stable id, e.g. "job-1". */
+  id: string;
+  command: string;
+  cwd: string;
+  status: JobStatus;
+  startedAt: number;
+  finishedAt?: number;
+  exitCode?: number | null;
+}
+
+interface Entry {
+  record: JobRecord;
+  proc: Bun.Subprocess<"ignore", "pipe", "pipe">;
+  promise: Promise<void>;
+}
+
+const OUTPUT_CAP = 20000;
+const TRUNCATION_MARKER = "[…output truncated…]\n";
+
+export class JobRegistry {
+  private readonly entries = new Map<string, Entry>();
+  private readonly buffers = new Map<string, string>();
+  private readonly truncated = new Set<string>();
+  private seq = 0;
+
+  private append(id: string, chunk: string): void {
+    if (!chunk) return;
+    let buf = (this.buffers.get(id) ?? "") + chunk;
+    if (buf.length > OUTPUT_CAP) {
+      buf = buf.slice(buf.length - OUTPUT_CAP);
+      if (!this.truncated.has(id)) {
+        this.truncated.add(id);
+        buf = TRUNCATION_MARKER + buf;
+      }
+    }
+    this.buffers.set(id, buf);
+  }
+
+  /** Spawn and START a background OS process; returns the (running) record immediately. */
+  start(command: string, cwd: string): JobRecord {
+    this.seq += 1;
+    const id = `job-${this.seq}`;
+    const record: JobRecord = {
+      id,
+      command,
+      cwd,
+      status: "running",
+      startedAt: Date.now(),
+    };
+    this.buffers.set(id, "");
+
+    let proc: Bun.Subprocess<"ignore", "pipe", "pipe">;
+    try {
+      proc = Bun.spawn(["bash", "-c", command], { cwd, stdin: "ignore", stdout: "pipe", stderr: "pipe" });
+    } catch (err) {
+      record.status = "failed";
+      record.finishedAt = Date.now();
+      this.append(id, err instanceof Error ? err.message : String(err));
+      // No process handle to store — nothing further to drain or cancel.
+      this.entries.set(id, { record, proc: undefined as any, promise: Promise.resolve() });
+      return record;
+    }
+
+    const drain = async (stream: ReadableStream<Uint8Array>) => {
+      const decoder = new TextDecoder();
+      for await (const chunk of stream) {
+        this.append(id, decoder.decode(chunk, { stream: true }));
+      }
+    };
+
+    const promise = (async () => {
+      try {
+        await Promise.all([drain(proc.stdout), drain(proc.stderr)]);
+        const exitCode = await proc.exited;
+        if (record.status === "killed") return;
+        record.status = "exited";
+        record.exitCode = exitCode;
+      } catch (err) {
+        if (record.status === "killed") return;
+        record.status = "failed";
+        this.append(id, err instanceof Error ? err.message : String(err));
+      } finally {
+        if (record.finishedAt === undefined) record.finishedAt = Date.now();
+      }
+    })();
+
+    this.entries.set(id, { record, proc, promise });
+    return record;
+  }
+
+  list(): JobRecord[] {
+    return [...this.entries.values()].map(e => e.record);
+  }
+
+  get(id: string): JobRecord | undefined {
+    return this.entries.get(id)?.record;
+  }
+
+  running(): JobRecord[] {
+    return this.list().filter(r => r.status === "running");
+  }
+
+  /** Current buffered output for one job (empty string if the id is unknown). */
+  tail(id: string): string {
+    return this.buffers.get(id) ?? "";
+  }
+
+  /** Wait for the given ids. With `timeoutMs` the wait is bounded — unfinished jobs
+   *  simply stay "running" in the returned snapshot. */
+  async awaitIds(ids: string[], timeoutMs?: number): Promise<JobRecord[]> {
+    const targets = ids
+      .map(id => this.entries.get(id))
+      .filter((e): e is Entry => e !== undefined);
+    const all = Promise.all(targets.map(e => e.promise)).then(() => {});
+    if (timeoutMs !== undefined && timeoutMs > 0) {
+      let handle: ReturnType<typeof setTimeout> | undefined;
+      const timer = new Promise<void>(resolve => {
+        handle = setTimeout(resolve, timeoutMs);
+      });
+      await Promise.race([all, timer]);
+      if (handle !== undefined) clearTimeout(handle);
+    } else {
+      await all;
+    }
+    return targets.map(e => e.record);
+  }
+
+  /** Cancel the given ids: SIGTERM via `proc.kill()` and mark killed. Already-terminal
+   *  records are returned unchanged. */
+  cancel(ids: string[]): JobRecord[] {
+    const out: JobRecord[] = [];
+    for (const id of ids) {
+      const e = this.entries.get(id);
+      if (!e) continue;
+      if (e.record.status === "running") {
+        e.record.status = "killed";
+        e.record.finishedAt = Date.now();
+        e.proc?.kill();
+      }
+      out.push(e.record);
+    }
+    return out;
+  }
+
+  /** Kill every still-running job (turn teardown / Ctrl-C). */
+  cancelAll(): JobRecord[] {
+    return this.cancel(this.running().map(r => r.id));
+  }
+}

package/src/agent/job-tool.ts

@@ -0,0 +1,106 @@
+/**
+ * `job` control tool — the parent's handle on BACKGROUND shell processes launched
+ * via `job {action:"start"}`. Mirrors gjc's `job`/async-bash control surface, scoped
+ * to an in-process registry: start, list, tail, await (optionally bounded), and cancel.
+ */
+import type { ToolHandler } from "./engine";
+import type { ToolResult } from "./tools";
+import type { JobRegistry, JobRecord } from "./job-registry";
+
+/** One-line protocol description appended to the launch system prompt. */
+export const JOB_TOOL_PROTOCOL_LINE =
+  `job {action:"start", command, cwd?} runs a shell command in the BACKGROUND as a real ` +
+  `parallel OS process and returns a job id immediately. job {action:"list"|"tail"|"await"|"cancel", ` +
+  `ids?, timeoutMs?} — 'tail' shows buffered output so far; 'await' blocks (optionally up to timeoutMs ` +
+  `ms) until it exits; 'cancel' kills it; omit ids to target all running.`;
+
+function truncate(s: string, n: number): string {
+  return s.length > n ? s.slice(0, n - 1) + "…" : s;
+}
+
+function elapsed(rec: JobRecord): string {
+  const end = rec.finishedAt ?? Date.now();
+  return `${Math.max(0, Math.round((end - rec.startedAt) / 1000))}s`;
+}
+
+function rowLine(rec: JobRecord): string {
+  return `- ${rec.id} [${rec.status.toUpperCase()}] ${elapsed(rec)} · ${truncate(rec.command, 100)}`;
+}
+
+function idsOf(args: Record<string, any>): string[] {
+  if (Array.isArray(args.ids)) return args.ids.map((x: unknown) => String(x));
+  if (args.id !== undefined) return [String(args.id)];
+  return [];
+}
+
+export function createJobTool(registry: JobRegistry): ToolHandler {
+  return async (args: Record<string, any>, cwd: string): Promise<ToolResult> => {
+    const action = String(args.action ?? "list").trim().toLowerCase();
+    const ids = idsOf(args);
+
+    if (action === "start") {
+      const command = typeof args.command === "string" ? args.command.trim() : "";
+      if (!command) {
+        return { success: false, output: "", error: `job {action:"start"} requires a non-empty 'command'.` };
+      }
+      const resolvedCwd = typeof args.cwd === "string" && args.cwd.trim() ? args.cwd : cwd;
+      const rec = registry.start(command, resolvedCwd);
+      return {
+        success: true,
+        output: `[background] started job '${rec.id}': ${truncate(command, 120)}. It runs in the background — ` +
+          `keep working, then use the 'job' tool ({action:"tail"|"await"|"list"|"cancel", ids?}) to check on it.`,
+      };
+    }
+
+    if (action === "list") {
+      const rows = registry.list();
+      if (rows.length === 0) {
+        return { success: true, output: `No background jobs this turn. Launch one with job {action:"start", command}.` };
+      }
+      const running = rows.filter(r => r.status === "running").length;
+      return { success: true, output: `${rows.length} job(s), ${running} running:\n${rows.map(rowLine).join("\n")}` };
+    }
+
+    if (action === "tail") {
+      const targets = ids.length ? ids : registry.running().map(r => r.id);
+      if (targets.length === 0) {
+        return { success: true, output: "No running jobs to tail." };
+      }
+      const unknown = targets.filter(id => !registry.get(id));
+      if (unknown.length > 0) {
+        return { success: false, output: "", error: `No job matches ${unknown.join(", ")}.` };
+      }
+      const blocks = targets.map(id => {
+        const rec = registry.get(id)!;
+        const out = registry.tail(id);
+        return `- ${rec.id} [${rec.status.toUpperCase()}]:\n${out || "(no output yet)"}`;
+      });
+      return { success: true, output: blocks.join("\n\n") };
+    }
+
+    if (action === "await") {
+      const targets = ids.length ? ids : registry.running().map(r => r.id);
+      if (targets.length === 0) {
+        return { success: true, output: "No running jobs to await." };
+      }
+      const timeoutMs = typeof args.timeoutMs === "number" && args.timeoutMs > 0 ? args.timeoutMs : undefined;
+      const recs = await registry.awaitIds(targets, timeoutMs);
+      const stillRunning = recs.filter(r => r.status === "running").length;
+      const head = stillRunning > 0
+        ? `Awaited ${recs.length} job(s); ${stillRunning} still running after the ${timeoutMs}ms timeout — await again or cancel.`
+        : `Awaited ${recs.length} job(s); all settled.`;
+      return { success: stillRunning === 0, output: `${head}\n\n${recs.map(rowLine).join("\n")}` };
+    }
+
+    if (action === "cancel") {
+      const targets = ids.length ? ids : registry.running().map(r => r.id);
+      if (targets.length === 0) {
+        return { success: true, output: "No running jobs to cancel." };
+      }
+      const recs = registry.cancel(targets);
+      return { success: true, output: `Cancelled ${recs.length} job(s):\n${recs.map(rowLine).join("\n")}` };
+    }
+
+    return { success: false, output: "", error: `Unknown job action '${action}'. Use start | list | tail | await | cancel.` };
+  };
+}

package/src/agent/lsp-rename-tool.ts

@@ -0,0 +1,108 @@
+/**
+ * `lsp_rename` tool — cross-file TypeScript/JavaScript symbol rename (gjc `lsp`
+ * `action:"rename"` parity), using the same in-process `ts.LanguageService` as the
+ * read-only `lsp` tool. MUTATING: kept as its own tool (not an action on `lsp`) so
+ * the read-only-role toolset filter — which excludes tools by NAME — cannot be
+ * bypassed by an `apply:true` argument hidden inside a nominally "read-only" tool.
+ * Writes go through the existing `writeTool`, so the mutation lock and stale-read
+ * guard apply exactly as they do for `write`/`edit`/`ast_edit`.
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import type * as ts from "typescript";
+import type { ToolHandler } from "./engine";
+import type { ToolResult } from "./tools";
+import { writeTool } from "./tools";
+import { languageServiceFor, parseSymbolSelector, resolvePosition, lineTextAt, lineOfPosition, formatLocation } from "./ts-language-service";
+
+/** One-line protocol description appended to the launch system prompt. */
+export const LSP_RENAME_TOOL_PROTOCOL_LINE =
+  `lsp_rename {file, line, symbol?, new_name, apply?} — rename a TypeScript/JavaScript symbol across every ` +
+  `file in the project via the same in-process language service as 'lsp' (same file/line/symbol addressing). ` +
+  `'apply' defaults to true (writes files — mutation lock/stale-read checks apply, same as write/edit); ` +
+  `apply:false previews every location that would change without writing anything.`;
+
+function err(message: string): ToolResult {
+  return { success: false, output: "", error: message };
+}
+
+const IDENTIFIER_RE = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+
+export function createLspRenameTool(): ToolHandler {
+  return async (args: Record<string, any>, cwd: string): Promise<ToolResult> => {
+    const fileArg = typeof args.file === "string" ? args.file.trim() : "";
+    if (!fileArg) return err(`lsp_rename requires a non-empty "file".`);
+
+    const newName = typeof args.new_name === "string" ? args.new_name.trim()
+      : typeof args.newName === "string" ? args.newName.trim() : "";
+    if (!newName) return err(`lsp_rename requires a non-empty "new_name".`);
+    if (!IDENTIFIER_RE.test(newName)) return err(`"new_name" must be a valid identifier, got '${newName}'.`);
+
+    const absPath = path.resolve(cwd, fileArg);
+    let text: string;
+    try {
+      text = await fs.readFile(absPath, "utf-8");
+    } catch {
+      return err(`Cannot read file '${fileArg}'.`);
+    }
+
+    const lineRaw = args.line;
+    const line = typeof lineRaw === "number" ? lineRaw : parseInt(String(lineRaw ?? ""), 10);
+    if (!Number.isFinite(line) || line < 1) return err(`lsp_rename requires a positive integer "line".`);
+
+    const symbol = parseSymbolSelector(typeof args.symbol === "string" ? args.symbol : undefined);
+    const pos = resolvePosition(text, line, symbol);
+    if ("error" in pos) return err(pos.error);
+
+    const service = await languageServiceFor(cwd, absPath);
+    const renameInfo = service.getRenameInfo(absPath, pos.position, {});
+    if (!renameInfo.canRename) {
+      const reason = "localizedErrorMessage" in renameInfo ? renameInfo.localizedErrorMessage : "not a renameable symbol here";
+      return err(`Cannot rename here: ${reason}.`);
+    }
+
+    const locations = service.findRenameLocations(absPath, pos.position, false, false, {}) ?? [];
+    if (locations.length === 0) return { success: true, output: "No rename locations found." };
+
+    const apply = args.apply !== false; // default true
+
+    const byFile = new Map<string, ts.TextSpan[]>();
+    for (const loc of locations) {
+      const spans = byFile.get(loc.fileName) ?? [];
+      spans.push(loc.textSpan);
+      byFile.set(loc.fileName, spans);
+    }
+
+    const preview: string[] = [];
+    let totalEdits = 0;
+    for (const [fName, spans] of byFile) {
+      const rel = path.relative(cwd, fName) || fName;
+      let content: string;
+      try {
+        content = await fs.readFile(fName, "utf-8");
+      } catch {
+        return err(`Cannot read file '${rel}' while applying rename.`);
+      }
+
+      for (const span of spans) {
+        totalEdits++;
+        const line1 = lineOfPosition(content, span.start);
+        preview.push(formatLocation(rel, line1, lineTextAt(content, line1)));
+      }
+
+      if (apply) {
+        let newText = content;
+        for (const span of [...spans].sort((a, b) => b.start - a.start)) {
+          newText = newText.slice(0, span.start) + newName + newText.slice(span.start + span.length);
+        }
+        const res = await writeTool(rel, newText, cwd);
+        if (!res.success) return err(`${rel}: ${res.error ?? "write failed"}`);
+      }
+    }
+
+    const header = apply
+      ? `Renamed ${totalEdits} occurrence(s) across ${byFile.size} file(s):`
+      : `Preview: ${totalEdits} occurrence(s) across ${byFile.size} file(s) would be renamed to '${newName}' (apply:false, nothing written):`;
+    return { success: true, output: `${header}\n${preview.join("\n")}` };
+  };
+}