thincoder 0.8.2 → 0.8.3

package/README.md

@@ -12,7 +12,8 @@ Design philosophy (the entire meaning of the name): if the Node standard library
 
 ## Features
 
-- **Agent loop**: LLM ↔ tool-call loop, 100-turn cap against runaway, completion guard blocks unverified changes
+- **Fix-verify loop**: file changes without `verify` get pushed back — syntax check + tests must pass before the agent can claim completion (auto-repair up to 3 rounds)
+- **Checkpoint system**: auto-snapshot before every user task, `list`/`create`/`rewind` tools for the model, single-file restore — rewinding itself is reversible (pre-rewind state auto-saved)
 - **Codebase understanding** ⭐0.5.0: `repo_outline` (dependency outline, auto-injected at startup), `code_search` (source FTS5 + vectors + JSDoc extraction), `doc_search` (docs chunked by ## headings) — background indexing, auto-incremental updates on file writes, three tools guided by "structure → intent → details"
 - **Model adaptation** ⭐: top-tier only, latest only. Built-in flagship models from five leading Chinese vendors — DeepSeek / Kimi / GLM / Qwen / MiniMax. No legacy model compatibility, no local model support. Auto-matched context windows, truncation-resume protocols (prefix/partial), thinking-mode APIs (thinking.type / reasoning_effort), reasoning_content echo strategies (reasoningEcho), output limits, temperature range clamping — all five deeply adapted.
 - **Toolset**: `read` / `write` / `edit` / `bash` / `glob` (supports `**`) / `grep` / `websearch` / `ls` / `fetch` + `read_image` (image/video paste) + three retrieval tools + MCP — all zero-dependency, file tools confined to the working directory

package/bin/thincoder.mjs

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
 
 /**
- * thincoder — 命令入口
- *   thincoder                 启动 TUI
- *   thincoder chat "..."      一次性 agent 问答（可调用工具，流式输出）
- *   thincoder memory <sub>    记忆管理：list / search / put / remove
- *   thincoder upgrade         从 npm 升级到最新版
- *   thincoder -v              显示版本号
- *   thincoder --help          显示帮助
+ * thincoder — CLI entry point
+ *   thincoder                 Launch the interactive TUI
+ *   thincoder chat "..."      One-shot agent run (tools enabled, streamed)
+ *   thincoder memory <sub>    Memory management: list / search / put / remove
+ *   thincoder upgrade         Update to the latest version from npm
+ *   thincoder -v              Print version
+ *   thincoder --help          Print help
  */
 
 import { readFileSync } from "node:fs"
@@ -15,7 +15,7 @@ import { join } from "node:path"
 import { runAgent } from "../src/agent.mjs"
 import { loadConfig, configPath } from "../src/config.mjs"
 import { createMemory, syncDir } from "../src/memory.mjs"
-import { makeAgent, teamConfig, gitAuthor } from "../src/cli/make-agent.mjs"
+import { assembleAgent, teamConfig, gitAuthor } from "../src/cli/make-agent.mjs"
 import { memoryCommand } from "../src/cli/memory-command.mjs"
 import { setupWizard } from "../src/cli/setup-wizard.mjs"
 import { summarize, askPermission } from "../src/cli/permission.mjs"
@@ -24,7 +24,7 @@ import { distillCommand } from "../src/cli/distill-command.mjs"
 const [command, ...args] = process.argv.slice(2)
 const VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version
 
-// 顶层兜底：任何未捕获错误打印一行消息干净退出，不糊用户一脸 stack
+// Top-level safety net: print one-line error and exit cleanly, no stack traces to the user
 process.on("uncaughtException", (error) => {
   console.error(`[error] ${error.message}`)
   exitSoon(1)
@@ -38,7 +38,7 @@ const USAGE = `thincoder - thin coding agent
 
 Usage:
   thincoder                 Launch the interactive TUI
-  thincoder chat <prompt>   One-shot agent run (tools enabled), streams reply to stdout
+  thincoder chat [--auto] <prompt>   One-shot agent run (tools enabled), streams reply to stdout; --auto approves all tool calls
   thincoder memory list [--type=<t>]           List memory entries
   thincoder memory search <query>              Search memory
   thincoder memory put --type=<t> --title=<t> --content=<c> [--tags=<t>]
@@ -51,21 +51,21 @@ Usage:
   thincoder upgrade         Update to the latest version from npm
   thincoder -v, --version   Print version
 
-Config: ~/.thincoder/config.json (providers[] + activeProvider；TUI 内用 /provider、/model 管理)
+Config: ~/.thincoder/config.json (providers[] + activeProvider; manage via /provider, /model in TUI)
 Env:    THINCODER_API_KEY, THINCODER_BASE_URL, THINCODER_MODEL, THINCODER_ACTIVE_PROVIDER
 `
 
-/** 缺 key 时的统一提示 */
+/** Unified message when no API key is configured */
 function noKeyMessage() {
-  return `还没有配置 API key。运行 thincoder 进入 TUI，用 /provider add 和 /provider key 配置；或直接编辑 ${configPath}`
+  return `No API key configured yet. Run "thincoder" to enter TUI, use /provider add and /provider key; or edit ${configPath} directly`
 }
 
-/** 延迟退出：fetch 后立刻 process.exit 在 Windows/Node 24 会触发 libuv 断言，让一句柄关完再走 */
+/** Delay exit: process.exit right after fetch triggers libuv assertion on Windows/Node 24; let handles drain first */
 function exitSoon(code) {
   setTimeout(() => process.exit(code), 100)
 }
 
-/** 语义化版本比较：a<b 返回 -1，相等 0，a>b 返回 1；非数字段按字符串比 */
+/** Semantic version comparison: a<b returns -1, equal 0, a>b returns 1; non-numeric segments compare as strings */
 function compareVersions(a, b) {
   const pa = String(a).split("."), pb = String(b).split(".")
   for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
@@ -90,7 +90,7 @@ switch (command) {
       break
     }
 
-    const agent = await makeAgent()
+    const agent = await assembleAgent()
     if (!agent.provider.apiKey) {
       if (!process.stdin.isTTY) {
         console.error(noKeyMessage())
@@ -104,7 +104,7 @@ switch (command) {
       }
       agent.provider = p
       agent.activeProvider = p.name
-      // 向导可能配了 embedding key：挂上向量检索
+      // Wizard may have configured an embedding key: attach vector search
       const fresh = loadConfig()
       if (fresh.embedding?.apiKey && agent.memory && !agent.memory.embedder) {
         const { createEmbedder } = await import("../src/embedding.mjs")
@@ -112,13 +112,13 @@ switch (command) {
       }
     }
     if (auto) agent.autoApprove = true
-    // 累计 token 用量，结束时输出到 stderr（不污染 stdout 管道）
+    // Accumulate token usage, output to stderr at the end (don't pollute stdout pipe)
     const usageTotal = { prompt: 0, completion: 0, cacheHit: 0, cacheMiss: 0 }
     try {
       await runAgent(agent, prompt, {
         onToken: (text) => process.stdout.write(text),
         onWait: ({ phase, seconds }) => {
-          console.error(phase === "gate" ? `[rate-limit] TPM 节流等待 ~${seconds}s` : `[rate-limit] 429，${seconds}s 后重试`)
+          console.error(phase === "gate" ? `[rate-limit] TPM throttle waiting ~${seconds}s` : `[rate-limit] 429 response, retrying in ${seconds}s`)
         },
         onToolCall: (name, toolArgs) => {
           console.error(`\n[tool] ${name} ${summarize(toolArgs)}`)
@@ -128,7 +128,7 @@ switch (command) {
           console.error(`[done] ${name} -> ${preview.split("\n")[0]}`)
         },
         onToolOutput: (name, chunk) => process.stderr.write(chunk),
-        onCompress: () => console.error(`\n[context] 上下文过长，已自动压缩（早期对话由 LLM 摘要）`),
+        onCompress: () => console.error(`\n[context] Context too long, auto-compacted (early conversation summarized by LLM)`),
         onTaskUpdate: (items) => {
           const done = items.filter((i) => i.status === "done").length
           const current = items.find((i) => i.status === "in_progress")
@@ -230,7 +230,7 @@ switch (command) {
 
   case "tui":
   case undefined: {
-    const agent = await makeAgent()
+    const agent = await assembleAgent()
     const config = loadConfig()
     // 恢复上次的会话（同一项目目录）；provider 按保存的名字切回（用户上次可能换过模型）
     const { loadSession, applySession } = await import("../src/session.mjs")
@@ -275,16 +275,16 @@ switch (command) {
     try {
       remote = execSync("npm view thincoder version", { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim()
     } catch {
-      console.error("[upgrade] 无法查询 npm registry，请确认网络和 npm 已安装")
+      console.error("[upgrade] Unable to query npm registry — check your network connection and that npm is installed")
       exitSoon(1)
       break
     }
     if (compareVersions(local, remote) >= 0) {
-      console.log(`ThinCoder ${local} 已是最新。`)
+      console.log(`ThinCoder ${local} is already the latest.`)
     } else {
-      console.log(`升级: ${local} → ${remote}`)
+      console.log(`Upgrading: ${local} → ${remote}`)
       execSync("npm install -g thincoder@latest", { stdio: "inherit" })
-      console.log(`已升级到 ${remote}`)
+      console.log(`Upgraded to ${remote}`)
     }
     break
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thincoder",
-  "version": "0.8.2",
+  "version": "0.8.3",
   "description": "Thin coding agent - zero dependencies, no build step, Node.js native. Sharp code, zero bloat.",
   "keywords": [
     "ai",

package/src/agent/dispatch.mjs

@@ -1,17 +1,17 @@
 /**
- * agent/dispatch.mjs — 工具调用两段式执行
+ * agent/dispatch.mjs — two-phase tool call execution
  */
 import { offloadToolResult } from "./helpers.mjs"
 
 /**
- * 两段式执行：
- * 阶段一（串行）：逐个解析参数 + planMode 检查 + 权限确认（有副作用工具）
- * 阶段二（保序执行）：严格按模型调用顺序——连续的只读/parallel 工具并发成组，
- * 有副作用工具在原位置逐个串行（写后读同一文件的一批调用，读必须看到写后的内容）。
- * 返回按调用顺序排列的结果数组（每项含 ok 标记执行成败）。
+ * Two-phase execution:
+ * Phase 1 (serial): parse args one by one + planMode check + permission confirmation (side-effecting tools)
+ * Phase 2 (order-preserving): strictly preserve model call order — consecutive readonly/parallel tools run as concurrent batches,
+ * side-effecting tools run serially in their original position (if a batch writes-then-reads the same file, the read must see the post-write content).
+ * Returns a results array in call order (each entry has an ok flag indicating success/failure).
  */
 export async function executeToolCalls(agent, toolByName, toolCalls, callbacks, depth = 0, signal) {
-  // ---- 阶段一：串行准备 ----
+  // ---- Phase 1: serial preparation ----
   const prepared = []
   for (const toolCall of toolCalls) {
     const tool = toolByName.get(toolCall.name)
@@ -34,7 +34,7 @@ export async function executeToolCalls(agent, toolByName, toolCalls, callbacks,
     }
 
     if (!tool.readonly) {
-      // autoApprove 短路：agent 已标记自动批准时不再询问
+      // autoApprove short-circuit: skip prompt when agent is already marked for auto-approval
       const allowed = agent.autoApprove
         ? true
         : callbacks.onPermissionRequest
@@ -50,17 +50,20 @@ export async function executeToolCalls(agent, toolByName, toolCalls, callbacks,
     prepared.push({ toolCall, tool, args })
   }
 
-  // ---- 阶段二：保序执行 ----
+  // ---- Phase 2: order-preserving execution ----
   const runOne = async (item) => {
     if (item.error) return { ...item, result: `Error: ${item.error}`, ok: false }
     if (item.denied) {
       const reason = item.reason === "plan mode"
         ? "Error: plan mode is active — only read-only tools are allowed. Exit plan mode first."
-        : "Error: permission denied by user"
+        : item.reason === "denied by user"
+          ? "Error: permission denied by user"
+          : "Error: no permission handler configured — this tool requires user approval but the current context doesn't support interaction (e.g. subagent or non-TUI mode)"
       return { ...item, result: reason, ok: false }
     }
     try {
-      const raw = String(await item.tool.execute(item.args, {
+      if (item.tool.outputPanel) callbacks.setupOutputPanel?.(item.toolCall.name)
+      const rawResult = await item.tool.execute(item.args, {
         cwd: agent.cwd,
         agent,
         depth,
@@ -69,7 +72,9 @@ export async function executeToolCalls(agent, toolByName, toolCalls, callbacks,
         onOutput: (chunk) => callbacks.onToolOutput?.(item.toolCall.name, chunk),
         onQuestion: callbacks.onQuestion,
         onPermissionRequest: callbacks.onPermissionRequest,
-      }))
+      })
+      if (rawResult === undefined) throw new Error(`Tool "${item.toolCall.name}" returned undefined — all tools must return a string value`)
+      const raw = String(rawResult)
       const result = item.toolCall.name === "read_image" ? raw : await offloadToolResult(raw, item.toolCall.id)
       callbacks.onToolResult?.(item.toolCall.name, result)
       return { ...item, result, ok: true }

package/src/agent/helpers.mjs

@@ -1,5 +1,5 @@
 /**
- * agent/helpers.mjs — Agent 工具函数与常量
+ * agent/helpers.mjs — Agent utility functions and constants
  */
 import { configDir } from "../config.mjs"
 import { readFileSync, readdirSync } from "node:fs"
@@ -8,7 +8,7 @@ import { join } from "node:path"
 import { execSync } from "node:child_process"
 
 export const DEFAULT_MAX_TURNS = 100
-export const DEFAULT_SUBAGENT_TURNS = 20
+export const DEFAULT_SUBAGENT_TURNS = 100
 export const DEFAULT_GOAL_TURNS = 200
 export const MIN_REPORT_CHARS = 200
 export const REPORT_CONTINUATION =
@@ -18,17 +18,23 @@ export const REPORT_CONTINUATION =
 const TOOL_RESULT_OFFLOAD_LIMIT = 16_000
 const TOOL_RESULT_PREVIEW = 2_000
 
+const GIT_TIMEOUT_MS = 5000
+const MAX_GIT_CHANGES_DISPLAY = 20
+
 export const OUTLINE_INJECT_PREFIX = "[System reminder: project dependency outline:"
 export const FILE_MUTATORS = new Set(["write", "edit", "insert_after", "apply_patch", "delete"])
 
+/** Escape XML special characters in a string for safe embedding in XML/HTML */
 export function escapeXml(s) {
   return String(s).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;")
 }
 
+/** Canonicalize a tool call signature for stall detection: name + stable JSON args */
 export function tryCanonicalize(name, args) {
   try { return name + ":" + JSON.stringify(JSON.parse(args)) } catch { return name + ":" + args }
 }
 
+/** Offload oversized tool results (>16k chars) to disk, returning a preview + file path */
 export async function offloadToolResult(text, callId) {
   if (text.length <= TOOL_RESULT_OFFLOAD_LIMIT) return text
   try {
@@ -46,9 +52,10 @@ export async function offloadToolResult(text, callId) {
   }
 }
 
+/** Collect git branch, recent commits, and working tree status as context text */
 export function collectGitContext(cwd) {
   try {
-    const opts = { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 5000 }
+    const opts = { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: GIT_TIMEOUT_MS }
     const branch = execSync("git branch --show-current", opts).trim()
     const log = execSync("git --no-pager log --oneline -5", opts).trim()
     const status = execSync("git status --short", opts).trim()
@@ -56,7 +63,7 @@ export function collectGitContext(cwd) {
     return [
       `Git context: on branch \`${branch || "(detached)"}\`${dirty ? `, ${dirty} uncommitted change(s)` : ", working tree clean"}.`,
       log ? `Recent commits:\n${log}` : "",
-      status ? `Uncommitted:\n${status.split("\n").slice(0, 20).join("\n")}${dirty > 20 ? `\n… (${dirty - 20} more)` : ""}` : "",
+      status ? `Uncommitted:\n${status.split("\n").slice(0, MAX_GIT_CHANGES_DISPLAY).join("\n")}${dirty > MAX_GIT_CHANGES_DISPLAY ? `\n… (${dirty - MAX_GIT_CHANGES_DISPLAY} more)` : ""}` : "",
     ].filter(Boolean).join("\n")
   } catch {
     return ""
@@ -71,18 +78,19 @@ export class ContinueError extends Error {
   }
 }
 
+/** Repair malformed conversation history: remove orphan tool messages and fill missing tool results */
 export function repairHistory(history) {
   const out = []
   let dirty = false
-  const knownIds = new Set() // 迄今 assistant 声明过的 tool_call id
+  const knownIds = new Set() // tool_call ids declared by assistant so far
   for (let i = 0; i < history.length; i++) {
     const m = history[i]
-    // 空 assistant 消息：无正文且无 tool_calls，丢弃
+    // empty assistant message: no content and no tool_calls, discard
     if (m.role === "assistant" && !m.tool_calls?.length && !m.content) {
       dirty = true
       continue
     }
-    // 孤儿 tool 消息：没有对应的 assistant tool_calls 声明，丢弃
+    // orphan tool message: no matching assistant tool_calls declaration, discard
     if (m.role === "tool" && !knownIds.has(m.tool_call_id)) {
       dirty = true
       continue
@@ -91,7 +99,7 @@ export function repairHistory(history) {
     if (m.role !== "assistant" || !m.tool_calls?.length) continue
 
     for (const tc of m.tool_calls) knownIds.add(tc.id)
-    // 收集紧随其后（下一个非 tool 消息之前）的 tool 结果 id
+    // collect tool result ids that immediately follow (before the next non-tool message)
     const answered = new Set()
     let j = i + 1
     while (j < history.length && history[j].role === "tool") {
@@ -99,11 +107,11 @@ export function repairHistory(history) {
         answered.add(history[j].tool_call_id)
         out.push(history[j])
       } else {
-        dirty = true // 孤儿 tool 结果，丢弃
+        dirty = true // orphan tool result, discard
       }
       j++
     }
-    i = j - 1 // 外层 for 会再 +1
+    i = j - 1 // outer for will increment again
 
     for (const tc of m.tool_calls) {
       if (!answered.has(tc.id)) {
@@ -119,6 +127,7 @@ export function repairHistory(history) {
   return dirty ? out : history
 }
 
+/** List working directory contents as a tree (directories expanded up to subMax entries each) */
 export function listWorkDir(cwd, { rootMax = 30, subMax = 10 } = {}) {
   const SKIP = new Set([".git", "node_modules"])
   let entries
@@ -158,12 +167,14 @@ export function listWorkDir(cwd, { rootMax = 30, subMax = 10 } = {}) {
   return lines.join("\n")
 }
 
+/** Return the set of tool names that are marked as read-only */
 export function readonlyToolNames(tools) {
   return new Set(tools.filter((t) => t.readonly).map((t) => t.name))
 }
 
 const MAX_INSTRUCTION_CHARS = 32_000
 
+/** Load AGENTS.md / project_rules.md from the project root, return as project instructions */
 export async function loadProjectInstructions(cwd) {
   const parts = []
   for (const name of ["AGENTS.md", "project_rules.md"]) {
@@ -172,7 +183,7 @@ export async function loadProjectInstructions(cwd) {
       if (!content) continue
       const key = name.toLowerCase()
       parts.push(`<!-- From: ${join(cwd, name)} -->\n${content}`)
-    } catch { /* 文件不存在 */ }
+    } catch { /* file does not exist */ }
   }
   const merged = parts.join("\n\n")
   if (!merged) return ""

package/src/agent/setup.mjs

@@ -1,5 +1,5 @@
 /**
- * agent/setup.mjs — runAgent 的前置准备：上下文注入、system prompt 构建、工具注入
+ * agent/setup.mjs — runAgent pre-flight setup: context injection, system prompt construction, tool injection
  */
 import { compressIfNeeded, compressFallback, COMPRESS_FAILURE_LIMIT } from "../context.mjs"
 import { search as memorySearch, docSearch } from "../memory.mjs"
@@ -14,26 +14,41 @@ import {
 } from "./helpers.mjs"
 
 const AUTO_REMINDER = "[System reminder: AUTO mode is active — all tool calls are automatically approved without asking.]"
+const DEFAULT_COMPACT_THRESHOLD = 100_000
+const DOC_SEARCH_LIMIT = 5
+const DOC_CHUNK_PREVIEW_LEN = 300
+const MEMORY_SEARCH_LIMIT = 3
 
 /**
- * 准备一次 agent run：注入上下文、构建 system prompt、注入工具。
- * 返回主循环需要的所有状态，同时把初始化消息写入 agent.history。
+ * Prepare an agent run: inject context, build system prompt, inject tools.
+ * Returns all state needed by the main loop, and writes initialization messages into agent.history.
  */
 export async function prepareRun(agent, input, callbacks, {
   depth = 0, signal, overrideTurns, resume, systemPrompt: corePrompt, disciplineRules, mainOverlay,
 } = {}) {
   const maxTurns = overrideTurns ?? agent.config?.agent?.maxTurns ?? DEFAULT_MAX_TURNS
-  const threshold = agent.config?.agent?.compactThreshold ?? 100_000
+  const threshold = agent.config?.agent?.compactThreshold ?? DEFAULT_COMPACT_THRESHOLD
 
   agent._lastPromptTokens = null
   agent._usageAtLen = null
   agent.history = repairHistory(agent.history)
 
   if (!resume) {
+      // Git context: branch, recent commits, uncommitted changes
+      if (depth === 0) {
+        const gitCtx = collectGitContext(agent.cwd)
+        if (gitCtx) {
+          agent.history.push({
+            role: "user",
+            content: `[System reminder: git context:\n${escapeXml(gitCtx)}]`,
+            transient: true,
+          })
+        }
+      }
     if (depth === 0) {
       const tree = listWorkDir(agent.cwd)
       if (tree) {
-        agent.history.push({ role: "user", content: `[System reminder: working directory snapshot:\n<untrusted_cwd_listing>\n${escapeXml(tree)}\n</untrusted_cwd_listing>]`, transient: true })
+        agent.history.push({ role: "user", content: `[System reminder: working directory snapshot (${new Date().toISOString()}):\n<untrusted_cwd_listing>\n${escapeXml(tree)}\n</untrusted_cwd_listing>]`, transient: true })
       }
       if (agent.memory && !agent.history.some((m) => typeof m.content === "string" && m.content.startsWith(OUTLINE_INJECT_PREFIX))) {
         try {
@@ -42,11 +57,11 @@ export async function prepareRun(agent, input, callbacks, {
           if (summary && !summary.startsWith("(no indexed")) {
             agent.history.push({ role: "user", content: `${OUTLINE_INJECT_PREFIX}\n${summary}]`, transient: true })
           }
-        } catch { /* 索引未就绪不报错 */ }
+        } catch { /* index not ready — suppress error */ }
       }
     }
     if (agent.memory) {
-      const docs = await docSearch(agent.memory, input, { limit: 5 })
+      const docs = await docSearch(agent.memory, input, { limit: DOC_SEARCH_LIMIT })
       if (docs.length > 0) {
         const count = agent.memory.db.prepare(`SELECT COUNT(*) AS n FROM doc_chunks`).get()?.n ?? 0
         const more = count > docs.length ? ` (${count} chunks indexed total — call doc_search if you need more)` : ""
@@ -54,12 +69,12 @@ export async function prepareRun(agent, input, callbacks, {
           role: "user",
           content:
             `[Relevant documentation${more}:\n` +
-            docs.map((d) => `- ${d.path}${d.heading ? " > " + d.heading : ""}: <untrusted_doc_chunk>${escapeXml(d.content.slice(0, 300))}</untrusted_doc_chunk>`).join("\n") +
+            docs.map((d) => `- ${d.path}${d.heading ? " > " + d.heading : ""}: <untrusted_doc_chunk>${escapeXml(d.content.slice(0, DOC_CHUNK_PREVIEW_LEN))}</untrusted_doc_chunk>`).join("\n") +
             "]",
           transient: true,
         })
       }
-      const memories = await memorySearch(agent.memory, input, { limit: 3 })
+      const memories = await memorySearch(agent.memory, input, { limit: MEMORY_SEARCH_LIMIT })
       if (memories.length > 0) {
         agent.history.push({
           role: "user",
@@ -71,6 +86,13 @@ export async function prepareRun(agent, input, callbacks, {
         })
       }
     }
+    if (depth === 0) {
+      agent.history.push({
+        role: "user",
+        content: `[System reminder: current time is ${new Date().toISOString()}.]`,
+        transient: true,
+      })
+    }
     agent.history.push({ role: "user", content: input })
   }
 
@@ -81,7 +103,7 @@ export async function prepareRun(agent, input, callbacks, {
     agent._pendingReminders = []
   }
 
-  // task/plan 工具随主循环注入；subagent/skill/goal/verify 只在顶层注入
+  // task/plan tools are injected with the main loop; subagent/skill/goal/verify only at top level
   const { planTool, subagentTool, taskTool, skillTool, goalTool, verifyTool, recentChangesTool } = await import("../agent-tools.mjs")
   const tools = [...agent.tools, taskTool, planTool, ...(depth === 0 ? [subagentTool, skillTool, goalTool, verifyTool, recentChangesTool] : [])]
   const toolSchemas = tools.map(toOpenAISchema)

package/src/agent-tools/goal.mjs

@@ -1,7 +1,8 @@
 /**
- * goal 工具：长程自主目标的生命周期管理（完成合约制）。
- * 三态：active / complete / blocked；完成要过 verify 证据门槛，
- * 阻塞要同一条件连续 3 次才受理；系统每轮注入状态 + 预算进度 + 审计纪律。
+ * goal tool: lifecycle management for long-running autonomous goals (completion contract).
+ * Three states: active / complete / blocked. Completion must pass a verify evidence threshold;
+ * blocked is only accepted after the same condition persists 3 consecutive times.
+ * The system injects status + budget progress + audit discipline every turn.
  */
 export const goalTool = {
   name: "goal",
@@ -39,7 +40,7 @@ export const goalTool = {
         setAt: Date.now(),
         status: "active",
         turnsUsed: 0,
-        _blockTally: null, // { reason, count } — 同一阻塞条件的连续次数（blocked 审计用）
+        _blockTally: null, // { reason, count } — consecutive count of the same blocking condition (for blocked audit)
       }
       return `Goal set: ${agent.goal.objective}\nDone when: ${agent.goal.criteria}\nThe system will inject goal status every turn. Completion and blocked claims are audited — see the reminders.`
     }
@@ -47,7 +48,7 @@ export const goalTool = {
       return `Error: no active goal to '${args.action}' (current: ${agent.goal?.status ?? "none"}). Set one first.`
     }
     if (args.action === "complete") {
-      // 证据链门槛：本轮改过文件却没跑过 verify，不许宣布完成（对齐完成守卫）
+      // Evidence chain threshold: files were mutated this run without verify — refuse completion (aligns with completion guard)
       if (agent._mutatedThisRun && !agent._verifiedThisRun) {
         return "Error: files were modified but verify has not run. Run the check your criteria names AND the verify tool before marking the goal complete — false completion is the worst outcome of autonomous work."
       }
@@ -56,7 +57,7 @@ export const goalTool = {
     }
     if (args.action === "blocked") {
       if (!args.reason) return "Error: 'reason' required for 'blocked' action."
-      // 阻塞审计：同一条件须连续出现 3 次（换过方法仍被同一条件挡住才算真阻塞）
+      // Blocked audit: same condition must appear 3 consecutive times (only counts as real blocking if different approaches still hit the same wall)
       const tally = agent.goal._blockTally
       const count = tally?.reason === args.reason ? tally.count + 1 : 1
       agent.goal._blockTally = { reason: args.reason, count }

package/src/agent-tools/plan.mjs

@@ -1,7 +1,7 @@
 /**
- * plan 工具：进入/退出规划模式。
- * 规划模式下只允许只读工具——探索代码、设计方案，不写代码。
- * 用户确认方案后退出规划模式开始实现。
+ * plan tool: enter/exit plan mode.
+ * In plan mode only read-only tools are allowed — explore code, design solutions, no code writing.
+ * After the user approves the plan, exit plan mode and start implementing.
  */
 export const planTool = {
   name: "plan",

package/src/agent-tools/recent-changes.mjs

@@ -1,7 +1,7 @@
 /**
- * recent_changes 工具：列出本轮 agent 触碰过的文件（write/edit/insert_after/delete）。
- * 比 git status 更精确——只看本会话的变更，不关心 git 追踪状态。
- * 帮助模型在长任务中回顾自己改了什么。
+ * recent_changes tool: list files touched by this agent run (write/edit/insert_after/delete).
+ * More precise than git status — only looks at this session's changes, independent of git tracking.
+ * Helps the model recall what it already modified during long tasks.
  */
 export const recentChangesTool = {
   name: "recent_changes",

package/src/agent-tools/skill.mjs

@@ -2,9 +2,9 @@ import { loadSkills, formatSkillListing, readSkill } from "../skills.mjs"
 import { escapeXml } from "../agent.mjs"
 
 /**
- * skill 工具：按需加载项目技能文件（.thincoder/skills/*.md）。
- * 加载后技能内容以 <skill-loaded> 包裹写入对话，供后续参考。
- * 列出所有可用技能用 action="list"。
+ * skill tool: load project skill files on demand (.thincoder/skills/*.md).
+ * After loading, skill content is injected into the conversation wrapped in <skill-loaded> for subsequent reference.
+ * Use action="list" to see all available skills.
  */
 export const skillTool = {
   name: "skill",
@@ -26,8 +26,8 @@ export const skillTool = {
       return skills.map((s) => `- ${s.name}: ${s.description}`).join("\n")
     }
     if (!args.name) return "Error: skill name required for 'load' action."
-    // 去重：history 里已有同名 <skill-loaded> 块就直接遵循它，不重复展开（历史即账本；
-    // 被压缩掉后这里自然查不到，会重新加载——正确行为）
+    // Dedup: skip reloading if history already contains an <skill-loaded> block with the same name
+    // (history is the ledger; if it got compacted away we naturally won't find it here — correct behavior)
     if (ctx.agent.history?.some((m) => typeof m.content === "string" && m.content.includes(`<skill-loaded name="${args.name}"`))) {
       return `Skill "${args.name}" is already loaded in this conversation — follow the instructions in the existing <skill-loaded> block above. Do not reload it.`
     }
@@ -36,7 +36,7 @@ export const skillTool = {
       const available = skills.map((s) => s.name).join(", ")
       return `Error: skill "${args.name}" not found. Available: ${available || "(none)"}`
     }
-    // 注入 skill 内容到 history（下一条 user 消息）
+    // Inject skill content into history (will appear as the next user message)
     ctx.agent._pendingReminders = ctx.agent._pendingReminders ?? []
     ctx.agent._pendingReminders.push(
       `<skill-loaded name="${args.name}" source=".thincoder/skills/${args.name}.md">\n${escapeXml(content)}\n</skill-loaded>\n\nFollow the skill's instructions above for the current task.`