thincoder 0.8.1 → 0.8.3

package/src/cli/setup-wizard.mjs

@@ -2,9 +2,9 @@ import { existsSync, readFileSync } from "node:fs"
 import { createInterface } from "node:readline"
 import { configPath, saveConfig, PROVIDER_PRESETS } from "../config.mjs"
 
-/** 首次使用（TTY 下的 chat/distill）：问答式配置一个 provider 并落盘，返回运行时 provider；取消返回 null */
+/** First-time setup (TTY chat / distill): ask a few questions to configure a provider, save to disk, return runtime provider. Cancel returns null. */
 export async function setupWizard() {
-  // 自带缓冲的提问器：rl.question 在输入被管道/快速粘贴时会丢行（问题注册前 line 已到达）
+  // Buffered asker: rl.question loses lines when input is piped/fast-pasted (line arrives before question is registered)
   const rl = createInterface({ input: process.stdin, terminal: false })
   const buffered = []
   let waiter = null
@@ -25,17 +25,17 @@ export async function setupWizard() {
     })
   try {
     const presets = Object.entries(PROVIDER_PRESETS)
-    console.error("首次使用，先配置一个模型提供商：")
+    console.error("First time using ThinCoder — let's configure a model provider:")
     presets.forEach(([n, p], i) => console.error(`  ${i + 1}. ${n.padEnd(10)} ${p.desc}`))
-    console.error(`  ${presets.length + 1}. 自定义端点`)
-    const choice = Number((await ask(`选择 [1-${presets.length + 1}]: `)).trim())
+    console.error(`  ${presets.length + 1}. Custom endpoint`)
+    const choice = Number((await ask(`Pick [1-${presets.length + 1}]: `)).trim())
     let name, baseURL, model
     if (choice === presets.length + 1) {
-      name = (await ask("名称（如 my-openai）: ")).trim()
-      baseURL = (await ask("baseURL（如 https://api.openai.com/v1）: ")).trim().replace(/\/+$/, "")
-      model = (await ask("模型（如 gpt-4o）: ")).trim()
+      name = (await ask("Name (e.g. my-openai): ")).trim()
+      baseURL = (await ask("baseURL (e.g. https://api.openai.com/v1): ")).trim().replace(/\/+$/, "")
+      model = (await ask("Model (e.g. gpt-4o): ")).trim()
       if (!name || !/^https?:\/\//.test(baseURL) || !model) {
-        console.error("输入不完整或 baseURL 不合法，已取消")
+        console.error("Incomplete input or invalid baseURL — cancelled")
         return null
       }
     } else if (choice >= 1 && choice <= presets.length) {
@@ -43,15 +43,15 @@ export async function setupWizard() {
       baseURL = presets[choice - 1][1].baseURL
       model = presets[choice - 1][1].model
     } else {
-      console.error("无效选择，已取消")
+      console.error("Invalid choice — cancelled")
       return null
     }
-    const apiKey = (await ask(`${name} 的 API key: `)).trim()
+    const apiKey = (await ask(`API key for ${name}: `)).trim()
     if (!apiKey) {
-      console.error("key 不能为空，已取消")
+      console.error("API key cannot be empty — cancelled")
       return null
     }
-    const embedKey = (await ask("可选：embedding API key（SiliconFlow，向量检索用；回车跳过）: ")).trim()
+    const embedKey = (await ask("Optional: embedding API key (SiliconFlow, for vector search; press Enter to skip): ")).trim()
     const raw = existsSync(configPath) ? JSON.parse(readFileSync(configPath, "utf8")) : {}
     const providers = raw.providers?.length ? raw.providers : []
     const existing = providers.find((p) => p.name === name)
@@ -61,8 +61,8 @@ export async function setupWizard() {
     raw.activeProvider = name
     if (embedKey) raw.embedding = { ...(raw.embedding ?? {}), apiKey: embedKey }
     saveConfig(raw)
-    console.error(`配置完成：${name} / ${model}（已写入 ${configPath}）`)
-    console.error(embedKey ? "向量检索已启用\n" : "（未配 embedding key：记忆为纯文本检索，之后在 config.json 的 embedding.apiKey 补上即可开启向量检索）\n")
+    console.error(`Configured: ${name} / ${model} (saved to ${configPath})`)
+    console.error(embedKey ? "Vector search enabled\n" : "(No embedding key configured: memory search will use text-only FTS. Add embedding.apiKey to config.json to enable vector search later.)\n")
     return { name, baseURL, model, apiKey }
   } finally {
     rl.close()

package/src/config.mjs

@@ -1,8 +1,8 @@
 /**
- * config.mjs — 配置加载与保存
- * 多 provider 结构：providers[] + activeProvider
- * 配置文件：~/.thincoder/config.json
- * API key 可用环境变量兜底（未在 providers 中配置时）。
+ * config.mjs — configuration loading and saving
+ * Multi-provider structure: providers[] + activeProvider
+ * Config file: ~/.thincoder/config.json
+ * API key can fall back to environment variables (when not configured in providers).
  */
 
 import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
@@ -12,7 +12,7 @@ import { join } from "node:path"
 export const configDir = join(homedir(), ".thincoder")
 export const configPath = join(configDir, "config.json")
 
-/** 内置提供商预设：/provider add <预设名>、首次启动向导共用 */
+/** Built-in provider presets: shared by /provider add <preset> and first-run wizard */
 export const PROVIDER_PRESETS = {
   deepseek: { baseURL: "https://api.deepseek.com/v1", model: "deepseek-v4-pro", thinking: { type: "enabled" }, reasoningEffort: "max", maxTokens: 393216, desc: "DeepSeek" },
   kimi:     { baseURL: "https://api.moonshot.cn/v1", model: "kimi-k3", thinking: null, reasoningEffort: "max", maxTokens: 131072, desc: "Kimi / Moonshot" },
@@ -21,14 +21,15 @@ export const PROVIDER_PRESETS = {
   minimax:  { baseURL: "https://api.minimax.chat/v1", chatPath: "/text/chatcompletion_v2", model: "MiniMax-M3", maxTokens: 131072, desc: "MiniMax" },
 }
 
-// 默认 provider 跟 deepseek 预设保持一致（去掉 desc 展示字段）
-const { desc: _presetDesc, ...deepseekPreset } = PROVIDER_PRESETS.deepseek
+// Default provider matches deepseek preset (strip the desc display field)
+const { desc: _, ...deepseekPreset } = PROVIDER_PRESETS.deepseek
 
 const DEFAULTS = {
   providers: [{ name: "deepseek", ...deepseekPreset }],
   activeProvider: "deepseek",
   agent: {
     maxTurns: 100,
+    subagentTurns: 100,
     compactThreshold: 100000,
   },
   memory: {
@@ -46,60 +47,60 @@ const DEFAULTS = {
 }
 
 /**
- * 已知模型的能力规格表（前缀匹配，长的在前）。
- * 用于压缩阈值推导、截断续写协议选择、能力感知优化。
+ * Known model capability spec table (prefix match, longer first).
+ * Used for compaction threshold derivation, continuation protocol selection, and capability-aware optimization.
  *
- * context:           上下文窗口（tokens）
- * maxOutput:         最大输出 tokens（默认 context）
- * thinking:          是否支持思考/推理模式
- * partialMode:       Kimi/Qwen Partial Mode 截断续写（assistant 消息带 partial:true）
- * prefixMode:        DeepSeek Prefix Completion 截断续写（走 /beta 端点，带 prefix:true）
- * multimodal:        是否多模态（支持图片/视觉输入）
- * cacheMode:         上下文缓存方式："auto"=自动/"prompt"=需显式/"none"=不支持
- * thinkApi:          思考模式 API 类型："type"=thinking.type 字段 / "effort"=reasoning_effort 字段
- * reasoningEcho:     reasoning_content 跨轮回传策略："required"=必须回传(缺失报错)/"optional"=回传可选(默认不回传)
- * reasoningEffortEnum: reasoning_effort 合法枚举值（未声明则不校验，原样透传）
- * tempRange:         temperature 合法范围 [min, max]（未声明则不裁剪）
+ * context:           context window (tokens)
+ * maxOutput:         max output tokens (defaults to context)
+ * thinking:          whether thinking/reasoning mode is supported
+ * partialMode:       Kimi/Qwen Partial Mode truncation continuation (assistant message with partial:true)
+ * prefixMode:        DeepSeek Prefix Completion truncation continuation (uses /beta endpoint, with prefix:true)
+ * multimodal:        whether multimodal (image/vision input supported)
+ * cacheMode:         context caching mode: "auto"=automatic / "prompt"=needs explicit / "none"=unsupported
+ * thinkApi:          thinking API type: "type"=thinking.type field / "effort"=reasoning_effort field
+ * reasoningEcho:     reasoning_content cross-turn echo strategy: "required"=must echo (error if missing) / "optional"=echo optional (default: don't echo)
+ * reasoningEffortEnum: valid reasoning_effort enum values (if undeclared, no validation — passed through as-is)
+ * tempRange:         valid temperature range [min, max] (if undeclared, no clamping)
  */
 const MODEL_SPECS = [
-  // DeepSeek V4 系列
+  // DeepSeek V4 series
   ["deepseek-v4-pro",   { context: 1_000_000, maxOutput: 384_000, thinking: true,  prefixMode: true,  cacheMode: "prompt", thinkApi: "type", reasoningEcho: "required", reasoningEffortEnum: ["high", "max"], tempRange: [0, 2] }],
   ["deepseek-v4-flash", { context: 256_000,   maxOutput: 384_000, thinking: false, prefixMode: true,  cacheMode: "prompt", thinkApi: "type", reasoningEcho: "required", reasoningEffortEnum: ["high", "max"], tempRange: [0, 2] }],
   ["deepseek-reasoner", { context: 256_000,   maxOutput: 384_000, thinking: true,  prefixMode: true,  cacheMode: "prompt", thinkApi: "type", reasoningEcho: "required", reasoningEffortEnum: ["high", "max"], tempRange: [0, 2] }],
   ["deepseek-chat",     { context: 256_000,   maxOutput: 384_000, thinking: false, prefixMode: true,  cacheMode: "prompt", thinkApi: "type", reasoningEcho: "required", reasoningEffortEnum: ["high", "max"], tempRange: [0, 2] }],
-  // Kimi 系列
+  // Kimi series
   ["kimi-k3",           { context: 1_000_000, maxOutput: 128_000, thinking: true,  partialMode: true, multimodal: true, cacheMode: "prompt", thinkApi: "effort", reasoningEcho: "required", reasoningEffortEnum: ["low", "high", "max"] }],
   ["kimi-k2",           { context: 256_000,   maxOutput: 128_000, thinking: false, partialMode: true, multimodal: true, cacheMode: "none" }],
   ["moonshot",          { context: 128_000,   maxOutput: 32_000,  thinking: false, cacheMode: "none" }],
-  // GLM 系列
+  // GLM series
   ["glm-5.2",           { context: 1_000_000, maxOutput: 128_000, thinking: true,  cacheMode: "auto", thinkApi: "type", reasoningEcho: "optional", reasoningEffortEnum: ["max", "xhigh", "high", "medium", "low", "minimal", "none"], tempRange: [0, 1] }],
   ["glm-5",             { context: 1_000_000, maxOutput: 128_000, thinking: true,  cacheMode: "auto", thinkApi: "type", reasoningEcho: "optional", reasoningEffortEnum: ["max", "xhigh", "high", "medium", "low", "minimal", "none"], tempRange: [0, 1] }],
   ["glm-4",             { context: 128_000,   maxOutput: 32_000,  thinking: true,  cacheMode: "auto", thinkApi: "type", reasoningEcho: "optional", tempRange: [0, 1] }],
-  // GPT 系列
+  // GPT series
   ["gpt-4.1",           { context: 1_000_000, maxOutput: 128_000, thinking: false, cacheMode: "prompt" }],
   ["gpt-4o",            { context: 128_000,   maxOutput: 16_000,  thinking: false, multimodal: true, cacheMode: "prompt" }],
-  // Qwen 系列
+  // Qwen series
   ["qwen3.8-max-preview", { context: 1_000_000, maxOutput: 128_000, thinking: false, partialMode: true, multimodal: true, cacheMode: "none", thinkApi: "effort", reasoningEffortEnum: ["xhigh", "medium", "low"], tempRange: [0, 2] }],
   ["qwen3.7-max",       { context: 1_000_000, maxOutput: 128_000, thinking: false, partialMode: true, multimodal: true, cacheMode: "none", thinkApi: "effort", tempRange: [0, 2] }],
   ["qwen3.8-max",       { context: 1_000_000, maxOutput: 128_000, thinking: false, partialMode: true, multimodal: true, cacheMode: "none", thinkApi: "effort", tempRange: [0, 2] }],
   ["qwen-max",          { context: 1_000_000, maxOutput: 128_000, thinking: false, partialMode: true, multimodal: true, cacheMode: "none", thinkApi: "effort", tempRange: [0, 2] }],
   ["qwen-plus",         { context: 1_000_000, maxOutput: 32_000,  thinking: false, partialMode: true, multimodal: true, cacheMode: "none", thinkApi: "effort", tempRange: [0, 2] }],
   ["qwen",              { context: 1_000_000, maxOutput: 128_000, thinking: false, partialMode: true, multimodal: true, cacheMode: "none", thinkApi: "effort", tempRange: [0, 2] }],
-  // MiniMax 系列
+  // MiniMax series
   ["MiniMax-M3",        { context: 1_000_000, maxOutput: 128_000, thinking: true,  multimodal: true, cacheMode: "auto", thinkApi: "type", tempRange: [0, 2] }],
   ["minimax-m3",        { context: 1_000_000, maxOutput: 128_000, thinking: true,  multimodal: true, cacheMode: "auto", thinkApi: "type", tempRange: [0, 2] }],
   ["minimax-m1",        { context: 256_000,   maxOutput: 128_000, thinking: false, cacheMode: "auto" }],
 ]
 const DEFAULT_SPEC = { context: 128_000, maxOutput: 32_000, cacheMode: "none" }
-// 窗口利用率上限：0.8（DeepSeek 内部即全窗口；压缩本身要花一次 LLM 调用，过早压缩是纯浪费。
-// 留 20% 余量给压缩后的尾部增长与输出 token）
-// 但 1M 窗口模型按 0.8 算 = 80 万 token，历史涨到那么大才压缩会打爆 TPM 预算、
-// 压缩请求本身也可能 429。加 cap：不超过 maxOutput 的 8 倍（128K×8≈100万→实际仍偏大但合理），
-// 不超过 30 万（大窗口模型的合理工作上限，再大缓存命中率下降）
+// Window utilization cap: 0.8 (DeepSeek internally uses full window; compaction itself costs an LLM call, premature compaction is pure waste.
+// Reserve 20% headroom for post-compaction tail growth and output tokens)
+// But for 1M-window models, 0.8 = 800K tokens — waiting until history grows that large would blow the TPM budget,
+// and the compaction request itself might 429. Add caps: no more than 8× maxOutput (128K×8≈1M → still large but reasonable),
+// no more than 300K (reasonable working ceiling for large-window models; beyond that cache hit rates drop)
 const COMPACT_RATIO = 0.8
 const COMPACT_CAP_TOKENS = 300_000
 
-/** 按模型名前缀查规格（大小写不敏感），未知模型给保守默认 */
+/** Look up spec by model name prefix (case-insensitive), conservative default for unknown models */
 export function specForModel(model) {
   const m = (model ?? "").toLowerCase()
   for (const [prefix, spec] of [...MODEL_SPECS].sort((a,b) => b[0].length - a[0].length)) {
@@ -108,24 +109,25 @@ export function specForModel(model) {
   return DEFAULT_SPEC
 }
 
+/** Return the context window size for a given model name */
 export function contextWindowForModel(model) {
   return specForModel(model).context
 }
 
-/** 推导压缩阈值；explicit 为配置文件中显式设置的值（优先），否则按模型自动算 */
+/** Derive compaction threshold; explicit is the value explicitly set in config file (takes priority), otherwise auto-computed from model */
 export function resolveCompactThreshold(explicit, model) {
   if (explicit != null) return { value: explicit, auto: false }
   const spec = specForModel(model)
   const ratioBased = Math.floor(spec.context * COMPACT_RATIO)
-  // 大窗口模型（1M）按比例算出来太大，用 cap 限制——宁可早压缩也别让历史涨到打爆 TPM
+  // Large-window models (1M) produce too-large ratio-based values; cap them — better to compact early than let history grow until it blows the TPM budget
   const value = Math.min(ratioBased, COMPACT_CAP_TOKENS)
   return { value, auto: true }
 }
 
 /**
- * 从 providers[] 中按 name 查找。
- * name 非空但找不到时抛错——activeProvider 打错字静默落到第一个 provider，会拿错 key 打错端点。
- * name 为空时返回第一个。
+ * Find provider by name in providers[].
+ * Throws if name is non-empty but not found — a typo in activeProvider silently falling to the first provider would use the wrong key on the wrong endpoint.
+ * Returns the first provider when name is empty.
  */
 export function findProvider(providers, name) {
   if (name) {
@@ -138,9 +140,9 @@ export function findProvider(providers, name) {
 }
 
 /**
- * 加载配置。
- * 环境变量优先级：THINCODER_ACTIVE_PROVIDER > 配置文件 activeProvider
- * THINCODER_API_KEY / THINCODER_BASE_URL / THINCODER_MODEL 覆盖当前激活 provider 的对应字段
+ * Load configuration.
+ * Env var priority: THINCODER_ACTIVE_PROVIDER > config file activeProvider
+ * THINCODER_API_KEY / THINCODER_BASE_URL / THINCODER_MODEL override the current active provider's corresponding fields
  */
 export function loadConfig() {
   let config = {}
@@ -162,29 +164,29 @@ export function loadConfig() {
     embedding: { ...DEFAULTS.embedding, ...config.embedding },
   }
 
-  // baseURL 尾斜杠归一化（防拼出 //chat/completions）
+  // Normalize baseURL trailing slash (prevents //chat/completions)
   for (const p of merged.providers) {
     if (p.baseURL) p.baseURL = p.baseURL.replace(/\/+$/, "")
   }
 
-  // 环境变量覆盖 activeProvider
+  // Env var overrides activeProvider
   if (process.env.THINCODER_ACTIVE_PROVIDER) {
     merged.activeProvider = process.env.THINCODER_ACTIVE_PROVIDER
   }
 
-  // 获取当前激活的 provider
+  // Get the currently active provider
   const active = findProvider(merged.providers, merged.activeProvider)
 
-  // 构建运行时 provider 对象（供 agent.provider 使用）
+  // Build runtime provider object (for agent.provider usage)
   const runtimeProvider = { ...active }
 
-  // 环境变量覆盖当前激活 provider 的字段
+  // Env vars override current active provider's fields
   if (process.env.THINCODER_API_KEY) runtimeProvider.apiKey = process.env.THINCODER_API_KEY
   if (process.env.THINCODER_BASE_URL) runtimeProvider.baseURL = process.env.THINCODER_BASE_URL
   if (process.env.THINCODER_MODEL) runtimeProvider.model = process.env.THINCODER_MODEL
 
-  // apiKey 还可用环境变量兜底（当 providers 里没配 key 时）
-  // 提供商专用的环境变量只对同名 provider 生效，避免 key 串到错误的端点
+  // apiKey also falls back to env vars (when providers doesn't include a key)
+  // Provider-specific env vars only apply to the matching provider name, preventing keys from leaking to wrong endpoints
   if (!runtimeProvider.apiKey?.trim()) {
     const envMap = { deepseek: "DEEPSEEK_API_KEY", openai: "OPENAI_API_KEY" }
     const keyVar = envMap[merged.activeProvider]
@@ -196,13 +198,13 @@ export function loadConfig() {
     merged.embedding.apiKey = process.env.SILICONFLOW_API_KEY || process.env.THINCODER_EMBEDDING_API_KEY
   }
 
-  // 压缩阈值跟模型走
+  // Compaction threshold follows the model
   const explicitThreshold = config.agent?.compactThreshold
   const { value, auto } = resolveCompactThreshold(explicitThreshold, runtimeProvider.model)
   merged.agent.compactThreshold = value
   merged.agent.compactThresholdAuto = auto
 
-  // 回写到 merged 方便上层使用
+  // Write back to merged for convenient access by upper layers
   merged.provider = runtimeProvider
   merged.providersList = merged.providers
 
@@ -210,12 +212,12 @@ export function loadConfig() {
 }
 
 /**
- * 保存配置。保留 providers 列表结构和 activeProvider 指针。
- * providers[i].apiKey 仅在显式传入时才写入（不覆盖环境变量兜底的 key）
+ * Save configuration. Preserves providers list structure and activeProvider pointer.
+ * providers[i].apiKey is only written when explicitly passed in (does not overwrite env-var-fallback keys).
  */
 export function saveConfig(config) {
   mkdirSync(configDir, { recursive: true })
-  // 0600：config.json 含 API key，不能世界可读（POSIX；Windows 下 chmod 尽力而为）
+  // 0600: config.json contains API keys, must not be world-readable (POSIX; chmod is best-effort on Windows)
   writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n", { encoding: "utf8", mode: 0o600 })
-  try { chmodSync(configPath, 0o600) } catch { /* Windows 上可能失败，忽略 */ }
+  try { chmodSync(configPath, 0o600) } catch { /* may fail on Windows, ignore */ }
 }

package/src/context.mjs

@@ -1,14 +1,16 @@
 /**
- * context.mjs — 上下文管理与压缩
- * token 无实测值时用估算兜底（ASCII/4 + 非 ASCII/1，不引 tokenizer 依赖）；
- * 有实测值（响应 usage.prompt_tokens）以实测为准——估算对 CJK 低估 3-4 倍，靠它触发可能永远来不及压缩。
- * 压缩策略：保留最早 2 条 + 最近 N 条，中间由 LLM 摘要成一条（学 kimi-code，简化版）。
+ * context.mjs — Context management and compaction
+ * When no measured token count is available, use estimation as fallback (ASCII/4 + non-ASCII/1, no tokenizer dependency).
+ * When a measured value exists (response usage.prompt_tokens), trust it — estimation underestimates CJK by 3-4x and relying solely on it may never trigger compaction.
+ * Compaction strategy: keep earliest 2 + latest N messages, summarize the middle into one via LLM (inspired by kimi-code, simplified).
  */
 
 import { chat } from "./provider/index.mjs"
 import { estimateText } from "./provider/rate.mjs"
 
-/** 粗估一组消息的 token 数（正文 + 思考链 + tool_calls 参数） */
+const IMAGE_TOKEN_ESTIMATE = 256 // rough estimate for image placeholder tokens
+
+/** Rough token count for a list of messages (body + reasoning + tool_calls params) */
 export function estimateTokens(messages) {
   let tokens = 0
   for (const m of messages) {
@@ -16,7 +18,7 @@ export function estimateTokens(messages) {
     else if (Array.isArray(m.content)) {
       for (const part of m.content) {
         if (part.type === "text") tokens += estimateText(part.text)
-        else if (part.type === "image_url") tokens += 256 // 图片占位估算
+        else if (part.type === "image_url") tokens += IMAGE_TOKEN_ESTIMATE
       }
     }
     if (typeof m.reasoning_content === "string") tokens += estimateText(m.reasoning_content)
@@ -27,59 +29,59 @@ export function estimateTokens(messages) {
   return tokens
 }
 
-const KEEP_HEAD = 2 // 最早的用户意图，不能丢
-const KEEP_TAIL = 10 // 最近的工作现场，不能丢
+const KEEP_HEAD = 2 // Keep the earliest user intent — must not lose it
+const KEEP_TAIL = 10 // Keep the most recent work context — must not lose it
 
-const SUMMARIZE_PROMPT = `你是一个对话压缩器。把下面的 agent 工作记录压缩成一份紧凑的摘要，供后续对话作为上下文使用。
-要求：
-- 用第一人称、现在时书写——这是"我"的交接笔记，延续自己的思路
-- 最重要的：保留设计决策与原因——架构选择、API 约定、命名规范、取舍理由。这是后续代码不能偏离的锚点
-- 保留：用户的原始需求、修改过的文件及原因、未解决的问题、下一步计划
-- 丢弃：客套话、重复内容、工具输出的细枝末节
-- 诚实标注不确定项：没有实际验证过的事必须写"未验证"，不要把猜测写成事实
-- 用条目式输出，以信息完整为目标，不要硬卡字数（旧 500 字限制已作废，1M 上下文时代宁长勿缺）
+const SUMMARIZE_PROMPT = `You are a conversation compressor. Summarize the following agent work log into a compact summary for use as context in the ongoing conversation.
+Requirements:
+- Write in first person, present tense — these are "my" handover notes, continuing my own train of thought
+- Most important: preserve design decisions and their reasons — architecture choices, API contracts, naming conventions, trade-off rationale. These are the anchors the subsequent code must not deviate from
+- Keep: the user's original request, files modified and why, unresolved issues, next steps
+- Drop: pleasantries, repetition, fine-grained tool output details
+- Honestly mark uncertain items: anything not actually verified must say "unverified"; do not present guesses as facts
+- Use bullet-point output; aim for information completeness, not a hard word limit (old 500-char cap is deprecated; in a 1M-context era, err on the long side)
 
-工作记录：
+Work log:
 `
 
-/** 压缩后的上下文前缀，告知 agent 发生了什么 */
+/** Context prefix after compaction, informing the agent what happened */
 const COMPACTION_PREFIX =
   "[Context was automatically compacted. Below is a summary of earlier work. " +
   "Treat it as notes, not proof — trust its conclusions (don't redo what it reports as done) " +
   "but re-verify transient state (open files, running processes) with tools before relying on them. " +
   "Design decisions made earlier may be summarized — if you recall a decision that is missing from the summary, check memory_search or re-examine the code.]\n\n"
 
-/** 压缩摘要调用连续失败达到此次数后，降级为确定性截断（丢信息好过任务被 400 打死） */
+/** After this many consecutive compaction summary failures, degrade to deterministic truncation (losing info is better than task-killing 400 errors) */
 export const COMPRESS_FAILURE_LIMIT = 3
 
-/** task 回注提醒前缀（压缩后重新注入前，先清掉历史里的旧版本，保持单一信息源） */
+/** Task re-injection reminder prefix (after compaction, clear old versions from history first for a single source of truth) */
 const TASK_REINJECT_PREFIX = "[System reminder: your current task list after compaction:"
 
-/** 截断兜底笔记（摘要 LLM 连续失败时用，无 LLM 调用） */
+/** Truncation fallback note (used when the summary LLM fails repeatedly; no LLM call) */
 const FALLBACK_NOTE =
   "[Context was truncated after repeated summarization failures. " +
   "The middle portion of earlier work was dropped WITHOUT a summary. " +
   "Re-verify any state you need with tools before relying on it.]\n\n"
 
 /**
- * 切分 head / middle(被摘要) / tail；没有可压缩的中间段返回 null。
- * head 终点必须避开断头 tool_calls：assistant 带了 tool_calls 时其 tool 响应必须留在 head，
- * 否则响应被摘要成纯文本后协议校验 400（tool_calls must be followed by tool messages）。
- * tail 起点必须包含 tool 结果对应的 assistant——tool 在 tail、assistant 在 middle 时，
- * 摘要会把 assistant 吞掉，留下 orphan tool 结果 → 协议 400。
+ * Split history into head / middle (to be summarized) / tail; return null if no middle to compress.
+ * The head boundary must avoid orphan tool_calls: when an assistant message has tool_calls, all its tool responses must stay in head,
+ * otherwise compressing them to plain text violates the protocol (tool_calls must be followed by tool messages).
+ * The tail boundary must include any assistant whose tool results are in the tail — if the assistant is in the middle,
+ * the summary swallows it, leaving orphan tool results → protocol 400.
  */
 function splitHistory(history) {
   if (history.length <= KEEP_HEAD + KEEP_TAIL + 1) return null
   let headEnd = KEEP_HEAD
-  // head 不能以断头 tool_calls 结尾：assistant 声明了 tool_calls，其 tool 结果必须全部留在 head。
-  // 并行调用时一个 assistant 后面跟多条 tool 消息——只收一条照样 400，必须一次收完
+  // head must not end with dangling tool_calls: when assistant declares tool_calls, all its tool results must stay in head.
+  // Parallel calls: one assistant followed by multiple tool messages — accepting only one still causes 400, must collect all
   if (history[headEnd - 1]?.role === "assistant" && history[headEnd - 1].tool_calls?.length) {
     while (headEnd < history.length && history[headEnd].role === "tool") headEnd++
   }
   let tailStart = history.length - KEEP_TAIL
 
-  // tail 区域内的 tool 消息对应的 assistant tool_calls 若在 middle 里，摘要会把 assistant 吞掉，
-  // 剩下 orphan tool 结果 → 协议 400。从 tail 收集 tool_call_id，往前找回所属 assistant 拉进 tail
+  // Tool messages in the tail region whose assistant tool_calls are in the middle: the summary would swallow the assistant,
+  // leaving orphan tool results → protocol 400. Collect tool_call_ids from the tail, find their owner assistants and pull them into tail
   const tailToolIds = new Set()
   for (let i = tailStart; i < history.length; i++) {
     if (history[i].role === "tool") tailToolIds.add(history[i].tool_call_id)
@@ -100,7 +102,7 @@ function splitHistory(history) {
   return { headEnd, tailStart }
 }
 
-/** 用一条笔记替换 middle，并回注 task/plan 状态（LLM 摘要与截断兜底共用） */
+/** Replace middle with a note, then re-inject task/plan state (shared by LLM summary and truncation fallback) */
 function applyCompression(agent, headEnd, tailStart, note) {
   const head = agent.history.slice(0, headEnd)
   const tail = agent.history.slice(tailStart)
@@ -110,13 +112,13 @@ function applyCompression(agent, headEnd, tailStart, note) {
     { role: "assistant", content: "Understood. I'll continue from these notes, re-verifying anything transient." },
     ...tail,
   ]
-  // 实测 token 基准随旧历史一起失效（prompt_tokens 对应的是压缩前的上下文），退回估算直到下次响应
+  // Measured token baseline is invalidated along with old history (prompt_tokens were for pre-compaction context), fall back to estimation until next response
   agent._lastPromptTokens = null
   agent._usageAtLen = null
 
-  // 压缩后回注 task 列表（agent 需要知道自己做到哪了）。
-  // 单一信息源：先清掉 tail 里残留的旧回注，再注入最新版本——
-  // 不再嵌入摘要正文（会与这里重复且逐渐过时）
+  // After compaction, re-inject the task list (the agent needs to know what it was doing).
+  // Single source of truth: first remove any stale re-injections from the tail, then inject the latest version —
+  // no longer embedded in the summary body (would duplicate and grow stale)
   agent.history = agent.history.filter(
     (m) => !(m.role === "user" && typeof m.content === "string" && m.content.startsWith(TASK_REINJECT_PREFIX))
   )
@@ -128,11 +130,11 @@ function applyCompression(agent, headEnd, tailStart, note) {
     })
   }
 
-  // 重置跟踪计数器（上下文已重建，从头开始计数）
+  // Reset tracking counters (context rebuilt, start counting from scratch)
   agent._turnsSinceTaskUpdate = 0
   agent._turnsInPlanMode = 0
 
-  // plan mode 中压缩：重新注入 plan 模式引导
+  // Plan mode compaction: re-inject plan mode guidance
   if (agent.planMode) {
     agent.history.push({
       role: "user",
@@ -142,14 +144,14 @@ function applyCompression(agent, headEnd, tailStart, note) {
 }
 
 /**
- * 如果历史超长则压缩。返回是否发生了压缩。
- * 只在循环的安全点调用（history 末尾是 user 或 tool 消息——完整交换的边界）。
- * 压缩后自动回注 task 列表状态。
+ * If history exceeds threshold, compact it. Returns whether compaction happened.
+ * Only called at safe points in the loop (history ends with user or tool message — a complete exchange boundary).
+ * Automatically re-injects task list state after compaction.
  */
 export async function compressIfNeeded(agent, threshold) {
   const history = agent.history
-  // 真实基准优先：上次响应的 prompt_tokens 是完整上下文（system+tools+history）的实测值，
-  // 之后追加的消息用估算补增量；无实测（首轮/恢复后/刚压缩完）退化为纯估算
+  // Prefer the real baseline: the last response's prompt_tokens is the measured value for the full context (system+tools+history).
+  // Subsequent appended messages use estimation as increment; when no measured value exists (first turn / after restore / right after compaction), fall back to pure estimation
   const tokens =
     agent._lastPromptTokens != null
       ? agent._lastPromptTokens + estimateTokens(history.slice(agent._usageAtLen ?? history.length))
@@ -158,23 +160,24 @@ export async function compressIfNeeded(agent, threshold) {
 
   const split = splitHistory(history)
   if (!split) {
-    // 历史太短（≤13 条）切不出中间段，但 token 已超阈值——典型是一条巨型消息
-    // （大段粘贴/超大注入）。摘要无路可走时退化为确定性瘦身，保证上下文总能减下去
+    // History is too short (≤13 messages) to find a middle section, but tokens exceed threshold — typically a single giant message
+    // (large paste / huge injection). When summarization has no room, degrade to deterministic shrinking to ensure context always reduces
     return shrinkOversized(agent)
   }
 
   const middle = history.slice(split.headEnd, split.tailStart)
   const serialized = middle
     .map((m) => {
-      const toolNote = m.tool_calls ? ` [调用了工具: ${m.tool_calls.map((t) => t.function.name).join(", ")}]` : ""
-      // user 消息放宽到 8000：用户粘贴的长需求被切掉会让摘要丢失原始意图；tool/assistant 2000 足够
+      const toolNote = m.tool_calls ? ` [called tools: ${m.tool_calls.map((t) => t.function.name).join(", ")}]` : ""
+      // user messages get a wider cap (8000): cutting off a long user-pasted requirement loses original intent; tool/assistant capped at 2000 is enough
       const cap = m.role === "user" ? 8000 : 2000
       const content = typeof m.content === "string" ? m.content.slice(0, cap) : ""
       return `[${m.role}]${toolNote} ${content}`
     })
     .join("\n")
 
-  const summary = await chat(agent.provider, {
+  // The summary is a plain-text task, no reasoning needed — passing thinking to the compaction provider wastes tokens
+  const summary = await chat({ ...agent.provider, thinking: null, reasoningEffort: null }, {
     messages: [{ role: "user", content: SUMMARIZE_PROMPT + serialized }],
   })
 
@@ -183,8 +186,8 @@ export async function compressIfNeeded(agent, threshold) {
 }
 
 /**
- * 确定性截断兜底：摘要 LLM 连续失败时调用，不碰网络。
- * 丢掉 middle 换任务能继续跑。返回是否发生了截断。
+ * Deterministic truncation fallback: called when the summary LLM fails repeatedly, no network call.
+ * Drops the middle so the task can continue. Returns whether truncation happened.
  */
 export function compressFallback(agent) {
   const split = splitHistory(agent.history)
@@ -193,21 +196,21 @@ export function compressFallback(agent) {
   return true
 }
 
-/** 单条消息正文的硬截断长度：超过且在压缩无法切分时截断换桩（防一条巨消息卡死压缩） */
+/** Hard truncation limit for a single message body: when exceeded and the splitter can't find a middle section, truncate to a stub (prevents one giant message from blocking compaction) */
 const OVERSIZE_CONTENT_LIMIT = 8_000
 
 /**
- * 确定性瘦身：splitHistory 切不出中间段（历史太短）但已超阈值时的最后手段，无 LLM 调用。
- * 把超过 OVERSIZE_CONTENT_LIMIT 的 user/tool 正文截断换桩（保留首尾）；
- * 不动 reasoning_content（DeepSeek/Kimi 回传协议）与 tool_calls 配对结构，无协议 400 风险。
- * 只在 compressIfNeeded 判定超阈值后调用。返回是否有消息被截断。
+ * Deterministic shrinking: last resort when splitHistory can't find a middle section (history too short) but threshold is exceeded. No LLM call.
+ * Truncates user/tool message bodies exceeding OVERSIZE_CONTENT_LIMIT to a stub (keeps head + tail);
+ * does not touch reasoning_content (DeepSeek/Kimi echo protocol) or tool_calls pairing structure — no protocol 400 risk.
+ * Only called after compressIfNeeded determines threshold is exceeded. Returns whether any message was truncated.
  */
 export function shrinkOversized(agent, limit = OVERSIZE_CONTENT_LIMIT) {
   let shrunk = false
   for (const m of agent.history) {
     if ((m.role !== "user" && m.role !== "tool") || typeof m.content !== "string") continue
     if (m.content.length <= limit) continue
-    // 截断保留首尾，中间换桩说明；keepHead/keepTail 按比例但不超过 limit 的 50%/25%
+    // Truncate keeping head + tail, insert stub in between; keepHead/keepTail proportional but not exceeding 50%/25% of limit
     const keepHead = Math.min(Math.floor(limit * 0.5), 4000)
     const keepTail = Math.min(Math.floor(limit * 0.25), 2000)
     m.content =
@@ -217,7 +220,7 @@ export function shrinkOversized(agent, limit = OVERSIZE_CONTENT_LIMIT) {
     shrunk = true
   }
   if (shrunk) {
-    // 与压缩同理：实测 token 基准随被改动的历史失效，退回估算直到下次响应
+    // Same as compaction: measured token baseline is invalidated by the changed history, fall back to estimation until next response
     agent._lastPromptTokens = null
     agent._usageAtLen = null
   }