@thincoder/core 0.10.2 → 0.10.3

package/provider/normalize.mjs

@@ -10,6 +10,63 @@
 
 const RASTER_IMAGE_URL = /^data:image\/(png|jpe?g|gif|webp);base64,/
 
+/** 历史图片累计字节预算（D-PR32——40MB 级请求体的保守下界，留两张大图余量；可调）。 */
+export const IMAGE_HISTORY_BYTES_BUDGET = 32 * 1024 * 1024
+
+/** 图片驱逐占位文本（D-PR32 逐字）。 */
+const IMAGE_BUDGET_PLACEHOLDER = "[image omitted — dropped to keep the request under the history image budget]"
+
+/** 单 part 的 base64 载荷长度（仅 data URL；非 data 引用不过请求体、零计账）。 */
+function imagePartBytes(p) {
+  if (p?.type !== "image_url") return 0
+  const url = p.image_url?.url
+  if (typeof url !== "string" || !url.startsWith("data:")) return 0
+  const comma = url.indexOf(",")
+  return comma >= 0 ? url.length - comma - 1 : 0
+}
+
+/**
+ * 历史图片累计字节预算（D-PR32）：全部 image part 的 base64 载荷和超 budgetBytes 时，
+ * 从**最老**图起替换为占位文本，直到剩余 ≤ 预算。纯函数 + 拷贝语义（未改动时返回原引用；
+ * 改动时仅重建涉及的消息对象）——发送前对消息副本用；注入面对 `history` 本体回写（同函数同预算）。
+ * @param {Array} messages
+ * @param {number} [budgetBytes]
+ */
+export function capHistoryImages(messages, budgetBytes = IMAGE_HISTORY_BYTES_BUDGET) {
+  if (!Array.isArray(messages)) return messages
+  const hits = []
+  let total = 0
+  for (let mi = 0; mi < messages.length; mi++) {
+    const parts = messages[mi]?.content
+    if (!Array.isArray(parts)) continue
+    for (let pi = 0; pi < parts.length; pi++) {
+      const bytes = imagePartBytes(parts[pi])
+      if (bytes <= 0) continue
+      total += bytes
+      hits.push({ mi, pi, bytes })
+    }
+  }
+  if (total <= budgetBytes || hits.length === 0) return messages
+  const drop = new Set()
+  let remaining = total
+  for (const hit of hits) {
+    if (remaining <= budgetBytes) break
+    drop.add(`${hit.mi}:${hit.pi}`)
+    remaining -= hit.bytes
+  }
+  return messages.map((m, mi) => {
+    const parts = m?.content
+    if (!Array.isArray(parts)) return m
+    let changed = false
+    const next = parts.map((p, pi) => {
+      if (!drop.has(`${mi}:${pi}`)) return p
+      changed = true
+      return { type: "text", text: IMAGE_BUDGET_PLACEHOLDER }
+    })
+    return changed ? { ...m, content: next } : m
+  })
+}
+
 export function stripImagesForTextModel(messages, spec) {
   let changed = false
   const out = messages.map((m) => {

package/provider/sse.mjs

@@ -3,6 +3,7 @@
  * Extracted from core.mjs. Parses Server-Sent Events for LLM chat responses.
  */
 import { abortError, timeoutError } from "../abort-provenance.mjs"
+import { terminateBody } from "../stream-destroy.mjs"
 
 /**
  * Normalize provider cache fields into DeepSeek-style prompt_cache_hit/miss_tokens.
@@ -20,29 +21,43 @@ export function normalizeUsageCache(u) {
   }
   return u
 }
+/** 帧形状分派用前缀补差（D-PR31）：全同 ⇒ ""（零再增）；已收为前缀 ⇒ 只补差量；
+ *  无前缀关系 ⇒ 整段按增量追加（不吞真实内容——无法判定时不丢文本）。 */
+function snapshotSuffix(accumulated, text) {
+  if (text === accumulated) return ""
+  if (text.startsWith(accumulated)) return text.slice(accumulated.length)
+  return text
+}
+
 /** Defensive tool-call merge (PROVIDER.md §10): skip null/malformed elements and count them;
- *  merge slots by index / id / name / tail, accumulate arguments. */
-function mergeToolCalls(result, delta) {
+ *  merge slots by index / id / name / tail, accumulate arguments.
+ *  `snapshot: true`（D-PR31——`choice.message` 完整快照帧）：已有 slot（index / id 命中）的
+ *  arguments **覆盖**（非 +=）——修快照帧二次拼接；新 slot 照常建、其余路径零变。 */
+function mergeToolCalls(result, delta, { snapshot = false } = {}) {
   for (const tc of delta.tool_calls ?? []) {
     if (!tc || typeof tc !== "object") { result.droppedToolCalls++; continue }
     let slot
+    let existed = false
     if (Number.isInteger(tc.index) && tc.index >= 0) {
+      existed = result.toolCalls[tc.index] != null
       slot = (result.toolCalls[tc.index] ??= { id: "", name: "", arguments: "" })
     } else if (tc.id) {
       slot = result.toolCalls.find((s) => s && s.id === tc.id)
+      existed = !!slot
       if (!slot) { slot = { id: tc.id, name: "", arguments: "" }; result.toolCalls.push(slot) }
     } else if (tc.function?.name) {
       slot = { id: "", name: "", arguments: "" }
       result.toolCalls.push(slot)
     } else {
       slot = result.toolCalls[result.toolCalls.length - 1]
+      existed = !!slot
       if (!slot) { result.droppedToolCalls++; continue }
     }
     if (tc.id && !slot.id) slot.id = tc.id
     if (tc.function?.name && !slot.name) slot.name = tc.function.name
     const arg = tc.function?.arguments
-    if (typeof arg === "string") slot.arguments += arg
-    else if (arg != null) slot.arguments += JSON.stringify(arg)
+    if (typeof arg === "string") slot.arguments = snapshot && existed ? arg : slot.arguments + arg
+    else if (arg != null) slot.arguments = snapshot && existed ? JSON.stringify(arg) : slot.arguments + JSON.stringify(arg)
   }
 }
 
@@ -135,19 +150,29 @@ export async function readSSE(response, { onToken, onReasoning, rules, signal, f
     hasChoices = true
     if (choice.finish_reason) result.finishReason = choice.finish_reason
 
-    const delta = choice.delta ?? choice.message ?? {}
+    // 帧形状分派（D-PR31）：`delta == null && message != null` = 完整快照帧（MiniMax v2 类端点）——
+    // content / reasoning 前缀补差、tool_calls 覆盖；`delta` 在场 = 纯增量语义照旧
+    //（真增量文本天然可重复——不做去重）。
+    const snapshot = choice.delta == null && choice.message != null
+    const delta = snapshot ? choice.message : (choice.delta ?? {})
     // reasoning 方言：DeepSeek/Kimi/GLM 用 reasoning_content，OpenAI o 系和部分
     // 路由器用 reasoning —— 两个都认（2026-08-31 会诊 #9）
     const rDelta = delta.reasoning_content ?? delta.reasoning
     if (rDelta) {
-      result.reasoning += rDelta
-      onReasoning?.(rDelta)
+      const add = snapshot ? snapshotSuffix(result.reasoning, rDelta) : rDelta
+      if (add) {
+        result.reasoning += add
+        onReasoning?.(add)
+      }
     }
     if (delta.content) {
-      result.content += delta.content
-      onToken?.(delta.content)
+      const add = snapshot ? snapshotSuffix(result.content, delta.content) : delta.content
+      if (add) {
+        result.content += add
+        onToken?.(add)
+      }
     }
-    mergeToolCalls(result, delta)
+    mergeToolCalls(result, delta, { snapshot })
   }
 
   const processLines = (lines) => {
@@ -172,10 +197,14 @@ export async function readSSE(response, { onToken, onReasoning, rules, signal, f
   // 直连 fetch 与 proxyFetch 统一走这里（proxy 的 _bodyIdleMs 语义与之等价，双保险）。
   const READ_IDLE_MS = 120_000
   let idleTimer = null
+  let idleError = null
   const armIdle = () => {
     if (idleTimer) clearTimeout(idleTimer)
     idleTimer = setTimeout(() => {
-      try { response.body?.destroy(timeoutError(`SSE idle timeout: no data for ${READ_IDLE_MS / 1000}s`, "provider", "sse-idle")) } catch { /* already gone */ }
+      // #878：断流单点分流——直连 fetch（web 流）走 `IDLE_ABORT` 内部 abort 通道，
+      // proxy 形回落 destroyBody（原契约）。
+      idleError = timeoutError(`SSE idle timeout: no data for ${READ_IDLE_MS / 1000}s`, "provider", "sse-idle")
+      try { terminateBody(response, idleError) } catch { /* already gone */ }
     }, READ_IDLE_MS)
     idleTimer.unref?.()
   }
@@ -224,20 +253,23 @@ export async function readSSE(response, { onToken, onReasoning, rules, signal, f
       if (idleTimer) clearTimeout(idleTimer)
       return result
     }
+    // #878：看门狗终结归类归一（abort 通道下底层错误形不定）——无内容 ⇒ idle 超时错误；
+    // 有部分内容 ⇒ partial + networkError（原径语义保持）。
+    const err = idleError ?? e
     // 2026-08-31 会诊 #2（流中断丢全部已收内容）：网络级失败（ECONNRESET / 半截 EOF /
     // proxy 断连）时若已解析出内容，把 partial 交回上层而不是整轮报废重试。
     // 标记 partial:true + networkError（上层可决定续写/重试/展示部分结果）。
     if (hasChoices && (result.content || result.toolCalls.length)) {
       finalizeToolCalls(result)
       result.partial = true
-      result.networkError = e.message ?? String(e)
+      result.networkError = err.message ?? String(err)
       const existing = result._warnings ??= []
       if (!existing.some((w) => w.name === "network-partial")) {
         existing.push({ name: "network-partial", message: `stream interrupted by network error after partial output: ${result.networkError}` })
       }
       return result
     }
-    throw e
+    throw err
   }
 
   if (idleTimer) clearTimeout(idleTimer)

package/proxy.mjs

@@ -7,6 +7,7 @@ import { connect as tlsConnect } from "node:tls";
 import { PassThrough } from "node:stream";
 import { URL } from "node:url";
 import { abortError, timeoutError } from "./abort-provenance.mjs";
+import { IDLE_ABORT, destroyBody } from "./stream-destroy.mjs";
 
 const FETCH_TIMEOUT = 15_000
 
@@ -91,12 +92,12 @@ export function streamHttpResponse(sock, urlStr, opts = {}, timeout = FETCH_TIME
     function fail(err) {
       cleanup()
       if (!settled) { settled = true; reject(err) }
-      else body.destroy(err)
+      else destroyBody(body, err)
     }
     /** body 阶段空闲看门狗：每次数据到达重置；无数据超时 → 断流（流式消费方抛错） */
     function armIdle() {
       clearTimeout(idleTimer)
-      if (bodyIdleMs > 0) idleTimer = setTimeout(() => body.destroy(timeoutError("Response body timeout (idle)", "provider", "proxy-body-idle")), bodyIdleMs)
+      if (bodyIdleMs > 0) idleTimer = setTimeout(() => destroyBody(body, timeoutError("Response body timeout (idle)", "provider", "proxy-body-idle")), bodyIdleMs)
     }
 
     sock.on("data", (d) => {
@@ -261,9 +262,18 @@ function tcpConnectProxy(proxyUri, signal, timeout) {
 /**
  * Generic fetch with proxy support.
  * No proxy → native fetch. Proxy + HTTPS → CONNECT tunnel. Proxy + HTTP → 经典代理转发（绝对 URI 请求行）。
+ * 直连分支 = 内部 abort 通道建设点（#878 D-PX8）：建 `AbortController` + signal 合成（`AbortSignal.any`，
+ * 无 user signal 时单独用）后经 `IDLE_ABORT` 挂 response——web `ReadableStream` 的读侧看门狗
+ * （`readSSE` ∥ `parseGeminiStream`）经 `terminateBody` 恢复有效；proxy 两分支不挂（自有 `_bodyIdleMs`）。
  */
 export async function proxyFetch(urlStr, opts, proxyUri) {
-  if (!proxyUri) return globalThis.fetch(urlStr, opts)
+  if (!proxyUri) {
+    const idleAbort = new AbortController()
+    const signal = opts?.signal ? AbortSignal.any([opts.signal, idleAbort.signal]) : idleAbort.signal
+    const response = await globalThis.fetch(urlStr, { ...opts, signal })
+    response[IDLE_ABORT] = idleAbort
+    return response
+  }
   const target = new URL(urlStr)
   if (target.protocol === "https:") return tunnelHttps(urlStr, opts, proxyUri)
   // http:// 目标：TCP 直连代理，请求行发绝对 URI（GET http://host/path HTTP/1.1）

package/session.mjs

@@ -106,8 +106,11 @@ function digestFromStore(fields, counters, mtimeMs) {
  *  Restore now always rebuilds from history (lazy, see startup.mjs).
  *  2026-08-31 会诊 F1：slot 粘性——首次认领后缓存 agent._slot，永不重跑 ensureActive
  *  （原实现每次保存重推，manifest active 被并发方翻动时会话静默迁移）。
- *  返回轮转的 .bak 路径或 null。 */
-export function saveSession(agent) {
+ *  返回轮转的 .bak 路径或 null。
+ *  **`opts.prefsSeedOnly`（加性 · 2026-10-04 解锁批 · R2——唯一传者 = 桌面两落盘点）**：回合关联落盘
+ *  **不携会话级三键**（`provider` / `model` / `effort`）——写前读槽：复合在场（`activeProvider` 非空串 ∧
+ *  `activeModel` 真值）⇒ 槽值赢 ∥ 缺 ⇒ 记忆值播种；`effort` 单键在场（值可 `null`）⇒ 槽值保留。 */
+export function saveSession(agent, opts = {}) {
   // _fullHistory is written at the source via pushReal — no flush needed here.
   // history        = FULL, never-compacted (human-readable; VS Code panel & CLI resume read this)
   // contextHistory = machine context (possibly compacted) so CLI resume keeps the token savings
@@ -168,6 +171,14 @@ export function saveSession(agent) {
   // 原值——`"off"` 记号原样写盘，不回填为具体档）；缺之 ⇒ 下一次回合保存把槽写面结果整对象抹除。
   // `undefined` = 本会话未携带（老槽无该键 / 未经 `applySession`）⇒ 键不落盘（禁回填）。
   if (agent._slotEffort !== undefined) fields.effort = agent._slotEffort
+  // R2（2026-10-04 解锁批 · 加性 `prefsSeedOnly`）：回合关联落盘**不携三键**——写前读槽（守卫后：轮转现场不参与判据），
+  // 复合在场（`activeProvider` 非空串 ∧ `activeModel` 真值）⇒ 槽值赢（防起跑快照覆写忙期新选定）∥ 缺 ⇒ 记忆值播种。
+  if (opts.prefsSeedOnly === true) {
+    const onDisk = loadSlotFile(agent.cwd, slot) ?? {}
+    const compositeOn = typeof onDisk.activeProvider === "string" && onDisk.activeProvider !== "" && Boolean(onDisk.activeModel)
+    if (compositeOn) Object.assign(fields, { activeProvider: onDisk.activeProvider, activeModel: onDisk.activeModel })
+    if (Object.hasOwn(onDisk, "effort")) fields.effort = onDisk.effort ?? null
+  }
   // 绑定态 → 流式投影（段原文拼接——VSC 兼容面逐字同形）；未绑定 → 既有全量物化写
   if (agent._recordStore) saveProjectedSlot(agent, p, fields, contextHistory)
   else writeSessionFile(p, { ...fields, history: legacyHistory(agent), contextHistory })

package/stream-destroy.mjs

@@ -0,0 +1,62 @@
+/**
+ * stream-destroy.mjs — response body 终止守卫（单一权威源——PROXY.md §2 ∥ §7 D-PX7）
+ *
+ * 无监听者瞬间的 `destroy(err)` 会 emit 未处理 'error' ⇒ uncaughtException ⇒ 整个进程被杀
+ * （2026-09-22/23 三份 crash-report 签名 = `Response body timeout (idle)`，栈 = proxy.mjs
+ * 看门狗；GitHub #16）。`destroyBody(body, err)` 在终止前先挂**永久** no-op `'error'`
+ * 监听者——pipe 内部监听者触发即自摘后的重发同样被兜住；消费面语义零变（在场 ∥ 迟到
+ * `for-await` 消费者仍收原错误；`stream.errored` 保留原错误对象）。
+ *
+ * 契约四则（PROXY.md §2）：
+ * ① body 空 ∥ 非 destroy 形态（web `ReadableStream`）∥ 已 `destroyed` ⇒ 显式返回（no-op）；
+ * ② 首次调用挂永久 no-op 'error' 监听者（一次性标记防重复挂）；
+ * ③ 再 `destroy(err)`——原错误对象直传；
+ * ④ 禁 `listenerCount('error') === 0` 预检（pipe 监听者使计数失真——触发即自摘后重发）。
+ *
+ * 内部 abort 通道（2026-10-04 · #878 D-PX8）：直连 fetch 的 body = web `ReadableStream`（无
+ * `destroy`——本档形态①的 no-op 面）。断流改经 `IDLE_ABORT` 符号挂载的 `AbortController`：
+ * `terminateBody(response, err)` 对挂通道者 `controller.abort(err)`（body 随之中止）；无通道回落
+ * `destroyBody`（原契约零变）。建设点 = `proxy.mjs` `proxyFetch` 直连分支单点。
+ *
+ * 零 import——proxy ∥ provider 消费点共用（无环）。
+ */
+
+/** 一次性标记（模块私有 Symbol——不占 body 公开面）。 */
+const GUARDED = Symbol("thincoder.destroyBody.guarded")
+
+/**
+ * 终止 body，且未处理 'error' 不逃逸到进程（契约四则见档头）。
+ * @param {import("node:stream").Stream} body — response body（PassThrough）；
+ *   web `ReadableStream`（无 destroy）⇒ 显式 no-op
+ * @param {Error} err — 原错误对象（直传 destroy）
+ */
+export function destroyBody(body, err) {
+  if (!body || typeof body.destroy !== "function" || body.destroyed) return
+  if (!body[GUARDED]) {
+    body[GUARDED] = true
+    body.on("error", () => {})
+  }
+  body.destroy(err)
+}
+
+/** 内部 abort 通道符号（#878 D-PX8——直连 fetch 响应的断流通道；module-private 语义面）。 */
+export const IDLE_ABORT = Symbol("thincoder.idleAbort")
+
+/**
+ * body 终止分流单点（#878）：
+ * - response 挂有 `IDLE_ABORT`（直连 fetch——web `ReadableStream`）⇒ `controller.abort(err)`
+ *   （读循环随之终结；原错误对象即 abort reason——undici 以该对象拒读）；
+ * - 否则回落 `destroyBody(response.body, err)`（proxy PassThrough ∥ 无通道 web 流——原契约零变）。
+ * response 缺位 / 无 body ⇒ no-op 不抛（幂等——二次调用对 AbortController 原生安全）。
+ * @param {Response|{body?: import("node:stream").Stream}} response
+ * @param {Error} err — 原错误对象（abort reason ∥ destroy 直传）
+ */
+export function terminateBody(response, err) {
+  if (!response) return
+  const controller = response[IDLE_ABORT]
+  if (controller) {
+    controller.abort(err)
+    return
+  }
+  destroyBody(response.body, err)
+}

package/tool-docs/verify.md

@@ -1 +1 @@
-Generic pre-completion verification gate — language/framework/project agnostic. verify does NOT run any test/verification command for you and does NOT require a test per change. You DECLARE your verification status via the verification argument ({ status: 'passed' | 'failed' | 'skipped', command?, summary? } — effects per parameter): the declaration is self-reported evidence — verify only mechanically gates on it ('passed' → allowed; 'failed' → blocked; 'skipped' → allowed but needs a reason). Whether/how to verify is described in natural language in the project's AGENTS.md and is decided + executed by you. The report also carries the changed files (git diff), an advisory node --check hint on changed .js/.mjs (not gating), the task list, and a self-review checklist. Call this BEFORE declaring a coding task complete — do not say 'done' until verify passes.
+Generic pre-completion verification gate — language/framework/project agnostic. verify does NOT run any test/verification command for you and does NOT require a test per change. You DECLARE your verification status via the verification argument ({ status: 'passed' | 'failed' | 'skipped', command?, summary?, basis? } — effects per parameter): the declaration is self-reported evidence — verify only mechanically gates on it ('passed' → allowed; 'failed' → blocked; 'skipped' → allowed but needs a reason). 'basis' (optional) is the 'what it stands on' dimension of the declaration — a judgment source, a read file:line coordinate, or an explicit 'unverified' (declaration-only: no format is enforced or machine-checked); a passed / skipped declaration with no basis gets one advisory hint line in the report — never blocking and never changing the gate — while the failed face gets no basis hint (already blocked). Whether/how to verify is described in natural language in the project's AGENTS.md and is decided + executed by you. The report also carries the changed files (git diff), an advisory node --check hint on changed .js/.mjs (not gating), the task list, and a self-review checklist. Call this BEFORE declaring a coding task complete — do not say 'done' until verify passes.

package/tools/edit-batch.mjs

@@ -23,7 +23,8 @@ import { assertEditArgsExclusive, assertEditsContainer, assertEditEntries, valid
 
 /**
  * Apply the `edits` array form: multi-file atomic replacement. Throws on any
- * failure (atomic — nothing written). Returns the per-entry result text (joined).
+ * failure (atomic — nothing written). Returns the per-entry result text (joined)
+ * + the constant batch summary line at the end (#796 — EDIT.md §5).
  */
 export async function applyEditBatch(args, ctx) {
   assertEditsContainer(args.edits)
@@ -105,7 +106,11 @@ export async function applyEditBatch(args, ctx) {
       note: p.note,
     }))
   }
-  return results.join("\n")
+  // #796（核面小修批——EDIT.md §5 批量回执汇总行 ∥ §8 D-9）：末行**恒为**汇总行——大回执
+  // （>64K）落盘后双端 preview 保尾（TOOL-OUTPUT-LIMITS.md §2）⇒ 汇总结论恒可见；N = 条目数
+  // （全判后原子写 ⇒ 成功恒 N/N）；路径 = 条目原样形、去重保序首现序（groups 插入序即首现序）。
+  const summary = `edit batch: ${args.edits.length}/${args.edits.length} entries — ${[...groups.values()].map((g) => g.path).join(", ")}`
+  return [...results, summary].join("\n")
 }
 
 // ---------------------------------------------------------------------------

package/undo-stack.mjs

@@ -6,13 +6,23 @@
  * 属核内面，函数本体零 TUI 依赖 ⇒ 按核内结构归位到核；`/undo` 命令面 `handleUndoCommand`
  * 留 CLI 壳——S2 由壳 import 本档）。
  *
+ * 双上界（#863 · TUI-COMMANDS.md §5.3）：单条备份超 `MAX_UNDO_BYTES` ⇒ **oversize 占位**条目
+ * （`oversize: true` · `backup: null`——列表可见 · 不可回退；与「文件创建」态靠 `oversize` 字段分判，
+ * 消费面 = `cmd-undo.mjs` 先判该字段再判 `backup === null`）；总量超 `MAX_UNDO_TOTAL_BYTES`
+ * ⇒ 逐最旧驱逐（条数上限 `MAX_UNDO` 保留）。
+ *
  * Tracks write/edit/delete/hashline_edit/apply_patch operations in agent._undoStack.
  */
 
-import { existsSync, readFileSync } from "node:fs"
+import { existsSync, readFileSync, statSync } from "node:fs"
 import { isAbsolute, join } from "node:path"
 
 const MAX_UNDO = 50
+const MAX_UNDO_BYTES = 10_000_000             // 10 MB — 单条备份上界（= tools/file.mjs 大档 read 守卫同值）
+const MAX_UNDO_TOTAL_BYTES = 64_000_000       // 64 MB — 备份总预算（超限逐最旧驱逐）
+
+/** 条目预算字节数（oversize 占位 ∥ 文件创建态（backup = null）不占预算）。 */
+const backupBytes = (e) => (typeof e?.backup === "string" ? Buffer.byteLength(e.backup, "utf8") : 0)
 
 /**
  * Snapshot a file before a side-effect tool modifies it.
@@ -26,22 +36,26 @@ export function snapshotForUndo(agent, toolName, args, cwd) {
   // 绝对路径直接用（path.join 对绝对段不重置——Windows 反斜杠路径也不按 "/" 切分）；相对路径整段 join(cwd)。
   const abs = isAbsolute(path) ? path : join(cwd, path)
   let backup = null
+  let oversize = false
   try {
     if (existsSync(abs)) {
-      backup = readFileSync(abs, "utf8")
+      if (statSync(abs).size > MAX_UNDO_BYTES) oversize = true // 大档不入内存——占位条目（与「文件创建」态分判）
+      else backup = readFileSync(abs, "utf8")
     }
   } catch {
     // can't read — maybe binary, skip
     return
   }
 
-  agent._undoStack.push({
-    tool: toolName,
-    path,
-    backup,
-    timestamp: Date.now(),
-  })
+  agent._undoStack.push(oversize
+    ? { tool: toolName, path, backup: null, oversize: true, timestamp: Date.now() }
+    : { tool: toolName, path, backup, timestamp: Date.now() })
   if (agent._undoStack.length > MAX_UNDO) agent._undoStack.shift()
+  // 总量上界：超限逐最旧驱逐（按字节预算计——条数上界保留）。
+  let total = agent._undoStack.reduce((n, e) => n + backupBytes(e), 0)
+  while (total > MAX_UNDO_TOTAL_BYTES && agent._undoStack.length > 0) {
+    total -= backupBytes(agent._undoStack.shift())
+  }
 }
 
-export { MAX_UNDO }
+export { MAX_UNDO, MAX_UNDO_BYTES, MAX_UNDO_TOTAL_BYTES }