mocode-ai 0.4.0 → 0.4.2

package/dist/context/budget.js

@@ -0,0 +1,225 @@
+// 五区 Context Budget Scheduler。
+//
+// 目的:把当前四道独立闸(cap / pipeline / relevance / maybeCompact)统一为
+//       「先看预算报告,再按 ROI 排序调度」的单一入口。
+//
+// 设计原则(对应用户拍板的设计方案):
+//   1. 五区分账:不是把 history 当一个黑盒,而是把上下文切成 5 区逐区配预算
+//      (System / History / Tool-Recent / Tool-Old / Summary) + 1 个 Reserve。
+//      Tool 内部再分 Hot/Cold:
+//        - Cold Tool(老化区,scheduler 优先压缩——ROI 最低,LLM 复述成本最低)
+//        - Hot Tool(当前±N 步内,scheduler **不主动 stub**——避免干扰 agent 当前步)
+//      注:**Hot 区「scheduler 不主动」≠ 「绝对不动」**。lifecycle age stub、pruner
+//      same-path 替代、agent 的 drop_context 工具仍可动 Hot 区;它们语义更精细(知道
+//      哪条已无关),不会盲目 stub。Scheduler 只在更粗的层面决策,粗判断不踩精细判断。
+//      Hot 区超预算时 scheduler 仅 cap(降单条上限,不丢内容)。
+//   2. ROI 排序:History > Summary > Hot Tool > Cold Tool。压缩时先动 Cold Tool
+//      (LLM 复述成本最低),再动 History(摘要成本高);Hot Tool 与 System 雷打不动(指 scheduler 层面)。
+//   3. 零行为变化兜底:调度器不是闸,而是「报告 + 决策」——执行仍复用现有
+//      cap / pipeline / relevance / compact / lifecycle / drop_context 实现,只是触发条件更精准。
+//
+// 依赖:本文件是叶子级,只依赖 ChatMessage / estimateTokens,绝不反向依赖
+//      agent / session / compact(避免循环与耦合)。具体执行动作由 agent/core.ts
+//      拿 ScheduleAction[] 去调现有闸。
+//
+// 开关(MOCODE_BUDGET_SCHEDULER):默认 true。false 时 agent/core.ts 走老路径
+//      (直接 maybeCompact),完全跳过本模块,零行为变化。
+import { estimateMessagesTokens, estimateTokens } from '../llm/index.js';
+/** 五区分账(占比对齐 CONTEXT_WINDOW)。顺序固定,便于遍历。 */
+export const BUDGET_LAYERS = [
+    'system',
+    'history',
+    'toolRecent', // Hot Tool
+    'toolOld', // Cold Tool
+    'summary',
+    'reserve', // Reserve(不占内容,只占预算分配;5%)
+];
+/** 占比(总和 = 0.95,留 5% 给 Reserve)。对齐用户修正版:
+ *  Recent Tool 25%(原 40% 偏大,因 Hot 区不该被压)+ Old Tool 25% 同等 +
+ *  History 20% + System 15% + Summary 10%(平时 0 占用,触发后才用) */
+export const BUDGET_RATIO = {
+    system: 0.15,
+    history: 0.20,
+    toolRecent: 0.25,
+    toolOld: 0.25,
+    summary: 0.10,
+    reserve: 0.05,
+};
+/** Hot/Cold 划分:当前 step 起往前 HOT_TURN_WINDOW 个 user turn 之内的工具结果视为 Hot,
+ * 之外的视为 Cold。0 = 全 Cold(等同老路径);越短 Hot 越小,压缩越激进。 */
+export const HOT_TURN_WINDOW = 4;
+/** 工具消息推入历史后,经过的「消费者 push 次数」即 age。
+ * Cold 区内:age ≥ TOOL_OLD_AGE 的非观察类工具结果可被调度器就地 stub。
+ * 默认 2 = 跨过 2 个消费者 push 仍未被消费,等同 lifecycle 的 DEFAULT_AGE_THRESHOLD。 */
+export const TOOL_OLD_AGE = 2;
+/** 把每条 token 拍平成字符串(只估 token,不深解析工具调用)。 */
+function toText(content) {
+    if (content == null)
+        return '';
+    if (typeof content === 'string')
+        return content;
+    try {
+        return JSON.stringify(content);
+    }
+    catch {
+        return String(content);
+    }
+}
+function msgTokens(m) {
+    const c = m.content;
+    const tcs = m.tool_calls;
+    let extra = toText(c);
+    if (tcs)
+        for (const tc of tcs)
+            extra += tc?.function?.arguments ?? '';
+    // 与 llm.estimateTokens 同公式(CJK 1/字,ASCII 1/4字);保证调度器评估与系统估算口径一致。
+    return 4 + estimateTokens(extra);
+}
+/** 从 history 末尾向前找最后一个 user 消息的索引;无 user 返 -1。 */
+export function lastUserIndex(history) {
+    for (let i = history.length - 1; i >= 1; i--) {
+        if (history[i].role === 'user')
+            return i;
+    }
+    return -1;
+}
+/** 从 idx 处向前数第 N 个 user turn 的边界 index(含该 user 之后的内容)。
+ * 用于把 history 切成 Hot 区(tail 一段,endExclusive=history.length)与 Cold 区(0..endExclusive)。
+ * 若 N 个 user 不足,Hot 区 = history.length(全保护);Cold 区空,无压缩目标。 */
+export function userTurnBoundary(history, window) {
+    let seen = 0;
+    for (let i = history.length - 1; i >= 1; i--) {
+        if (history[i].role === 'user') {
+            seen++;
+            if (seen >= window)
+                return i;
+        }
+    }
+    return 1; // 没攒够 N 个 user 之前的全归 Cold(history[0] system 不动)
+}
+/** 评估当前 history 的五区预算(纯函数,改不动 history)。
+ * 传入 step 是当前所在 step 编号(agent 循环 step 变量),用于日志/调试。 */
+export function evaluateBudget(history, window, step = 0) {
+    const layers = {};
+    for (const k of BUDGET_LAYERS) {
+        const budget = Math.floor(BUDGET_RATIO[k] * window);
+        layers[k] = { actual: 0, budget, overBudget: false, overRatio: 0 };
+    }
+    const sysMsg = history[0];
+    if (sysMsg)
+        layers.system.actual = msgTokens(sysMsg);
+    // Summary 检测:role:'system' 且不是 history[0] 的,视为摘要(compact.ts 摘要插 index 1)。
+    // 简单启发:若 history[1]?.role === 'system' 且 content 含「# 会话摘要」特征串,计入 summary。
+    // 命中时循环跳过 i=1;不命中时当作普通 message(罕见,落到下方 user/assistant 分支)。
+    let summaryHit = false;
+    if (history.length > 1 && history[1].role === 'system') {
+        const c1 = toText(history[1].content);
+        if (c1.startsWith('# 会话摘要') || c1.includes('会话摘要')) {
+            layers.summary.actual = msgTokens(history[1]);
+            summaryHit = true;
+        }
+    }
+    // 划 Hot/Cold 边界
+    const hotStart = userTurnBoundary(history, HOT_TURN_WINDOW);
+    // history 区 = 减去 summary + tool 单算;tool 按 Hot/Cold 分。
+    for (let i = 1; i < history.length; i++) {
+        const m = history[i];
+        if (i === 1 && summaryHit)
+            continue; // summary 已单独算过
+        if (m.role === 'tool') {
+            const t = msgTokens(m);
+            if (i >= hotStart)
+                layers.toolRecent.actual += t;
+            else
+                layers.toolOld.actual += t;
+        }
+        else if (m.role !== 'system') {
+            // user / assistant 全部计入 history(对话轨迹)
+            layers.history.actual += msgTokens(m);
+        }
+        // 其它 system(几乎不存在)跳过
+    }
+    // 计算 overBudget + overRatio
+    const triggers = [];
+    for (const k of BUDGET_LAYERS) {
+        const lb = layers[k];
+        if (lb.actual > lb.budget) {
+            lb.overBudget = true;
+            lb.overRatio = (lb.actual - lb.budget) / Math.max(lb.budget, 1);
+            triggers.push(k);
+        }
+    }
+    // 按 overRatio 降序
+    triggers.sort((a, b) => layers[b].overRatio - layers[a].overRatio);
+    const total = BUDGET_LAYERS.reduce((s, k) => s + (k === 'reserve' ? 0 : layers[k].actual), 0);
+    const totalOver = total >= 0.85 * window;
+    return {
+        step,
+        total,
+        window,
+        layers,
+        triggers,
+        totalOver,
+        hotBoundary: hotStart,
+    };
+}
+/** 根据 BudgetReport 生成调度动作(从轻到重,直至总占用回落到 0.85 以下)。
+ * 规则:
+ *   - system 超 → warn(不压,配置问题不是内容问题)
+ *   - toolOld 超 → 先 L1(中截超大)→ L2(same-path 已有 relevance)→ L3(age stub,新增)
+ *   - toolRecent 超 → cap(只降低单条上限,不 stub)
+ *   - history 超 或 totalOver → compact_history(调 maybeCompact / compactHistory)
+ *   - summary 超 → 不动(摘要本身就压缩产物,删它等于丢历史,只能放任或扩 Recent 预算) */
+export function scheduleActions(report) {
+    const actions = [];
+    const { layers, totalOver, total } = report;
+    const headroom = 0.85 * report.window - total;
+    // system 超 → warn,不是 schedule 目标
+    if (layers.system.overBudget) {
+        actions.push({
+            kind: 'warn',
+            layer: 'system',
+            reason: `System prompt 超预算(${layers.system.actual} > ${layers.system.budget}),请检查配置/MOCODE.md`,
+        });
+    }
+    // 渐进:toolOld(轻→重)
+    if (layers.toolOld.overBudget && layers.toolOld.overRatio > 0.1) {
+        actions.push({ kind: 'shrink_cold_tools', level: 1 });
+    }
+    if (layers.toolOld.overBudget && layers.toolOld.overRatio > 0.3) {
+        actions.push({ kind: 'shrink_cold_tools', level: 2 });
+    }
+    if (layers.toolOld.overBudget && layers.toolOld.overRatio > 0.6) {
+        actions.push({ kind: 'shrink_cold_tools', level: 3 });
+    }
+    // Hot 区只 cap
+    if (layers.toolRecent.overBudget && layers.toolRecent.overRatio > 0.15) {
+        actions.push({ kind: 'cap_hot_tools', aggressive: layers.toolRecent.overRatio > 0.5 });
+    }
+    // History / total 超 → 摘要(最贵);headroom < -2K 真正触发,让 cold tools 先动
+    if ((layers.history.overBudget || totalOver) && headroom < -2000) {
+        actions.push({ kind: 'compact_history' });
+    }
+    // 排序(同 kind 已在上面排好):warn → cold L1→L2→L3 → cap_hot → compact_history
+    return actions;
+}
+/** 拍平成人类可读(供 /context 命令与 check-budget 脚本用)。 */
+export function formatReport(report) {
+    const lines = [];
+    lines.push(`step ${report.step}  total ${report.total}/${report.window}  (${((report.total / report.window) * 100).toFixed(1)}%)`);
+    for (const k of BUDGET_LAYERS) {
+        const lb = report.layers[k];
+        const pct = lb.budget > 0 ? ((lb.actual / lb.budget) * 100).toFixed(0) : '-';
+        const flag = lb.overBudget ? '⚠' : ' ';
+        lines.push(`  ${flag} ${k.padEnd(10)} ${String(lb.actual).padStart(6)} / ${String(lb.budget).padStart(6)} (${pct.padStart(3)}%)`);
+    }
+    if (report.triggers.length > 0) {
+        lines.push(`  triggers: ${report.triggers.join(' → ')}`);
+    }
+    return lines.join('\n');
+}
+/** 便捷:把 history 一把估成总 token 数(给 cap.js 等复用,避免重复实现)。
+ * 注意:此处是粗估(只看 content 长度),不区分五区——只用于「系统层整体还剩多少」快查。 */
+export function quickEstimate(history) {
+    return estimateMessagesTokens(history);
+}

package/dist/context/index.js

@@ -1,10 +1,13 @@
-// context/ barrel:Context Optimization Pipeline。
+// context/ barrel:Context Optimization Pipeline + 五区 Budget Scheduler。
 //
 // 单一入口 optimizeToolResult(agent/core.ts pushToolResult 调)接管"工具结果进 LLM 前"的表示。
+// 单一入口 runScheduler(agent/core.ts 步前调)接管"何时调用哪一闸"的调度。
 // 不调 LLM、不碰 Tool Calling schema / executeTool / tool_call_id 配对 / TUI 渲染
 // (叶子级:仅 stdlib + tools/constants + session/compact 的 capToolResultForHistory 兜底 + config 开关)。
 //
-// 见 CLAUDE.md「Context Optimization Pipeline」节。
+// 见 CLAUDE.md「Context Optimization Pipeline」节 +「Context Budget Scheduler」节。
 export { optimizeToolResult } from './pipeline.js';
 export { classify, knownToolKinds } from './classifier.js';
 export { registerEncoder, registerAll, getEncoder, registeredKinds, } from './registry.js';
+// ── Context Budget Scheduler ───────────────────────────────────────────────
+export { evaluateBudget, scheduleActions, formatReport, quickEstimate, userTurnBoundary, lastUserIndex, BUDGET_LAYERS, BUDGET_RATIO, HOT_TURN_WINDOW, TOOL_OLD_AGE, } from './budget.js';

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);
+}