thincoder 0.8.2 → 0.8.4

package/src/git/checkpoint.mjs

@@ -1,16 +1,18 @@
 /**
- * checkpoint.mjs — 工作区快照与回滚
- * 快照 = git diff HEAD 补丁 + 未跟踪文件副本（尊重 .gitignore）。
- * 仅 git 仓库内可用。回滚前会先打新快照（回滚可逆）。
+ * checkpoint.mjs — workspace snapshot and rollback
+ * Snapshot = git diff HEAD patch + untracked file copies (respects .gitignore).
+ * Only available inside git repos. Rewind creates a new snapshot first (rewind is reversible).
+ * rewind supports a path parameter for per-file restore (restores only the specified file).
  */
-
 import { execFileSync } from "node:child_process"
 import { createHash } from "node:crypto"
-import { existsSync } from "node:fs"
+import { existsSync, readFileSync } from "node:fs"
 import { cp, mkdir, readFile, readdir, rm, writeFile, copyFile } from "node:fs/promises"
-import { dirname, join, relative } from "node:path"
+import { dirname, join } from "node:path"
 import { configDir } from "../config.mjs"
 
+const CWD_HASH_LEN = 12
+
 const MAX_CHECKPOINTS = 20
 
 function git(cwd, args, { allowFail = false } = {}) {
@@ -23,46 +25,71 @@ function git(cwd, args, { allowFail = false } = {}) {
 }
 
 function checkpointRoot(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, "checkpoints", hash)
 }
 
-/** 当前目录是否 git 仓库 */
+/** Extract the list of tracked files changed from a unified diff */
+function trackedFilesFromPatch(patch) {
+  if (!patch.trim()) return []
+  const files = new Set()
+  for (const m of patch.matchAll(/^--- a\/(.+)$/gm)) files.add(m[1])
+  return [...files].sort()
+}
+
+/** Extract a single file's patch hunks from a unified diff */
+function extractFileHunks(patch, filePath) {
+  // Split by file: each file block starts with "diff --git"
+  const sections = patch.split(/(?=^diff --git )/m)
+  for (const sec of sections) {
+    if (!sec.trim()) continue
+    const m = sec.match(/^diff --git a\/(.+) b\/(.+)/m)
+    if (!m) continue
+    if (m[1] === filePath || m[2] === filePath) return sec.trim()
+  }
+  return ""
+}
+
+/** Whether the current directory is a git repo */
 export function isGitRepo(cwd) {
   return git(cwd, ["rev-parse", "--is-inside-work-tree"], { allowFail: true }) === "true"
 }
 
 /**
- * 打快照。返回 { id, time, files } 或 null（非 git 仓库）。
+ * Create a snapshot. Returns { id, time, files } or null (non-git repo).
  */
 export async function createCheckpoint(cwd) {
   if (!isGitRepo(cwd)) return null
 
-  // 随机后缀：同一毫秒内两次快照的 id 不互撞（排序仍按时间戳前缀有序）
+  // Random suffix: prevents id collisions for two snapshots in the same millisecond (sorting stays ordered by timestamp prefix)
   const id = Date.now().toString(36) + "-" + Math.random().toString(36).slice(2, 6)
   const dir = join(checkpointRoot(cwd), id)
   await mkdir(join(dir, "untracked"), { recursive: true })
 
-  // 跟踪文件的改动 → 补丁
+  // Tracked file changes → patch
   const patch = git(cwd, ["diff", "HEAD", "--binary"], { allowFail: true }) ?? ""
   await writeFile(join(dir, "patch.diff"), patch, "utf8")
+  const tracked = trackedFilesFromPatch(patch)
 
-  // 未跟踪文件（尊重 .gitignore）→ 原样复制
+  // Untracked files (respects .gitignore) → copy as-is
   const untrackedRaw = git(cwd, ["ls-files", "--others", "--exclude-standard"], { allowFail: true }) ?? ""
   const untracked = untrackedRaw ? untrackedRaw.split("\n").filter(Boolean) : []
   for (const rel of untracked) {
     const src = join(cwd, rel)
     const dst = join(dir, "untracked", rel)
     await mkdir(dirname(dst), { recursive: true })
-    await copyFile(src, dst).catch(() => {}) // 复制失败（socket/设备文件等）跳过
+    await copyFile(src, dst).catch(() => {}) // Copy failed (socket/device file etc.) — skip
   }
-  await writeFile(join(dir, "meta.json"), JSON.stringify({ id, time: Date.now(), untracked }, null, 2), "utf8")
+
+  await writeFile(join(dir, "meta.json"), JSON.stringify({
+    id, time: Date.now(), untracked, tracked,
+  }, null, 2), "utf8")
 
   await pruneCheckpoints(cwd)
-  return { id, time: Date.now(), files: untracked.length + (patch ? 1 : 0) }
+  return { id, time: Date.now(), files: untracked.length + tracked.length, tracked, untracked }
 }
 
-/** 列出快照（新→旧） */
+/** List checkpoints (newest→oldest), with file change summary */
 export async function listCheckpoints(cwd) {
   const root = checkpointRoot(cwd)
   if (!existsSync(root)) return []
@@ -71,37 +98,38 @@ export async function listCheckpoints(cwd) {
   for (const id of ids) {
     try {
       const meta = JSON.parse(await readFile(join(root, id, "meta.json"), "utf8"))
-      out.push({ id, time: meta.time, untracked: meta.untracked.length })
+      // Compat with old checkpoints (no tracked field): extract from patch file
+      const tracked = meta.tracked ?? (() => {
+        try {
+          return trackedFilesFromPatch(readFileSync(join(root, id, "patch.diff"), "utf8"))
+        } catch { return [] }
+      })()
+      out.push({
+        id, time: meta.time,
+        untracked: meta.untracked ?? [],
+        tracked,
+      })
     } catch {
-      // 损坏的快照跳过
+      // Corrupted checkpoint — skip
     }
   }
   return out
 }
 
-/**
- * 回滚到指定快照（先把当前状态存成新快照，保证回滚可逆）。
- * 返回恢复摘要。
- */
-export async function rewind(cwd, id) {
-  const dir = join(checkpointRoot(cwd), id)
-  if (!existsSync(join(dir, "meta.json"))) throw new Error(`checkpoint ${id} not found`)
-  const meta = JSON.parse(await readFile(join(dir, "meta.json"), "utf8"))
-
-  // 回滚也可逆：先给当前状态打快照
-  await createCheckpoint(cwd)
+// ---- restore core ----
 
-  // 1. 工作区+暂存区 → HEAD，再应用快照补丁 → 快照时状态
-  // 必须连暂存区一起重置：checkout -- . 只从 index 恢复工作区，
-  // 有 staged 改动时工作区留下的是 staged 版本，补丁（diff HEAD，含 staged 内容）会 apply 失败
+/** Full restore of tracked files from a checkpoint: reset to HEAD → apply patch */
+async function fullRestoreTracked(cwd, dir) {
   git(cwd, ["restore", "--source=HEAD", "--staged", "--worktree", "."])
   const patch = await readFile(join(dir, "patch.diff"), "utf8")
   if (patch.trim()) {
-    const patchFile = join(dir, "patch.diff")
-    git(cwd, ["apply", "--whitespace=nowarn", patchFile])
+    git(cwd, ["apply", "--whitespace=nowarn", join(dir, "patch.diff")])
   }
+  return Boolean(patch.trim())
+}
 
-  // 2. 快照之后新建的未跟踪文件 → 删除
+/** Full restore of untracked files from a checkpoint: delete new ones → restore from snapshot */
+async function fullRestoreUntracked(cwd, dir, meta) {
   const nowUntracked = (git(cwd, ["ls-files", "--others", "--exclude-standard"], { allowFail: true }) ?? "")
     .split("\n")
     .filter(Boolean)
@@ -114,7 +142,6 @@ export async function rewind(cwd, id) {
     }
   }
 
-  // 3. 快照时存在、现在被改/被删的未跟踪文件 → 还原
   let restored = 0
   for (const rel of meta.untracked) {
     const src = join(dir, "untracked", rel)
@@ -124,11 +151,157 @@ export async function rewind(cwd, id) {
       restored++
     }
   }
+  return { deleted, restored }
+}
+
+/** Restore a single tracked file: checkout HEAD → apply that file's patch hunks */
+async function partialRestoreTracked(cwd, patchContent, filePath) {
+  // Reset the file to HEAD state first
+  git(cwd, ["checkout", "HEAD", "--", filePath], { allowFail: true })
+  const hunks = extractFileHunks(patchContent, filePath)
+  if (!hunks) return false
+  const tmpFile = join(checkpointRoot(cwd), ".tmp_partial.patch")
+  await writeFile(tmpFile, hunks, "utf8")
+  try {
+    git(cwd, ["apply", "--whitespace=nowarn", tmpFile])
+    return true
+  } finally {
+    await rm(tmpFile, { force: true })
+  }
+}
+
+/** Restore a single untracked file */
+async function partialRestoreUntracked(cwd, dir, filePath) {
+  const src = join(dir, "untracked", filePath)
+  if (!existsSync(src)) return false
+  await mkdir(dirname(join(cwd, filePath)), { recursive: true })
+  await cp(src, join(cwd, filePath), { force: true })
+  return true
+}
+
+// ---- rewind ----
+
+/**
+ * Rewind to a specific snapshot (saves current state as a new snapshot first, making rewind reversible).
+ *
+ * Options:
+ * - path: restore only this single file (tracked or untracked); other files are left untouched.
+ *   Omit for a full rewind (all changes → snapshot state).
+ *
+ * Returns summary { patchApplied, deleted?, restored? }; in path mode includes { file, type }.
+ */
+export async function rewind(cwd, id, { path } = {}) {
+  const root = checkpointRoot(cwd)
+  const dir = join(root, id)
+  if (!existsSync(join(dir, "meta.json"))) throw new Error(`checkpoint ${id} not found`)
+  const meta = JSON.parse(await readFile(join(dir, "meta.json"), "utf8"))
+  const patchContent = await readFile(join(dir, "patch.diff"), "utf8")
+
+  // Rewind is reversible: snapshot current state first
+  const preRewindCp = await createCheckpoint(cwd)
+
+  // ---- per-file restore ----
+  if (path) {
+    // Determine whether it's a tracked or untracked file
+    const isTracked = meta.tracked?.includes(path) ?? extractFileHunks(patchContent, path) !== ""
+    const inUntracked = (meta.untracked ?? []).includes(path)
+
+    if (!isTracked && !inUntracked) {
+      throw new Error(`file "${path}" not found in checkpoint ${id} (tracked: ${(meta.tracked ?? []).join(", ") || "none"}, untracked: ${(meta.untracked ?? []).join(", ") || "none"})`)
+    }
+
+    let ok = false
+    if (isTracked) {
+      ok = await partialRestoreTracked(cwd, patchContent, path)
+    }
+    if (inUntracked) {
+      ok = await partialRestoreUntracked(cwd, dir, path) || ok
+    }
+
+    return { path, type: isTracked ? "tracked" : "untracked", restored: ok, patchApplied: false }
+  }
+
+  // ---- full rewind ----
+  try {
+    const patchApplied = await fullRestoreTracked(cwd, dir)
+    const { deleted, restored } = await fullRestoreUntracked(cwd, dir, meta)
+    return { deleted, restored, patchApplied }
+  } catch (e) {
+    // git apply failed: working tree may have been reset to HEAD by restore.
+    // Restore from pre-rewind snapshot to ensure no data is lost on rewind failure
+    const preDir = join(root, preRewindCp.id)
+    try {
+      await fullRestoreTracked(cwd, preDir)
+      await fullRestoreUntracked(cwd, preDir, JSON.parse(await readFile(join(preDir, "meta.json"), "utf8")))
+    } catch {
+      // Double failure: pre-rewind may also be corrupt, stop trying
+    }
+    throw new Error(
+      `Rewind to ${id} failed: ${e.message}. ` +
+      `The pre-rewind state was restored from checkpoint ${preRewindCp.id} — no work was lost.`
+    )
+  }
+}
 
-  return { deleted, restored, patchApplied: Boolean(patch.trim()) }
+// ---- view ----
+
+/**
+ * View a file's content from a checkpoint (does not modify the working tree).
+ * Tracked files: temporarily restore via checkout HEAD + apply patch hunks, read, then restore original.
+ * Untracked files: read the copy directly from the checkpoint directory.
+ * Returns the file content string.
+ */
+export async function catFile(cwd, id, filePath) {
+  const root = checkpointRoot(cwd)
+  const dir = join(root, id)
+  if (!existsSync(join(dir, "meta.json"))) throw new Error(`checkpoint ${id} not found`)
+  const meta = JSON.parse(await readFile(join(dir, "meta.json"), "utf8"))
+  const patchContent = await readFile(join(dir, "patch.diff"), "utf8")
+
+  const isTracked = meta.tracked?.includes(filePath) ?? extractFileHunks(patchContent, filePath) !== ""
+  const inUntracked = (meta.untracked ?? []).includes(filePath)
+
+  if (!isTracked && !inUntracked) {
+    throw new Error(`file "${filePath}" not in checkpoint ${id}`)
+  }
+
+  // Untracked file: read the copy directly
+  if (inUntracked && !isTracked) {
+    const src = join(dir, "untracked", filePath)
+    if (!existsSync(src)) throw new Error(`untracked file "${filePath}" copy missing in checkpoint`)
+    return await readFile(src, "utf8")
+  }
+
+  // Tracked file: temporarily restore → read → restore working tree
+  const abs = join(cwd, filePath)
+  const existed = existsSync(abs)
+  let saved = null
+  if (existed) saved = await readFile(abs, "utf8")
+
+  try {
+    git(cwd, ["checkout", "HEAD", "--", filePath])
+    const hunks = extractFileHunks(patchContent, filePath)
+    if (hunks) {
+      const tmpPatch = join(root, ".tmp_cat.patch")
+      await writeFile(tmpPatch, hunks, "utf8")
+      try {
+        git(cwd, ["apply", "--whitespace=nowarn", tmpPatch])
+      } finally {
+        await rm(tmpPatch, { force: true })
+      }
+    }
+    return await readFile(abs, "utf8")
+  } finally {
+    // Restore original working tree state
+    if (existed) {
+      await writeFile(abs, saved, "utf8")
+    } else {
+      await rm(abs, { force: true })
+    }
+  }
 }
 
-/** 只留最近 MAX_CHECKPOINTS 个 */
+/** Keep only the most recent MAX_CHECKPOINTS */
 async function pruneCheckpoints(cwd) {
   const root = checkpointRoot(cwd)
   const ids = (await readdir(root)).sort()

package/src/git/gitmem.mjs

@@ -1,8 +1,9 @@
 /**
- * gitmem.mjs — Team 层记忆的 git 同步
- * 全部通过 child_process 调系统 git，零依赖。
- * 冲突策略（已定）：不同条目天然不冲突；真冲突时中止 rebase 保持仓库干净，
- * 报带手动指引的错误——不做自动合并。
+ * gitmem.mjs — Team-layer memory git sync
+ * All through child_process calling system git, zero dependencies.
+ * Conflict strategy (decided): different entries are naturally conflict-free;
+ * on real conflicts abort rebase to keep the repo clean,
+ * report an error with manual resolution guidance — no auto-merge.
  */
 
 import { execFile } from "node:child_process"
@@ -13,7 +14,7 @@ import { promisify } from "node:util"
 
 const execFileAsync = promisify(execFile)
 
-/** 在 dir 下执行 git，失败抛带 stderr 的错误 */
+/** Run git in dir, throw with stderr on failure */
 async function git(dir, args) {
   try {
     const { stdout } = await execFileAsync("git", args, { cwd: dir, encoding: "utf8" })
@@ -27,7 +28,7 @@ async function git(dir, args) {
   }
 }
 
-/** 团队仓库不存在则 clone。返回是否发生了 clone */
+/** Clone team repo if it doesn't exist. Returns whether a clone happened */
 export async function ensureClone({ repo, dir }) {
   if (existsSync(join(dir, ".git"))) return false
   await mkdir(dirname(dir), { recursive: true })
@@ -36,12 +37,12 @@ export async function ensureClone({ repo, dir }) {
 }
 
 /**
- * 同步：pull --rebase。远端还是空仓库时直接跳过（首次使用前）。
- * 冲突时中止 rebase（保持仓库干净）并抛带指引的错误。
- * 返回 true=拉取成功（调用方随后 syncDir 重建索引）
+ * Sync: pull --rebase. Skip if remote is still empty (first-time use).
+ * On conflict, abort rebase (keep repo clean) and throw a guided error.
+ * Returns true = pull succeeded (caller should then syncDir to rebuild index)
  */
 export async function pullTeam(dir) {
-  // 远端空仓库：没有可拉取的分支（ls-remote 无输出）
+  // Empty remote repo: no branch to pull (ls-remote has no output)
   const refs = await git(dir, ["ls-remote", "--heads", "origin"])
   if (!refs) return false
 
@@ -52,9 +53,9 @@ export async function pullTeam(dir) {
     if (await hasConflict(dir)) {
       await git(dir, ["rebase", "--abort"]).catch(() => {})
       throw new Error(
-        `团队记忆同步冲突：本地与远端修改了同一条目。\n` +
-        `请到 ${dir} 手动执行 git pull 解决冲突，然后重新运行 thincoder sync。\n` +
-        `（本地仓库已恢复到同步前状态，未丢失任何内容）`,
+        `Team memory sync conflict: local and remote modified the same entry.\n` +
+        `Please resolve manually in ${dir} with \`git pull\`, then re-run \`thincoder sync\`.\n` +
+        `(The local repo has been restored to its pre-sync state — nothing was lost.)`,
       )
     }
     throw error
@@ -62,28 +63,28 @@ export async function pullTeam(dir) {
 }
 
 /**
- * 提交并推送一个条目文件。push 被拒（远端有新提交）时 pull --rebase 后重试一次；
- * rebase 冲突同样中止并报错。
+ * Commit and push an entry file. On push rejection (remote has new commits),
+ * pull --rebase then retry once; rebase conflicts also abort and error out.
  */
 export async function commitAndPush(dir, filename, message) {
   await git(dir, ["add", filename])
-  // 内容没变化时 commit 会以 exit 1 报 "nothing to commit"——这是正常的幂等结果，不是错误
+  // Nothing to commit (content unchanged) — this is normal idempotent behavior, not an error
   const dirty = await git(dir, ["status", "--porcelain", "--", filename])
   if (dirty) await git(dir, ["commit", "-m", message])
   try {
     await git(dir, ["push"])
   } catch {
-    await pullTeam(dir) // 冲突时这里会抛出带指引的错误
+    await pullTeam(dir) // Conflicts will throw a guided error here
     await git(dir, ["push"])
   }
 }
 
-/** 当前是否处于 rebase 冲突状态（存在未合并路径） */
+/** Whether currently in a rebase conflict state (unmerged paths exist) */
 async function hasConflict(dir) {
   try {
     const out = await git(dir, ["status", "--porcelain"])
-    // 未合并状态共 7 种：DD AU UD UA DU AA UU——只看 UU/AA/DD 会漏掉带 U 的四种，
-    // 漏判就不 abort，仓库留在冲突中间态（与"保持仓库干净"的承诺相悖）
+    // There are 7 unmerged states: DD AU UD UA DU AA UU — only checking UU/AA/DD misses 4 states with U,
+    // which means the rebase is left mid-conflict (violating the "keep repo clean" promise)
     return out.split("\n").some((l) => l[0] === "U" || l[1] === "U" || l.startsWith("AA") || l.startsWith("DD"))
   } catch {
     return false

package/src/markdown.mjs

@@ -1,14 +1,14 @@
 /**
- * markdown.mjs — 记忆条目的 markdown + frontmatter 格式
- * 零依赖解析/序列化。条目格式见 ARCHITECTURE-v2.md。
+ * markdown.mjs — markdown + frontmatter format for memory entries
+ * Zero-dependency parsing/serialization. Entry format see ARCHITECTURE-v2.md.
  */
 
 const VALID_TYPES = new Set(["rule", "knowledge", "decision", "pattern"])
 
 /**
- * 解析 markdown 条目。
+ * Parse a markdown entry.
  * → { meta: { type, title, tags, author, created, embedding? }, content }
- * 无 frontmatter 或缺必要字段时抛错。
+ * Throws if frontmatter is missing or required fields absent.
  */
 export function parseEntry(text) {
   const match = text.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/)
@@ -36,13 +36,13 @@ export function parseEntry(text) {
 }
 
 /**
- * 序列化为 markdown 条目文本。
+ * Serialize to markdown entry text.
  */
 export function serializeEntry(meta, content) {
   if (!VALID_TYPES.has(meta.type)) throw new Error(`invalid type "${meta.type}"`)
   if (!meta.title) throw new Error("meta.title is required")
-  // frontmatter 标量必须单行：title/author 含换行会注入伪 frontmatter 行
-  // （如 title "x\ntype: rule" 解析时覆盖真实 type），tags 含换行/逗号同理
+  // frontmatter scalars must be single-line: newlines in title/author would inject fake frontmatter rows
+  // (e.g. title "x\ntype: rule" would override real type when parsed), same for tags with newlines/commas
   const tags = (meta.tags ?? []).map((t) => oneLine(t).replaceAll(",", " ")).join(", ")
   const lines = [
     "---",
@@ -57,7 +57,7 @@ export function serializeEntry(meta, content) {
   return lines.join("\n")
 }
 
-/** 标题转文件名 slug：保留中英文数字，其余转连字符 */
+/** Convert title to filename slug: keep alphanumeric + CJK, convert rest to hyphens */
 export function slugify(title) {
   return title
     .trim()
@@ -67,23 +67,23 @@ export function slugify(title) {
     .slice(0, 50) || "untitled"
 }
 
-/** 生成条目文件名：YYYYMMDD-<slug>-<rand4>.md */
+/** Generate entry filename: YYYYMMDD-<slug>-<rand4>.md */
 export function entryFilename(title, date = new Date()) {
   const ymd = date.toISOString().slice(0, 10).replaceAll("-", "")
   const rand = Math.random().toString(36).slice(2, 6)
   return `${ymd}-${slugify(title)}-${rand}.md`
 }
 
-// ---------------------------------------------------------------- 内部
+// ---------------------------------------------------------------- internal
 
-/** 压成单行（frontmatter 标量用）：换行折叠为空格，防注入伪字段行 */
+/** Collapse to single line (for frontmatter scalars): fold newlines into spaces, prevent injecting fake field lines */
 function oneLine(v) {
   return String(v).replace(/\s*\r?\n\s*/g, " ").trim()
 }
 
 /**
- * 极简 YAML 子集解析：只支持 `key: value` 和 `key: [a, b, c]`。
- * 我们的 frontmatter 是自己生成的，不需要完整 YAML。
+ * Minimal YAML subset parser: only supports `key: value` and `key: [a, b, c]`.
+ * Our frontmatter is self-generated, no need for full YAML.
  */
 function parseFrontmatter(text) {
   const meta = {}

package/src/mcp/helpers.mjs

@@ -1,5 +1,5 @@
 /**
- * mcp/helpers.mjs — MCP 共享工具函数与常量
+ * mcp/helpers.mjs — MCP shared utility functions and constants
  */
 
 export const INIT_TIMEOUT_MS = 30_000
@@ -7,10 +7,12 @@ export const CALL_TIMEOUT_MS = 120_000
 export const ENDPOINT_WAIT_MS = 5_000
 
 let nextRpcId = 0
+/** Generate a unique incrementing RPC ID string */
 export function rpcId() {
   return String(++nextRpcId)
 }
 
+/** Race a promise against a timeout, rejecting after ms milliseconds */
 export function withTimeout(promise, ms) {
   let timer
   const timeout = new Promise((_, reject) => {
@@ -20,10 +22,12 @@ export function withTimeout(promise, ms) {
   return Promise.race([promise.finally(() => clearTimeout(timer)), timeout])
 }
 
+/** Quote a shell argument: wrap in double-quotes if it contains whitespace or quotes */
 export function quoteArg(s) {
   return /[\s"]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s
 }
 
+/** Append a Bearer token as a query parameter to a WebSocket URL */
 export function withAuthToken(wsUrl, authorization) {
   if (!authorization) return wsUrl
   const token = authorization.replace(/^Bearer\s+/i, "")
@@ -32,6 +36,7 @@ export function withAuthToken(wsUrl, authorization) {
   return u.href
 }
 
+/** Sanitize a tool name: replace non-alphanumeric chars with underscores, cap at 64 chars */
 export function sanitizeToolName(name) {
   return name.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 64)
 }

package/src/mcp/transport-http.mjs

@@ -3,6 +3,7 @@
  */
 import { rpcId, CALL_TIMEOUT_MS, ENDPOINT_WAIT_MS, withTimeout } from "./helpers.mjs"
 
+/** Create an MCP HTTP+SSE transport for Streamable HTTP servers */
 export function httpTransport(baseURL, extraHeaders = {}) {
   const url = baseURL.replace(/\/+$/, "")
   let sessionId = null
@@ -82,7 +83,7 @@ export function httpTransport(baseURL, extraHeaders = {}) {
               pending.delete(msg.id)
               resolver(msg)
             }
-          } catch { /* 非 JSON，忽略 */ }
+          } catch { /* not JSON, ignore */ }
         }
       } catch (error) {
         if (!closed) {

package/src/mcp/transport-stdio.mjs

@@ -4,6 +4,7 @@
 import { spawn } from "node:child_process"
 import { rpcId, CALL_TIMEOUT_MS, withTimeout, quoteArg } from "./helpers.mjs"
 
+/** Create an MCP stdio transport over a spawned child process */
 export function stdioTransport(command, args) {
   const spawnOptions = { stdio: ["pipe", "pipe", "pipe"], windowsHide: true, env: { ...process.env } }
   const child =
@@ -39,7 +40,7 @@ export function stdioTransport(command, args) {
           pending.delete(msg.id)
           resolver(msg)
         }
-      } catch { /* 非 JSON 行忽略 */ }
+      } catch { /* non-JSON line, ignore */ }
     }
   })
 
@@ -77,7 +78,7 @@ export function stdioTransport(command, args) {
     if (closed) return
     try {
       child.stdin.write(JSON.stringify({ jsonrpc: "2.0", method, params }) + "\n")
-    } catch { /* 忽略 */ }
+    } catch { /* ignore */ }
   }
 
   return { send, notify, close: () => { if (!closed) child.kill() } }

package/src/mcp/transport-ws.mjs

@@ -3,6 +3,7 @@
  */
 import { rpcId, INIT_TIMEOUT_MS, CALL_TIMEOUT_MS, withTimeout, withAuthToken } from "./helpers.mjs"
 
+/** Create an MCP WebSocket transport */
 export function wsTransport(wsUrl, extraHeaders = {}) {
   const pending = new Map()
   let closed = false
@@ -36,7 +37,7 @@ export function wsTransport(wsUrl, extraHeaders = {}) {
             pending.delete(msg.id)
             resolver(msg)
           }
-        } catch { /* 非 JSON，忽略 */ }
+        } catch { /* not JSON, ignore */ }
       })
 
       ws.addEventListener("error", (event) => {
@@ -80,7 +81,7 @@ export function wsTransport(wsUrl, extraHeaders = {}) {
   const close = () => {
     closed = true
     failAll("Connection closed")
-    try { ws?.close() } catch { /* 忽略 */ }
+    try { ws?.close() } catch { /* ignore */ }
   }
 
   return { send, notify, close, connect }

package/src/mcp.mjs

@@ -1,6 +1,6 @@
 /**
  * mcp.mjs — MCP (Model Context Protocol) client
- * config: { command, args?, name } 或 { url, name, headers? } 或 { wsUrl, name, headers? }
+ * config: { command, args?, name } or { url, name, headers? } or { wsUrl, name, headers? }
  */
 import { INIT_TIMEOUT_MS, withTimeout, sanitizeToolName } from "./mcp/helpers.mjs"
 import { stdioTransport } from "./mcp/transport-stdio.mjs"
@@ -46,6 +46,7 @@ async function doInitialize(transport, name) {
   return toolsResp.result?.tools ?? []
 }
 
+/** Connect to an MCP server (stdio/http/ws), initialize, and return built tool wrappers */
 export async function connectMcpServer(config) {
   if (config.wsUrl) {
     const transport = wsTransport(config.wsUrl, config.headers ?? {})
@@ -64,7 +65,7 @@ export async function connectMcpServer(config) {
     try {
       await transport.openSSE()
     } catch {
-      // 不支持 GET 的 server（纯 Streamable HTTP POST）：降级为无 SSE 模式
+      // Server doesn't support GET (pure Streamable HTTP POST): degrade to no-SSE mode
     }
     try {
       const mcpTools = await doInitialize(transport, config.name ?? config.url)
@@ -89,12 +90,14 @@ export async function connectMcpServer(config) {
   throw new Error(`MCP server "${config.name}": needs either 'wsUrl' (websocket), 'command' (stdio), or 'url' (http)`)
 }
 
+/** Close all MCP transport connections on an agent's tools */
 export function closeAllMcp(agent) {
   for (const t of agent.tools) {
     if (t._mcpTransport) t._mcpTransport.close()
   }
 }
 
+/** Remove MCP tools belonging to a specific server from the agent's tool list */
 export function removeMcpTools(agent, serverName) {
   const keep = []
   for (const t of agent.tools) {