mocode-ai 0.4.0 → 0.4.1

package/dist/context/lifecycle.js

@@ -0,0 +1,384 @@
+// Observation Lifecycle Engine:tool 消息的「观察者生命周期」状态机。
+//
+// 在 Relevance Pruner 之上的第二层被动裁剪。Relevance Pruner 只管 read_file 的「同 path 新旧替换 +
+// mutation 覆写」,本层补足「grep/glob/codegraph 这类观察类工具」的引用追踪。
+//
+// 四态机(LIVE → REFERENCED → OBSOLETE → STUB):
+//   - LIVE:刚 push 进 history 的工具结果,尚未被任何下游工具消费。
+//   - REFERENCED:被某个下游 read_file/edit_file/write_file 引用过(基于 path 字符串匹配)。
+//   - OBSOLETE:无任何消费者引用,且距离当前 push 已老化 N 步(默认 2)。
+//   - STUB:已被替换为存根(物理上 content 变成「⌦[无消费者:...]」)。
+//
+// 用户拍板的激进风险护栏(避免误伤):
+//   - grep/glob/codegraph/web_search/web_fetch 等「观察/检索类」工具,**永远只到 REFERENCED**,
+//     不参与自动 STUB。理由:返回多个候选(grep 10 文件但你只读 1 个),剩余候选可能后续被消费。
+//   - 当前轮保护区(最后一个 user 之后的工具结果)完全不动。
+//   - 已 STUB(含「⌦[已过时:...]」或「⌦[已剔除:...]」或本层的「⌦[无消费者:...]」)不重复处理。
+//   - 永不抛错(对齐上下文管道的「调度器永不抛错」契约)。
+//   - 只改 .content,不动 tool_call_id / 不删消息 / 不动 tool_calls 数组。
+//
+// 与 Relevance Pruner 的分工(不重复):
+//   - Relevance Pruner:管 read_file 同 path 旧 read + mutation 覆写 → 直接 STUB。
+//   - 本层:管「无消费者的观察类工具老化后 → STUB」 + 「被消费的工具 → REFERENCED 标记(可视)」。
+//
+// 触发点(agent/core.ts):
+//   - pushToolResult 出口,新 message idx = history.length - 1。
+//   - mutation 分支额外调 pushMutation 通知(也走 observeMutation 同语义)。
+//
+// 开关:`config.contextLifecycle`(默认 true;MOCODE_LIFECYCLE=false 回退)。
+/** 观察类工具(永远只到 REFERENCED,不参与自动 STUB)。 */
+const OBSERVER_TOOLS = new Set([
+    'grep',
+    'glob',
+    'codegraph',
+    'web_search',
+    'web_fetch',
+]);
+/** 消费者工具(这些工具的 push 会触发「上游被消费」标记)。
+ *  只列能基于 path 静态判定消费的;run_command/memory_* 等不参与(避免误伤)。 */
+const CONSUMER_TOOLS = new Set(['read_file', 'edit_file', 'write_file']);
+/** mutation 工具:pushTool 跳过 autoStubOrphans(让 pushMutation 标完 read REFERENCED 再统一老化)。 */
+const MUTATION_TOOLS = new Set(['edit_file', 'write_file']);
+/** 存根前缀(区分 Relevance Pruner 与 drop_context)。 */
+const STUB_PREFIX_NO_CONSUMER = '⌦[无消费者:观察结果已无引用价值]';
+/** 老化阈值:某条工具消息自 push 以来经历的「消费者 push」次数。
+ *  ≥ 这个值且仍为 LIVE 且非观察类 → 视为 OBSOLETE → STUB。
+ *  默认 2:等价于「跨过两个消费者 push 仍无人引用」= 跨过整轮最末尾的工具调用。 */
+const DEFAULT_AGE_THRESHOLD = 2;
+/** 复用 drop.ts 的取 path 思路,但本层要支持更多字段名(read_file/edit_file/write_file 都有 path;
+ *  edit_file 还可能有 file_path,但这里只看 path,保持单一)。 */
+function extractPath(argsRaw) {
+    if (!argsRaw)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(argsRaw);
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== 'object')
+        return null;
+    const p = parsed.path;
+    return typeof p === 'string' && p ? p : null;
+}
+/** 从 tool 消息往前找匹配的 assistant.tool_calls 拿 tool 名。找不到返 null(保守跳过)。 */
+function toolNameOf(history, idx) {
+    const tcId = history[idx].tool_call_id;
+    if (!tcId)
+        return null;
+    for (let j = idx - 1; j >= 1; j--) {
+        const m = history[j];
+        if (m.role !== 'assistant')
+            continue;
+        const tcs = m.tool_calls;
+        if (!tcs)
+            continue;
+        const hit = tcs.find((tc) => tc?.id === tcId);
+        if (hit)
+            return hit.function?.name ?? null;
+    }
+    return null;
+}
+/** 找最后一个 user 消息索引;无 user 返 -1。 */
+function lastUserIndex(history) {
+    for (let i = history.length - 1; i >= 1; i--) {
+        if (history[i].role === 'user')
+            return i;
+    }
+    return -1;
+}
+function toText(content) {
+    if (content == null)
+        return '';
+    if (typeof content === 'string')
+        return content;
+    try {
+        return JSON.stringify(content);
+    }
+    catch {
+        return String(content);
+    }
+}
+/** 从 tool 结果的 content 中提取「生产者命中过的 path 列表」。
+ *  - read_file:没有 path 列表(本身就是单 path 消费者,无需再追生产者)。
+ *  - grep:content 是 `file:line: ...` 行,提取每行的 file 段(只保留绝对路径形态或与 pattern 匹配的)。
+ *    简化:把所有看起来像「相对路径 + 文件名」的 token 抽出,留 narrow。
+ *  - glob:content 是路径列表,按行 / 空格拆。
+ *  - codegraph:content 里通常含 `path/to/file.ts:line`,按行拆,提 file 段。
+ *
+ *  返回值:命中过的 path 字符串集合(已 dedup)。失败返空集。 */
+function extractProducerPaths(toolName, content) {
+    if (!content)
+        return [];
+    const out = new Set();
+    try {
+        if (toolName === 'grep') {
+            // 典型行:`src/foo.ts:42: hello world` 或 `path\to\file.ts:42: ...`
+            // 取冒号前段(冒号必须跟在数字前面避免切到路径里的冒号)。
+            const re = /^([^\s:][^:]*?\.[A-Za-z0-9]+):(\d+):/gm;
+            let m;
+            while ((m = re.exec(content)))
+                out.add(m[1]);
+        }
+        else if (toolName === 'glob') {
+            // glob 输出一般是「paths:」+ 换行 + 多路径;每行一个绝对或相对路径。
+            // 简化:按行切,跳过含空格的(避免命中 prose),取看起来像路径的行。
+            for (const line of content.split(/\r?\n/)) {
+                const t = line.trim();
+                if (!t || t.includes(' '))
+                    continue;
+                // 含扩展名或含路径分隔符
+                if (/\.[A-Za-z0-9]+$/.test(t) || t.includes('/') || t.includes('\\'))
+                    out.add(t);
+            }
+        }
+        else if (toolName === 'codegraph') {
+            // codegraph 输出通常 `path\to\file.ts:line:col  symbol` 或类似;按行 + 冒号分隔。
+            for (const line of content.split(/\r?\n/)) {
+                const m = /^([^\s:][^:]*?\.[A-Za-z0-9]+):(\d+):/.exec(line);
+                if (m)
+                    out.add(m[1]);
+            }
+        }
+        else if (toolName === 'web_search' || toolName === 'web_fetch') {
+            // 网络结果不在文件系统路径范畴;不参与 producer 路径索引(避免误匹配)。
+        }
+    }
+    catch {
+        // 永不抛错:任何解析失败返当前累积。
+    }
+    return [...out];
+}
+/**
+ * Observation Lifecycle Engine。
+ * 每个 runAgentCore 实例持一个;pushToolResult 出口调 pushTool、mutation 分支调 pushMutation。
+ * 内部 try/catch 兜底,对外永不抛错。
+ */
+export class LifecycleEngine {
+    ageThreshold;
+    /** 工具消息 idx → 状态。 */
+    states = new Map();
+    /** 工具消息 idx → 被消费的次数(同一上游被多次消费也只算 REFERENCED,不计并发)。 */
+    consumerCount = new Map();
+    /** 工具消息 idx → 自 push 以来的「消费者 push」次数(用于老化判定)。
+     * 每次 pushTool 触发,所有 LIVE 工具消息 age++。 */
+    age = new Map();
+    /** producer 路径 → 生产者工具消息 idx 列表(逆查用:某个 path 被消费时,反查上游 producer)。
+     * 注意:不存 read_file,因为 read 自身就是消费者不充当 producer。 */
+    producersByPath = new Map();
+    /** 当前步序号(用于 age 老化:每次 pushTool 自增,对比 age 阈值)。 */
+    step = 0;
+    /** 最后 user 索引缓存(pushTool 时重算;pushMutation 时也重算,因为 mutation 可能跟 user 同行)。 */
+    lastUser = -1;
+    constructor(ageThreshold = DEFAULT_AGE_THRESHOLD) {
+        this.ageThreshold = ageThreshold;
+    }
+    /** 新工具结果 push 进 history 时调;idx = history.length - 1。
+     *  mutation 工具(edit_file/write_file)的 push 跳过本轮的 autoStubOrphans(由调用方在
+     *  pushMutation 标完 read REFERENCED 之后再触发),避免刚被 mutation 消费的 read 被提前 STUB。 */
+    pushTool(history, idx) {
+        try {
+            const m = history[idx];
+            if (!m || m.role !== 'tool')
+                return;
+            const toolName = toolNameOf(history, idx);
+            if (!toolName)
+                return;
+            // 已 stub 的不重复登记(幂等)。
+            const c = toText(m.content);
+            if (c.startsWith('⌦['))
+                return;
+            // 登记为 LIVE。
+            this.states.set(idx, 'LIVE');
+            this.consumerCount.set(idx, 0);
+            this.age.set(idx, 0);
+            // 如果是 producer 类工具(grep/glob/codegraph),登记其命中的路径。
+            if (OBSERVER_TOOLS.has(toolName)) {
+                const paths = extractProducerPaths(toolName, c);
+                for (const p of paths) {
+                    const arr = this.producersByPath.get(p) ?? [];
+                    if (!arr.includes(idx))
+                        arr.push(idx);
+                    this.producersByPath.set(p, arr);
+                }
+            }
+            // 如果是 consumer 类工具(read/edit/write),找出上游「被消费的 producer」,标 REFERENCED。
+            if (CONSUMER_TOOLS.has(toolName)) {
+                const argsRaw = (() => {
+                    // tool 消息本身没有 args;args 在前导 assistant.tool_calls 里;直接走同 idx 前的 assistant。
+                    const tcId = m.tool_call_id;
+                    for (let j = idx - 1; j >= 1; j--) {
+                        const mm = history[j];
+                        if (mm.role !== 'assistant')
+                            continue;
+                        const tcs = mm.tool_calls;
+                        const hit = tcs?.find((tc) => tc?.id === tcId);
+                        if (hit)
+                            return hit.function?.arguments ?? '';
+                    }
+                    return '';
+                })();
+                const path = extractPath(argsRaw);
+                if (path) {
+                    // 1) 找该 path 的所有上游 producer(grep/glob/codegraph)→ 标 REFERENCED。
+                    const producers = this.producersByPath.get(path);
+                    if (producers) {
+                        for (const pidx of producers) {
+                            if (this.states.get(pidx) === 'LIVE') {
+                                this.states.set(pidx, 'REFERENCED');
+                            }
+                            this.consumerCount.set(pidx, (this.consumerCount.get(pidx) ?? 0) + 1);
+                        }
+                    }
+                    // 2) 同 path 的旧 read_file(被本 read「替代」)→ 也标 REFERENCED(由 Relevance Pruner 已 stub)。
+                    //    这里不重复操作,Relevance Pruner 那边管「内容已被新 read 替代」的语义。
+                }
+            }
+            // 所有 LIVE 工具消息 age++(本次 push 算一步)。stale 的 READ 消息也涨 age,直到 ≥ 阈值才可能 STUB。
+            for (const k of this.states.keys()) {
+                this.age.set(k, (this.age.get(k) ?? 0) + 1);
+            }
+            this.step++;
+            this.lastUser = lastUserIndex(history);
+            // mutation 工具跳过本轮 autoStubOrphans:调用方会调 pushMutation 标完 read REFERENCED 后,
+            // 再调 flushAutoStub 触发老化检查,避免 read 在被标 REFERENCED 之前被提前 STUB。
+            if (MUTATION_TOOLS.has(toolName))
+                return;
+            // 老化检查:本次 push 完,扫描 LIVE(且非观察类)的工具消息,age ≥ 阈值 → 标 OBSOLETE → STUB。
+            this.autoStubOrphans(history);
+        }
+        catch {
+            // 永不抛错。
+        }
+    }
+    /** mutation 工具(edit_file/write_file)push 后调。语义与 pushTool 一致,但额外标记「被 mutation 消费」的 read。
+     *  注意:本层不直接 stub read(那是 Relevance Pruner 的职责);本层只更新状态图。
+     *  注意:puhToolResult 出口已经登记过 mutation 本身,这里不再调 pushTool(避免 age 翻倍)。 */
+    pushMutation(history, mutationIdx, path) {
+        try {
+            // mutation 自身已在 pushToolResult 出口登记(若 lifecycle 存在);此处仅做「mutation 是
+            // path 的消费者」语义:把该 path 在 mutation 之前的所有 read_file(未被 stub 的 LIVE/REFERENCED)
+            // 标 REFERENCED。
+            const protectedFrom = Math.max(0, this.lastUser);
+            for (let i = 1; i < mutationIdx; i++) {
+                if (i >= protectedFrom)
+                    continue;
+                const m = history[i];
+                if (m?.role !== 'tool')
+                    continue;
+                const tn = toolNameOf(history, i);
+                if (tn !== 'read_file')
+                    continue;
+                const c = toText(m.content);
+                if (c.startsWith('⌦['))
+                    continue;
+                const argsRaw = this.findToolArgs(history, i);
+                if (extractPath(argsRaw) === path) {
+                    if (this.states.get(i) === 'LIVE')
+                        this.states.set(i, 'REFERENCED');
+                    this.consumerCount.set(i, (this.consumerCount.get(i) ?? 0) + 1);
+                }
+            }
+            // 标完 read REFERENCED 后,统一跑老化检查(本次 mutation push 之前 pushTool 已跳过)。
+            this.autoStubOrphans(history);
+        }
+        catch {
+            // 永不抛错。
+        }
+    }
+    /** 老化自动 STUB:扫描所有 LIVE(且非观察类)且 age ≥ 阈值且不在保护区的工具消息 → OBSOLETE → STUB。 */
+    autoStubOrphans(history) {
+        try {
+            const protectedFrom = Math.max(0, this.lastUser);
+            for (const [idx, state] of this.states) {
+                if (state !== 'LIVE')
+                    continue;
+                if (idx >= protectedFrom)
+                    continue; // 当前轮保护区
+                const age = this.age.get(idx) ?? 0;
+                if (age < this.ageThreshold)
+                    continue;
+                const tn = toolNameOf(history, idx);
+                if (!tn)
+                    continue;
+                // 观察类工具永远只到 REFERENCED,不自动 STUB(用户拍板)。
+                if (OBSERVER_TOOLS.has(tn)) {
+                    this.states.set(idx, 'REFERENCED');
+                    continue;
+                }
+                // 执行 STUB。
+                this.stubOne(history, idx, tn);
+            }
+        }
+        catch {
+            // 永不抛错。
+        }
+    }
+    /** 实际替换 content 为存根。 */
+    stubOne(history, idx, toolName) {
+        try {
+            const m = history[idx];
+            if (!m)
+                return;
+            const c = toText(m.content);
+            if (c.startsWith('⌦['))
+                return; // 幂等
+            const origLen = c.length;
+            const stub = `${STUB_PREFIX_NO_CONSUMER} ${toolName} ${origLen} 字符 → 老化无消费者,自动归档`;
+            m.content = stub;
+            this.states.set(idx, 'STUB');
+        }
+        catch {
+            // 永不抛错。
+        }
+    }
+    /** 找某条 tool 消息对应的 assistant.tool_calls.arguments。 */
+    findToolArgs(history, idx) {
+        try {
+            const tcId = history[idx].tool_call_id;
+            if (!tcId)
+                return '';
+            for (let j = idx - 1; j >= 1; j--) {
+                const mm = history[j];
+                if (mm.role !== 'assistant')
+                    continue;
+                const tcs = mm.tool_calls;
+                const hit = tcs?.find((tc) => tc?.id === tcId);
+                if (hit)
+                    return hit.function?.arguments ?? '';
+            }
+        }
+        catch {
+            // 永不抛错。
+        }
+        return '';
+    }
+    // ── 观测 API(供 /context 面板、调试脚本用) ─────────────────────────────
+    /** 拿某 idx 的当前状态;不在图里返 null。 */
+    getState(idx) {
+        return this.states.get(idx) ?? null;
+    }
+    /** 拿当前各状态计数。供 /context 显示「live=N, referenced=M, obsolete=K, stubbed=S」。 */
+    stats() {
+        let live = 0;
+        let referenced = 0;
+        let obsolete = 0;
+        let stubbed = 0;
+        for (const s of this.states.values()) {
+            if (s === 'LIVE')
+                live++;
+            else if (s === 'REFERENCED')
+                referenced++;
+            else if (s === 'OBSOLETE')
+                obsolete++;
+            else if (s === 'STUB')
+                stubbed++;
+        }
+        return { live, referenced, obsolete, stubbed };
+    }
+}
+/** 默认单例工厂。runAgentCore 入口 new 一个,后续 pushTool / pushMutation 共享。 */
+export function createLifecycleEngine(ageThreshold) {
+    return new LifecycleEngine(ageThreshold);
+}

package/dist/context/relevance.js

@@ -0,0 +1,284 @@
+// Relevance Pruner:read_file 相关性裁剪(纯静态分析,零 LLM 调用)。
+//
+// 场景(用户描述):
+//   1) read foo.ts → 后来又 read foo.ts → 旧结果无价值 → 替换为存根
+//   2) read foo.ts → edit foo.ts → read foo.ts → 中间那次 read 之前的所有旧 read
+//      在 mutation 之后已失效 → 替换为存根
+//
+// 与现有子系统的关系:
+//   - Context Optimization Pipeline(`pipeline.ts`):单条上限 + 类型化编码。本层在其外,
+//     在 pushToolResult 出口再做一次"跨条"裁剪。
+//   - drop_context(`session/drop.ts`):agent 主动剔除已知无关的旧 tool 结果。本层是被动自动,
+//     不需要 agent 调;两者并存不冲突。
+//   - compact(`session/compact.ts`):阈值触发的整体微压缩+摘要。本层只裁"明确失效"的旧 read,
+//     不触发摘要;门槛更低、零成本。
+//
+// 不变量(对齐 drop_context / compact):
+//   - 只改 .content,不删消息、不动 tool_call_id、不动 tool_calls 数组结构。
+//   - 当前轮保护区:不剔除"最后一个 user 消息及其之后"的 read_file 结果(agent 本轮还在用,
+//     剔除会破坏正在进行的推理)。实现复用 drop.ts 的 lastUserIndex 思路。
+//   - 幂等:已 stub(含「已过时」标记)不重复 stub,避免反复重写同一条消息。
+//   - 永不抛错(对齐「调度器永不抛错」契约);无匹配 / 解析失败 / 异常 → 静默 no-op。
+//   - TUI 渲染(hooks.onToolResult)用原始 output,与本层解耦——屏上看全量,LLM 看裁剪后版。
+//
+// 零行为变化兜底:开关 `config.contextRelprune` 关闭时,pipeline 路径完全不调本模块。
+/** stub 标记前缀(供幂等判定)。drop_context 用的是「⌦[已剔除:与当前任务无关]」,
+ *  本层用「⌦[已过时:同 path 已有新 read / 已被 mutation 覆写]」,区分两类剔除来源。 */
+const STUB_PREFIX = '⌦[已过时:同 path 已有新 read / 已被 mutation 覆写]';
+/** 解析工具 arguments(只关心 path);非法返 null。 */
+function extractPath(argsRaw) {
+    if (!argsRaw)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(argsRaw);
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== 'object')
+        return null;
+    const p = parsed.path;
+    if (typeof p !== 'string' || !p)
+        return null;
+    return p;
+}
+/** 从 history 末尾向前找最后一个 user 消息的索引;无 user 返 -1。
+ *  复用 drop.ts 的思路:user 及其之后的 tool 结果视为当前轮保护区。
+ *  在本层里,read_file tool 消息若落在 user 之后,本轮还在用,不能 stub。
+ *  注:history[0] 是 system,user 不会落在 0;若 user 就在末尾(即 0 user 之后),
+ *  protectedFrom=0 时整段历史都不可 stub(实际不会发生:pushToolResult 必在 user 之后)。 */
+function lastUserIndex(history) {
+    for (let i = history.length - 1; i >= 1; i--) {
+        if (history[i].role === 'user')
+            return i;
+    }
+    return -1;
+}
+/** 取 tool 消息对应的工具名(从紧邻的前导 assistant.tool_calls 按 tool_call_id 配对找)。
+ *  返回 null 表示找不到(孤儿 tool,极少见),本层保守不动。 */
+function toolNameOf(history, idx) {
+    const tcId = history[idx].tool_call_id;
+    if (!tcId)
+        return null;
+    for (let j = idx - 1; j >= 1; j--) {
+        const m = history[j];
+        if (m.role !== 'assistant')
+            continue;
+        const tcs = m.tool_calls;
+        if (!tcs)
+            continue;
+        const hit = tcs.find((tc) => tc?.id === tcId);
+        if (hit)
+            return hit.function?.name ?? null;
+    }
+    return null;
+}
+/** 把 content 拍平成字符串(对齐 drop.ts)。 */
+function toText(content) {
+    if (content == null)
+        return '';
+    if (typeof content === 'string')
+        return content;
+    try {
+        return JSON.stringify(content);
+    }
+    catch {
+        return String(content);
+    }
+}
+/**
+ * 维护「path → 该 path 所有 read_file tool 消息的 history index」映射。
+ *  - observePush:把刚 push 的 read_file tool 消息登记,并把同 path 的"更早" read 全部 stub。
+ *  - observeMutation:把该 mutation path 的"在 mutation 之前的" read 全部 stub。
+ *
+ * 设计:每个 agent 会话(每个 runAgentCore 实例)持有一个 pruner。会话结束/换 plan 时
+ * 可新建;不持久化(history 重建时索引自然过期)。
+ *
+ * 零依赖:仅依赖 ChatMessage 形状;不 import llm / tools / agent。
+ */
+export class RelevancePruner {
+    /** path → [history index, ...]  按插入序;最新在末尾。 */
+    readByPath = new Map();
+    /** 把刚 push 的消息通知 pruner。
+     *  - 只处理 tool 消息(role==='tool')。
+     *  - 只关心 read_file:登记 + 反向 stub 同 path 旧 read。
+     *  - 非 read_file 的 tool 消息:无操作(本层只管 read_file)。
+     *  - 非 tool 消息(assistant / user / system):无操作。
+     */
+    observePush(history, msg) {
+        try {
+            if (msg.role !== 'tool')
+                return;
+            const m = msg;
+            const tcId = m.tool_call_id;
+            if (!tcId)
+                return;
+            const idx = history.length - 1;
+            if (idx < 1 || history[idx] !== msg)
+                return; // 防御:必须刚 push 到末尾
+            const name = toolNameOf(history, idx);
+            if (name !== 'read_file')
+                return;
+            const content = toText(msg.content);
+            if (content.startsWith(STUB_PREFIX))
+                return; // 已是存根(防御)
+            // 从前导 assistant.tool_calls 找对应 tc.arguments(精确 path 来源)。
+            // 退化方案:从消息内容首行解析路径(read_file 输出形如 `\n     1\t...`,无 path;
+            // 故必须从 args 取)。找不到则保守不动。
+            let path = null;
+            for (let j = idx - 1; j >= 1; j--) {
+                const mm = history[j];
+                if (mm.role !== 'assistant')
+                    continue;
+                const tcs = mm.tool_calls;
+                if (!tcs)
+                    continue;
+                const hit = tcs.find((tc) => tc?.id === tcId);
+                if (hit) {
+                    path = extractPath(hit.function?.arguments);
+                    break;
+                }
+            }
+            if (!path)
+                return;
+            // 先 stub 旧 read(同 path,idx 之前),再登记新 idx。
+            this.stubPriorReads(history, path, idx);
+            // 登记新 idx
+            const list = this.readByPath.get(path);
+            if (list)
+                list.push(idx);
+            else
+                this.readByPath.set(path, [idx]);
+        }
+        catch {
+            /* 永不抛错 */
+        }
+    }
+    /**
+     * 把该 mutation path 的"在 mutation 之前的" read 全部 stub。
+     * 通常用于 edit_file / write_file 工具:mutation 之后,之前的 read_file(p) 内容
+     * 已失效(已不再是文件当前状态),模型后续若依赖旧 read 来 edit_file 会失败,但 edit_file
+     * 的 old_string 来自模型记忆/后读,不依赖旧 read 结果文本。
+     *
+     * 调用时机:agent/core.ts 在 mutation 工具调用的 pushToolResult 之后立即调;
+     * 此时 history 末尾就是 mutation 的 tool 消息,prior reads 指 < idx。
+     */
+    observeMutation(history, path) {
+        try {
+            if (!path)
+                return;
+            const idx = history.length - 1;
+            if (idx < 1)
+                return;
+            // mutation 之前的所有同 path read → stub
+            this.stubPriorReads(history, path, idx);
+            // 该 path 的 read 索引全部作废(mutation 之后再 read 会重新登记)
+            this.readByPath.delete(path);
+        }
+        catch {
+            /* 永不抛错 */
+        }
+    }
+    /**
+     * 把 history 里 "path 同 + index < beforeIdx + 不在当前轮保护区" 的所有 read_file
+     * tool 消息替换为存根(只改 .content,不动 id / 数组结构)。
+     *
+     * 实现:
+     *  - 用 readByPath[path] 直接拿到所有 index(已登记过),筛 < beforeIdx 的 stub。
+     *  - 同时扫一遍 [1, beforeIdx) 区间找未登记的(防御:索引可能漏登;不依赖索引也能 stub,
+     *    保证正确性。索引只用于"避免重复扫全表"的优化)。
+     *  - protectedFrom = lastUserIndex(history):user 之后一律不动。
+     *  - 幂等:已是 STUB_PREFIX 的跳过。
+     */
+    stubPriorReads(history, path, beforeIdx) {
+        const STUB_PREFIX_LOCAL = STUB_PREFIX;
+        const guard = lastUserIndex(history);
+        // protectedFrom = 最后一个 user index(若 >0);user 之后(>= guard)的 read 永不动。
+        // protectedFrom=0 表示无 user(history 只有 system),整段都可 stub。
+        const protectedFrom = guard > 0 ? guard : 0;
+        const stubOne = (i) => {
+            if (i >= beforeIdx)
+                return;
+            if (i >= protectedFrom && protectedFrom > 0)
+                return; // 当前轮保护区
+            const m = history[i];
+            if (!m || m.role !== 'tool')
+                return;
+            const content = toText(m.content);
+            if (content.startsWith(STUB_PREFIX_LOCAL))
+                return; // 幂等
+            const name = toolNameOf(history, i);
+            if (name !== 'read_file')
+                return;
+            // 校验 tool_call_id 配对(防御:孤儿子消息不动)
+            const tcId = m.tool_call_id;
+            if (!tcId)
+                return;
+            const stub = `${STUB_PREFIX_LOCAL} read_file(${path}) ${content.length} 字符 → 已被新 read / mutation 替代 · id …${tcId.slice(-6)}⌫`;
+            m.content = stub;
+        };
+        // 1) 用 Map 索引(快路径)
+        const indexed = this.readByPath.get(path);
+        if (indexed) {
+            for (const i of indexed)
+                stubOne(i);
+        }
+        // 2) 全表扫一遍(防御:索引可能漏登 / 历史来自 resume)
+        //    仅扫 [1, beforeIdx) 且不在保护区内的 range,成本可控。
+        const scanEnd = Math.min(beforeIdx, protectedFrom > 0 ? protectedFrom : beforeIdx);
+        for (let i = 1; i < scanEnd; i++) {
+            stubOne(i);
+        }
+    }
+}
+/** 默认单例:每个 agent 循环一个。runAgentCore 入口 new 一个,后续 observe 共享。 */
+export function createRelevancePruner() {
+    return new RelevancePruner();
+}
+/** 解析一条 stub 字符串,提取原 content 长度(若可解析)。失败返 null。 */
+function parseStubOriginalLen(stub) {
+    // 格式:⌦[已过时:同 path 已有新 read / 已被 mutation 覆写] read_file(<path>) <N> 字符 → ...
+    const m = / read_file\([^)]+\) (\d+) 字符 /.exec(stub);
+    if (!m)
+        return null;
+    const n = Number(m[1]);
+    return Number.isFinite(n) && n >= 0 ? n : null;
+}
+/**
+ * 扫 history,统计被相关性裁剪 stub 的 read_file tool 消息(条数 + 原字节数)。
+ * 供 /context 渲染统计行用(让用户直观看到「prune 帮了多少」)。
+ * 永不抛错(对齐本模块契约);history 为空 / 无 stub 时返零值。
+ *
+ * 注意:stub 后只剩 stub 字符串(原 content 已丢失),故只能从 stub 字符串里 parse
+ * 原字节数,误差 = stub 时记录的 content.length(精确);token 估算走 estimateTokens。
+ */
+export function computePruneStats(history) {
+    let stubbed = 0;
+    let originalChars = 0;
+    let stubChars = 0;
+    for (const m of history) {
+        if (m.role !== 'tool')
+            continue;
+        const c = toText(m.content);
+        if (!c.startsWith(STUB_PREFIX))
+            continue;
+        stubbed++;
+        stubChars += c.length;
+        const orig = parseStubOriginalLen(c);
+        if (orig != null)
+            originalChars += orig;
+    }
+    // token 估算:用 estimateTokens(懒导入,避免循环依赖 llm)
+    // 这里偷懒:走粗略 chars/4(中文混合下会过估,安全侧)
+    // 准确应调 estimateTokens,但 /context 已经是粗算,误差可接受
+    const originalTokens = Math.ceil(originalChars / 4);
+    const stubTokens = Math.ceil(stubChars / 4);
+    return {
+        stubbed,
+        originalChars,
+        originalTokens,
+        stubChars,
+        freedTokens: Math.max(0, originalTokens - stubTokens),
+    };
+}