minimal-agent 0.13.0 → 0.14.0

package/src/config/numericLimits.js

@@ -17,6 +17,20 @@
  * 边界，否则又回到多份真值。
  */
 export const CONFIG_LIMITS = {
+    /** 同一进程同时运行的顶层动态工作流数。 */
+    workflowMaxActiveRuns: { min: 1, max: 64, step: 1, kind: 'integer' },
+    /** 同一进程动态工作流共享的模型并发。 */
+    workflowModelConcurrency: { min: 1, max: 64, step: 1, kind: 'integer' },
+    /** 同一进程动态工作流共享的工具并发。 */
+    workflowToolConcurrency: { min: 1, max: 128, step: 1, kind: 'integer' },
+    /** 同一进程动态工作流共享的外部进程并发。 */
+    workflowProcessConcurrency: { min: 1, max: 64, step: 1, kind: 'integer' },
+    /** 单个 pipeline 的默认 item 并发。 */
+    workflowPipelineConcurrency: { min: 1, max: 32, step: 1, kind: 'integer' },
+    /** 工作流可为单个 pipeline 显式申请的最大并发。 */
+    workflowPipelineMaxConcurrency: { min: 1, max: 32, step: 1, kind: 'integer' },
+    /** 一棵父子工作流调用树的调用总量熔断。 */
+    workflowMaxCalls: { min: 1, max: 100_000, step: 100, kind: 'integer' },
     /** 顾问单次咨询喂进去的输入 token 上限。上界给到 200 万是为了容纳百万级上下文模型；
      *  真正生效值还会再被「所选顾问模型的 contextWindow」二次收窄（见 advisor.ts）。 */
     advisorInputTokenBudget: { min: 1_000, max: 2_000_000, step: 1_000, kind: 'integer' },
@@ -32,6 +46,14 @@ export const CONFIG_LIMITS = {
     subagentExploreMaxTurns: { min: 5, max: 500, step: 5, kind: 'integer' },
     /** general（读写执行）子任务的轮数上限。 */
     subagentGeneralMaxTurns: { min: 10, max: 1_000, step: 10, kind: 'integer' },
+    /** Goal 的 token 预算上限（input+output 之和）。⚠️ 它是**可选**的：
+     *  不设 = 不限（契约里存 `null`，不是 0 —— 0 会被判成「一开始就超了」）。
+     *  这条边界只在用户真的填了数字时约束它。 */
+    goalTokenBudget: { min: 1_000, max: 100_000_000, step: 1_000, kind: 'integer' },
+    /** `verify()` 里 `shell:` 检查的默认超时（毫秒）。默认值在
+     *  `infra/verification.ts::DEFAULT_SHELL_CHECK_TIMEOUT_MS`；上界给到 10 分钟，
+     *  容纳「必须跑一整个测试套件才算数」的硬门，但默认仍保持 30s 以免阻塞流水线。 */
+    verifyShellTimeoutMs: { min: 1_000, max: 600_000, step: 1_000, kind: 'integer' },
     /** 电脑操作每帧画面的像素预算。 */
     computerUseMaxImagePixels: { min: 100_000, max: 10_000_000, step: 100_000, kind: 'integer' },
     /** 自动压缩触发阈值，占 contextWindow 的比例（0,1]。UI 按百分比展示，保留 2 位小数。 */

package/src/config/numericLimits.ts

@@ -27,6 +27,20 @@ export interface NumericLimit {
 }
 
 export const CONFIG_LIMITS = {
+  /** 同一进程同时运行的顶层动态工作流数。 */
+  workflowMaxActiveRuns: { min: 1, max: 64, step: 1, kind: 'integer' },
+  /** 同一进程动态工作流共享的模型并发。 */
+  workflowModelConcurrency: { min: 1, max: 64, step: 1, kind: 'integer' },
+  /** 同一进程动态工作流共享的工具并发。 */
+  workflowToolConcurrency: { min: 1, max: 128, step: 1, kind: 'integer' },
+  /** 同一进程动态工作流共享的外部进程并发。 */
+  workflowProcessConcurrency: { min: 1, max: 64, step: 1, kind: 'integer' },
+  /** 单个 pipeline 的默认 item 并发。 */
+  workflowPipelineConcurrency: { min: 1, max: 32, step: 1, kind: 'integer' },
+  /** 工作流可为单个 pipeline 显式申请的最大并发。 */
+  workflowPipelineMaxConcurrency: { min: 1, max: 32, step: 1, kind: 'integer' },
+  /** 一棵父子工作流调用树的调用总量熔断。 */
+  workflowMaxCalls: { min: 1, max: 100_000, step: 100, kind: 'integer' },
   /** 顾问单次咨询喂进去的输入 token 上限。上界给到 200 万是为了容纳百万级上下文模型；
    *  真正生效值还会再被「所选顾问模型的 contextWindow」二次收窄（见 advisor.ts）。 */
   advisorInputTokenBudget: { min: 1_000, max: 2_000_000, step: 1_000, kind: 'integer' },
@@ -44,6 +58,16 @@ export const CONFIG_LIMITS = {
   /** general（读写执行）子任务的轮数上限。 */
   subagentGeneralMaxTurns: { min: 10, max: 1_000, step: 10, kind: 'integer' },
 
+  /** Goal 的 token 预算上限（input+output 之和）。⚠️ 它是**可选**的：
+   *  不设 = 不限（契约里存 `null`，不是 0 —— 0 会被判成「一开始就超了」）。
+   *  这条边界只在用户真的填了数字时约束它。 */
+  goalTokenBudget: { min: 1_000, max: 100_000_000, step: 1_000, kind: 'integer' },
+
+  /** `verify()` 里 `shell:` 检查的默认超时（毫秒）。默认值在
+   *  `infra/verification.ts::DEFAULT_SHELL_CHECK_TIMEOUT_MS`；上界给到 10 分钟，
+   *  容纳「必须跑一整个测试套件才算数」的硬门，但默认仍保持 30s 以免阻塞流水线。 */
+  verifyShellTimeoutMs: { min: 1_000, max: 600_000, step: 1_000, kind: 'integer' },
+
   /** 电脑操作每帧画面的像素预算。 */
   computerUseMaxImagePixels: { min: 100_000, max: 10_000_000, step: 100_000, kind: 'integer' },
 

package/src/config.js

@@ -78,6 +78,7 @@ export async function loadProvider() {
     const compactRatio = parseCompactRatio(process.env.MINIMAL_AGENT_COMPACT_RATIO);
     const maxTokens = parsePositiveInt(process.env.MINIMAL_AGENT_MAX_TOKENS) ?? DEFAULT_MAX_TOKENS;
     return {
+        source: 'local',
         name: process.env.MINIMAL_AGENT_PROVIDER ?? 'env',
         baseURL,
         apiKey,

package/src/config.ts

@@ -17,7 +17,7 @@
  */
 
 import { configService } from './config/configService.js';
-import type { Provider } from './types.js';
+import type { LocalProvider, Provider } from './types.js';
 
 const DEFAULT_CONTEXT_WINDOW = 128_000;
 
@@ -52,7 +52,7 @@ function parseCompactRatio(raw: string | undefined): number | undefined {
  * 加载 Provider 配置（从环境变量）。
  * 缺少必需变量时抛出明确错误。
  */
-export async function loadProvider(): Promise<Provider> {
+export async function loadProvider(): Promise<LocalProvider> {
   const baseURL = process.env.MINIMAL_AGENT_BASE_URL;
   const apiKey = process.env.MINIMAL_AGENT_API_KEY;
   const model = process.env.MINIMAL_AGENT_MODEL;
@@ -88,6 +88,7 @@ export async function loadProvider(): Promise<Provider> {
     parsePositiveInt(process.env.MINIMAL_AGENT_MAX_TOKENS) ?? DEFAULT_MAX_TOKENS;
 
   return {
+    source: 'local',
     name: process.env.MINIMAL_AGENT_PROVIDER ?? 'env',
     baseURL,
     apiKey,

package/src/context/budgetPlan.js

@@ -20,7 +20,7 @@ export function buildContextBudgetPlan(input) {
         overBudget: totalInputTokens > inputLimit,
     };
 }
-const AUXILIARY_REMOVAL_ORDER = ['Advisor', 'Agent'];
+const AUXILIARY_REMOVAL_ORDER = ['AdvisorDecision', 'Advisor', 'Agent'];
 /**
  * Last-resort schema reduction. Normal requests keep the full catalog; this is
  * used only after history compaction still cannot fit the provider window.

package/src/context/budgetPlan.ts

@@ -47,7 +47,7 @@ export interface EmergencyToolFit {
   plan: ContextBudgetPlan;
 }
 
-const AUXILIARY_REMOVAL_ORDER = ['Advisor', 'Agent'];
+const AUXILIARY_REMOVAL_ORDER = ['AdvisorDecision', 'Advisor', 'Agent'];
 
 /**
  * Last-resort schema reduction. Normal requests keep the full catalog; this is

package/src/context/compact.js

@@ -292,6 +292,9 @@ export function findTailWithCompleteToolChains(messages, minKeep = MIN_KEEP_RECE
  * @param opts     可选的辅助数据，用于校正系统性低估：
  *   - actualPromptTokens：本轮 LLM done 事件返回的真实 prompt token 数（如有）
  *   - toolsTokens：工具 schema 占的估算 token 数（由 estimateToolsTokens 算出）
+ *   - serverDeletedTokens：cacheEdits 模式下，服务端已删除但本地 history 仍完整
+ *     存在的内容的 token 估算（CacheEditsState.activeDeletedTokens）--先从历史
+ *     估算里扣掉再进 max，否则虚高的一方永远获胜，压缩会过早触发
  * @returns 可能更短的新 messages 数组（不修改原数组）
  *
  * 判据（取"真实 usage"与"估算+工具token"两者之大者）：
@@ -303,8 +306,10 @@ export function findTailWithCompleteToolChains(messages, minKeep = MIN_KEEP_RECE
  */
 export async function autoCompactIfNeeded(messages, provider, opts) {
     const before = countMessagesTokens(messages); // 纯历史 token，保持语义不变（UI/snip/对比均依赖此值）
-    // 判据：真实 usage（若有）与「估算 + 工具 schema」取大者，校正系统性低估
-    const estimated = before + (opts?.toolsTokens ?? 0) + (opts?.transientTokens ?? 0);
+    // 判据：真实 usage（若有）与「估算 + 工具 schema」取大者，校正系统性低估。
+    // serverDeletedTokens 只从历史部分（before）里扣--它对应 history 里的已删内容，
+    // 与工具 schema / transient 无关；扣完再进 max，真实 usage 才有机会主导判据。
+    const estimated = before - (opts?.serverDeletedTokens ?? 0) + (opts?.toolsTokens ?? 0) + (opts?.transientTokens ?? 0);
     const judge = Math.max(opts?.actualPromptTokens ?? 0, estimated);
     const threshold = getCompactThreshold(provider);
     if (judge < threshold) {

package/src/context/compact.ts

@@ -353,6 +353,9 @@ export function findTailWithCompleteToolChains(
  * @param opts     可选的辅助数据，用于校正系统性低估：
  *   - actualPromptTokens：本轮 LLM done 事件返回的真实 prompt token 数（如有）
  *   - toolsTokens：工具 schema 占的估算 token 数（由 estimateToolsTokens 算出）
+ *   - serverDeletedTokens：cacheEdits 模式下，服务端已删除但本地 history 仍完整
+ *     存在的内容的 token 估算（CacheEditsState.activeDeletedTokens）--先从历史
+ *     估算里扣掉再进 max，否则虚高的一方永远获胜，压缩会过早触发
  * @returns 可能更短的新 messages 数组（不修改原数组）
  *
  * 判据（取"真实 usage"与"估算+工具token"两者之大者）：
@@ -369,6 +372,8 @@ export async function autoCompactIfNeeded(
     actualPromptTokens?: number;
     toolsTokens?: number;
     transientTokens?: number;
+    /** cacheEdits 模式的估算校正量：服务端已删、本地未删的 token（见函数头注） */
+    serverDeletedTokens?: number;
     signal?: AbortSignal;
     promptCache?: PromptCacheContext;
     /** 注入 chat 实现（仅测试用，验证 signal 透传；生产不传走默认实现）。 */
@@ -376,8 +381,10 @@ export async function autoCompactIfNeeded(
   },
 ): Promise<AutoCompactResult> {
   const before = countMessagesTokens(messages); // 纯历史 token，保持语义不变（UI/snip/对比均依赖此值）
-  // 判据：真实 usage（若有）与「估算 + 工具 schema」取大者，校正系统性低估
-  const estimated = before + (opts?.toolsTokens ?? 0) + (opts?.transientTokens ?? 0);
+  // 判据：真实 usage（若有）与「估算 + 工具 schema」取大者，校正系统性低估。
+  // serverDeletedTokens 只从历史部分（before）里扣--它对应 history 里的已删内容，
+  // 与工具 schema / transient 无关；扣完再进 max，真实 usage 才有机会主导判据。
+  const estimated = before - (opts?.serverDeletedTokens ?? 0) + (opts?.toolsTokens ?? 0) + (opts?.transientTokens ?? 0);
   const judge = Math.max(opts?.actualPromptTokens ?? 0, estimated);
   const threshold = getCompactThreshold(provider);
   if (judge < threshold) {

package/src/context/microCompactLite.js

@@ -1,6 +1,6 @@
 /**
  * ============================================================
- *  src/context/microCompactLite.ts —— 工具结果微压缩（v2）
+ *  src/context/microCompactLite.ts —— 工具结果微压缩（v4）
  * ------------------------------------------------------------
  *  对齐 kakadeai 的 microCompact 设计，纯规则实现，零 LLM 调用。
  *
@@ -8,14 +8,30 @@
  *    工具执行结果在写入 history 前经过一道"单向检查门"，
  *    用规则压缩冗余内容，减少 token 消耗但不丢失关键信息。
  *
- *  对齐 kakadeai 的两条有效路径：
+ *  对齐 kakadeai 的三条有效路径（本实现对高价值工具更保守）：
  *    Path A: Cached MC → 本方案用 SHA-1 进程缓存 + 计数淘汰实现
  *    Path B: Time-based MC → 本方案用轮次衰减实现
+ *    Path C: 批量回收 → reclaimOldToolResults：低风险工具结果数超阈值时，
+ *            只保留最近几条的完整内容，其余按模式处理：
+ *            - inline（默认，全 provider 可用）：本地 history 原地替换为占位符。
+ *              wire token 真实减少，代价是前缀缓存从被改消息起失效。
+ *            - cacheEdits（v4，Anthropic 格式 + provider.cacheEdits 开启）：本地
+ *              history **不改**，删除目标记入 CacheEditsState，由 anthropicFormat
+ *              组装 cache_edits block 随请求发送——对齐 kakadeai Cached MC 的
+ *              triggerThreshold/keepRecent 语义与服务端原地删除效果：模型看到
+ *              的上下文变短、前缀缓存完整保留。
  *
  *  kakadeai 已删除 Legacy LLM path → 本方案不实现 LLM 压缩
+ *
+ *  为什么需要 Path C：SHA-1 去重要求内容完全相同才计数，
+ *  而真实工具结果带行号/时间戳/文件内容，几乎不会完全重复——去重路径
+ *  形同虚设，工具结果实际全部永久留在 history 里。这是 minimal-agent
+ *  上下文膨胀比 kakadeai 快得多的根因（工具结果 token 占比 60-80%）。
  * ============================================================
  */
-import { createHash } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
+import { countTextTokens } from './tokenCounter.js';
+import { clearToolResultArchive } from './toolResultArchive.js';
 // ==================== 配置常量 ====================
 /** 同一内容最多原样保留多少次，之后用压缩引用替代 */
 const MAX_REPEAT_COUNT = 3;
@@ -29,8 +45,28 @@ const TAIL_KEEP_CHARS = 1000;
 const MAX_KEEP_ROUNDS = 10;
 /** 短内容阈值：不超过此长度的内容直接放行（不做任何处理） */
 const SHORT_CONTENT_THRESHOLD = 200;
+/** Path C 批量回收：可回收工具结果的存活数量超过该值时触发回收 */
+const RECLAIM_TRIGGER_THRESHOLD = 8;
+/** Path C 批量回收：触发后保留最近多少条完整内容（热尾部） */
+const RECLAIM_KEEP_RECENT = 4;
+/**
+ * Path C 批量回收的占位符前缀。用 startsWith 检测已回收的消息，
+ * 保证幂等（不会重复计数、重复替换）。刻意与去重标记 `[↑ `、
+ * 截断标记 `[... 省略了` 不同字形，避免互相误判。
+ */
+const RECLAIM_MARKER_PREFIX = '[旧工具结果已回收';
+function createEmptyCacheEdits() {
+    return { deletedToolIds: new Set(), pinned: [], pendingNew: [], activeDeletedTokens: 0 };
+}
 export function createMicroCompactState() {
-    return { turn: 0, cache: new Map() };
+    return {
+        turn: 0,
+        cache: new Map(),
+        reclaimedCount: 0,
+        reclaimedChars: 0,
+        archiveKey: randomUUID(),
+        cacheEdits: createEmptyCacheEdits(),
+    };
 }
 const defaultState = createMicroCompactState();
 export function incrementTurn(state = defaultState) {
@@ -57,24 +93,51 @@ export function getCacheStats(state = defaultState) {
             expiredCount++;
         }
     }
-    return { totalEntries: state.cache.size, repeatedCount, compressedCount, expiredCount, truncatedCount, totalCharsSaved };
+    return {
+        totalEntries: state.cache.size,
+        repeatedCount,
+        compressedCount,
+        expiredCount,
+        truncatedCount,
+        totalCharsSaved,
+        reclaimedCount: state.reclaimedCount,
+        reclaimedChars: state.reclaimedChars,
+    };
 }
 /** 清空缓存（供 /new 命令或测试使用） */
 export function clearCache(state = defaultState) {
     state.cache.clear();
     state.turn = 0;
+    state.reclaimedCount = 0;
+    state.reclaimedChars = 0;
+    void clearToolResultArchive(state.archiveKey);
+    state.archiveKey = randomUUID();
+    resetCacheEdits(state);
+}
+/**
+ * 重置 cacheEdits 状态。调用时机（漏掉任何一个都会造成下标错位或重复删除）：
+ *  - autoCompact / 手动 compact 之后：history 被砍头重写，pinned 的翻译后下标
+ *    全部失义，服务端缓存前缀也已失效，编辑指令没有继续存在的意义。
+ *  - /new 新会话（clearCache 内已调用）。
+ */
+export function resetCacheEdits(state = defaultState) {
+    state.cacheEdits.deletedToolIds.clear();
+    state.cacheEdits.pinned.length = 0;
+    state.cacheEdits.pendingNew.length = 0;
+    // 有效删除量一并清零：compact 后历史被重写，旧删除账目对应的内容可能已不在
+    // 新历史里，不清零会让 autoCompact 校正过度（判据虚低 -> 该压不压撑爆上下文）。
+    state.cacheEdits.activeDeletedTokens = 0;
 }
 // ==================== 工具白名单 ====================
 /**
- * 只有这些工具的返回值参与微压缩（长度截断 + SHA-1 去重）。
+ * 只有低风险观察工具的返回值参与长度截断（SHA-1 去重对所有工具生效）。
  *
- * 排除 Read/Edit/Write 的原因：输出本身就短，有独立的大小限制。
- * 排除 WebSearch 的原因：搜索结果是"一次性知识注入"，首次必须完整展示给模型；
- *   后续重复时由 SHA-1 去重处理，但不做长度截断（避免丢失关键信息）。
+ * Read/Edit/Write/Bash/WebSearch 默认不截断：它们可能包含源码中段、diff、
+ * 一次性诊断或不可复现证据。超大结果由 toolResultArchive 先保存原文并提供可恢复引用。
+ * 低风险工具仍保留头尾截断，以控制普通搜索结果的上下文成本。
  */
 const COMPRESSIBLE_TOOLS = new Set([
     'Grep',
-    'Bash',
     'WebFetch',
     'Glob',
 ]);
@@ -94,7 +157,7 @@ const COMPRESSIBLE_TOOLS = new Set([
  * @param content 工具返回的原始内容
  * @returns 处理后的内容（可能被压缩、截断、或原样返回）
  */
-export function microCompact(toolName, content, state = defaultState) {
+export function microCompact(toolName, content, state = defaultState, policy = getToolResultPolicy(toolName)) {
     if (!content)
         return content;
     // Rule 0: 错误信息原样保留
@@ -118,8 +181,8 @@ export function microCompact(toolName, content, state = defaultState) {
     // 首次看到此内容
     state.cache.set(hash, { count: 1, firstToolName: toolName, firstSeenTurn: state.turn });
     // Rule 2: 不需要——首次出现不存在时间衰减问题
-    // Rule 3: 长度截断（仅白名单工具）
-    if (content.length > MAX_RESULT_SIZE && COMPRESSIBLE_TOOLS.has(toolName)) {
+    // Rule 3: 长度截断（仅低风险工具；高价值结果禁止不可逆中段丢弃）
+    if (!policy.highValue && content.length > MAX_RESULT_SIZE && COMPRESSIBLE_TOOLS.has(toolName)) {
         return truncateContent(content);
     }
     return content;
@@ -139,10 +202,146 @@ export function expireOldEntries(state = defaultState) {
     }
     return expired;
 }
+// ==================== Path C: 批量回收旧工具结果 ====================
+/**
+ * 可回收的工具集合：仅保留低风险观察工具。即便这些工具通常可重放，
+ * 高价值结果也可通过 tool_result_policy 显式保护，不会因为工具名而强行清掉。
+ *
+ * 刻意排除高价值/不可稳定重放的工具：
+ *  - Bash / WebSearch：一次性诊断和外部搜索结果可能无法复现
+ *  - Read / Edit / Write：源码中段、diff 或生成内容可能是后续推理证据
+ *  - Ask / AskUserQuestion：用户答案不可重放，清了就永远丢了
+ *  - Task / agent 系：子任务结论昂贵且常被后续轮次引用
+ *  - PresentResult：最终交付物清单，是本轮对话的核心产出
+ */
+const RECLAIMABLE_TOOLS = new Set([
+    'Grep',
+    'Glob',
+    'WebFetch',
+]);
+const EMPTY_RECLAIM_STATS = { reclaimedCount: 0, reclaimedChars: 0 };
+/**
+ * Path C：批量回收旧工具结果（每轮 LLM 调用前执行）。
+ *
+ * 语义（对齐 kakadeai Cached MC 的 triggerThreshold / keepRecent）：
+ *   history 中"存活"的可回收工具结果数量 > RECLAIM_TRIGGER_THRESHOLD 时，
+ *   只保留最近 RECLAIM_KEEP_RECENT 条的完整内容（热尾部），其余按 mode 处理：
+ *   - 'inline'（默认）：原地替换为占位符（含工具名与被替换的字符数，
+ *     模型需要时可重新调用该工具）。
+ *   - 'cacheEdits'：**不改 history**——删除目标（tool_call_id）记入
+ *     state.cacheEdits.pendingNew，由 anthropicFormat 组装 cache_edits block
+ *     随请求发送，服务端在 KV 缓存内原地删除。
+ *
+ * 设计约束与取舍：
+ *   1. inline 只改 tool 消息的 content，tool_call_id / display_metadata 原样保留——
+ *      API 协议完整性不受影响，且 display_metadata 在发送 Provider 前本就
+ *      被剥离（仅本地展示用），所以 UI 渲染不受影响。
+ *   2. 幂等：inline 用占位符前缀（RECLAIM_MARKER_PREFIX）检测已回收消息；
+ *      cacheEdits 用 deletedToolIds 集合检测。已回收的不计入候选、不二次处理。
+ *      触发频率 = 每攒 (阈值-保留数) 条新结果触发一次。
+ *   3. 跳过 Error 结果（短且常是排障线索）和 ≤200 字符的短结果
+ *      （占位符本身就有 ~60 字符，清短结果纯亏）。
+ *   4. 缓存代价（模式差异的核心）：
+ *      inline 直接改 history，前缀缓存从被改消息起失效——换 wire token 真实
+ *      削减，一次缓存重建几轮就回本，适用于无 cache_edits 能力的端点（含全部
+ *      OpenAI 格式 provider）。
+ *      cacheEdits 本地不动、服务端原地删——前缀 hash 不变、缓存命中完整保留；
+ *      代价是 wire 上完整内容仍要发送（省的是服务端 KV 驻留与模型注意力窗口，
+ *      不是请求体积）。reclaimedChars 在此模式下统计的是"服务端删除的内容量"。
+ *   5. tool_call_id → 工具名的映射来自 assistant 消息的 tool_calls 数组，
+ *      扫一遍 history 即得，不需要额外状态。
+ *   6. cacheEdits 模式下本函数只做决策不做协议——它不认识 Anthropic 消息形状，
+ *      翻译后下标由 anthropicFormat 的组装函数负责回填（见其 pinned 逻辑）。
+ *
+ * @param history 完整会话历史（inline 模式原地修改命中的 tool 消息；cacheEdits 模式只读）
+ * @param state 微压缩状态（累计统计写入 reclaimedCount / reclaimedChars；cacheEdits 模式另写 pendingNew）
+ * @param mode 'inline'（默认）| 'cacheEdits'（Anthropic 格式 + provider.cacheEdits）
+ * @returns 本次回收的条数与字符数（未触发时全为 0）
+ */
+export function reclaimOldToolResults(history, state = defaultState, mode = 'inline') {
+    // 1. 建立 tool_call_id → 工具名 映射
+    const toolNameById = new Map();
+    for (const msg of history) {
+        if (msg.role !== 'assistant' || !msg.tool_calls)
+            continue;
+        for (const tc of msg.tool_calls) {
+            if (tc.id && tc.function?.name)
+                toolNameById.set(tc.id, tc.function.name);
+        }
+    }
+    // 2. 收集可回收候选：白名单工具 + 存活（未回收过）+ 非错误 + 非短内容
+    //    存活判据按模式分叉：inline 看占位符前缀，cacheEdits 看 deletedToolIds。
+    const candidates = [];
+    for (const msg of history) {
+        if (msg.role !== 'tool' || typeof msg.content !== 'string')
+            continue;
+        const content = msg.content;
+        if (content.startsWith(RECLAIM_MARKER_PREFIX))
+            continue;
+        if (content.startsWith('Error:') || content.startsWith('错误'))
+            continue;
+        if (content.length <= SHORT_CONTENT_THRESHOLD)
+            continue;
+        const toolCallId = msg.tool_call_id;
+        const toolName = toolCallId ? toolNameById.get(toolCallId) : undefined;
+        const policy = msg.tool_result_policy ?? (toolName ? getToolResultPolicy(toolName) : undefined);
+        if (!toolCallId
+            || !toolName
+            || !RECLAIMABLE_TOOLS.has(toolName)
+            || !policy?.reclaimable
+            || policy.highValue)
+            continue;
+        if (mode === 'cacheEdits' && state.cacheEdits.deletedToolIds.has(toolCallId))
+            continue;
+        candidates.push({ msg: msg, toolCallId, chars: content.length });
+    }
+    // 3. 未超阈值不动（> 而非 >=：恰好等于阈值视为健康水位）
+    if (candidates.length <= RECLAIM_TRIGGER_THRESHOLD) {
+        return EMPTY_RECLAIM_STATS;
+    }
+    // 4. 保留热尾部（按消息顺序的最后 KEEP_RECENT 条），其余按模式处理
+    const toClear = candidates.slice(0, candidates.length - RECLAIM_KEEP_RECENT);
+    let reclaimedChars = 0;
+    if (mode === 'cacheEdits') {
+        for (const { msg, toolCallId, chars } of toClear) {
+            state.cacheEdits.deletedToolIds.add(toolCallId);
+            state.cacheEdits.pendingNew.push(toolCallId);
+            // 累计有效删除量（token 估算，与 tokenCounter 同一套系数）：
+            // autoCompact 判据用它校正「本地 history 未瘦身」造成的虚高估算。
+            state.cacheEdits.activeDeletedTokens += countTextTokens(msg.content);
+            reclaimedChars += chars;
+        }
+    }
+    else {
+        for (const { msg, toolCallId, chars } of toClear) {
+            const toolName = toolNameById.get(toolCallId) ?? 'tool';
+            reclaimedChars += chars;
+            const archiveHint = msg.tool_result_policy?.archiveRef
+                ? ` | 完整原文可用 Read 读取：${msg.tool_result_policy.archiveRef}`
+                : '';
+            msg.content =
+                `${RECLAIM_MARKER_PREFIX} | ${toolName} | 原本 ${chars.toLocaleString()} 字符${archiveHint} | ` +
+                    `如需再次查看请重新调用该工具]`;
+        }
+    }
+    // 5. 累计统计（getCacheStats 可查，观测回收效果）
+    state.reclaimedCount += toClear.length;
+    state.reclaimedChars += reclaimedChars;
+    return { reclaimedCount: toClear.length, reclaimedChars };
+}
 // ==================== 内部函数 ====================
 function sha1(str) {
     return createHash('sha1').update(str).digest('hex');
 }
+export function getToolResultPolicy(toolName) {
+    // Bash/WebSearch/Read/Edit/Write 等结果可能包含一次性诊断、关键源码或不可复现证据，
+    // 默认高价值且不可回收；低风险观察工具才进入 Path C。
+    const reclaimable = RECLAIMABLE_TOOLS.has(toolName);
+    return {
+        reclaimable,
+        highValue: !reclaimable,
+    };
+}
 function truncateContent(content) {
     const omitted = content.length - HEAD_KEEP_CHARS - TAIL_KEEP_CHARS;
     return (content.slice(0, HEAD_KEEP_CHARS) +