jeo-code 0.7.30 → 0.7.32

package/src/agent/engine.ts

@@ -15,6 +15,12 @@ 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 { isRateLimitError, waitAbortable } from "../util/retry";
 import { isContextOverflowError, isRefusalError, friendlyProviderError } from "../util/provider-error";
 import { runPreToolHooks, runPostTurnHooksForBatch } from "./hooks";
@@ -82,7 +88,21 @@ 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(),
 };
 /** Tool-protocol description injected into the system prompt. */
 export const TOOL_PROTOCOL = [
@@ -98,7 +118,12 @@ 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. 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 +145,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 +468,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
@@ -545,14 +579,39 @@ export async function runAgentLoop(history: Message[], opts: AgentLoopOptions):
     // (a TUI). Non-interactive/test callers leave onModelStream unset → a single
     // non-streaming call(), unchanged. The accumulated text is still parsed as one JSON
     // tool call below, so streaming changes nothing about loop semantics.
+    //
+    // Emission throttle (~80ms, mirroring the bash live sink): every delta still
+    // ACCUMULATES, but re-emitting the full growing buffer per token made the handoff
+    // O(len²) over a long response — each emit flattens the rope and the TUI re-scans
+    // its head. Timer-less by design; flushStreams() below guarantees the consumers'
+    // LAST snapshot is the complete text before it is parsed/committed.
+    const STREAM_EMIT_MS = 80;
     let streamBuf = "";
+    let lastModelEmit = 0;
     const onToken = ev.onModelStream
-      ? (delta: string) => { streamBuf += delta; ev.onModelStream!(streamBuf); }
+      ? (delta: string) => {
+          streamBuf += delta;
+          const now = Date.now();
+          if (now - lastModelEmit >= STREAM_EMIT_MS) { lastModelEmit = now; ev.onModelStream!(streamBuf); }
+        }
       : undefined;
     let reasonBuf = "";
+    let lastReasonEmit = 0;
     const onReasoning = ev.onReasoningStream
-      ? (delta: string) => { reasonBuf += delta; ev.onReasoningStream!(reasonBuf); }
+      ? (delta: string) => {
+          reasonBuf += delta;
+          const now = Date.now();
+          if (now - lastReasonEmit >= STREAM_EMIT_MS) { lastReasonEmit = now; ev.onReasoningStream!(reasonBuf); }
+        }
       : undefined;
+    // The TUI commits its thought/plan blocks from the LAST received snapshot
+    // (onAssistant); emit the complete buffers once so a throttled trailing delta
+    // can never be dropped from the committed record. Re-emitting an identical
+    // snapshot is idempotent for the consumers (they diff before drawing).
+    const flushStreams = () => {
+      if (streamBuf) ev.onModelStream?.(streamBuf);
+      if (reasonBuf) ev.onReasoningStream?.(reasonBuf);
+    };
     // Capture provider-native reasoning ARTIFACTS for replay (always — independent of any
     // TUI display sink). Stays scoped to THIS step so a later consolidation push can't
     // inherit a prior step's signatures.
@@ -687,6 +746,7 @@ export async function runAgentLoop(history: Message[], opts: AgentLoopOptions):
       // separate error event here printed the same message twice (live stream + reply).
       return finish({ done: false, steps: step, doneReason: `Error: ${message}` });
     }
+    flushStreams(); // deliver the final (possibly throttled-out) snapshot before parse/commit
     if (sawUsage) ev.onUsage?.({ ...acc });
 
     let invocation: any;
@@ -780,12 +840,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
@@ -837,10 +917,12 @@ export async function runAgentLoop(history: Message[], opts: AgentLoopOptions):
     //    after a SUCCESSFUL write because nothing ever told the model to stop
     //    repeating — a recovery prompt resolves that without killing the turn.
     //  - 3rd identical step (repeated through the explicit correction) → stop.
-    const callSigs = toolCalls.map(c => `${c.tool}:${JSON.stringify(c.arguments ?? {})}`);
-    // Fixed-size digest of the whole step — `write` signatures embed entire file
-    // bodies, so the repeat/cycle guards compare digests, not megabyte strings.
-    const sig = hashSignature(callSigs.join(" | "));
+    // Per-call fixed-size digests — `write` arguments embed entire file bodies, so
+    // every guard below compares/records digests, never megabyte strings. Hashing
+    // once per call here (instead of joining full sigs, hashing, then re-hashing
+    // inside budget.record) avoids re-scanning a large write body 3× per step.
+    const callSigs = toolCalls.map(c => hashSignature(`${c.tool}:${JSON.stringify(c.arguments ?? {})}`));
+    const sig = callSigs.length === 1 ? callSigs[0] : hashSignature(callSigs.join(" | "));
     if (sig === lastSig) repeatCount++;
     else {
       repeatCount = 1;
@@ -1145,7 +1227,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++;
   }
 

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.` };
+  };
+}