thincoder 0.8.2 → 0.8.3

package/src/tools/shared.mjs

@@ -1,9 +1,9 @@
 /**
- * tools/shared.mjs — 共享工具函数、常量、OpenAI schema 转换
- * 被 tools/file.mjs / system.mjs / web.mjs / git.mjs 导入
+ * tools/shared.mjs — shared tool utilities, constants, OpenAI schema conversion
+ * Imported by tools/file.mjs / system.mjs / web.mjs / git.mjs
  */
 
-import { spawn, execFileSync } from "node:child_process"
+import { spawn, execFileSync, execFile } from "node:child_process"
 import { readFileSync, existsSync, realpathSync } from "node:fs"
 import { dirname, join, resolve, relative, isAbsolute, sep } from "node:path"
 import { fileURLToPath } from "node:url"
@@ -13,11 +13,14 @@ export const DESC = (name) => readFileSync(join(__dirname, "..", "tools", `${nam
 
 export const MAX_READ_LINES = 2000
 export const MAX_OUTPUT_CHARS = 200_000
+
+const ENCODING_DETECT_MAX_TRIM = 3
+const SYNTAX_CHECK_TIMEOUT = 10000
 export const BASH_TIMEOUT_MS = 120_000
 export const MAX_RESPONSE_BODY_BYTES = 5_000_000
 export const IGNORED_DIRS = new Set(["node_modules", ".git", "dist", "build", ".turbo", "coverage"])
 
-/** 转成 OpenAI tools 参数格式 */
+/** Convert to OpenAI tools parameter format */
 export function toOpenAISchema(tool) {
   return {
     type: "function",
@@ -29,7 +32,7 @@ export function toOpenAISchema(tool) {
   }
 }
 
-/** 剥离 ANSI 转义序列 */
+/** Strip ANSI escape sequences */
 export function sanitizeOutput(s) {
   return s
     .replace(/\x1b\[[0-9;?]*[\x40-\x7E]|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)|\x1b[()][0-9A-B]|\x1b[=>#][0-9]?/g, "")
@@ -37,12 +40,13 @@ export function sanitizeOutput(s) {
     .replace(/\r/g, "\n")
 }
 
+/** Truncate text to max chars, appending a truncation notice */
 export function truncate(text, max = MAX_OUTPUT_CHARS) {
   if (text.length <= max) return text
   return text.slice(0, max) + `\n[... truncated: ${text.length - max} chars omitted — redirect to a file if you need the full output]`
 }
 
-/** 限量读取响应体 */
+/** Read response body with a byte limit */
 export async function readBodyText(response, limit = MAX_RESPONSE_BODY_BYTES) {
   if (!response.body) return ""
   const reader = response.body.getReader()
@@ -59,7 +63,8 @@ export async function readBodyText(response, limit = MAX_RESPONSE_BODY_BYTES) {
   return new TextDecoder("utf-8").decode(Buffer.concat(chunks))
 }
 
-/** 流解码器：编码嗅探 ASCII→UTF-8→GBK */
+/** Streaming decoder: encoding sniffing ASCII→UTF-8→GBK.
+ *  Each call creates an independent decoder instance — must not be shared across parallel streams (internal decoder state accumulates). */
 export function makeDecoder() {
   let decoder = null
   let pending = Buffer.alloc(0)
@@ -68,7 +73,7 @@ export function makeDecoder() {
     if (!decoder) {
       const hasHighByte = pending.some((b) => b >= 0x80)
       if (!hasHighByte) { const s = pending.toString("ascii"); pending = Buffer.alloc(0); return s }
-      for (let trim = 0; trim <= 3 && !decoder; trim++) {
+      for (let trim = 0; trim <= ENCODING_DETECT_MAX_TRIM && !decoder; trim++) {
         try { new TextDecoder("utf-8", { fatal: true }).decode(pending.subarray(0, pending.length - trim)); decoder = new TextDecoder("utf-8") }
         catch { /* continue */ }
       }
@@ -80,7 +85,7 @@ export function makeDecoder() {
   }
 }
 
-/** 单文件 git diff，失败静默返回空。大 diff 超 maxBuffer 时截断而非吞掉 */
+/** Single-file git diff. Silently returns empty on failure. Large diffs that exceed maxBuffer are truncated rather than swallowed. */
 export function gitDiffOne(cwd, abs) {
   try {
     const diff = execFileSync("git", ["--no-pager", "diff", "--no-color", "--", abs], {
@@ -91,7 +96,7 @@ export function gitDiffOne(cwd, abs) {
     if (lines.length <= 200) return diff
     return lines.slice(0, 200).join("\n") + `\n... (${lines.length - 200} more diff lines)`
   } catch (e) {
-    // maxBuffer 溢出时 e.stdout 含已收集的部分；其他错误（非 git 仓库等）返回空
+    // maxBuffer overflow: e.stdout contains partial collected output; other errors (non-git repo etc.) return empty
     if (e.code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER" && e.stdout) {
       const lines = e.stdout.toString().split("\n")
       return lines.slice(0, 200).join("\n") + `\n... (diff too large, showing first 200 of more lines)`
@@ -100,19 +105,32 @@ export function gitDiffOne(cwd, abs) {
   }
 }
 
-/** 文件变更后自动语法检查 */
-export function autoSyntaxCheck(abs) {
+/** Auto syntax check after file modification */
+export async function autoSyntaxCheck(abs) {
   if (!/\.(m?js)$/i.test(abs)) return ""
   try {
-    execFileSync("node", ["--check", abs], { stdio: ["ignore", "pipe", "pipe"], timeout: 10000 })
+    await new Promise((resolve, reject) => {
+      const child = execFile("node", ["--check", abs], { timeout: SYNTAX_CHECK_TIMEOUT, stdio: ["ignore", "pipe", "pipe"] })
+      let stderr = ""
+      child.stderr.on("data", (d) => { stderr += d.toString() })
+      child.on("error", reject)
+      child.on("close", (code) => {
+        if (code === 0) resolve()
+        else {
+          const err = new Error(stderr.trim() || `node --check exited with code ${code}`)
+          err.stderr = stderr
+          reject(err)
+        }
+      })
+    })
     return "\nSyntax: OK"
   } catch (e) {
     const err = (e.stderr || e.stdout || e.message || "").toString().split("\n").slice(0, 3).join("\n")
-    return `\nSyntax: FAILED — ${err}`
+    return `\nSyntax: FAILED — ${err}\n(If this file was corrupted by a bad edit, recover it from a checkpoint: checkpoint action=list then action=rewind with the latest id.)`
   }
 }
 
-/** 逐级向上找真实路径 */
+/** Resolve realpath by walking up the directory tree */
 export function realpathNearest(abs) {
   let cur = abs
   const tail = []
@@ -127,11 +145,13 @@ export function realpathNearest(abs) {
 }
 
 const realCwdCache = new Map()
+/** Resolve cwd to realpath, cached */
 export function realCwd(cwd) {
   if (!realCwdCache.has(cwd)) realCwdCache.set(cwd, realpathNearest(resolve(cwd)))
   return realCwdCache.get(cwd)
 }
 
+/** Assert that a resolved path is inside cwd; throws on escape */
 export function assertInside(cwd, resolved, p) {
   const rel = relative(cwd, resolved)
   if (isAbsolute(rel) || rel === ".." || rel.startsWith(".." + sep)) {
@@ -139,6 +159,7 @@ export function assertInside(cwd, resolved, p) {
   }
 }
 
+/** Resolve a user-supplied path relative to cwd, asserting it stays within cwd */
 export function resolveInCwd(ctx, p) {
   const cwd = realCwd(ctx.cwd)
   const resolved = resolve(cwd, p)
@@ -148,25 +169,25 @@ export function resolveInCwd(ctx, p) {
   return resolved
 }
 
-/** 破坏性预检用的粗切分（也切 > >> <，使段内破坏性检测在重定向时仍生效） */
+/** Coarse segmentation for destructive pre-check (also splits on > >> < so destructive detection still works through redirection) */
 export function shellSegments(command) {
   return command.split(/&&|\|\||>>|\$\(|[;|\n<>]|`|[(]/)
 }
 
-/** 检测 shell 输出/输入重定向（> >> < 后跟文件名）——引号内未排除，保守拦截 */
+/** Detect shell output/input redirection (> >> < followed by filename) — not excluded inside quotes, conservative block */
 export function hasFileRedirection(command) {
   return /(^|[\s;&|])>{1,2}\s*\S/.test(command) || /(^|[\s;&|])<\s*\S/.test(command)
 }
 
-/** 单命令段是否为破坏性非 git 命令（保守：宁可误拦） */
+/** Whether a single command segment is a destructive non-git command (conservative: prefer false positives) */
 export function isDestructiveCommand(seg) {
   const s = seg
-  // rm 同时带递归(-r/-R)与强制(-f)标志：-rf / -fr / -r -f / -Rf 等
+  // rm with both recursive (-r/-R) and force (-f) flags: -rf / -fr / -r -f / -Rf etc.
   if (/\brm\b/.test(s) && /\s-\S*r/i.test(s) && /\s-\S*f/i.test(s)) return true
   if (/\brmdir\b/i.test(s)) return true
   if (/\bdel\b/i.test(s) && /\/f\b/i.test(s)) return true
   if (/\brd\b/i.test(s) && /\/s\b/i.test(s)) return true
-  // format 作为命令调用（排除 --format= 之类的选项误报）
+  // format called as a command (exclude --format= option false positives)
   if (/\bformat\b\s+\S/i.test(s) && !/--format\b/i.test(s)) return true
   if (/\bshred\b/i.test(s)) return true
   if (/\bdd\b/.test(s) && /\bof=/i.test(s)) return true
@@ -176,7 +197,7 @@ export function isDestructiveCommand(seg) {
   return false
 }
 
-/** 单命令段是否销毁未提交改动 */
+/** Whether a single command segment destroys uncommitted changes */
 export function isDestructiveGitSegment(seg) {
   if (!/^\s*git\s/.test(seg)) return false
   if (/\scheckout\s+(?:--|\.(?:\s|$))/.test(seg)) return true
@@ -186,7 +207,7 @@ export function isDestructiveGitSegment(seg) {
   return false
 }
 
-/** cwd 是否在 git 仓库内 */
+/** Whether cwd is inside a git repository */
 export function insideGitRepo(cwd) {
   try {
     execFileSync("git", ["rev-parse", "--is-inside-work-tree"], {
@@ -196,7 +217,7 @@ export function insideGitRepo(cwd) {
   } catch { return false }
 }
 
-/** glob 转正则 */
+/** Convert glob pattern to regex */
 export function globToRegex(pattern) {
   const DS = "\u0001", DP = "\u0002"
   const escaped = pattern
@@ -208,7 +229,7 @@ export function globToRegex(pattern) {
   return new RegExp(`^${escaped}$`)
 }
 
-/** 剥 HTML 标签 */
+/** Strip HTML tags */
 export function stripTags(html) {
   return html
     .replace(/<[^>]+>/g, "")
@@ -223,7 +244,7 @@ export function stripTags(html) {
     .trim()
 }
 
-/** HTML → 粗文本：去脚本样式、块级标签换行、剥标签、解码实体、压缩空行 */
+/** HTML → plain text: strip scripts/styles, newline block tags, strip tags, decode entities, compress blank lines */
 export function htmlToText(html) {
   return html
     .replace(/<script[\s\S]*?<\/script>/gi, "")
@@ -239,18 +260,18 @@ export function htmlToText(html) {
     .replace(/&lt;/g, "<")
     .replace(/&gt;/g, ">")
     .replace(/&quot;/g, '"')
-    .replace(/&amp;/g, "&") // &amp; 必须最后解码，否则 &amp;lt; 会被二次解码成 <
+    .replace(/&amp;/g, "&") // &amp; must be decoded last, otherwise &amp;lt; gets double-decoded to <
     .replace(/[ \t]+/g, " ")
     .replace(/\n\s*\n\s*\n+/g, "\n\n")
     .trim()
 }
 
-/** 执行 git 命令。maxBuffer 10MB 防大 diff/log 溢出；溢出时返回截断的部分输出而非空。 */
+/** Execute a git command. maxBuffer 10MB prevents large diff/log overflow; on overflow, returns truncated partial output rather than empty. */
 export function runGit(cwd, cmdArgs) {
   try {
     return execFileSync("git", cmdArgs, { cwd, encoding: "utf8", maxBuffer: 10 * 1024 * 1024, stdio: ["ignore", "pipe", "ignore"] }).trim().replace(/\r/g, "")
   } catch (e) {
-    // ERR_CHILD_PROCESS_STDIO_MAXBUFFER 时 e.stdout 含部分输出，截取前 200 行返回
+    // ERR_CHILD_PROCESS_STDIO_MAXBUFFER: e.stdout contains partial output, return first 200 lines
     if (e.stdout) return String(e.stdout).trim().replace(/\r/g, "").split("\n").slice(0, 200).join("\n")
     return ""
   }

package/src/tools/system.mjs

@@ -13,14 +13,11 @@ import {
   insideGitRepo,
   globToRegex
 } from "./shared.mjs";
-import { spawn } from "node:child_process";
-import { execFileSync } from "node:child_process";
-import { readFile } from "node:fs/promises";
-import { readdir } from "node:fs/promises";
-import { stat, lstat } from "node:fs/promises";
+import { spawn, execFileSync } from "node:child_process";
+import { readFile, readdir, stat, lstat } from "node:fs/promises";
 import { join } from "node:path";
 
-/** 子进程环境变量白名单：只透传安全变量，隔离 API key 等敏感信息 */
+/** Child process environment variable whitelist: only pass through safe variables, isolate sensitive info like API keys */
 const SAFE_ENV_KEYS = new Set([
   "PATH", "HOME", "USERPROFILE", "APPDATA", "LOCALAPPDATA",
   "TEMP", "TMP", "TMPDIR", "LANG", "LC_ALL", "LC_CTYPE", "SHELL",
@@ -30,6 +27,152 @@ const SAFE_ENV_KEYS = new Set([
   "GIT_PAGER", "PAGER", "TERM",
 ])
 
+/** Maximum buffer size per stream (stdout / stderr) before truncation */
+const MAX_STREAM_BUF = 2_000_000
+
+// ====================================================================
+// bash — command execution with safety gates
+// ====================================================================
+
+/**
+ * Pre-execution safety checks for bash commands.
+ * Three layers: file redirection → destructive commands → destructive git ops with uncommitted changes.
+ * Throws with actionable guidance on failure.
+ */
+function checkBashSafety(command, cwd) {
+  if (hasFileRedirection(command)) {
+    throw new Error("File redirection via bash is not allowed — use the write/edit/insert_after tools instead")
+  }
+  if (shellSegments(command).some(isDestructiveCommand)) {
+    throw new Error(
+      "Destructive command blocked — use specific tools or confirm with the user first. " +
+      "(If work was already destroyed, recover from auto-snapshot: checkpoint action=list then action=rewind.)"
+    )
+  }
+  if (shellSegments(command).some(isDestructiveGitSegment)) {
+    if (!insideGitRepo(cwd)) {
+      throw new Error(`Refusing destructive git command: not a git repository: ${cwd}`)
+    }
+    const status = execFileSync("git", ["status", "--porcelain"], {
+      cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"],
+    }).trim()
+    if (status) {
+      throw new Error(
+        `Refusing destructive git command: uncommitted changes exist.\n` +
+        `First create a checkpoint (action=create) to protect current work, then commit or stash before the destructive operation.\n` +
+        `(If uncommitted work was already lost, recover from the latest auto-snapshot: checkpoint action=list, then action=rewind.)\n\n${status}`
+      )
+    }
+  }
+}
+
+/**
+ * Build a sanitized environment for the child process.
+ * Whitelists safe variables, forces non-interactive defaults (EDITOR/PAGER/TERM),
+ * and sets PYTHONIOENCODING on Windows to override GBK default for Python scripts.
+ */
+function buildBashEnv() {
+  const winCmd = process.platform === "win32"
+  return {
+    ...Object.fromEntries(
+      Object.entries(process.env).filter(([k]) => SAFE_ENV_KEYS.has(k))
+    ),
+    GIT_EDITOR: "true",
+    EDITOR: "true",
+    VISUAL: "true",
+    GIT_PAGER: "cat",
+    PAGER: "cat",
+    TERM: "dumb",
+    ...(winCmd ? { PYTHONIOENCODING: "utf-8" } : {}),
+  }
+}
+
+/**
+ * Platform-aware process tree kill.
+ * POSIX: kill process group (spawned with detached=true).
+ * Windows: taskkill /T to reach grandchildren (npm test's subprocesses, etc.).
+ */
+function killProcessTree(child) {
+  if (process.platform === "win32") {
+    try { execFileSync("taskkill", ["/PID", String(child.pid), "/T", "/F"], { stdio: "ignore" }) } catch {}
+  } else {
+    try { process.kill(-child.pid, "SIGKILL") } catch {}
+    try { child.kill("SIGKILL") } catch {} // fallback: kill directly if group kill fails
+  }
+}
+
+/**
+ * Run a bash command: spawn, stream stdout/stderr with buffering and decoding,
+ * enforce timeout and signal abort, return formatted result.
+ *
+ * Returns a promise that resolves to the formatted output string (stdout + stderr + status + truncation note).
+ */
+function runBash(command, cwd, { timeout, signal, onOutput }) {
+  return new Promise((resolve) => {
+    const child = spawn(command, {
+      cwd,
+      shell: true,
+      windowsHide: true,
+      detached: process.platform !== "win32",
+      stdio: ["ignore", "pipe", "pipe"],
+      env: buildBashEnv(),
+    })
+
+    const killTree = () => killProcessTree(child)
+
+    // Separate decoders for stdout / stderr (same encoding in practice, but separate
+    // collection is cleaner and lets the model locate errors via stderr quickly)
+    const outDecoder = makeDecoder()
+    const errDecoder = makeDecoder()
+    let outBuf = ""
+    let errBuf = ""
+    let truncatedNote = ""
+
+    child.stdout.on("data", (d) => {
+      const s = sanitizeOutput(outDecoder(d))
+      if (s) {
+        onOutput?.(s)
+        if (outBuf.length < MAX_STREAM_BUF) outBuf += s
+        else if (!truncatedNote) truncatedNote =
+          "\n[... output exceeded 2MB, remainder discarded — redirect to a file if you need the full output]"
+      }
+    })
+
+    child.stderr.on("data", (d) => {
+      const s = sanitizeOutput(errDecoder(d))
+      if (errBuf.length < MAX_STREAM_BUF) errBuf += s
+    })
+
+    const timer = setTimeout(killTree, timeout)
+    if (signal) signal.addEventListener("abort", killTree, { once: true })
+
+    child.on("error", (error) => {
+      clearTimeout(timer)
+      resolve(truncate(`Command failed: ${error.message}\n[stdout]:\n${outBuf || "(empty)"}`))
+    })
+
+    child.on("close", (code, exitSignal) => {
+      clearTimeout(timer)
+      // Flush decoder tails (trailing multi-byte sequences that incomplete buffers left pending)
+      outBuf += sanitizeOutput(outDecoder(Buffer.alloc(0), true))
+      errBuf += sanitizeOutput(errDecoder(Buffer.alloc(0), true))
+
+      const status = exitSignal
+        ? `killed: ${signal?.aborted ? "user interrupted" : "timeout"}`
+        : `exit code ${code}`
+
+      const parts = [`[stdout]:\n${outBuf.trim() || "(empty)"}`]
+      if (errBuf.trim()) parts.push(`[stderr]:\n${errBuf.trim()}`)
+      parts.push(`(${status})`)
+      resolve(truncate(parts.join("\n\n") + truncatedNote))
+    })
+  })
+}
+
+// ====================================================================
+// tool definitions
+// ====================================================================
+
 export const bashTool = {
   name: "bash",
   description: DESC("bash"),
@@ -42,111 +185,13 @@ export const bashTool = {
     required: ["command"],
   },
   readonly: false,
+  outputPanel: true, // stream stdout/stderr to panel during execution, collapse to summary on completion
   async execute(args, ctx) {
-    // 安全预检：禁止 shell 重定向（> >> <）——应改用 write/edit/insert_after 工具
-    if (hasFileRedirection(args.command)) {
-      throw new Error("File redirection via bash is not allowed — use the write/edit/insert_after tools instead")
-    }
-    // 安全预检：破坏性非 git 命令（rm -rf / DROP TABLE 等）直接拒绝
-    if (shellSegments(args.command).some(isDestructiveCommand)) {
-      throw new Error("Destructive command blocked — use specific tools or confirm with the user first")
-    }
-    // 安全预检：销毁性 git 操作先检查未提交改动，有则拒绝——防一键清掉几小时工作
-    if (shellSegments(args.command).some(isDestructiveGitSegment)) {
-      if (!insideGitRepo(ctx.cwd)) {
-        throw new Error(`Refusing destructive git command: not a git repository: ${ctx.cwd}`)
-      }
-      const status = execFileSync("git", ["status", "--porcelain"], {
-        cwd: ctx.cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"],
-      }).trim()
-      if (status) {
-        throw new Error(
-          `Refusing destructive git command: uncommitted changes exist. Commit or stash first.\n` +
-          `(If uncommitted work was already lost, the checkpoint tool can restore the auto-snapshot: action=list, then action=rewind.)\n\n${status}`
-        )
-      }
-    }
-
-    return new Promise((resolve) => {
-      // detached: 让子进程成为进程组组长，超时/中断时才能整树杀掉（POSIX 用负 pid 组杀，
-      // Windows 用 taskkill /T）——只 kill 壳进程会把孙进程（如 npm test）留在后台继续跑
-      const killTree = () => {
-        if (process.platform === "win32") {
-          try { execFileSync("taskkill", ["/PID", String(child.pid), "/T", "/F"], { stdio: "ignore" }) } catch {}
-        } else {
-          try { process.kill(-child.pid, "SIGKILL") } catch {}
-          try { child.kill("SIGKILL") } catch {} // 组杀失败时兜底杀本体
-        }
-      }
-      // Windows 中文系统默认代码页是 GBK (CP936)，cmd.exe 重定向写文件时用 ANSI 代码页，
-      // chcp 65001 也改不了重定向的编码。bash 工具写含 CJK 的文件会产生 GBK——
-      // 提示词层已禁止用 bash 写文件（用 write/edit 工具替代），这里设 PYTHONIOENCODING
-      // 覆盖 Python 脚本的 stdout 编码（Python 是唯一可能正确响应环境变量的子进程）
-      const winCmd = process.platform === "win32"
-      const child = spawn(args.command, {
-        cwd: ctx.cwd,
-        shell: true,
-        windowsHide: true,
-        detached: process.platform !== "win32",
-        stdio: ["ignore", "pipe", "pipe"],
-        env: {
-          ...Object.fromEntries(
-            Object.entries(process.env).filter(([k]) => SAFE_ENV_KEYS.has(k))
-          ),
-          GIT_EDITOR: "true",
-          EDITOR: "true",
-          VISUAL: "true",
-          GIT_PAGER: "cat",
-          PAGER: "cat",
-          TERM: "dumb",
-          ...(winCmd ? { PYTHONIOENCODING: "utf-8" } : {}),
-        },
-      })
-      // stdout / stderr 各自独立解码（同进程通常同编码，但分开收集更干净，
-      // 且允许模型按 stderr 快速定位错误）
-      const outDecoder = makeDecoder()
-      const errDecoder = makeDecoder()
-      let outBuf = ""
-      let errBuf = ""
-      let truncatedNote = ""
-
-      const onStdout = (d) => {
-        const s = sanitizeOutput(outDecoder(d))
-        if (s) {
-          ctx.onOutput?.(s)
-          if (outBuf.length < 2_000_000) outBuf += s
-          else if (!truncatedNote) truncatedNote = "\n[... output exceeded 2MB, remainder discarded]"
-        }
-      }
-      const onStderr = (d) => {
-        const s = sanitizeOutput(errDecoder(d)) // 始终解码，防 pending 无限累积
-        if (errBuf.length < 2_000_000) errBuf += s
-      }
-
-      child.stdout.on("data", onStdout)
-      child.stderr.on("data", onStderr)
-
-      const timer = setTimeout(killTree, args.timeout ?? BASH_TIMEOUT_MS)
-      if (ctx.signal) {
-        ctx.signal.addEventListener("abort", killTree, { once: true })
-      }
-      child.on("error", (error) => {
-        clearTimeout(timer)
-        resolve(truncate(`Command failed: ${error.message}\n[stdout]:\n${outBuf || "(empty)"}`))
-      })
-      child.on("close", (code, signal) => {
-        clearTimeout(timer)
-        // 冲刷解码器尾部
-        outBuf += sanitizeOutput(outDecoder(Buffer.alloc(0), true))
-        errBuf += sanitizeOutput(errDecoder(Buffer.alloc(0), true))
-        const status = signal
-          ? `killed: ${ctx.signal?.aborted ? "user interrupted" : "timeout"}`
-          : `exit code ${code}`
-        const parts = [`[stdout]:\n${outBuf.trim() || "(empty)"}`]
-        if (errBuf.trim()) parts.push(`[stderr]:\n${errBuf.trim()}`)
-        parts.push(`(${status})`)
-        resolve(truncate(parts.join("\n\n") + truncatedNote))
-      })
+    checkBashSafety(args.command, ctx.cwd)
+    return runBash(args.command, ctx.cwd, {
+      timeout: args.timeout ?? BASH_TIMEOUT_MS,
+      signal: ctx.signal,
+      onOutput: ctx.onOutput,
     })
   },
 }
@@ -180,7 +225,7 @@ export const globTool = {
   },
 }
 
-/** 递归遍历文件，产出相对路径（跳过 IGNORED_DIRS） */
+/** Recursively traverse files, yield relative paths (skip IGNORED_DIRS) */
 async function* walkFiles(dir, rel = "") {
   let entries
   try {
@@ -199,7 +244,7 @@ async function* walkFiles(dir, rel = "") {
   }
 }
 
-/** glob 转正则：**\/ 匹配零或多级目录，** 跨目录，* 段内，? 段内单字符 */
+/** Glob to regex: **\/ matches zero or more directory levels, ** crosses directories, * within segment, ? single char within segment */
 
 // ---------------------------------------------------------------- grep
 
@@ -226,17 +271,17 @@ export const grepTool = {
     const after = Math.max(0, Math.floor(args.after ?? 0))
     const wantCtx = before > 0 || after > 0
     const hits = [] // { file, line(1-based), text }
-    const fileLines = new Map() // file -> string[]（仅 wantCtx 时缓存）
+    const fileLines = new Map() // file -> string[] (cached only when context lines requested)
 
     async function search(file) {
       let content
       try {
-        // 大文件保护：超 10MB 跳过，防 OOM
+        // Large file guard: skip files over 10MB to prevent OOM
         const fst = await stat(file)
         if (fst.size > 10_000_000) return
         content = await readFile(file, "utf8")
       } catch {
-        return // 不可读文件跳过；二进制会被按 utf8 读入并照常搜索（可能产生乱码匹配）
+        return // Skip unreadable files; binary files will be read as UTF-8 and searched (may produce garbled matches)
       }
       const lines = content.split("\n")
       if (wantCtx) fileLines.set(file, lines)
@@ -250,7 +295,7 @@ export const grepTool = {
 
     async function walk(target) {
       if (hits.length >= 200) return
-      // 用 lstat 不跟随符号链接——防 ./evil → /etc 时 grep 读遍 /etc
+      // Use lstat to avoid following symlinks — prevents ./evil → /etc from making grep scan the entire system
       let s
       try { s = await lstat(target) } catch { return }
       if (!s.isDirectory()) {
@@ -272,12 +317,12 @@ export const grepTool = {
     await walk(base)
     if (hits.length === 0) return "(no matches)"
 
-    // 无上下文：保持原 path:line: content 格式
+    // No context: keep original path:line: content format
     if (!wantCtx) {
       return truncate(hits.map((h) => `${h.file}:${h.line}: ${h.text}`).join("\n"))
     }
 
-    // 带上下文：匹配行用 ':'，上下文行用 '-'（同 ripgrep）；同文件相邻区间去重合并
+    // With context: matching lines use ':', context lines use '-' (like ripgrep); overlapping ranges in same file are merged and de-duplicated
     const fileMatched = new Map() // file -> Set<line>
     for (const h of hits) {
       if (!fileMatched.has(h.file)) fileMatched.set(h.file, new Set())

package/src/tools/web.mjs

@@ -36,7 +36,7 @@ export const websearchTool = {
       throw new Error(`websearch request failed: ${error.cause?.code ?? error.message}`)
     }
 
-    // 结果块 <li class="b_algo">：<h2><a href>标题</a></h2> + <p>摘要</p>
+    // Result block <li class="b_algo">: <h2><a href>title</a></h2> + <p>snippet</p>
     const blocks = html.split('<li class="b_algo"').slice(1)
     const results = []
     for (const block of blocks) {
@@ -60,17 +60,17 @@ export const websearchTool = {
 
 // ---------------------------------------------------------------- ls
 
-/** SSRF 防护：拒绝内网私有段/metadata 端点（localhost 放行——用户本机，测试也依赖） */
+/** SSRF protection: block internal private-network/metadata endpoints (localhost allowed — user's dev server, tests depend on it) */
 function isPrivateUrl(urlStr) {
   let u
   try { u = new URL(urlStr) } catch { return true }
   const host = u.hostname.toLowerCase()
-  // localhost / 127.x 放行（用户本机开发服务器、测试 mock server）
+  // localhost / 127.x allowed (user's dev server on local machine, test mock server)
   if (host === "localhost" || host === "0.0.0.0" || host.endsWith(".localhost")) return false
   if (host === "127.0.0.1" || host.startsWith("127.")) return false
-  // 云 metadata 端点
+  // cloud metadata endpoint
   if (host === "169.254.169.254" || host === "metadata.google.internal") return true
-  // IPv4 私有段
+  // IPv4 private ranges
   const m = host.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/)
   if (m) {
     const [a, b] = [Number(m[1]), Number(m[2])]
@@ -80,7 +80,7 @@ function isPrivateUrl(urlStr) {
     if (a === 169 && b === 254) return true
     if (a === 0) return true
   }
-  // IPv6 环回 / 链路本地 / 唯一本地地址
+  // IPv6 loopback / link-local / unique local addresses
   if (host === "::1" || host === "fe80::1" || host.startsWith("fc") || host.startsWith("fd")) return true
   return false
 }