thincoder 0.12.62 → 0.12.63

package/src/tools/file.mjs

@@ -1,469 +0,0 @@
-import {
-  DESC,
-  truncate,
-  MAX_READ_LINES,
-  gitDiffOne,
-  autoSyntaxCheck,
-  resolveInCwd,
-  resolveExternal,
-  normalizeEOL,
-  detectFileEol,
-  joinWithEol,
-  majorityEol,
-  FFFD_WARNING,
-} from "./shared.mjs";
-import { applyEditBatch } from "./edit-batch.mjs";
-import { runSingleEdit } from "./edit-diff.mjs";
-import { specForModel } from "../config.mjs";
-import { createHash } from "node:crypto";
-import { mkdir, readFile, stat, writeFile, unlink } from "node:fs/promises";
-import { join, relative, dirname } from "node:path";
-
-const MAX_FILE_READ_BYTES = 10_000_000
-const MAX_IMAGE_BYTES = 15_000_000
-// DUAL-END-TRUNCATION (F-1, C 方案——2026-09-09)：read 双端尾行数——窗口截断大文件时
-// 返回 头 N 行（N = 请求窗口，默认 MAX_READ_LINES）+ 省略注 + 尾 M 行（本常量）。M 与
-// 窗口合计（2500 行）为"整读上限"——K=0（尾区与窗口相接）时整印剩余、不产生假省略注。
-export const READ_TAIL_LINES = 500
-
-// ────────────────────────────────────────
-// Dirty-file tracking (read-before-insert guard)
-// ────────────────────────────────────────
-// insert_after anchors on LINE NUMBERS — the most drift-prone addressing.
-// Every write tool marks the file dirty; insert_after refuses to run on a
-// dirty file until the agent reads it again (fresh line numbers). This turns
-// the "read after edit" discipline into a structural guarantee: a stale
-// after_line can never silently land in the wrong place again.
-const dirtyPaths = new Set()
-export function markDirty(abs) { dirtyPaths.add(abs) }
-export function clearDirty(abs) { dirtyPaths.delete(abs) }
-export function isDirty(abs) { return dirtyPaths.has(abs) }
-
-// 2026-08-31 工具顺手度优化（用户批准）：写入工具记录受影响行范围——insert_after
-// 精确判定：after_line 在未受影响区（< lastWrite.startLine）→ 行号未漂移 → 允许
-// （消掉"我写的文件被当外部修改、必须重 read"的摩擦）；受影响区内 → 拒绝（护栏保留）；
-// write 全文重写 → 全文件受影响，任何 after_line 拒绝。
-const lastWrites = new Map() // abs → { type: 'write'|'edit'|'insert', startLine, shift }
-export function recordWrite(abs, write) {
-  lastWrites.set(abs, write)
-  dirtyPaths.delete(abs) // 本 session 写入——等效于刚 read 过（快照在 lastWrites）
-}
-export function lastWriteOf(abs) { return lastWrites.get(abs) }
-export function clearLastWrite(abs) { lastWrites.delete(abs) }
-
-/** 2026-08-31 工具顺手度（用户批准"可以啊"）：写入工具返回带上下文窗口——
- *  模型拿到的不只是"inserted at L395"，而是"L395 这行是什么内容"——下次再操作时
- *  能自检"我的行号 vs 实际内容"是否匹配，匹配不上 = 行号漂了，先 read——
- *  死循环就断了（根因：模型对行号锚点的"新鲜度"没有感知——数字本身不携带语义）。
- *  write 全文重写跳过（无行号锚点——模型刚写的知道内容）。
- *  edit-batch.mjs（数组形态）复用——导出仅供内部模块，非公共 API。 */
-export async function appendWriteContext(abs, writeLine, baseResult) {
-  const content = normalizeEOL(await readFile(abs, "utf8"))
-  const lines = content.split("\n")
-  const start = Math.max(1, writeLine - 3)
-  const end = Math.min(lines.length, writeLine + 3)
-  const ctxLines = []
-  for (let i = start; i <= end; i++) {
-    const marker = i === writeLine ? "→" : " "
-    ctxLines.push(`${marker} L${i}\t${lines[i - 1]}`)
-  }
-  return `${baseResult}\ncontext (L${start}-L${end}):\n${ctxLines.join("\n")}`
-}
-
-export const readTool = {
-  name: "read",
-  description: DESC("read"),
-  parameters: {
-    type: "object",
-    properties: {
-      path: { type: "string", description: "File path (relative to cwd or absolute)" },
-      filePath: { type: "string", description: "Alias for path (supported for API compatibility)" },
-      offset: { type: "number", description: "1-based line number to start from" },
-      limit: { type: "number", description: `Max lines to return (default ${MAX_READ_LINES})` },
-      allowExternal: { type: "boolean", description: "No-op retained for API compatibility — path resolution no longer asserts a working-directory boundary (all paths resolve relative to cwd)." },
-      hashes: { type: "boolean", description: "Include SHA256 line hashes for hash-based editing (default false). Use when you plan to edit the file with hashline_edit." },
-    },
-    required: ["path"],
-  },
-  readonly: true,
-  async execute(args, ctx) {
-    const p = args.path ?? args.filePath
-    const abs = args.allowExternal ? resolveExternal(ctx, p) : resolveInCwd(ctx, p)
-    // Large file guard: check size first, reject reading entire file if >10MB (offset/limit only affect the returned slice, not buffering)
-    const st = await stat(abs).catch(() => null)
-    if (st && st.size > MAX_FILE_READ_BYTES) throw new Error(`File too large (${Math.round(st.size / 1_000_000)}MB > 10MB limit). Use bash with head/tail or grep for targeted extraction.`)
-    const content = normalizeEOL(await readFile(abs, "utf8"))
-    // A read refreshes the agent's view — line numbers are fresh again.
-    clearDirty(abs)
-    clearLastWrite(abs) // 2026-08-31：read 同时清写入快照（新视图以 read 为准）
-    const lines = content.split("\n")
-    const offset = Math.max(1, args.offset ?? 1)
-    const limit = Math.min(args.limit ?? MAX_READ_LINES, MAX_READ_LINES)
-    const windowEnd = offset - 1 + limit // index just past the requested window
-    const render = (slice, startLn) => slice.map((l, i) => {
-      const ln = startLn + i
-      if (args.hashes) return `${ln}\t[${hashLine(l)}] ${l}`
-      return `${ln}\t${l}`
-    }).join("\n")
-    // DUAL-END-TRUNCATION (F-1, C 方案——DUAL-END-TRUNCATION.md 2026-09-09):
-    // 大文件（> MAX_READ_LINES 行）窗口截断时返回 头（请求窗口）+ 中段省略注 +
-    // 文件真实尾部（末 READ_TAIL_LINES 行——现尾注升级为真实尾行内容——offload 产物
-    // 的尾端结论可见）。≤ 阈值文件任何窗口走旧头向路径（字节零变化）；窗口覆盖全文件
-    // 也走旧路径。与 hashes 模式照常交互（头尾行 hash 照算）。
-    if (windowEnd >= lines.length || lines.length <= MAX_READ_LINES) {
-      const suffix = windowEnd < lines.length ? `\n... (${lines.length} lines total, use offset to continue)` : ""
-      return truncate(render(lines.slice(offset - 1, windowEnd), offset) + suffix)
-    }
-    const head = render(lines.slice(offset - 1, windowEnd), offset)
-    // 尾区 = 文件末 READ_TAIL_LINES 行；尾区起点落在窗口内（重叠）→ 尾区从窗口后开始
-    // —— 任何行不打印两次；剩余全被覆盖（K=0）→ 整印余段且无假省略注。
-    const tailStart = Math.max(windowEnd, lines.length - READ_TAIL_LINES)
-    const middle = tailStart - windowEnd
-    const tail = render(lines.slice(tailStart), tailStart + 1)
-    return middle > 0
-      ? `${head}\n…(truncated: ${middle} lines in middle, use offset to continue)\n${tail}`
-      : `${head}\n${tail}`
-  },
-}
-
-// ---------------------------------------------------------------- read_image
-
-// Raster formats only — every mainstream vision API (Kimi, Anthropic, OpenAI, Gemini)
-// rejects svg/bmp. svg is served as text source below; bmp is refused with a hint.
-const IMAGE_EXTENSIONS = { png: "image/png", jpg: "image/jpeg", jpeg: "image/jpeg", gif: "image/gif", webp: "image/webp" }
-const MAX_SVG_CHARS = 100_000
-
-export const readImageTool = {
-  name: "read_image",
-  description: DESC("read_image"),
-  parameters: {
-    type: "object",
-    properties: {
-      path: { type: "string", description: "Path to image file (relative to cwd or absolute). Supports png, jpg, gif, webp. svg files are returned as text source (no vision API accepts svg)." },
-    },
-    required: ["path"],
-  },
-  readonly: true,
-  multimodal: true, // returns JSON { text, images } — agent loop converts to multimodal user message
-  /** Returns JSON: { text, images }, for the agent layer to convert into multimodal user messages */
-  async execute(args, ctx) {
-    const abs = resolveInCwd(ctx, args.path)
-    const ext = abs.slice(abs.lastIndexOf(".") + 1).toLowerCase()
-
-    // SVG is text markup — return the source directly. Works with text-only models too
-    // (no vision gate), and never poisons history with an image part the API will 400 on.
-    if (ext === "svg") {
-      const st = await stat(abs).catch(() => null)
-      if (st && st.size > MAX_IMAGE_BYTES) throw new Error(`Image too large: ${Math.round(st.size / 1_000_000)}MB (max 15MB)`)
-      const src = normalizeEOL(await readFile(abs, "utf8"))
-      return `[read_image: ${args.path} (svg source, ${src.length} chars — no vision API accepts image/svg+xml, showing markup instead)]\n` +
-        truncate(src, MAX_SVG_CHARS)
-    }
-
-    // Vision capability gate: injecting an image into a text-only model's history poisons the whole
-    // conversation (every subsequent request 400s on the image part). Refuse before reading the file.
-    // F-3（IMAGE-DOWNGRADE-VISION——2026-09-09）：软引导句逐字锚（设计档照抄——CLI 无 extension
-    // 式自动降级——模型收到错误后自选 spawn 视觉渠道子代理路径）。
-    const model = ctx.agent?.provider?.model
-    if (model && !specForModel(model).multimodal) {
-      throw new Error(
-        `Model "${model}" does not support image input — read_image is unavailable with this provider. ` +
-        `Verify visual output programmatically (file size, dimensions, pixel checks via code) or ask the user to switch to a vision-capable provider.\n` +
-        `模型不支持图像——可 spawn 一个视觉模型子代理（subagent model 参数指视觉渠道）用 read_image 读图`
-      )
-    }
-    const mime = IMAGE_EXTENSIONS[ext]
-    if (!mime) {
-      const hint = ext === "bmp" ? " Convert it to PNG first (no mainstream vision API accepts BMP)." : ""
-      throw new Error(`Unsupported image format: .${ext}. Supported: ${Object.keys(IMAGE_EXTENSIONS).join(", ")}, svg (as text source).${hint}`)
-    }
-    // Check size before reading — prevent huge images from blowing up memory (20MB base64 ≈ 15MB raw)
-    const imgStat = await stat(abs).catch(() => null)
-    if (imgStat && imgStat.size > MAX_IMAGE_BYTES) throw new Error(`Image too large: ${Math.round(imgStat.size / 1_000_000)}MB (max 15MB)`)
-    const buf = await readFile(abs) // raw buffer, no encoding
-    const b64 = buf.toString("base64")
-    const bytes = buf.length
-    const result = JSON.stringify({
-      text: `[read_image: ${args.path} (${mime}, ${bytes} bytes)]`,
-      images: [{ type: "image_url", image_url: { url: `data:${mime};base64,${b64}` } }],
-    })
-    // Paste-created temp files: delete after use, no litter
-    const basename = abs.includes("/") ? abs.slice(abs.lastIndexOf("/") + 1) : abs.slice(abs.lastIndexOf("\\") + 1)
-    if (basename.startsWith(".thincoder-paste-")) {
-      try { await unlink(abs) } catch { /* can't delete, so be it */ }
-    }
-    return result
-  },
-}
-
-// ---------------------------------------------------------------- write
-
-export const writeTool = {
-  name: "write",
-  description: DESC("write"),
-  parameters: {
-    type: "object",
-    properties: {
-      path: { type: "string", description: "File path (relative to cwd or absolute)" },
-      content: { type: "string", description: "Full content to write" },
-    },
-    required: ["path", "content"],
-  },
-  readonly: false,
-  touchedPaths(args) { return args.path ? [args.path] : [] },
-  async execute(args, ctx) {
-    const abs = resolveInCwd(ctx, args.path)
-    await mkdir(dirname(abs), { recursive: true })
-    const st = await stat(abs).catch(() => null)
-    if (st?.isDirectory()) throw new Error(`Path is a directory: ${args.path}`)
-    // EOL semantics: overwriting an existing file restores ITS original EOL style (F1);
-    // a new file follows the directory's majority style, defaulting to LF (F2).
-    const prev = st ? await readFile(abs, "utf8").catch(() => null) : null
-    const eol = prev != null ? detectFileEol(prev) : majorityEol(dirname(abs))
-    const content = eol === "\r\n" ? normalizeEOL(args.content).replace(/\n/g, "\r\n") : args.content
-    await writeFile(abs, content, "utf8")
-    recordWrite(abs, { type: "write", startLine: 1, shift: 0 }) // 全文重写——全文件受影响
-    const diff = gitDiffOne(ctx.cwd, abs)
-    return `Wrote ${args.content.length} chars to ${args.path}${diff ? "\n" + diff : ""}${await autoSyntaxCheck(abs)}`
-  },
-}
-
-// ---------------------------------------------------------------- edit
-
-export const editTool = {
-  name: "edit",
-  description: DESC("edit"),
-  parameters: {
-    type: "object",
-    properties: {
-      path: { type: "string", description: "File path — single form: required; with the edits array: optional top-level default for entries without their own path" },
-      old_string: { type: "string", description: "Exact text to replace (tolerant matching: exact → whitespace-only variant → fuzzy match at ≥90% line equality after whitespace/indent/quote normalization). Mutually exclusive with line/startLine/endLine" },
-      new_string: { type: "string", description: "Replacement text — content-based edits require it (empty is an explicit error); with line-based targeting (line/startLine/endLine) give it to replace the line/range, or OMIT it to delete (an explicit empty string is an error — omission is the delete signal)" },
-      line: { type: "integer", description: "1-based line number — replace that single line with new_string, or OMIT new_string to DELETE the line; no old_string needed (mutually exclusive with old_string and startLine/endLine)" },
-      startLine: { type: "integer", description: "1-based first line of the range to replace with new_string (inclusive — requires endLine; mutually exclusive with old_string); OMIT new_string to DELETE the range" },
-      endLine: { type: "integer", description: "1-based last line of the range to replace with new_string (inclusive — requires startLine; mutually exclusive with old_string); OMIT new_string to DELETE the range" },
-      replace_all: { type: "boolean", description: "Replace all occurrences (default false)" },
-      edits: {
-        type: "array",
-        description: "Batch form — multiple edits in ONE call, atomic (any failure writes nothing; same-file entries apply serially, each based on the previous result). Use it for multiple changes to the same file AND for independent changes across multiple files — prefer one batched call over N single edits. A top-level path is allowed — it defaults entries without their own path (entry paths win). Mutually exclusive with top-level old_string/new_string/line/startLine/endLine — provide each change's targeting (old_string, or line / startLine+endLine) inside its edits entry; new_string replaces when given, and line-targeted entries may omit it to DELETE the line/range.",
-        items: {
-          type: "object",
-          properties: {
-            path: { type: "string" },
-            old_string: { type: "string" },
-            new_string: { type: "string" },
-            line: { type: "integer" },
-            startLine: { type: "integer" },
-            endLine: { type: "integer" },
-            replace_all: { type: "boolean" },
-          },
-        },
-      },
-    },
-    required: [],
-  },
-  readonly: false,
-  touchedPaths(args) {
-    // 2026-09-05 用户裁定：顶层 path = 批默认——仅当有条目缺 path 时计入（条目全带 path
-    // 时顶层 path 不实际使用——不虚报进 _touchedFiles）
-    if (args.edits) {
-      const out = args.edits.map((e) => e.path).filter(Boolean)
-      if (args.path && args.edits.some((e) => !e.path)) out.push(args.path)
-      return out
-    }
-    return args.path ? [args.path] : []
-  },
-  async execute(args, ctx) {
-    // 2026-08-31 工具顺手度（用户批准）：数组形态——一次多文件原子替换
-    // （应用逻辑在 edit-batch.mjs——2026-09-01 拆出，500 行硬限，先例 git-ext.mjs）
-    if (args.edits) return applyEditBatch(args, ctx)
-
-    // 单文件（现状路径）——执行体整段迁出至 edit-diff.mjs（EDIT.md §6——
-    // 行级 LCS 判定：零重叠→替换即删 / 一般 diff→LCS / 空 new→显式报错）
-    return runSingleEdit(args, ctx)
-  },
-}
-
-// ---------------------------------------------------------------- insert_after
-
-export const insertAfterTool = {
-  name: "insert_after",
-  description: DESC("insert_after"),
-  parameters: {
-    type: "object",
-    properties: {
-      path: { type: "string", description: "File path" },
-      after_line: { type: "number", description: "Line number to insert after (1-based). Takes priority over after_regex." },
-      after_regex: { type: "string", description: "JavaScript regex to find the line to insert after (must match exactly one line)" },
-      content: { type: "string", description: "Text to insert (with leading newline if you need a blank line)" },
-    },
-    required: ["path", "content"],
-  },
-  readonly: false,
-  touchedPaths(args) { return args.path ? [args.path] : [] },
-  async execute(args, ctx) {
-    const abs = resolveInCwd(ctx, args.path)
-    // Read-before-insert guard: after_line anchors are line numbers, and any
-    // write since the last read made them stale. Refuse instead of silently
-    // inserting at a drifted position (the failure mode that corrupted test
-    // structure repeatedly). after_regex callers get the same gate — a stale
-    // target line is just as wrong, and the rule is simpler to reason about.
-    // 2026-08-31 工具顺手度（用户批准）：判定精确化——本 session 写入工具记录受影响区
-    // （lastWrite），after_line 在未受影响区（<= startLine）→ 行号未漂移 → 允许
-    // （消掉"我写的文件被当外部修改"的摩擦）；受影响区内/write 全文重写 → 拒绝。
-    const lw = lastWriteOf(abs)
-    if (lw && args.after_line != null) {
-      if (lw.type === "write") {
-        throw new Error(
-          `${args.path} 刚被 write 全文重写（was modified since your last read）——任何行号都可能漂移，必须重 read。`
-        )
-      }
-      if (args.after_line > lw.startLine) {
-        throw new Error(
-          `${args.path} 的 after_line ${args.after_line} 在上次写入（L${lw.startLine}）之后——` +
-          `行号已漂移 ${lw.shift >= 0 ? "+" : ""}${lw.shift}，请用新行号或先 read。`
-        )
-      }
-      // after_line <= startLine → 行号未漂移 → 允许
-    } else if (isDirty(abs)) {
-      throw new Error(
-        `${args.path} was modified since your last read — line numbers may be stale.\n` +
-        `Read the file again (read tool) to refresh line numbers, then retry insert_after.`
-      )
-    }
-    const raw = await readFile(abs, "utf8") // original bytes — EOL detection needs the file's real line endings
-    const text = normalizeEOL(raw)
-    const lines = text.split("\n")
-
-    let targetLine
-    if (args.after_line != null) {
-      targetLine = args.after_line
-      if (!Number.isInteger(targetLine)) {
-        throw new Error(`after_line must be an integer, got: ${args.after_line}`)
-      }
-      if (targetLine < 1 || targetLine > lines.length) {
-        throw new Error(`after_line ${targetLine} out of range (file has ${lines.length} lines)`)
-      }
-    } else if (args.after_regex) {
-      let regex
-      try {
-        regex = new RegExp(args.after_regex)
-      } catch (e) {
-        throw new Error(`after_regex /${args.after_regex}/ is not a valid JavaScript regex: ${e.message}`, { cause: e })
-      }
-      const matches = []
-      for (let i = 0; i < lines.length; i++) {
-        if (regex.test(lines[i])) matches.push(i + 1)
-      }
-      if (matches.length === 0) throw new Error(`after_regex /${args.after_regex}/ matched no lines in ${args.path}`)
-      if (matches.length > 1) throw new Error(`after_regex /${args.after_regex}/ matched ${matches.length} lines (${matches.slice(0, 5).join(", ")}${matches.length > 5 ? "…" : ""}); use a more specific pattern or after_line instead`)
-      targetLine = matches[0]
-    } else {
-      throw new Error("Either after_line or after_regex is required")
-    }
-
-    lines.splice(targetLine, 0, normalizeEOL(args.content))
-    // Write back in the file's ORIGINAL EOL style (review R9#2: same bug class as
-    // edit — a CRLF file must not silently become LF here either).
-    const updated = joinWithEol(lines, raw)
-    await writeFile(abs, updated, "utf8")
-    recordWrite(abs, { type: "insert", startLine: targetLine, shift: normalizeEOL(args.content).split("\n").length })
-    const diff = gitDiffOne(ctx.cwd, abs)
-    const baseResult = `Inserted after line ${targetLine} in ${args.path}${diff ? "\n" + diff : ""}${await autoSyntaxCheck(abs)}`
-    return await appendWriteContext(abs, targetLine + 1, baseResult)
-  },
-}
-
-// ---------------------------------------------------------------- hashline_edit
-
-/**
- * Compute a 12-char hex SHA256 hash for a line (exact content, no trimming).
- * Used by both read (hashes=true) and hashline_edit for hash-based matching.
- */
-export function hashLine(content) {
-  return createHash("sha256").update(content).digest("hex").slice(0, 12)
-}
-
-export const hashlineEditTool = {
-  name: "hashline_edit",
-  description: DESC("hashline_edit"),
-  parameters: {
-    type: "object",
-    properties: {
-      path: { type: "string", description: "File path" },
-      old_hashes: { type: "array", items: { type: "string" }, description: "SHA256 hashes (12 chars) of the lines to replace. Read the file with hashes=true first to obtain these hashes. Single line: pass 1 hash; multiple lines: pass the exact sequence of hashes." },
-      new_content: { type: "string", description: "Replacement text (can span multiple lines)" },
-    },
-    required: ["path", "old_hashes", "new_content"],
-  },
-  readonly: false,
-  touchedPaths(args) { return args.path ? [args.path] : [] },
-  async execute(args, ctx) {
-    const abs = resolveInCwd(ctx, args.path)
-    if (!args.old_hashes?.length) throw new Error("old_hashes must not be empty — read the file with hashes=true to get line hashes")
-    const raw = await readFile(abs, "utf8")
-    const content = normalizeEOL(raw)
-    // Encoding-corruption probe: U+FFFD means the file is not clean UTF-8 — hash
-    // addressing may be unreliable. Warn (never block).
-    const corrupted = content.includes("\uFFFD")
-    const lines = content.split("\n")
-    const fileHashes = lines.map((l) => hashLine(l))
-    const target = args.old_hashes
-
-    // Sliding-window match: find all occurrences of the hash sequence.
-    // When multiple matches are found (e.g. empty lines), report positions so the
-    // model can include more context lines (adjacent lines with unique hashes).
-    const matches = []
-    for (let i = 0; i <= fileHashes.length - target.length; i++) {
-      let match = true
-      for (let j = 0; j < target.length; j++) {
-        if (fileHashes[i + j] !== target[j]) { match = false; break }
-      }
-      if (match) matches.push(i)
-    }
-
-    if (matches.length === 0) {
-      // Help the model recover: show the current file hashes for context
-      const maxShow = Math.min(fileHashes.length, 50)
-      const hashDump = fileHashes.slice(0, maxShow).map((h, i) => `${h}  L${i + 1}: ${lines[i].slice(0, 80)}`).join("\n")
-      const preview = target.join(" ")
-      throw new Error(
-        `Hash sequence not found in ${args.path}: ${preview} — for fresh hashes, re-read the file with hashes=true\n` +
-        `The file may have been modified since you last read it. Current hashes (first ${maxShow} lines):\n${hashDump}` +
-        (corrupted ? `\n${FFFD_WARNING}` : "")
-      )
-    }
-
-    if (matches.length > 1) {
-      const ctx = 2 // lines of surrounding context
-      const detail = matches.map((m) => {
-        const start = Math.max(0, m - ctx)
-        const end = Math.min(lines.length, m + target.length + ctx)
-        const preview = lines.slice(start, end).map((l, i) => {
-          const ln = start + i + 1
-          const marker = m <= ln - 1 && ln - 1 < m + target.length ? ">" : " "
-          return `${marker} L${ln}: ${l.slice(0, 80)}`
-        }).join("\n")
-        return `  Match at line ${m + 1} (${target.length} line(s)):\n${preview}`
-      }).join("\n\n")
-      throw new Error(
-        `Hash sequence matches ${matches.length} positions in ${args.path} — ambiguous.\n` +
-        `Include more surrounding lines (unique-hash lines before/after the target) to disambiguate.\n\n` +
-        `All matches with surrounding context:\n\n${detail}`
-      )
-    }
-
-    const pos = matches[0]
-    // Replace: remove old lines, insert new lines at the same position
-    const newLines = normalizeEOL(args.new_content).split("\n") // normalize: CRLF in new_content would join into \r\r\n
-    lines.splice(pos, target.length, ...newLines)
-    // Write back in the file's original EOL style (same rule as edit / apply_patch).
-    const updated = joinWithEol(lines, raw)
-    await writeFile(abs, updated, "utf8")
-    recordWrite(abs, { type: "edit", startLine: pos + 1, shift: newLines.length - target.length })
-    const diff = gitDiffOne(ctx.cwd, abs)
-    const baseResult = `Edited ${args.path}: replaced ${target.length} line(s) at L${pos + 1} with ${newLines.length} line(s)${diff ? "\n" + diff : ""}${await autoSyntaxCheck(abs)}${corrupted ? `\n${FFFD_WARNING}` : ""}`
-    return await appendWriteContext(abs, pos + 1, baseResult)
-  },
-}
-

package/src/tools/file_ops.md

@@ -1,17 +0,0 @@
-Move, copy, or rename a file/directory.
-
-**Route to file_ops instead of bash:**
-- `mv a b` → file_ops action=move
-- `cp a b` / `copy` → file_ops action=copy
-- `ren a b` / `rename a b` → file_ops action=rename
-
-Parameters:
-- action (required): move | copy | rename
-- source (required): source path, relative to cwd or absolute
-- dest (required): destination path
-
-Notes:
-- Paths resolve relative to cwd — no directory restriction (same boundary as bash; the approval gate is the guard).
-- `dest` is overwritten if it already exists. `copy` is recursive for directories.
-- To create a directory, use `write` (creates parent dirs) or `bash mkdir`.
-- Returns `Moved|Copied|Renamed <source> -> <dest>` or `Error: ...` (same-path and missing-path errors).

package/src/tools/get_current_time.md

@@ -1,8 +0,0 @@
-Get the current date, time, weekday, and timezone.
-
-**Route to get_current_time instead of bash:**
-- `date` / `time` → get_current_time
-
-Use it whenever a task depends on the current time or date (deadlines, freshness, timestamps) rather than shelling out.
-
-Returns `Date` / `Timezone` / `Weekday` / `Local` lines (UTC + local timezone).

package/src/tools/git-checkpoint.mjs

@@ -1,143 +0,0 @@
-/**
- * git-checkpoint.mjs — git 工具 checkpoint action 子系统（CHECKPOINT.md F2/F6）。
- * git.mjs 的 checkpoint case 委托到这里：list/create/rewind/cat/versions + F6 懒清理 +
- * F2/D7 提示行 + 文件树格式化。CLI 与 VS Code 两端同构（镜像，修改须两端同批）。
- */
-import { runGit } from "./shared.mjs"
-import { escapeXml } from "../agent/helpers.mjs"
-import {
-  createCheckpoint,
-  listCheckpoints,
-  rewind,
-  listFileVersions,
-  catFile,
-  isGitRepo,
-  deleteCheckpointsForCwd,
-} from "../git/checkpoint.mjs"
-
-/** F6 lazy fallback (CHECKPOINT.md D3): an EXTERNAL git commit (via bash / IDE — not the git
- *  tool) leaves this cwd's checkpoints as pre-commit state. Compare HEAD commit time
- *  (epoch SECONDS from %ct) against the newest snapshot's meta.time (ms): `%ct × 1000` aligns
- *  both to ms. HEAD newer → every snapshot predates the commit → clear all. All-or-nothing:
- *  any snapshot NEWER than HEAD (e.g. a manual create after the external commit) skips the
- *  whole clear. Best-effort — never blocks the checkpoint op. */
-export async function lazyClearIfCommitted(cwd) {
-  try {
-    const cps = await listCheckpoints(cwd)
-    if (cps.length === 0) return
-    const headSec = runGit(cwd, ["log", "-1", "--format=%ct"])
-    const headMs = Number.parseInt(headSec, 10) * 1000
-    if (!Number.isFinite(headMs) || headMs <= 0) return
-    const newest = cps[0] // listCheckpoints returns newest → oldest
-    if (headMs > newest.time) await deleteCheckpointsForCwd(cwd)
-  } catch {
-    // best-effort (NF7 philosophy) — a lazy-clear failure must not break list/create
-  }
-}
-
-/** checkpoint case 主入口（git 工具 checkpoint action 的全部子动作）。 */
-export async function executeCheckpointAction(args, ctx) {
-  const { checkpointAction: sub, checkpointId: id, path } = args
-  if (!isGitRepo(ctx.cwd)) throw new Error("Not a git repository — checkpoints unavailable")
-
-  if (!sub) return "checkpoint: missing checkpointAction — use: list | create | rewind | cat | versions"
-
-  // F6 lazy fallback (list/create entry): an EXTERNAL git commit (HEAD time newer
-  // than the newest snapshot) means every snapshot predates a safety baseline —
-  // clear them. All-or-nothing: if any snapshot is newer than HEAD, skip entirely.
-  if (sub === "list" || sub === "create") await lazyClearIfCommitted(ctx.cwd)
-
-  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 === "versions") {
-    if (!path) throw new Error("path is required for versions — the file whose history you want")
-    const versions = await listFileVersions(ctx.cwd, path)
-    if (versions.length === 0) return `No snapshot copies of "${path}" found (it was never part of an auto/protection snapshot).`
-    return (
-      `Historical versions of "${path}" (${versions.length}, newest first):\n` +
-      versions.map((v) =>
-        `  ${v.snapshotId}  ${new Date(v.time).toISOString()}  ${v.size}B  sha:${v.sha}  (${v.source})` +
-        (v.sha === versions[versions.indexOf(v) - 1]?.sha ? "  ← same content as previous" : "")
-      ).join("\n") +
-      `\nRestore a version: checkpointAction=rewind checkpointId=<snapshotId> path="${path}"`
-    )
-  }
-  if (sub === "rewind") {
-    if (!id) throw new Error("checkpointId is required for rewind — use checkpointAction=list to see snapshot ids")
-    if (!path) throw new Error("path is required for rewind — full restore is disabled (as dangerous as `git checkout -- .`). Restore files individually. Use checkpointAction=versions path=<file> to list a file's historical versions.")
-    const s = await rewind(ctx.cwd, id, { path })
-    return `Restored "${path}" (${s.type}) from checkpoint ${id}.\n(The pre-restore state was snapshotted first — you can restore again to go back.)`
-  }
-  if (sub === "cat") {
-    if (!id) throw new Error("checkpointId is required for cat — use checkpointAction=list to see snapshot ids")
-    if (!path) throw new Error("path is required for cat — specify which file to read")
-    return await catFile(ctx.cwd, id, path)
-  }
-  if (sub === "list") {
-    const cps = await listCheckpoints(ctx.cwd)
-    if (cps.length === 0) return "(no checkpoints yet)"
-
-    // Specific id: show the file tree within that snapshot
-    if (id) {
-      const cp = cps.find((c) => c.id === id)
-      if (!cp) throw new Error(`checkpoint ${id} 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). F2/D7: fixed
-    // hint line at the tail — the recovery entry for a snapshot after an accident.
-    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") + "\n(意外丢弃改动？checkpointAction=rewind 可恢复操作前状态)"
-  }
-  throw new Error(`Unknown checkpoint action: ${sub}. Use: list | create | rewind | cat | versions`)
-}
-
-/** 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: escapeXml(f), type: "" })),
-    ...(cp.untracked ?? []).map((f) => ({ path: escapeXml(f), type: " (untracked)" })),
-  ]
-  if (all.length === 0) return "(empty checkpoint)"
-
-  all.sort((a, b) => a.path.localeCompare(b.path))
-
-  const tree = new Map()
-  for (const { path, type } of all) {
-    const dir = path.includes("/") ? path.slice(0, path.lastIndexOf("/")) : "."
-    if (!tree.has(dir)) tree.set(dir, [])
-    tree.get(dir).push({ name: path.slice(dir === "." ? 0 : dir.length + 1), type })
-  }
-
-  const lines = []
-  const dirs = [...tree.keys()].sort()
-  for (const dir of dirs) {
-    if (dir !== "." && !lines.includes(dir + "/")) {
-      const parts = dir.split("/")
-      for (let i = 1; i <= parts.length; i++) {
-        const prefix = parts.slice(0, i).join("/") + "/"
-        if (!lines.includes(prefix)) lines.push(prefix)
-      }
-    }
-  }
-  for (const dir of dirs) {
-    if (dir !== ".") {
-      for (const { name, type } of tree.get(dir)) {
-        lines.push(`  ${dir}/${name}${type}`)
-      }
-    }
-  }
-  for (const { name, type } of tree.get(".") ?? []) {
-    lines.push(name + type)
-  }
-
-  return lines.join("\n")
-}