thincoder 0.10.0 → 0.11.1

package/src/tools/git.mjs

@@ -3,104 +3,138 @@ import {
   truncate,
   runGit
 } from "./shared.mjs";
+import { escapeXml } from "../agent/helpers.mjs";
 import { execFileSync } from "node:child_process";
 import { join } from "node:path";
 
-export const gitDiffTool = {
-  name: "git_diff",
-  description: DESC("git_diff"),
+export const gitTool = {
+  name: "git",
+  description:
+    "Run a git command. Use this to see uncommitted changes, staged changes, diff against a ref, recent commits, or manage checkpoints. Only works inside a git repository.\n" +
+    "- action='diff': Show unified diff — what changed since last commit. Set staged=true for staged-only diff, ref=<ref> to compare against a specific commit/branch, path=<dir> to scope to a file or directory.\n" +
+    "- action='status': Show working tree state — staged, unstaged, untracked files, and conflicts. Returns categorized lists.\n" +
+    "- action='log': Show recent commit history. Set count to limit, oneline=true for compact format, path=<file> to see history of one file.\n" +
+    "- action='checkpoint': Manage git-based snapshots. Use checkpointAction to choose: list (overview), create (snapshot now), rewind (restore snapshot by id), cat (read a file from a snapshot).",
   parameters: {
     type: "object",
     properties: {
-      staged: { type: "boolean", description: "Show staged changes (default false)" },
-      path: { type: "string", description: "File or directory to diff (default all)" },
-      ref: { type: "string", description: "Compare against this ref (default HEAD)" },
+      action: { type: "string", enum: ["diff", "status", "log", "checkpoint"], description: "diff / status / log / checkpoint" },
+      // diff/log params
+      staged: { type: "boolean", description: "(diff) Show staged changes instead of working tree" },
+      path: { type: "string", description: "(diff/log/checkpoint:cat/checkpoint:rewind) File or directory to scope to" },
+      ref: { type: "string", description: "(diff) Compare against this ref (default HEAD)" },
+      count: { type: "number", description: "(log) Number of commits (default 10)" },
+      oneline: { type: "boolean", description: "(log) One-line-per-commit format" },
+      // checkpoint params
+      checkpointAction: { type: "string", enum: ["list", "create", "rewind", "cat"], description: "(checkpoint) list snapshots / create one / restore by id / read file from snapshot" },
+      checkpointId: { type: "string", description: "(checkpoint) Snapshot id — required for rewind and cat; optional for list (shows file tree)" },
     },
+    required: ["action"],
   },
-  readonly: true,
-  execute(args, ctx) {
-    const ref = args.ref ?? "HEAD"
-    // ref supplied by model and placed before "--": validate charset, prevent "--output=..." etc. from being treated as git options
-    if (!/^[A-Za-z0-9._\/~^][A-Za-z0-9._\/~^-]*$/.test(ref)) throw new Error(`Invalid git ref: ${ref}`)
-    const flags = args.staged ? ["--staged"] : []
-    const paths = args.path ? [args.path] : []
-    const out = runGit(ctx.cwd, ["diff", ...flags, ref, "--", ...paths])
-    return truncate(out || "(no changes)")
-  },
-}
-
-// ---------------------------------------------------------------- git_status
-
-export const gitStatusTool = {
-  name: "git_status",
-  description: DESC("git_status"),
-  parameters: {
-    type: "object",
-    properties: {},
-  },
-  readonly: true,
-  execute(_args, ctx) {
-    const porcelain = runGit(ctx.cwd, ["status", "--porcelain"])
-    if (!porcelain) return "(clean — no changes)"
-
-    const staged = []
-    const unstaged = []
-    const untracked = []
-    const conflicts = []
-    for (const line of porcelain.split("\n")) {
-      if (!line) continue
-      // porcelain: XY path — 2 status chars + space + file path (some environments have only 1 space)
-      // Strip possible CR (execFileSync on some Windows git leaves \r at end of line but not in newline)
-      const clean = line.replace(/\r/g, "")
-      // Try matching "XY path" or "XY  path" (variable spacing)
-      const m = clean.match(/^(..?)\s+(.+)$/)
-      if (!m) continue
-      const [, status, rawFile] = m
-      // Rename entries in porcelain output are "R  old -> new", split for clarity instead of treating as a literal filename
-      const file = status.includes("R") && rawFile.includes(" -> ") ? rawFile.replace(" -> ", " → ") : rawFile
-      const idx = status[0] ?? " "
-      const wt = status[1] ?? " "
-      if (idx === "U" || wt === "U" || (idx === "A" && wt === "A")) {
-        conflicts.push(file)
-      } else if (idx === "?" && wt === "?") {
-        untracked.push(file)
-      } else {
-        if (idx !== " " && idx !== "?") staged.push(idx + " " + file)
-        if (wt !== " " && wt !== "?") unstaged.push(wt + " " + file)
+  readonly: false,
+  async execute(args, ctx) {
+    switch (args.action) {
+      case "diff": {
+        const ref = args.ref ?? "HEAD"
+        if (!/^[A-Za-z0-9._\/~^@][A-Za-z0-9._\/~^@{}\-]*$/.test(ref)) throw new Error(`Invalid git ref: ${ref}`)
+        const flags = args.staged ? ["--staged"] : []
+        const paths = args.path ? [args.path] : []
+        const out = runGit(ctx.cwd, ["diff", ...flags, ref, "--", ...paths])
+        return truncate(out || "(no changes)")
+      }
+      case "status": {
+        const porcelain = runGit(ctx.cwd, ["status", "--porcelain"])
+        if (!porcelain) return "(clean — no changes)"
+
+        const staged = []
+        const unstaged = []
+        const untracked = []
+        const conflicts = []
+        for (const line of porcelain.split("\n")) {
+          if (!line) continue
+          const clean = line.replace(/\r/g, "")
+          const m = clean.match(/^(..?)\s+(.+)$/)
+          if (!m) continue
+          const [, status, rawFile] = m
+          const file = status.includes("R") && rawFile.includes(" -> ") ? rawFile.replace(" -> ", " → ") : rawFile
+          const idx = status[0] ?? " "
+          const wt = status[1] ?? " "
+          if (idx === "U" || wt === "U" || (idx === "A" && wt === "A")) {
+            conflicts.push(file)
+          } else if (idx === "?" && wt === "?") {
+            untracked.push(file)
+          } else {
+            if (idx !== " " && idx !== "?") staged.push(idx + " " + file)
+            if (wt !== " " && wt !== "?") unstaged.push(wt + " " + file)
+          }
+        }
+        const parts = []
+        if (staged.length) parts.push("Staged (" + staged.length + "):\n" + staged.join("\n"))
+        if (unstaged.length) parts.push("Unstaged (" + unstaged.length + "):\n" + unstaged.join("\n"))
+        if (untracked.length) parts.push("Untracked (" + untracked.length + "):\n" + untracked.join("\n"))
+        if (conflicts.length) parts.push("Conflicts (" + conflicts.length + "):\n" + conflicts.join("\n"))
+        return truncate(parts.join("\n\n"))
+      }
+      case "log": {
+        const n = Math.min(Math.max(1, args.count ?? 10), 200)
+        const isOneline = args.oneline
+        const cmdArgs = isOneline
+          ? ["log", "-" + n, "--oneline"]
+          : ["log", "-" + n, "--format=%h %ad %an %s", "--date=short"]
+        if (args.path) cmdArgs.push("--", args.path)
+        const out = runGit(ctx.cwd, cmdArgs)
+        return truncate(out || "(no commits)")
       }
+      case "checkpoint": {
+        const { createCheckpoint, listCheckpoints, rewind, isGitRepo } = await import("../git/checkpoint.mjs")
+        if (!isGitRepo(ctx.cwd)) throw new Error("Not a git repository — checkpoints unavailable")
+
+        const sub = args.checkpointAction
+        if (!sub) return "checkpoint: missing checkpointAction — use: list | create | rewind | cat"
+
+        if (sub === "create") {
+          const cp = await createCheckpoint(ctx.cwd)
+          return `Checkpoint ${cp.id} created (${cp.files} file(s): ${cp.tracked.length} tracked, ${cp.untracked.length} untracked)`
+        }
+        if (sub === "rewind") {
+          if (!args.checkpointId) throw new Error("checkpointId is required for rewind — use checkpointAction=list to see snapshot ids")
+          const s = await rewind(ctx.cwd, args.checkpointId, { path: args.path })
+          if (args.path) {
+            return `Restored "${args.path}" (${s.type}) from checkpoint ${args.checkpointId}.\n(The pre-rewind state was snapshotted first — you can rewind again to go back.)`
+          }
+          return `Rewound to checkpoint ${args.checkpointId}: patch ${s.patchApplied ? "applied" : "(empty)"}, ${s.restored ?? 0} untracked file(s) restored, ${s.deleted ?? 0} file(s) deleted.\n(The pre-rewind state was snapshotted first — you can rewind again to go back.)`
+        }
+        if (sub === "cat") {
+          if (!args.checkpointId) throw new Error("checkpointId is required for cat — use checkpointAction=list to see snapshot ids")
+          if (!args.path) throw new Error("path is required for cat — specify which file to read")
+          const { catFile } = await import("../git/checkpoint.mjs")
+          return await catFile(ctx.cwd, args.checkpointId, args.path)
+        }
+        if (sub === "list") {
+          const cps = await listCheckpoints(ctx.cwd)
+          if (cps.length === 0) return "(no checkpoints yet — one is auto-created before each user task)"
+
+          // Specific id: show the file tree within that snapshot
+          if (args.checkpointId) {
+            const cp = cps.find((c) => c.id === args.checkpointId)
+            if (!cp) throw new Error(`checkpoint ${args.checkpointId} not found`)
+            return formatFileTree(cp)
+          }
+
+          // Overview: list of all snapshots (file names are XML-escaped: they are
+          // untrusted input that flows back into the model's context)
+          return cps.map((c) => {
+            const parts = [`${c.id}  ${new Date(c.time).toISOString()}`]
+            if (c.tracked.length) parts.push(`${c.tracked.length} tracked: ${c.tracked.map(escapeXml).join(", ")}`)
+            if (c.untracked.length) parts.push(`${c.untracked.length} untracked: ${c.untracked.map(escapeXml).join(", ")}`)
+            return parts.join("  ")
+          }).join("\n")
+        }
+        throw new Error(`Unknown checkpoint action: ${sub}. Use: list | create | rewind | cat`)
+      }
+      default:
+        return `Unknown action '${args.action}'. Use: diff | status | log | checkpoint`
     }
-    const parts = []
-    if (staged.length) parts.push("Staged (" + staged.length + "):\n" + staged.join("\n"))
-    if (unstaged.length) parts.push("Unstaged (" + unstaged.length + "):\n" + unstaged.join("\n"))
-    if (untracked.length) parts.push("Untracked (" + untracked.length + "):\n" + untracked.join("\n"))
-    if (conflicts.length) parts.push("Conflicts (" + conflicts.length + "):\n" + conflicts.join("\n"))
-    return truncate(parts.join("\n\n"))
-  },
-}
-
-// ---------------------------------------------------------------- git_log
-
-export const gitLogTool = {
-  name: "git_log",
-  description: DESC("git_log"),
-  parameters: {
-    type: "object",
-    properties: {
-      count: { type: "number", description: "Number of commits (default 10)" },
-      path: { type: "string", description: "File or directory (default all)" },
-      oneline: { type: "boolean", description: "One-line-per-commit format (default false)" },
-    },
-  },
-  readonly: true,
-  execute(args, ctx) {
-    const n = Math.min(Math.max(1, args.count ?? 10), 200)
-    const isOneline = args.oneline
-    const cmdArgs = isOneline
-      ? ["log", "-" + n, "--oneline"]
-      : ["log", "-" + n, "--format=%h %ad %an %s", "--date=short"]
-    if (args.path) cmdArgs.push("--", args.path)
-    const out = runGit(ctx.cwd, cmdArgs)
-    return truncate(out || "(no commits)")
   },
 }
 
@@ -128,79 +162,17 @@ export const questionTool = {
   },
 }
 
-/** Execute a git command; returns empty string when not a git repo / git unavailable */
-
-// ---------------------------------------------------------------- checkpoint
-
-export const checkpointTool = {
-  name: "checkpoint",
-  description: DESC("checkpoint"),
-  parameters: {
-    type: "object",
-    properties: {
-      action: { type: "string", enum: ["list", "create", "rewind", "cat"], description: "list snapshots / create one now / restore a snapshot by id / read a file's content from a snapshot" },
-      id: { type: "string", description: "Snapshot id (required for rewind and cat; optional for list — shows file tree of that snapshot)" },
-      path: { type: "string", description: "Restore only this single file from the checkpoint (tracked or untracked). Other files are left untouched." },
-    },
-    required: ["action"],
-  },
-  readonly: false,
-  async execute(args, ctx) {
-    const { createCheckpoint, listCheckpoints, rewind, isGitRepo } = await import("../git/checkpoint.mjs")
-    if (!isGitRepo(ctx.cwd)) throw new Error("Not a git repository — checkpoints unavailable")
-    if (args.action === "create") {
-      const cp = await createCheckpoint(ctx.cwd)
-      return `Checkpoint ${cp.id} created (${cp.files} file(s): ${cp.tracked.length} tracked, ${cp.untracked.length} untracked)`
-    }
-    if (args.action === "rewind") {
-      if (!args.id) throw new Error("id is required for rewind — use action=list to see snapshot ids")
-      const s = await rewind(ctx.cwd, args.id, { path: args.path })
-      if (args.path) {
-        return `Restored "${args.path}" (${s.type}) from checkpoint ${args.id}.\n(The pre-rewind state was snapshotted first — you can rewind again to go back.)`
-      }
-      return `Rewound to checkpoint ${args.id}: patch ${s.patchApplied ? "applied" : "(empty)"}, ${s.restored ?? 0} untracked file(s) restored, ${s.deleted ?? 0} file(s) deleted.\n(The pre-rewind state was snapshotted first — you can rewind again to go back.)`
-    }
-    if (args.action === "cat") {
-      if (!args.id) throw new Error("id is required for cat — use action=list to see snapshot ids")
-      if (!args.path) throw new Error("path is required for cat — specify which file to read")
-      const { catFile } = await import("../git/checkpoint.mjs")
-      return await catFile(ctx.cwd, args.id, args.path)
-    }
-    if (args.action === "list") {
-      const cps = await listCheckpoints(ctx.cwd)
-      if (cps.length === 0) return "(no checkpoints yet — one is auto-created before each user task)"
-
-      // Specific id: show the file tree within that snapshot
-      if (args.id) {
-        const cp = cps.find((c) => c.id === args.id)
-        if (!cp) throw new Error(`checkpoint ${args.id} not found`)
-        return formatFileTree(cp)
-      }
-
-      // Overview: list of all snapshots
-      return cps.map((c) => {
-        const parts = [`${c.id}  ${new Date(c.time).toISOString()}`]
-        if (c.tracked.length) parts.push(`${c.tracked.length} tracked: ${c.tracked.join(", ")}`)
-        if (c.untracked.length) parts.push(`${c.untracked.length} untracked: ${c.untracked.join(", ")}`)
-        return parts.join("  ")
-      }).join("\n")
-    }
-    throw new Error(`Unknown action: ${args.action}`)
-  },
-}
-
 /** Format a checkpoint's file list as a directory tree (directories first, indented display) */
 function formatFileTree(cp) {
+  // File names are XML-escaped: untrusted input that flows back into the model's context
   const all = [
-    ...(cp.tracked ?? []).map((f) => ({ path: f, type: "" })),
-    ...(cp.untracked ?? []).map((f) => ({ path: f, type: " (untracked)" })),
+    ...(cp.tracked ?? []).map((f) => ({ path: escapeXml(f), type: "" })),
+    ...(cp.untracked ?? []).map((f) => ({ path: escapeXml(f), type: " (untracked)" })),
   ]
   if (all.length === 0) return "(empty checkpoint)"
 
-  // Sort by path (directories group naturally)
   all.sort((a, b) => a.path.localeCompare(b.path))
 
-  // Build directory → file list map
   const tree = new Map()
   for (const { path, type } of all) {
     const dir = path.includes("/") ? path.slice(0, path.lastIndexOf("/")) : "."
@@ -208,12 +180,10 @@ function formatFileTree(cp) {
     tree.get(dir).push({ name: path.slice(dir === "." ? 0 : dir.length + 1), type })
   }
 
-  // Output sorted by directory
   const lines = []
   const dirs = [...tree.keys()].sort()
   for (const dir of dirs) {
     if (dir !== "." && !lines.includes(dir + "/")) {
-      // Parent directory before child directory
       const parts = dir.split("/")
       for (let i = 1; i <= parts.length; i++) {
         const prefix = parts.slice(0, i).join("/") + "/"
@@ -221,7 +191,6 @@ function formatFileTree(cp) {
       }
     }
   }
-  // Ensure directories precede files
   for (const dir of dirs) {
     if (dir !== ".") {
       for (const { name, type } of tree.get(dir)) {

package/src/tools/index.mjs

@@ -2,27 +2,27 @@
 export { toOpenAISchema } from "./shared.mjs";
 
 import { readTool, writeTool, editTool, insertAfterTool, readImageTool, hashlineEditTool } from "./file.mjs";
-import { applyPatchTool, syntaxCheckTool, deleteTool } from "./patch.mjs";
+import { applyPatchTool, deleteTool } from "./patch.mjs";
 import { bashTool, globTool, grepTool, lsTool } from "./system.mjs";
 import { websearchTool, fetchTool } from "./web.mjs";
-import { gitDiffTool, gitStatusTool, gitLogTool, questionTool, checkpointTool } from "./git.mjs";
+import { gitTool, questionTool } from "./git.mjs";
 import { checklistTool } from "./checklist.mjs";
-import { linterTool } from "./linter.mjs";
+import { lintTool } from "./linter.mjs";
 import { lspTool } from "./lsp.mjs";
 import { codeModeTool } from "./codemode.mjs";
 
 export const builtinTools = [
   readTool, writeTool, editTool, insertAfterTool, hashlineEditTool, applyPatchTool,
-  syntaxCheckTool, readImageTool, bashTool, globTool, grepTool,
+  readImageTool, bashTool, globTool, grepTool,
   websearchTool, lsTool, fetchTool, deleteTool,
-  gitDiffTool, gitStatusTool, gitLogTool, questionTool, checkpointTool,
-  checklistTool, linterTool, lspTool, codeModeTool,
+  gitTool, questionTool,
+  checklistTool, lintTool, lspTool, codeModeTool,
 ];
 
 export {
   readTool, writeTool, editTool, insertAfterTool, hashlineEditTool, applyPatchTool,
-  syntaxCheckTool, readImageTool, bashTool, globTool, grepTool,
+  readImageTool, bashTool, globTool, grepTool,
   websearchTool, lsTool, fetchTool, deleteTool,
-  gitDiffTool, gitStatusTool, gitLogTool, questionTool, checkpointTool,
-  checklistTool, linterTool, lspTool, codeModeTool,
+  gitTool, questionTool,
+  checklistTool, lintTool, lspTool, codeModeTool,
 };

package/src/tools/linter.mjs

@@ -1,38 +1,66 @@
 import { DESC, resolveInCwd } from "./shared.mjs"
+import { execFileSync } from "node:child_process"
+import { existsSync } from "node:fs"
+import { join, relative } from "node:path"
 
-export const linterTool = {
-  name: "linter",
-  description: DESC("linter"),
+export const lintTool = {
+  name: "lint",
+  description:
+    "Run the appropriate linter/checker for a file. Auto-detects based on file extension and project config.\n" +
+    "Without 'full', runs a fast node --check (JS/TS syntax only, catches parse errors in milliseconds).\n" +
+    "With 'full', runs the language-aware cascade: eslint → tsc –noEmit → node --check (JS/TS/TSX); ruff (Python); cargo check (Rust); go vet (Go).\n" +
+    "Use the fast default after every write/edit; use 'full' before declaring a task complete.",
   parameters: {
     type: "object",
     properties: {
-      path: { type: "string", description: "File path (default: most recently modified file)" },
+      path: { type: "string", description: "File to check (default: most recently modified file)" },
+      full: { type: "boolean", description: "Run the full language-aware cascade instead of just node --check (default false)" },
     },
+    required: [],
   },
   readonly: true,
   async execute(args, ctx) {
-    const { execFileSync } = await import("node:child_process")
-    const { existsSync } = await import("node:fs")
-    const { join, relative } = await import("node:path")
-    const abs = args.path ? resolveInCwd(ctx, args.path) : (ctx.agent?._touchedFiles?.at(-1) || null)
-    if (!abs) return "linter: no file specified and no recently modified file to check"
+    const abs = args.path
+      ? resolveInCwd(ctx, args.path)
+      : (ctx.agent?._touchedFiles?.at(-1) || null)
+    if (!abs) return "lint: no file specified and no recently modified file to check"
 
+    if (!args.full) {
+      // Fast path: node --check only
+      return nodeCheckResult(abs)
+    }
+
+    // Full cascade: language-aware (eslint → tsc → node --check, etc.)
     const ext = abs.split(".").pop()?.toLowerCase()
     const checkers = LANG_CHECKERS[ext]
-    if (!checkers) return `linter: no linter configured for .${ext} files. Supported: ${Object.keys(LANG_CHECKERS).map(e => `.${e}`).join(", ")}`
+    if (!checkers) return nodeCheckResult(abs) // fall back to node --check
 
     for (const checker of checkers) {
       const result = await checker(abs, { cwd: ctx.cwd, existsSync, execFileSync, join, relative })
       if (result !== null) return result
     }
-    return `linter: no linter available for ${args.path || abs}. Install one?`
+    return `lint: no linter available for ${abs}. Install one?`
   },
 }
 
-// ─── Checker definitions ──────────────────────
+function nodeCheckResult(abs) {
+  if (!/\.(?:m?js|cjs|m?ts|cts|jsx|tsx)$/.test(abs)) {
+    return `lint (check): only JS/TS-family files supported for fast syntax check; use full=true for other languages. Path: ${abs}`
+  }
+  try {
+    execFileSync(process.execPath, ["--check", abs], {
+      encoding: "utf8", timeout: 10000, stdio: ["ignore", "pipe", "pipe"],
+    })
+    return `Syntax OK: ${abs}`
+  } catch (e) {
+    const msg = (e.stderr || e.stdout || e.message || "").trim()
+    return `Syntax error in ${abs}:\n${msg || "(unknown)"}`
+  }
+}
+
+// ─── Full-check cascade checkers ──────────────────────
 
 async function eslintCheck(file, { cwd, existsSync, execFileSync, join, relative }) {
-  // Walk up to find eslint config
   let dir = file.split(/[\\/]/).slice(0, -1).join("/") || "."
   while (true) {
     for (const cfg of [".eslintrc.js", ".eslintrc.cjs", ".eslintrc.json", ".eslintrc.yaml", ".eslintrc.yml", "eslint.config.js", "eslint.config.mjs"]) {
@@ -73,18 +101,6 @@ async function tscCheck(file, { cwd, existsSync, execFileSync, join }) {
   }
 }
 
-async function nodeCheck(file, { execFileSync, cwd }) {
-  if (!/\.(m?js|cjs)$/.test(file)) return null
-  try {
-    execFileSync(process.execPath, ["--check", file], {
-      cwd, encoding: "utf8", timeout: 10000, stdio: ["ignore", "pipe", "pipe"],
-    })
-    return "✓ node --check: Syntax OK"
-  } catch (e) {
-    return `✗ node --check: ${(e.stderr || e.message).slice(0, 500)}`
-  }
-}
-
 async function ruffCheck(file, { cwd, execFileSync }) {
   if (!/\.py$/.test(file)) return null
   try {
@@ -93,7 +109,7 @@ async function ruffCheck(file, { cwd, execFileSync }) {
     })
     return "✓ ruff: no issues"
   } catch (e) {
-    if (e.code === "ENOENT") return "linter: ruff not installed. Run: pip install ruff"
+    if (e.code === "ENOENT") return "lint: ruff not installed. Run: pip install ruff"
     const stdout = (e.stdout || "").trim()
     if (stdout) return stdout
     return `✗ ruff: ${(e.stderr || e.message).slice(0, 500)}`
@@ -129,13 +145,11 @@ async function goVet(file, { cwd, execFileSync }) {
   }
 }
 
-// ─── Language → checkers (first available wins) ──
-
 const LANG_CHECKERS = {
-  js:  [eslintCheck, nodeCheck],
-  mjs: [eslintCheck, nodeCheck],
-  cjs: [eslintCheck, nodeCheck],
-  jsx: [eslintCheck, nodeCheck],
+  js:  [eslintCheck],
+  mjs: [eslintCheck],
+  cjs: [eslintCheck],
+  jsx: [eslintCheck],
   ts:  [eslintCheck, tscCheck],
   tsx: [eslintCheck, tscCheck],
   mts: [eslintCheck, tscCheck],

package/src/tools/read.md

@@ -1,4 +1,11 @@
 Read a text file. Returns numbered lines. Use offset/limit to page large files.
+
+**Routing:**
+- Don't know which file? → `repo_outline` / `code_search` / `glob` first
+- Know the symbol but not the location? → `code_search` or `lsp definition`
+- Know the file but not the lines? → `grep` to find line numbers, then read that range with offset/limit
+- Reading an image? → `read_image` instead
+
 Parameters:
 - path (required): File path, relative to cwd or absolute (alias: filePath)
 - offset: 1-based line number to start reading from

package/src/tools/shared.mjs

@@ -20,6 +20,22 @@ 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"])
 
+/** SSRF guard: check if a hostname is private/internal. Shared by web.mjs and codemode.mjs. */
+export function isPrivateHost(hostname) {
+  const h = hostname.toLowerCase()
+  if (h === "localhost" || h === "0.0.0.0" || h.endsWith(".localhost")) return false
+  if (h === "127.0.0.1" || h.startsWith("127.")) return false
+  if (h === "169.254.169.254" || h === "metadata.google.internal") return true
+  // IPv6 private ranges — only check if host contains ":"
+  if (h.includes(":") && (h === "::1" || h === "fe80::1" || h.startsWith("fc") || h.startsWith("fd"))) return true
+  const m = h.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/)
+  if (m) {
+    const [a, b] = [Number(m[1]), Number(m[2])]
+    if (a === 10 || (a === 172 && b >= 16 && b <= 31) || a === 192 && b === 168 || a === 169 && b === 254 || a === 0) return true
+  }
+  return false
+}
+
 /** Normalize Windows line endings to Unix: \r\n → \n.
  *  Applied on every text-file read so that edit/hash matching
  *  and hash computation are platform-consistent. */

package/src/tools/system.mjs

@@ -119,16 +119,15 @@ function runBash(command, cwd, { timeout, signal, onOutput }) {
 
     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]"
-      }
+      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 (s) onOutput?.(s)
       if (errBuf.length < MAX_STREAM_BUF) errBuf += s
     })
 
@@ -142,11 +141,16 @@ function runBash(command, cwd, { timeout, signal, onOutput }) {
 
     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))
+      // Flush decoder tails — also push final bytes to panel
+      const outFlush = sanitizeOutput(outDecoder(Buffer.alloc(0), true))
+      const errFlush = sanitizeOutput(errDecoder(Buffer.alloc(0), true))
+      outBuf += outFlush
+      errBuf += errFlush
+      if (outFlush) onOutput?.(outFlush)
+      if (errFlush) onOutput?.(errFlush)
 
-      const status = exitSignal
+      // Windows has no POSIX signals — check signal.aborted for user interrupts
+      const status = (exitSignal || signal?.aborted)
         ? `killed: ${signal?.aborted ? "user interrupted" : "timeout"}`
         : `exit code ${code}`