thincoder 0.8.1 → 0.8.3

package/src/provider/core.mjs

@@ -1,5 +1,5 @@
 /**
- * provider/core.mjs — LLM 调用核心
+ * provider/core.mjs — LLM call core
  * chat / listModels / createProvider / requestWithRetry / readSSE
  */
 
@@ -10,10 +10,13 @@ import {
   estimateRequestTokens, rateGate, recordRate,
 } from "./rate.mjs"
 
+const FETCH_TIMEOUT_MS = 120000
+
+/** Create a validated provider config object from raw config */
 export function createProvider(config) {
-  if (!config?.baseURL) throw new Error("provider config: baseURL is required")
-  if (!config?.apiKey) throw new Error("provider config: apiKey is required (config file or THINCODER_API_KEY env)")
-  if (!config?.model) throw new Error("provider config: model is required")
+  if (!config?.baseURL) throw new Error("provider config: baseURL is required — configure providers in ~/.thincoder/config.json")
+  if (!config?.apiKey) throw new Error("provider config: apiKey is required — set THINCODER_API_KEY env or configure in ~/.thincoder/config.json")
+  if (!config?.model) throw new Error("provider config: model is required — configure in ~/.thincoder/config.json")
   return {
     baseURL: config.baseURL.replace(/\/+$/, ""),
     apiKey: config.apiKey,
@@ -27,6 +30,7 @@ export function createProvider(config) {
   }
 }
 
+/** Send a streaming chat completion request with automatic continuation on truncation */
 export async function chat(provider, { messages, tools, onToken, onReasoning, onWait, signal }) {
   const spec = specForModel(provider.model)
   const body = {
@@ -108,6 +112,7 @@ export async function chat(provider, { messages, tools, onToken, onReasoning, on
   return result
 }
 
+/** List available model IDs from the provider's /models endpoint */
 export async function listModels(provider, { signal } = {}) {
   const response = await fetch(`${provider.baseURL}/models`, {
     headers: { Authorization: `Bearer ${provider.apiKey}` },
@@ -138,7 +143,7 @@ async function requestWithRetry(provider, body, signal, onWait) {
           Authorization: `Bearer ${provider.apiKey}`,
         },
         body: JSON.stringify(body),
-        signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(120000)]) : AbortSignal.timeout(120000),
+        signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(FETCH_TIMEOUT_MS)]) : AbortSignal.timeout(FETCH_TIMEOUT_MS),
       })
     } catch (error) {
       if (error.name === "AbortError") throw error
@@ -233,7 +238,7 @@ async function readSSE(response, { onToken, onReasoning }) {
 }
 
 function betaBaseURL(baseURL) {
-  // DeepSeek prefix 续写走 /beta 端点；只处理 /v1 后缀，缺 /v1 时追加 /beta
+  // DeepSeek prefix continuation uses /beta endpoint; only handle /v1 suffix, append /beta when /v1 is missing
   if (/\/v1$/.test(baseURL)) return baseURL.replace(/\/v1$/, "/beta")
   return baseURL.endsWith("/") ? baseURL + "beta" : baseURL + "/beta"
 }

package/src/provider/index.mjs

@@ -1,6 +1,6 @@
 /**
- * provider/index.mjs — 后端兼容重导出
- * import { chat } from "./provider" → 自动解析到本文件
+ * provider/index.mjs — backward-compatible re-export
+ * import { chat } from "./provider" → resolves to this file
  */
 export { chat, createProvider, listModels } from "./core.mjs"
 export { RETRYABLE_STATUS, _rateHooks, estimateText, estimateRequestTokens, rateGate, recordRate } from "./rate.mjs"

package/src/provider/rate.mjs

@@ -1,6 +1,6 @@
 /**
- * provider/rate.mjs — TPM/RPM 主动节流闸门
- * 滑动窗口记账，发请求前预检预算，超支则睡到窗口腾出空间。
+ * provider/rate.mjs — TPM/RPM proactive throttling gate
+ * Sliding-window accounting; pre-check budget before sending requests; sleep until window frees space when over budget.
  */
 
 import { specForModel } from "../config.mjs"
@@ -11,8 +11,8 @@ export const MAX_CONTINUATIONS = 3
 export const RATE_LIMIT_BACKOFF_MS = [15_000, 30_000, 60_000]
 
 /**
- * 测试钩子：睡眠/时钟/窗口长度可替换（离线测试不能真等 60s）。
- * 生产代码不要直接调 setTimeout/sleep，统一走这里。
+ * Test hooks: sleep/clock/window length are replaceable (offline tests can't really wait 60s).
+ * Production code should never call setTimeout/sleep directly — always go through these.
  */
 export const _rateHooks = {
   sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
@@ -23,20 +23,20 @@ export const _rateHooks = {
 const rateWindows = new Map() // key → { tokens: [{ts, n}], requests: [ts] }
 
 function rateKey(provider) {
-  // 归一化：/beta 和 /v1 视为同一账户的同一限流窗口（DeepSeek prefix continuation 改 /beta 端点）
+  // Normalize: /beta and /v1 are treated as the same account's rate-limit window (DeepSeek prefix continuation switches to /beta endpoint)
   const base = provider.baseURL.replace(/\/beta$/, "/v1")
   return `${base}|${provider.apiKey ?? ""}`
 }
 
-/** 粗估文本 token 数。
- *  ASCII 按 ~4 字符/token；非 ASCII（CJK/emoji）按 ~1 字符/token（保守，实测 BPE 1.5-2.5 字/token）。 */
+/** Rough estimate of text token count.
+ *  ASCII ~4 chars/token; non-ASCII (CJK/emoji) ~1 char/token (conservative; measured BPE is 1.5-2.5 chars/token). */
 export function estimateText(s) {
   let nonAscii = 0
   for (let i = 0; i < s.length; i++) if (s.charCodeAt(i) > 0x7f) nonAscii++
   return Math.ceil((s.length - nonAscii) / 4) + nonAscii
 }
 
-/** 本次请求的 prompt 估算 */
+/** Estimated prompt tokens for this request */
 export function estimateRequestTokens(body) {
   let tokens = 0
   for (const m of body.messages ?? []) {
@@ -50,7 +50,7 @@ export function estimateRequestTokens(body) {
   return tokens
 }
 
-/** 闸门：超预算则睡到窗口腾出空间 */
+/** Gate: sleep until window frees space when over budget */
 export async function rateGate(provider, estimated, onWait, signal) {
   const tpm = provider.tpm != null && estimated <= provider.tpm ? provider.tpm : null
   const rpm = provider.rpm ?? null
@@ -87,7 +87,7 @@ export async function rateGate(provider, estimated, onWait, signal) {
   }
 }
 
-/** 记账：响应回来后按实测 usage 记 */
+/** Accounting: record measured usage after response returns */
 export function recordRate(provider, estimated, usage) {
   if (provider.tpm == null && provider.rpm == null) return
   const key = rateKey(provider)
@@ -98,7 +98,7 @@ export function recordRate(provider, estimated, usage) {
   w.requests = w.requests.filter((ts) => ts > cutoff)
   w.requests.push(now)
   w.tokens.push({ ts: now, n: usage ? (usage.prompt_tokens ?? estimated) + (usage.completion_tokens ?? 0) : estimated })
-  // 窗口已空则删条目，防长期跨 provider 配置时 Map 无界增长
+  // Delete entry when window is empty, preventing unbounded Map growth across long-running provider configs
   if (w.tokens.length === 0 && w.requests.length === 0) rateWindows.delete(key)
   else rateWindows.set(key, w)
 }

package/src/session.mjs

@@ -1,9 +1,9 @@
 /**
- * session.mjs — 会话持久化
- * 每个项目（按 cwd 哈希）最多保留 5 轮会话，按最后使用时间轮转。
- * 两种恢复需求分开存：agent 恢复（history）要上下文连续，用户恢复（display）要所见即所得。
+ * session.mjs — session persistence
+ * Each project (keyed by cwd hash) keeps up to 5 session slots, rotated by last-access time.
+ * Two recovery needs stored separately: agent recovery (history) needs context continuity, user recovery (display) needs WYSIWYG.
  *
- * 文件布局：{hash}.json（当前）、{hash}.json.1~5（槽位）、{hash}.json.manifest（槽位元数据）
+ * File layout: {hash}.json (current), {hash}.json.1~5 (slots), {hash}.json.manifest (slot metadata)
  */
 
 import { createHash } from "node:crypto"
@@ -12,18 +12,20 @@ import { join, dirname } from "node:path"
 import { configDir } from "./config.mjs"
 
 const MAX_SLOTS = 5
+const CWD_HASH_LEN = 12
 
+/** Derive session file path from cwd hash */
 export function sessionPath(cwd) {
-  const hash = createHash("sha1").update(cwd).digest("hex").slice(0, 12)
+  const hash = createHash("sha1").update(cwd).digest("hex").slice(0, CWD_HASH_LEN)
   return join(configDir, "sessions", `${hash}.json`)
 }
 
 function slotPath(cwd, n) { return sessionPath(cwd) + "." + n }
 function manifestPath(cwd) { return sessionPath(cwd) + ".manifest" }
 
-/** 原子写：先写临时文件再 rename 替换，防写入中途崩溃留下截断的 JSON 丢整个会话。
- *  rename 在 POSIX 上原子；Windows 上目标已存在时 Node 24 用 MoveFileExW+REPLACE_EXISTING 也能原子替换。
- *  某些旧 Windows 文件系统可能抛 EPERM，重试一次。 */
+/** Atomic write: write to temp file then rename to replace, preventing truncated JSON from mid-write crash.
+ *  rename is atomic on POSIX; on Windows with existing target, Node 24 uses MoveFileExW+REPLACE_EXISTING for atomic replace.
+ *  Some older Windows filesystems may throw EPERM — retry once. */
 function writeSessionFile(p, data) {
   mkdirSync(dirname(p), { recursive: true })
   const tmp = `${p}.tmp`
@@ -31,13 +33,19 @@ function writeSessionFile(p, data) {
   try {
     renameSync(tmp, p)
   } catch {
-    // Windows EPERM 兜底：删目标后重试（极罕见，仅旧 NTFS/网络盘）
+    // Windows: rename may fail due to antivirus lock / network drive contention — delete target and retry
     try { unlinkSync(p) } catch {}
-    renameSync(tmp, p)
+    try {
+      renameSync(tmp, p)
+      // rename succeeded: clean up temp file
+      try { unlinkSync(tmp) } catch {}
+    } catch {
+      // rename still failed: keep tmp as fallback data (next read prefers main file; if missing, tmp is at least there)
+    }
   }
 }
 
-// ========== 槽位管理 ==========
+// ========== slot management ==========
 
 function loadManifest(cwd) {
   try {
@@ -51,14 +59,14 @@ function saveManifest(cwd, m) {
   writeSessionFile(manifestPath(cwd), m)
 }
 
-/** 归档当前会话到空闲槽位——满了踢最老；exclude 指定一个不许被踢的槽位（switchToSlot 的目标槽） */
+/** Archive current session to a free slot — evict oldest if full; exclude specifies a slot that must not be evicted (switchToSlot target) */
 export function archiveCurrent(cwd, { exclude } = {}) {
   const src = sessionPath(cwd)
   if (!existsSync(src)) return
   const m = loadManifest(cwd)
 
   let slot
-  // 只计数字 key 的槽位，排除 _currentName 等遗留非数字 key
+  // Only count numeric-keyed slots, exclude legacy non-numeric keys like _currentName
   const entries = Object.entries(m.slots).filter(([n]) => /^\d+$/.test(n))
   if (entries.length < MAX_SLOTS) {
     slot = 1
@@ -69,12 +77,12 @@ export function archiveCurrent(cwd, { exclude } = {}) {
   }
 
   const dst = slotPath(cwd, slot)
-  // 复制（rename 会丢当前）；走原子写，防中途崩溃留下截断的 JSON 丢归档
+  // Copy (rename would lose current); use atomic write to prevent truncated JSON in archive from mid-crash
   let data
   try {
     data = JSON.parse(readFileSync(src, "utf8"))
   } catch {
-    // 会话文件损坏，放弃归档，下次保存会覆盖
+    // Session file corrupted, abandon archive; next save will overwrite
     return
   }
   writeSessionFile(dst, data)
@@ -84,7 +92,7 @@ export function archiveCurrent(cwd, { exclude } = {}) {
   return slot
 }
 
-/** 列出所有归档槽位，最新在前 */
+/** List all archive slots, newest first */
 export function listSlots(cwd) {
   const m = loadManifest(cwd)
   return Object.entries(m.slots)
@@ -92,29 +100,29 @@ export function listSlots(cwd) {
     .sort((a, b) => b.timestamp - a.timestamp)
 }
 
-/** 切换到指定槽位：归档当前 → 槽位文件复制到当前 → 返回恢复数据（失败返回 null） */
+/** Switch to a specific slot: archive current → copy slot file to current → return recovered data (null on failure) */
 export function switchToSlot(cwd, slot) {
   const m = loadManifest(cwd)
   if (!m.slots[slot]) return null
 
-  // 归档当前（内部写 manifest；之后我们的 m 已过期，需重读）
-  // 满槽时排除目标槽：否则最老槽=目标槽，归档会把目标覆盖掉再复制回来，目标会话永久丢失
+  // Archive current (internally writes manifest; our `m` is stale after, must reload)
+  // When full, exclude target slot: otherwise oldest=target, archive would overwrite target then copy back, permanently losing the target session
   archiveCurrent(cwd, { exclude: slot })
 
-  // 槽位文件 → 当前（copy+unlink，不用 rename：Windows rename 目标已存在会抛 EPERM）
+  // Slot file → current (copy+unlink, not rename: Windows rename on existing target throws EPERM)
   const src = slotPath(cwd, slot)
   const dst = sessionPath(cwd)
   if (!existsSync(src)) return null
   try {
-    try { unlinkSync(dst) } catch { /* 不存在就算了 */ }
+    try { unlinkSync(dst) } catch { /* doesn't exist, that's fine */ }
     copyFileSync(src, dst)
     unlinkSync(src)
   } catch {
-    // 文件操作失败（磁盘满/权限不足/锁文件），放弃切换
+    // File operations failed (disk full / permissions / lock), abandon switch
     return null
   }
 
-  // 重读 manifest（archiveCurrent 改了它）
+  // Reload manifest (archiveCurrent modified it)
   const m2 = loadManifest(cwd)
   delete m2.slots[slot]
   saveManifest(cwd, m2)
@@ -122,7 +130,7 @@ export function switchToSlot(cwd, slot) {
   return loadSession(cwd)
 }
 
-// ========== 旧版 transient 前缀清理 ==========
+// ========== legacy transient prefix cleanup ==========
 
 const LEGACY_TRANSIENT_PREFIXES = [
   "[System reminder: working directory snapshot:",
@@ -137,8 +145,9 @@ function isLegacyTransient(m) {
   )
 }
 
-// ========== 核心读写 ==========
+// ========== core read/write ==========
 
+/** Save agent state and display lines to the session file (atomic write) */
 export function saveSession(agent, display) {
   const history = agent.history.filter((m) => !m.transient && !isLegacyTransient(m))
   const data = {
@@ -158,22 +167,45 @@ export function saveSession(agent, display) {
   writeSessionFile(sessionPath(agent.cwd), data)
 }
 
+/** Load session data from disk; returns null if missing, corrupted, or version mismatch */
 export function loadSession(cwd) {
-  try {
-    const p = sessionPath(cwd)
-    if (!existsSync(p)) return null
-    const data = JSON.parse(readFileSync(p, "utf8"))
-    if (data?.version !== 1 && data?.version !== 2) return null
-    if (!Array.isArray(data.history)) return null
-    if (data.cwd && data.cwd.toLowerCase() !== cwd.toLowerCase()) return null
-    data.history = data.history.filter((m) => !isLegacyTransient(m))
-    data.display = Array.isArray(data.display)
-      ? data.display.filter((l) => l && typeof l.text === "string").map((l) => ({ text: l.text, color: l.color }))
-      : []
-    return data
-  } catch { return null }
+  const tryLoad = (p) => {
+    try {
+      if (!existsSync(p)) return null
+      const data = JSON.parse(readFileSync(p, "utf8"))
+      if (data?.version !== 1 && data?.version !== 2) return null
+      if (!Array.isArray(data.history)) return null
+      if (data.cwd && data.cwd.toLowerCase() !== cwd.toLowerCase()) return null
+      data.history = data.history.filter((m) => !isLegacyTransient(m))
+      data.display = Array.isArray(data.display)
+        ? data.display.filter((l) => l && typeof l.text === "string").map((l) => ({ text: l.text, color: l.color }))
+        : []
+      data._recovered = false
+      return data
+    } catch (e) {
+      return { _error: e }
+    }
+  }
+  const p = sessionPath(cwd)
+  let result = tryLoad(p)
+  if (result?._error) {
+    // Main file corrupted — try the .tmp fallback from a failed atomic write
+    console.error(`[session] failed to load ${p}: ${result._error.message}. Trying .tmp fallback...`)
+    const tmpResult = tryLoad(`${p}.tmp`)
+    if (tmpResult && !tmpResult._error) {
+      console.error(`[session] recovered from .tmp fallback`)
+      result = tmpResult
+      result._recovered = true
+    } else {
+      console.error(`[session] .tmp fallback also failed — session lost. Backing up corrupted file as .corrupted.`)
+      try { renameSync(p, `${p}.corrupted`) } catch {}
+      return null
+    }
+  }
+  return result && !result._error ? result : null
 }
 
+/** Apply loaded session data onto an agent object; returns true if provider was switched */
 export function applySession(agent, data) {
   agent.history = data.history
   agent.tasks = data.tasks ?? []
@@ -182,7 +214,7 @@ export function applySession(agent, data) {
   agent.goal = data.goal ?? null
   agent._pendingReminders = data.pendingReminders ?? []
   agent._sessionStart = data.sessionStart ?? null
-  // 重置轮次计数器：切换会话后不应继承旧会话的停滞/压缩状态
+  // Reset turn counters: after switching sessions, should not inherit old session's stall/compaction state
   agent._turnsSinceTaskUpdate = 0
   agent._turnsInPlanMode = 0
   agent._compressFailures = 0
@@ -199,12 +231,13 @@ export function applySession(agent, data) {
   return false
 }
 
+/** Archive current session and reset the session file to empty state */
 export function clearSession(cwd) {
   try {
     archiveCurrent(cwd)
     const p = sessionPath(cwd)
     writeSessionFile(p, { version: 2, cwd, history: [], tasks: [], display: [], goal: null, autoApprove: false, pendingReminders: [], sessionStart: null })
   } catch {
-    // 清不掉就算了，下次保存会覆盖
+    // Can't clear, oh well — next save will overwrite
   }
 }

package/src/skills.mjs

@@ -1,17 +1,17 @@
 /**
- * skills.mjs — 技能系统
- * 从 .thincoder/skills/ 目录发现 .md 技能文件，
- * 注入到 system prompt 供 agent 按需加载。
- * 用 skill 工具激活指定技能，内容以 <skill-loaded> 包裹写入对话历史。
+ * skills.mjs — skill system
+ * Discovers .md skill files from .thincoder/skills/ directory,
+ * injects into system prompt for agent to load on demand.
+ * Use the skill tool to activate a specific skill; content is written into conversation history wrapped in <skill-loaded>.
  */
 
 import { readFile, readdir, stat } from "node:fs/promises"
 import { join } from "node:path"
 
 /**
- * 扫描 .thincoder/skills/ 目录，返回技能列表。
- * 每个技能：{ name, path, description } — name 取文件名（去扩展名）。
- * 目录不存在或无文件返回空数组。
+ * Scan .thincoder/skills/ directory, return skill list.
+ * Each skill: { name, path, description } — name is the filename (without extension).
+ * Returns empty array if directory is missing or empty.
  */
 export async function loadSkills(cwd) {
   const dir = join(cwd, ".thincoder", "skills")
@@ -23,13 +23,13 @@ export async function loadSkills(cwd) {
   }
   const skills = []
   for (const name of entries) {
-    if (!/^[a-zA-Z0-9_-]+\.md$/.test(name)) continue // 与 readSkill 的名字校验一致，防"列得出、读不了"
+    if (!/^[a-zA-Z0-9_-]+\.md$/.test(name)) continue // must match readSkill's name validation; prevents "listed but unreadable"
     const p = join(dir, name)
     try {
       const s = await stat(p)
       if (!s.isFile()) continue
-      // 提取描述（前 400 字符里第一段非空、非标题行）；文件带 frontmatter 时整块跳过，
-      // 否则会把 frontmatter 字段行（如 "name: x"）误当描述
+      // Extract description (first non-empty, non-heading line in first 400 chars);
+      // skip entire frontmatter block, otherwise frontmatter fields (e.g. "name: x") get mistaken for description
       const head = await readFile(p, "utf8")
       const body = head.slice(0, 400).split("\n")
       let desc = ""
@@ -45,16 +45,16 @@ export async function loadSkills(cwd) {
       }
       skills.push({ name: name.replace(/\.md$/, ""), path: p, description: desc || "(no description)" })
     } catch {
-      // 读失败跳过
+      // Read failure — skip
     }
   }
   return skills
 }
 
 /**
- * 生成技能列表文本，注入 system prompt。
- * 最多 3 个（占位少），超过则标 "... and N more"。
- * 以 DISREGARD 开头：清单刷新（技能增删）后旧清单自动作废，无需删历史（借鉴 kimi-code）。
+ * Generate skill listing text for system prompt injection.
+ * At most 3 (small footprint); overflow marked "... and N more".
+ * Prefixed with DISREGARD: when listing refreshes (skills added/removed), old listings are auto-invalidated without needing to delete history (inspired by kimi-code).
  */
 export function formatSkillListing(skills) {
   if (skills.length === 0) return ""
@@ -65,11 +65,11 @@ export function formatSkillListing(skills) {
 }
 
 /**
- * 读取指定技能文件的完整内容。
- * 返回文本，找不到返回 null。
+ * Read the full content of a specific skill file.
+ * Returns text, or null if not found.
  */
 export async function readSkill(cwd, name) {
-  // 安全检查：技能名只能是字母数字 + 连字符/下划线
+  // Safety check: skill name must be alphanumeric + hyphens/underscores only
   if (!/^[a-zA-Z0-9_-]+$/.test(name)) return null
   const p = join(cwd, ".thincoder", "skills", `${name}.md`)
   try {

package/src/tools/checkpoint.md

@@ -1,11 +1,15 @@
 List, create, and restore workspace snapshots (checkpoints). Git repositories only.
 
 Parameters:
-- action (required): "list" | "create" | "rewind"
-- id: snapshot id (required for rewind)
+- action (required): "list" | "create" | "rewind" | "cat"
+- id: snapshot id (required for rewind and cat; optional for list — when given, shows the file tree inside that snapshot)
+- path: for rewind — restore only this single file; for cat — read this file's content from the snapshot
 
 Notes:
 - A checkpoint is AUTO-CREATED before every user task. If uncommitted work was destroyed (by you, a git command, or a failed refactor), use action=list then action=rewind with the latest id to recover it
 - A checkpoint captures all uncommitted state: tracked-file changes (as a diff) plus copies of untracked files
 - Rewind first snapshots the current state, so rewinding is itself reversible
+- Rewind AUTO-RECOVERS: if git apply fails (corrupt patch), the pre-rewind state is restored — never lose data
 - Create one manually before risky bulk operations
+- list now shows which files changed (tracked + untracked); use path to recover individual files selectively
+- cat reads a file's content from a snapshot without touching the worktree — useful for inspecting before rewinding

package/src/tools/file.mjs

@@ -13,6 +13,9 @@ import { writeFile } from "node:fs/promises";
 import { 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
+
 export const readTool = {
   name: "read",
   description: DESC("read"),
@@ -28,9 +31,9 @@ export const readTool = {
   readonly: true,
   async execute(args, ctx) {
     const abs = resolveInCwd(ctx, args.path)
-    // 大文件保护：先查大小，超 10MB 拒绝整文件读入（offset/limit 只影响返回切片，不影响缓冲）
+    // 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 > 10_000_000) 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.`)
+    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 = await readFile(abs, "utf8")
     const lines = content.split("\n")
     const offset = Math.max(1, args.offset ?? 1)
@@ -57,15 +60,16 @@ export const readImageTool = {
     required: ["path"],
   },
   readonly: true,
-  /** 返回 JSON：{ text, images }，供 agent 层转为多模态 user 消息 */
+  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()
     const mime = IMAGE_EXTENSIONS[ext]
     if (!mime) throw new Error(`Unsupported image format: .${ext}. Supported: ${Object.keys(IMAGE_EXTENSIONS).join(", ")}`)
-    // 先查大小再读入——防超大图片撑爆内存（20MB base64 ≈ 15MB 原始）
+    // 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 > 15_000_000) throw new Error(`Image too large: ${Math.round(imgStat.size / 1_000_000)}MB (max 15MB)`)
+    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
@@ -73,10 +77,10 @@ export const readImageTool = {
       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 { /* 删不掉就算了 */ }
+      try { await unlink(abs) } catch { /* can't delete, so be it */ }
     }
     return result
   },
@@ -103,7 +107,7 @@ export const writeTool = {
     if (st?.isDirectory()) throw new Error(`Path is a directory: ${args.path}`)
     await writeFile(abs, args.content, "utf8")
     const diff = gitDiffOne(ctx.cwd, abs)
-    return `Wrote ${args.content.length} chars to ${args.path}${diff ? "\n" + diff : ""}${autoSyntaxCheck(abs)}`
+    return `Wrote ${args.content.length} chars to ${args.path}${diff ? "\n" + diff : ""}${await autoSyntaxCheck(abs)}`
   },
 }
 
@@ -131,7 +135,7 @@ export const editTool = {
     const content = await readFile(abs, "utf8")
     const occurrences = content.split(args.old_string).length - 1
     if (occurrences === 0) {
-      // 给出线索帮模型定位：首行预览 + 常见原因
+      // Give clues to help the model locate: first-line preview + common causes
       const preview = args.old_string.slice(0, 100).split("\n")[0]
       throw new Error(
         `old_string not found in ${args.path}\n` +
@@ -144,11 +148,11 @@ export const editTool = {
     }
     const updated = args.replace_all
       ? content.split(args.old_string).join(args.new_string)
-      // 函数式替换：避免 new_string 里的 $ 替换模式（匹配串/前后文引用）被展开
+      // Functional replacement: avoid $-substitution patterns in new_string (match string / backreference) being expanded
       : content.replace(args.old_string, () => args.new_string)
     await writeFile(abs, updated, "utf8")
     const diff = gitDiffOne(ctx.cwd, abs)
-    return `Edited ${args.path}: replaced ${args.replace_all ? occurrences : 1} occurrence(s)${diff ? "\n" + diff : ""}${autoSyntaxCheck(abs)}`
+    return `Edited ${args.path}: replaced ${args.replace_all ? occurrences : 1} occurrence(s)${diff ? "\n" + diff : ""}${await autoSyntaxCheck(abs)}`
   },
 }
 
@@ -199,7 +203,7 @@ export const insertAfterTool = {
     const updated = lines.join("\n")
     await writeFile(abs, updated, "utf8")
     const diff = gitDiffOne(ctx.cwd, abs)
-    return `Inserted after line ${targetLine} in ${args.path}${diff ? "\n" + diff : ""}${autoSyntaxCheck(abs)}`
+    return `Inserted after line ${targetLine} in ${args.path}${diff ? "\n" + diff : ""}${await autoSyntaxCheck(abs)}`
   },
 }