@noobdemon/noob-cli 1.10.20 → 1.11.0

package/src/tools.js

@@ -1,7 +1,7 @@
-import fs from "node:fs/promises";
-import fssync from "node:fs";
-import path from "node:path";
-import { spawn } from "node:child_process";
+import fs from 'node:fs/promises';
+import fssync from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
 
 const MAX_OUT = 30000; // hard cap on any tool result fed back to the model
 const cwd = () => process.cwd();
@@ -18,8 +18,8 @@ const extraRoots = new Set();
 export class OutOfScopeError extends Error {
   constructor(p, suggestedRoot) {
     super(`path nằm ngoài phạm vi (cwd + /add-dir): ${p}`);
-    this.name = "OutOfScopeError";
-    this.code = "OUT_OF_SCOPE";
+    this.name = 'OutOfScopeError';
+    this.code = 'OUT_OF_SCOPE';
     this.path = p;
     this.suggestedRoot = suggestedRoot;
   }
@@ -51,14 +51,14 @@ export function nearestExistingDir(p) {
 // Lưu NGAY khi addRoot được gọi (cả /add-dir lẫn auto-prompt path), nên user
 // không phải /add-dir lại mỗi lần mở project. Nếu read-only hoặc permission
 // deny → âm thầm bỏ qua (addRoot vẫn áp dụng cho phiên hiện tại).
-const WORKSPACE_DIRS_FILE = () => path.join(cwd(), ".noob", "dirs.json");
+const WORKSPACE_DIRS_FILE = () => path.join(cwd(), '.noob', 'dirs.json');
 function loadWorkspaceRoots() {
   try {
-    const raw = fssync.readFileSync(WORKSPACE_DIRS_FILE(), "utf8");
+    const raw = fssync.readFileSync(WORKSPACE_DIRS_FILE(), 'utf8');
     const arr = JSON.parse(raw);
     if (!Array.isArray(arr)) return;
     for (const r of arr) {
-      if (typeof r !== "string") continue;
+      if (typeof r !== 'string') continue;
       const full = path.resolve(r);
       try {
         if (fssync.statSync(full).isDirectory()) extraRoots.add(full);
@@ -70,7 +70,7 @@ function saveWorkspaceRoots() {
   try {
     const file = WORKSPACE_DIRS_FILE();
     fssync.mkdirSync(path.dirname(file), { recursive: true });
-    fssync.writeFileSync(file, JSON.stringify([...extraRoots], null, 2), "utf8");
+    fssync.writeFileSync(file, JSON.stringify([...extraRoots], null, 2), 'utf8');
     return true;
   } catch {
     return false;
@@ -79,11 +79,15 @@ function saveWorkspaceRoots() {
 loadWorkspaceRoots();
 
 export function addRoot(p) {
-  if (!p) throw new Error("thiếu path");
+  if (!p) throw new Error('thiếu path');
   const full = path.resolve(p);
   let st;
-  try { st = fssync.statSync(full); } catch { throw new Error("không tồn tại: " + p); }
-  if (!st.isDirectory()) throw new Error("không phải thư mục: " + p);
+  try {
+    st = fssync.statSync(full);
+  } catch {
+    throw new Error('không tồn tại: ' + p);
+  }
+  if (!st.isDirectory()) throw new Error('không phải thư mục: ' + p);
   extraRoots.add(full);
   saveWorkspaceRoots(); // persist per-workspace — lần sau mở project auto-load
   return full;
@@ -102,7 +106,7 @@ export function listRoots() {
 function within(root, full) {
   if (full === root) return true;
   const rel = path.relative(root, full);
-  return !!rel && !rel.startsWith("..") && !path.isAbsolute(rel);
+  return !!rel && !rel.startsWith('..') && !path.isAbsolute(rel);
 }
 
 const abs = (p) => {
@@ -125,11 +129,11 @@ const abs = (p) => {
   }
   throw new OutOfScopeError(p, nearestExistingDir(p));
 };
-const rel = (p) => path.relative(cwd(), p) || ".";
+const rel = (p) => path.relative(cwd(), p) || '.';
 // Tên rút gọn để hiển thị: nếu path thuộc cwd → relative cwd; nếu thuộc một
 // extra root → "<rootName>/<rel>" để user phân biệt được; còn lại fallback path tuyệt đối.
 function displayPath(full) {
-  if (within(cwd(), full)) return path.relative(cwd(), full) || ".";
+  if (within(cwd(), full)) return path.relative(cwd(), full) || '.';
   for (const r of extraRoots) {
     if (within(r, full)) {
       const sub = path.relative(r, full);
@@ -139,10 +143,22 @@ function displayPath(full) {
   return full;
 }
 function relFrom(root, full) {
-  return path.relative(root, full) || ".";
+  return path.relative(root, full) || '.';
 }
 // Thư mục bỏ qua khi walk (glob/grep). node_modules + các thư mục build/cache phổ biến.
-const SKIP_DIRS = new Set(["node_modules", ".next", "dist", "build", ".venv", "venv", "__pycache__", ".cache", ".turbo", ".parcel-cache", "target"]);
+const SKIP_DIRS = new Set([
+  'node_modules',
+  '.next',
+  'dist',
+  'build',
+  '.venv',
+  'venv',
+  '__pycache__',
+  '.cache',
+  '.turbo',
+  '.parcel-cache',
+  'target',
+]);
 
 function clip(s) {
   if (s.length <= MAX_OUT) return s;
@@ -150,7 +166,36 @@ function clip(s) {
 }
 
 // Tools that mutate the filesystem or run code require user approval.
-export const DESTRUCTIVE = new Set(["write_file", "edit_file", "run_command"]);
+export const DESTRUCTIVE = new Set(['write_file', 'edit_file', 'run_command']);
+
+/**
+ * Tên các tool model có thể gọi.
+ * @typedef {'read_file'|'write_file'|'edit_file'|'list_dir'|'glob'|'grep'|'run_command'|'bg_output'|'kill_bg'} ToolName
+ */
+
+/**
+ * Input cho mỗi tool (chỉ liệt kê field thực sự dùng — gateway có thể gửi thêm).
+ * @typedef {Object} ToolInput
+ * @property {string} [path] read_file/write_file/edit_file/list_dir
+ * @property {number} [offset] read_file: dòng bắt đầu (1-indexed)
+ * @property {number} [limit] read_file: số dòng tối đa
+ * @property {string} [content] write_file
+ * @property {string} [old_string] edit_file
+ * @property {string} [new_string] edit_file
+ * @property {boolean} [replace_all] edit_file: thay tất cả thay vì 1 lần
+ * @property {string} [pattern] glob/grep
+ * @property {string} [glob] grep: filter file theo glob
+ * @property {string} [command] run_command
+ * @property {number} [timeout] run_command: ms (default 60000)
+ * @property {boolean} [background] run_command: spawn ngầm, trả về NGAY
+ * @property {number} [id] bg_output/kill_bg
+ */
+
+/**
+ * Options khi chạy tool.
+ * @typedef {Object} ToolRunOpts
+ * @property {AbortSignal} [signal] Ctrl+C → tool bail giữa chừng
+ */
 
 // ── Tiến trình nền ─────────────────────────────────────────────────────────
 // Lệnh chạy lâu / không bao giờ thoát (dev server, watcher) KHÔNG được chạy ở
@@ -160,7 +205,8 @@ const bg = new Map(); // id -> { child, command, out, exited, code, startedAt }
 let bgSeq = 0;
 function killBgTree(child) {
   try {
-    if (process.platform === "win32" && child.pid) spawn("taskkill", ["/pid", String(child.pid), "/T", "/F"]);
+    if (process.platform === 'win32' && child.pid)
+      spawn('taskkill', ['/pid', String(child.pid), '/T', '/F']);
     else child.kill();
   } catch {}
 }
@@ -171,8 +217,8 @@ function killBgTree(child) {
 function cleanupBg() {
   for (const p of bg.values()) killBgTree(p.child);
 }
-process.on("exit", cleanupBg);
-process.on("SIGTERM", () => {
+process.on('exit', cleanupBg);
+process.on('SIGTERM', () => {
   cleanupBg();
   process.exit(143);
 });
@@ -180,39 +226,39 @@ process.on("SIGTERM", () => {
 // Helper: throw nếu signal đã abort. Dùng ở đầu mỗi tool + giữa các vòng walk dài
 // để tool fs (glob/grep) cũng phản ứng với Ctrl+C, không chỉ run_command.
 function checkAbort(signal) {
-  if (signal?.aborted) throw new Error("aborted");
+  if (signal?.aborted) throw new Error('aborted');
 }
 
 export const TOOLS = {
   async read_file({ path: p, offset, limit }, { signal } = {}) {
     checkAbort(signal);
-    const data = await fs.readFile(abs(p), "utf8");
-    let lines = data.split("\n");
+    const data = await fs.readFile(abs(p), 'utf8');
+    let lines = data.split('\n');
     const start = offset ? Math.max(0, offset - 1) : 0;
     if (offset || limit) lines = lines.slice(start, limit ? start + limit : undefined);
     const width = String(start + lines.length).length;
     return clip(
-      lines.map((l, idx) => String(start + idx + 1).padStart(width) + "  " + l).join("\n"),
+      lines.map((l, idx) => String(start + idx + 1).padStart(width) + '  ' + l).join('\n')
     );
   },
 
   async write_file({ path: p, content }, { signal } = {}) {
     checkAbort(signal);
     await fs.mkdir(path.dirname(abs(p)), { recursive: true });
-    await fs.writeFile(abs(p), content ?? "", "utf8");
-    const n = (content ?? "").split("\n").length;
+    await fs.writeFile(abs(p), content ?? '', 'utf8');
+    const n = (content ?? '').split('\n').length;
     return `Wrote ${n} line(s) to ${rel(abs(p))}`;
   },
 
   async edit_file({ path: p, old_string, new_string, replace_all }, { signal } = {}) {
     checkAbort(signal);
     const file = abs(p);
-    const data = await fs.readFile(file, "utf8");
-    if (old_string === new_string) throw new Error("old_string and new_string are identical");
-    const useCRLF = data.includes("\r\n");
+    const data = await fs.readFile(file, 'utf8');
+    if (old_string === new_string) throw new Error('old_string and new_string are identical');
+    const useCRLF = data.includes('\r\n');
     const adapt = (s) => {
-      const lf = s.replace(/\r\n/g, "\n");
-      return useCRLF ? lf.replace(/\n/g, "\r\n") : lf;
+      const lf = s.replace(/\r\n/g, '\n');
+      return useCRLF ? lf.replace(/\n/g, '\r\n') : lf;
     };
     // Thay không diễn giải $&/$1… (split/slice, không dùng String.replace).
     const applyExact = (cand, newS) => {
@@ -222,14 +268,18 @@ export const TOOLS = {
     };
 
     // Tier 1 + 2: khớp NGUYÊN VĂN, rồi khớp sau khi chỉnh CRLF cho hợp file.
-    for (const cand of old_string === adapt(old_string) ? [old_string] : [old_string, adapt(old_string)]) {
+    for (const cand of old_string === adapt(old_string)
+      ? [old_string]
+      : [old_string, adapt(old_string)]) {
       const count = data.split(cand).length - 1;
       if (count === 0) continue;
       if (count > 1 && !replace_all)
-        throw new Error(`old_string is not unique (${count} matches) in ${rel(file)}; set replace_all, or add surrounding lines to make it unique`);
+        throw new Error(
+          `old_string is not unique (${count} matches) in ${rel(file)}; set replace_all, or add surrounding lines to make it unique`
+        );
       // LUÔN adapt new_string về line ending của file (kể cả khi cand match raw old_string),
       // tránh tạo file mix CRLF/LF làm git/editor hiển thị diff lạ → user tưởng 'Edited nhưng không apply'.
-      await fs.writeFile(file, applyExact(cand, adapt(new_string)), "utf8");
+      await fs.writeFile(file, applyExact(cand, adapt(new_string)), 'utf8');
       return `Edited ${rel(file)} (${replace_all ? count : 1} replacement(s))`;
     }
 
@@ -237,29 +287,33 @@ export const TOOLS = {
     // (Thụt đầu dòng vẫn phải khớp → không bao giờ sửa nhầm chỗ.)
     const m = matchByLines(data, old_string);
     if (m && m.count > 1 && !replace_all)
-      throw new Error(`old_string khớp ${m.count} chỗ (sau khi bỏ qua khoảng trắng cuối dòng) trong ${rel(file)}; thêm dòng ngữ cảnh hoặc dùng replace_all`);
+      throw new Error(
+        `old_string khớp ${m.count} chỗ (sau khi bỏ qua khoảng trắng cuối dòng) trong ${rel(file)}; thêm dòng ngữ cảnh hoặc dùng replace_all`
+      );
     if (m && m.count === 1) {
       const next = data.slice(0, m.start) + adapt(new_string) + data.slice(m.end);
-      await fs.writeFile(file, next, "utf8");
+      await fs.writeFile(file, next, 'utf8');
       return `Edited ${rel(file)} (1 replacement(s))`;
     }
 
     // Không thấy → lỗi GIÀU THÔNG TIN: cho model thấy đúng byte trong file để sửa.
     throw new Error(
       `old_string not found in ${rel(file)}. Copy the target text EXACTLY (indentation/whitespace included, NO line-number prefix).` +
-        nearbyContext(data, old_string),
+        nearbyContext(data, old_string)
     );
   },
 
-  async list_dir({ path: p = "." }, { signal } = {}) {
+  async list_dir({ path: p = '.' }, { signal } = {}) {
     checkAbort(signal);
     const dir = abs(p);
     const entries = await fs.readdir(dir, { withFileTypes: true });
     const rows = entries
-      .filter((e) => !e.name.startsWith(".git") && e.name !== "node_modules")
-      .sort((a, b) => Number(b.isDirectory()) - Number(a.isDirectory()) || a.name.localeCompare(b.name))
-      .map((e) => (e.isDirectory() ? e.name + "/" : e.name));
-    return clip(`${rel(dir)}/  (${rows.length} entries)\n` + rows.map((r) => "  " + r).join("\n"));
+      .filter((e) => !e.name.startsWith('.git') && e.name !== 'node_modules')
+      .sort(
+        (a, b) => Number(b.isDirectory()) - Number(a.isDirectory()) || a.name.localeCompare(b.name)
+      )
+      .map((e) => (e.isDirectory() ? e.name + '/' : e.name));
+    return clip(`${rel(dir)}/  (${rows.length} entries)\n` + rows.map((r) => '  ' + r).join('\n'));
   },
 
   async glob({ pattern }, { signal } = {}) {
@@ -279,38 +333,40 @@ export const TOOLS = {
         }
         for (const e of ents) {
           if ((++tickCounter & 0xff) === 0) checkAbort(signal);
-          if (SKIP_DIRS.has(e.name) || e.name.startsWith(".git")) continue;
+          if (SKIP_DIRS.has(e.name) || e.name.startsWith('.git')) continue;
           const full = path.join(dir, e.name);
           if (e.isDirectory()) walk(full);
-          else if (rx.test(relFrom(root, full).split(path.sep).join("/"))) hits.push(displayPath(full));
+          else if (rx.test(relFrom(root, full).split(path.sep).join('/')))
+            hits.push(displayPath(full));
           if (hits.length > 500) return;
         }
       })(root);
       if (hits.length > 500) break;
     }
-    return hits.length ? clip(hits.join("\n")) : "No files matched.";
+    return hits.length ? clip(hits.join('\n')) : 'No files matched.';
   },
 
   async grep({ pattern, path: p, glob: g }, { signal } = {}) {
     checkAbort(signal);
-    const rx = new RegExp(pattern, "i");
+    const rx = new RegExp(pattern, 'i');
     const gRx = g ? globToRegExp(g) : null;
     const out = [];
     let tickCounter = 0;
     function scanFile(full) {
       if ((++tickCounter & 0xff) === 0) checkAbort(signal);
       const disp = displayPath(full);
-      const relp = disp.split(path.sep).join("/");
+      const relp = disp.split(path.sep).join('/');
       if (gRx && !gRx.test(relp)) return;
       let txt;
       try {
-        txt = fssync.readFileSync(full, "utf8");
+        txt = fssync.readFileSync(full, 'utf8');
       } catch {
         return;
       }
-      if (txt.includes("\u0000")) return; // skip binary files
-      txt.split("\n").forEach((l, idx) => {
-        if (rx.test(l) && out.length < 200) out.push(`${relp}:${idx + 1}: ${l.trim().slice(0, 200)}`);
+      if (txt.includes('\u0000')) return; // skip binary files
+      txt.split('\n').forEach((l, idx) => {
+        if (rx.test(l) && out.length < 200)
+          out.push(`${relp}:${idx + 1}: ${l.trim().slice(0, 200)}`);
       });
     }
     function walkDir(dir) {
@@ -321,7 +377,7 @@ export const TOOLS = {
         return;
       }
       for (const e of ents) {
-        if (SKIP_DIRS.has(e.name) || e.name.startsWith(".git")) continue;
+        if (SKIP_DIRS.has(e.name) || e.name.startsWith('.git')) continue;
         const full = path.join(dir, e.name);
         if (e.isDirectory()) {
           walkDir(full);
@@ -331,25 +387,25 @@ export const TOOLS = {
       }
     }
     // Không truyền path → quét cwd + tất cả extra roots. Có path → chỉ vùng đó.
-    if (p == null || p === "" || p === ".") {
+    if (p == null || p === '' || p === '.') {
       for (const root of listRoots()) walkDir(root);
     } else {
       let st;
       try {
         st = fssync.statSync(abs(p));
       } catch {
-        return "No matches.";
+        return 'No matches.';
       }
       if (st.isFile()) scanFile(abs(p));
       else walkDir(abs(p));
     }
-    return out.length ? clip(out.join("\n")) : "No matches.";
+    return out.length ? clip(out.join('\n')) : 'No matches.';
   },
 
   run_command({ command, timeout = 60000, background = false }, { signal } = {}) {
-    const isWin = process.platform === "win32";
-    const shell = isWin ? "powershell.exe" : "/bin/bash";
-    const args = isWin ? ["-NoProfile", "-NonInteractive", "-Command", command] : ["-c", command];
+    const isWin = process.platform === 'win32';
+    const shell = isWin ? 'powershell.exe' : '/bin/bash';
+    const args = isWin ? ['-NoProfile', '-NonInteractive', '-Command', command] : ['-c', command];
     // stdin: "ignore" — tiến trình con KHÔNG được chạm vào console/stdin của
     // CLI. Nếu để con kế thừa stdin, trên Windows nó có thể làm readline phát
     // 'close' → CLI tự tắt. Đóng hẳn stdin con để tránh hoàn toàn.
@@ -358,32 +414,32 @@ export const TOOLS = {
     // bằng bg_output, dừng bằng kill_bg.
     if (background) {
       const id = ++bgSeq;
-      const child = spawn(shell, args, { cwd: cwd(), stdio: ["ignore", "pipe", "pipe"] });
-      const proc = { child, command, out: "", exited: false, code: null, startedAt: Date.now() };
+      const child = spawn(shell, args, { cwd: cwd(), stdio: ['ignore', 'pipe', 'pipe'] });
+      const proc = { child, command, out: '', exited: false, code: null, startedAt: Date.now() };
       const cap = (d) => {
         proc.out += d;
         if (proc.out.length > MAX_OUT * 2) proc.out = proc.out.slice(-MAX_OUT * 2); // giữ phần mới nhất
       };
-      child.stdout.on("data", cap);
-      child.stderr.on("data", cap);
-      child.on("error", (e) => {
+      child.stdout.on('data', cap);
+      child.stderr.on('data', cap);
+      child.on('error', (e) => {
         proc.exited = true;
         proc.out += `\n[failed to start: ${e.message}]`;
       });
-      child.on("close", (code) => {
+      child.on('close', (code) => {
         proc.exited = true;
         proc.code = code;
       });
       bg.set(id, proc);
       return Promise.resolve(
-        `Started background process #${id} (pid ${child.pid ?? "?"}): ${command}\n` +
-          `It keeps running and does NOT block further steps. Read its output with bg_output {"id": ${id}}, stop it with kill_bg {"id": ${id}}.`,
+        `Started background process #${id} (pid ${child.pid ?? '?'}): ${command}\n` +
+          `It keeps running and does NOT block further steps. Read its output with bg_output {"id": ${id}}, stop it with kill_bg {"id": ${id}}.`
       );
     }
 
     return new Promise((resolve) => {
-      const child = spawn(shell, args, { cwd: cwd(), stdio: ["ignore", "pipe", "pipe"] });
-      let out = "";
+      const child = spawn(shell, args, { cwd: cwd(), stdio: ['ignore', 'pipe', 'pipe'] });
+      let out = '';
       let timedOut = false;
       let aborted = false;
       const killer = setTimeout(() => {
@@ -398,24 +454,24 @@ export const TOOLS = {
       };
       if (signal) {
         if (signal.aborted) onAbort();
-        else signal.addEventListener("abort", onAbort, { once: true });
+        else signal.addEventListener('abort', onAbort, { once: true });
       }
-      child.stdout.on("data", (d) => (out += d));
-      child.stderr.on("data", (d) => (out += d));
-      child.on("error", (e) => {
+      child.stdout.on('data', (d) => (out += d));
+      child.stderr.on('data', (d) => (out += d));
+      child.on('error', (e) => {
         clearTimeout(killer);
-        signal?.removeEventListener?.("abort", onAbort);
+        signal?.removeEventListener?.('abort', onAbort);
         resolve(`Failed to start command: ${e.message}`);
       });
-      child.on("close", (code) => {
+      child.on('close', (code) => {
         clearTimeout(killer);
-        signal?.removeEventListener?.("abort", onAbort);
+        signal?.removeEventListener?.('abort', onAbort);
         const tail = aborted
           ? `\n[aborted by user (Ctrl+C) — killed.]`
           : timedOut
-          ? `\n[timed out after ${Math.round(timeout / 1000)}s — killed. If this is a server or other long-running task, re-run with {"background": true} instead.]`
-          : `\n[exit code ${code}]`;
-        resolve(clip((out.trim() || "(no output)") + tail));
+            ? `\n[timed out after ${Math.round(timeout / 1000)}s — killed. If this is a server or other long-running task, re-run with {"background": true} instead.]`
+            : `\n[exit code ${code}]`;
+        resolve(clip((out.trim() || '(no output)') + tail));
       });
     });
   },
@@ -423,15 +479,20 @@ export const TOOLS = {
   // Đọc trạng thái + output đã gom của tiến trình nền. Không có id → liệt kê tất cả.
   bg_output({ id } = {}) {
     if (id == null) {
-      if (!bg.size) return "No background processes.";
+      if (!bg.size) return 'No background processes.';
       return [...bg.entries()]
-        .map(([i, p]) => `#${i} ${p.exited ? `exited(code ${p.code})` : `running(pid ${p.child.pid})`} — ${p.command}`)
-        .join("\n");
+        .map(
+          ([i, p]) =>
+            `#${i} ${p.exited ? `exited(code ${p.code})` : `running(pid ${p.child.pid})`} — ${p.command}`
+        )
+        .join('\n');
     }
     const p = bg.get(id);
     if (!p) return `No background process #${id}.`;
-    const status = p.exited ? `exited (code ${p.code})` : `running (pid ${p.child.pid}, ${Math.round((Date.now() - p.startedAt) / 1000)}s)`;
-    return clip(`#${id} ${status} — ${p.command}\n${p.out.trim() || "(no output yet)"}`);
+    const status = p.exited
+      ? `exited (code ${p.code})`
+      : `running (pid ${p.child.pid}, ${Math.round((Date.now() - p.startedAt) / 1000)}s)`;
+    return clip(`#${id} ${status} — ${p.command}\n${p.out.trim() || '(no output yet)'}`);
   },
 
   // Dừng một tiến trình nền (kèm cây con trên Windows).
@@ -448,9 +509,9 @@ export const TOOLS = {
 // dòng. Trả {count, start, end} (offset ký tự trong data) khi khớp đúng 1 chỗ,
 // {count>1} khi nhập nhằng, hoặc null khi không thấy.
 function matchByLines(data, oldStr) {
-  const trim = (l) => l.replace(/\r$/, "").replace(/[ \t]+$/, "");
-  const fileLines = data.split("\n");
-  const oldLines = oldStr.replace(/\r\n/g, "\n").replace(/\n$/, "").split("\n");
+  const trim = (l) => l.replace(/\r$/, '').replace(/[ \t]+$/, '');
+  const fileLines = data.split('\n');
+  const oldLines = oldStr.replace(/\r\n/g, '\n').replace(/\n$/, '').split('\n');
   if (!oldLines.length) return null;
   const nFile = fileLines.map(trim);
   const nOld = oldLines.map(trim);
@@ -480,9 +541,14 @@ function matchByLines(data, oldStr) {
 // Khi không khớp: in vùng file gần dòng giống nhất, dạng JSON-escaped để model
 // thấy rõ tab/space → sửa old_string cho khớp ngay lần sau.
 function nearbyContext(data, oldStr) {
-  const want = (oldStr.replace(/\r\n/g, "\n").split("\n").find((l) => l.trim()) || "").trim();
-  if (!want) return "";
-  const lines = data.replace(/\r\n/g, "\n").split("\n");
+  const want = (
+    oldStr
+      .replace(/\r\n/g, '\n')
+      .split('\n')
+      .find((l) => l.trim()) || ''
+  ).trim();
+  if (!want) return '';
+  const lines = data.replace(/\r\n/g, '\n').split('\n');
   // Dòng giống nhất = tiền tố chung dài nhất với `want` (sau khi trim).
   const commonPrefix = (a, b) => {
     let i = 0;
@@ -499,68 +565,83 @@ function nearbyContext(data, oldStr) {
       hit = i;
     }
   }
-  if (hit < 0 || best < 6) return ` (no similar line found; the file has ${lines.length} lines — re-read it.)`;
+  if (hit < 0 || best < 6)
+    return ` (no similar line found; the file has ${lines.length} lines — re-read it.)`;
   const a = Math.max(0, hit - 2);
   const b = Math.min(lines.length, hit + 3);
   const snippet = lines
     .slice(a, b)
     .map((l, k) => `  ${a + k + 1}: ${JSON.stringify(l)}`)
-    .join("\n");
+    .join('\n');
   return `\nActual file lines near the closest match (JSON-escaped — match these bytes EXACTLY):\n${snippet}`;
 }
 
 function globToRegExp(glob) {
-  let rx = "";
+  let rx = '';
   for (let i = 0; i < glob.length; i++) {
     const ch = glob[i];
-    if (ch === "*") {
-      if (glob[i + 1] === "*") {
-        rx += ".*";
+    if (ch === '*') {
+      if (glob[i + 1] === '*') {
+        rx += '.*';
         i++;
-        if (glob[i + 1] === "/") i++;
-      } else rx += "[^/]*";
-    } else if (ch === "?") rx += "[^/]";
-    else if (".+^${}()|[]\\".includes(ch)) rx += "\\" + ch;
+        if (glob[i + 1] === '/') i++;
+      } else rx += '[^/]*';
+    } else if (ch === '?') rx += '[^/]';
+    else if ('.+^${}()|[]\\'.includes(ch)) rx += '\\' + ch;
     else rx += ch;
   }
-  return new RegExp("^" + rx + "$");
+  return new RegExp('^' + rx + '$');
 }
 
-// One-line human preview for the permission prompt / activity log.
+/**
+ * Mô tả 1 dòng tool call cho permission prompt / activity log.
+ * @param {ToolName} name
+ * @param {ToolInput} input
+ * @returns {string}
+ */
 export function describe(name, input) {
   switch (name) {
-    case "read_file":
+    case 'read_file':
       return `read ${input.path}`;
-    case "write_file":
-      return `write ${input.path} (${(input.content ?? "").split("\n").length} lines)`;
-    case "edit_file":
+    case 'write_file':
+      return `write ${input.path} (${(input.content ?? '').split('\n').length} lines)`;
+    case 'edit_file':
       return `edit ${input.path}`;
-    case "list_dir":
-      return `ls ${input.path || "."}`;
-    case "glob":
+    case 'list_dir':
+      return `ls ${input.path || '.'}`;
+    case 'glob':
       return `glob ${input.pattern}`;
-    case "grep":
-      return `grep "${input.pattern}"${input.path ? " in " + input.path : ""}`;
-    case "run_command":
-      return (input.background ? "$ (nền) " : "$ ") + input.command;
-    case "bg_output":
-      return input.id != null ? `xem tiến trình nền #${input.id}` : "liệt kê tiến trình nền";
-    case "kill_bg":
+    case 'grep':
+      return `grep "${input.pattern}"${input.path ? ' in ' + input.path : ''}`;
+    case 'run_command':
+      return (input.background ? '$ (nền) ' : '$ ') + input.command;
+    case 'bg_output':
+      return input.id != null ? `xem tiến trình nền #${input.id}` : 'liệt kê tiến trình nền';
+    case 'kill_bg':
       return `dừng tiến trình nền #${input.id}`;
-    case "spawn_agent":
-      return `↳ sub-agent: ${String(input.task || "").slice(0, 80)}`;
-    case "spawn_agents":
+    case 'spawn_agent':
+      return `↳ sub-agent: ${String(input.task || '').slice(0, 80)}`;
+    case 'spawn_agents':
       return `↳ ${(input.tasks || []).length} sub-agent song song`;
     default:
       return name;
   }
 }
 
+/**
+ * Chạy 1 tool theo tên. Ném `Error('Unknown tool: ...')` nếu name không tồn tại,
+ * ném `Error('aborted')` nếu signal đã abort trước/giữa khi chạy, hoặc
+ * `OutOfScopeError` nếu path nằm ngoài cwd + extraRoots.
+ * @param {ToolName} name
+ * @param {ToolInput} input
+ * @param {ToolRunOpts} [opts]
+ * @returns {Promise<string>} Kết quả text (đã clip ở `MAX_OUT`).
+ */
 export async function runTool(name, input, opts = {}) {
   const fn = TOOLS[name];
   if (!fn) throw new Error(`Unknown tool: ${name}`);
   const { signal } = opts;
   // Pre-check: nếu user đã Ctrl+C trước khi tool kịp chạy, bail ngay.
-  if (signal?.aborted) throw new Error("aborted");
+  if (signal?.aborted) throw new Error('aborted');
   return await fn(input || {}, { signal });
 }