mocode-ai 0.3.0 → 0.4.1

package/dist/agent/core.js

@@ -10,9 +10,12 @@ import { executeTool } from '../tools/registry.js';
 import { PLAN_DISABLED_TOOLS } from '../tools/constants.js';
 import { getAgentMode, setAgentMode } from './mode.js';
 import { maybeCompact, contextState, dropContextFromHistory } from '../session/index.js';
+import { createBudgetScheduler } from '../session/scheduler.js';
 import { optimizeToolResult } from '../context/index.js';
+import { createRelevancePruner } from '../context/relevance.js';
 import { config } from '../config/index.js';
 import { jailResolve } from '../sandbox/index.js';
+import { createLifecycleEngine } from '../context/lifecycle.js';
 /** 解析工具 arguments JSON;非法或空返 null(调用方据此降级到普通 preview)。 */
 function parseArgs(raw) {
     try {
@@ -70,15 +73,31 @@ function readDiffContext(tc, parsed) {
 }
 /** 回灌 tool 结果到 history:经 Context Optimization Pipeline 编码(tree/search/log/...)后裁到单条上限。
  *  tool_call_id 与 assistant.tool_calls 按序配对。未注册 encoder 时回落 capToolResultForHistory(零行为变化)。
- *  TUI 渲染(hooks.onToolResult)用原始 output,与此解耦——屏上看全量,LLM 看编码后紧凑版。 */
-function pushToolResult(history, tc, output) {
-    history.push({
+ *  TUI 渲染(hooks.onToolResult)用原始 output,与此解耦——屏上看全量,LLM 看编码后紧凑版。
+ *  出口再经 Relevance Pruner 做跨条裁剪:同 path 旧 read_file 自动 stub 为存根。
+ *  - pruner 在每个 runAgentCore 实例化一次(本闭包持有),会话级状态。
+ *  - 开关关闭时 pruner 不创建(零开销、零行为变化)。
+ *  出口再经 Lifecycle Engine 做引用追踪:LIVE→REFERENCED→OBSOLETE→STUB 四态。
+ *  - lifecycle 也在每个 runAgentCore 实例化一次,登记 grep/glob/codegraph 等 producer
+ *    与 read/edit/write 的 consumer 关系;孤立+老化自动 STUB(观察类工具永不到 STUB)。
+ *  - 开关关闭时 lifecycle=null 完全跳过。 */
+function pushToolResult(history, tc, output, pruner, lifecycle, scheduler) {
+    const msg = {
         role: 'tool',
         tool_call_id: tc.id,
         // optimizeToolResult:classifier 选 encoder → encode(保不变量压缩)→ capToolResultForHistory 兜底。
         // tc.arguments 透传给 encoder(上下文感知编码,如 read_file 的 offset/limit)。永不抛错。
         content: optimizeToolResult(tc.name, output, tc.arguments),
-    });
+    };
+    history.push(msg);
+    // 相关性裁剪:只动 read_file / edit_file / write_file 三类(其它 tool 与本层无关)。
+    // pruner 内部 try/catch + 幂等,永不抛错;开关关闭时 pruner=null 完全跳过。
+    if (pruner)
+        pruner.observePush(history, msg);
+    // 观察者生命周期:新 push 一律先登记 LIVE;内部自动维护 producer/consumer 图 + 老化 STUB。
+    // lifecycle 内部 try/catch + 幂等;开关关闭时 lifecycle=null 完全跳过。
+    if (lifecycle)
+        lifecycle.pushTool(history, history.length - 1);
 }
 /**
  * agent 核心循环(纯逻辑):
@@ -111,6 +130,18 @@ export async function runAgentCore(opts) {
     // 保护由 dropContextFromHistory 内部保证:history[0](system)+ 当前轮(最后 user 及其后)永不剔除。
     // 子 agent 也在自己的 history 上操作(子 agent 独立 history);skipRollback 不影响此行为。
     const dropContext = (filter) => dropContextFromHistory(history, filter);
+    // 相关性裁剪 pruner:每个 runAgentCore 实例一个,纯静态、不调 LLM、自动判定 read_file 失效。
+    // 开关关闭时为 null,所有 pushToolResult 调用走无 pruner 路径(零行为变化)。
+    const relprune = config.contextRelprune ? createRelevancePruner() : null;
+    // 观察者生命周期引擎:每个 runAgentCore 实例一个,纯静态、自动维护 grep/glob/codegraph 等
+    // producer 与 read/edit/write 的 consumer 引用关系;孤立+老化的非观察类工具自动 STUB。
+    // 开关关闭时为 null,所有 pushToolResult / mutation 调用走无 lifecycle 路径(零行为变化)。
+    const lifecycle = config.contextLifecycle ? createLifecycleEngine() : null;
+    // 预算调度器:每个 runAgentCore 实例一个,步前 evaluateBudget + scheduleActions。
+    // 决策按 ROI 分发(cold tools 优先 / history 摘要最后);contextBudget 开关关闭时为 null。
+    const scheduler = config.contextBudget !== false
+        ? createBudgetScheduler() // 在 step 循环之外实例化一次,跨步持有 lastRunLog
+        : null;
     // 本轮流式状态:首个正文 token 到达即停 spinner(思考期间 spinner 持续转「思考中…」,不写思考内容)。
     let mode = 'idle';
     let gotText = false;
@@ -146,8 +177,15 @@ export async function runAgentCore(opts) {
                 abortRestore();
                 return { completed: false, finalText: null };
             }
-            // 步前:接近窗口上限时自动压缩(三层)。此时 spinner 已停,通知行干净。
-            await maybeCompact(history);
+            // 步前:五区 Budget Scheduler 决策——按 ROI 调度(冷工具优先 / history 摘要最后)。
+            // 开关关闭(scheduler=null)时退化回原 maybeCompact 路径,零行为变化。
+            // 此时 spinner 已停,通知行干净。
+            if (scheduler) {
+                await scheduler.runStep(history, step);
+            }
+            else {
+                await maybeCompact(history);
+            }
             hooks.onStepStart?.(); // 主 agent:spinner.start('思考中')
             mode = 'idle';
             gotText = false;
@@ -214,7 +252,7 @@ export async function runAgentCore(opts) {
                             const output = await started[k];
                             hooks.onToolDone?.();
                             hooks.onToolResult?.(tc, output, null, null, 1); // 只读工具无 diff
-                            pushToolResult(history, tc, output);
+                            pushToolResult(history, tc, output, relprune, lifecycle, scheduler);
                         }
                         i = j;
                     }
@@ -234,7 +272,7 @@ export async function runAgentCore(opts) {
                             hooks.onToolHeader?.(tc);
                             const err = `错误:计划模式下禁用工具 ${tc.name}(仅读探查,不改动文件 / 不跑命令)`;
                             hooks.onToolResult?.(tc, err, null, null, 1);
-                            pushToolResult(history, tc, err);
+                            pushToolResult(history, tc, err, relprune, lifecycle, scheduler);
                             i++;
                             continue;
                         }
@@ -253,7 +291,7 @@ export async function runAgentCore(opts) {
                             const tc = batch[k];
                             const output = await started[k];
                             hooks.onToolResult?.(tc, output, null, null, 1); // task 结果是摘要,无 diff
-                            pushToolResult(history, tc, output);
+                            pushToolResult(history, tc, output, relprune, lifecycle, scheduler);
                         }
                         hooks.onToolDone?.();
                         i = j;
@@ -267,7 +305,7 @@ export async function runAgentCore(opts) {
                             hooks.onToolHeader?.(tc);
                             const err = `错误:计划模式下禁用工具 ${tc.name}(仅读探查,不改动文件 / 不跑命令)`;
                             hooks.onToolResult?.(tc, err, null, null, 1);
-                            pushToolResult(history, tc, err);
+                            pushToolResult(history, tc, err, relprune, lifecycle, scheduler);
                             i++;
                             continue;
                         }
@@ -280,7 +318,19 @@ export async function runAgentCore(opts) {
                         const output = await executeTool(tc.name, tc.arguments, signal, { skipRollback, dropContext });
                         hooks.onToolDone?.();
                         hooks.onToolResult?.(tc, output, parsed, preWriteOld, editStartLine);
-                        pushToolResult(history, tc, output);
+                        pushToolResult(history, tc, output, relprune, lifecycle, scheduler);
+                        // 相关性裁剪 mutation 通知:edit_file/write_file 后,该 path 之前的所有 read_file
+                        // 结果已失效(已不再是文件当前状态)→ stub 为存根。pruner 内部 try/catch + 幂等。
+                        // 非 mutation 工具(run_command/use_skill/memory_* 等)此处 path="" 不触发。
+                        // 观察者生命周期:mutation push 后通知 lifecycle 把同 path 的旧 read 标 REFERENCED。
+                        if (relprune && isMutationTool(tc.name)) {
+                            const mp = parsed?.path;
+                            if (typeof mp === 'string' && mp) {
+                                relprune.observeMutation(history, mp);
+                                if (lifecycle)
+                                    lifecycle.pushMutation(history, history.length - 1, mp);
+                            }
+                        }
                         i++;
                     }
                 }

package/dist/config/index.js

@@ -81,6 +81,11 @@ ${PLATFORM_NOTE}
 - Small steps: break tasks into verifiable sub-steps. Before each step, think clearly about what to change and why.
 - Verify after change: run typecheck / tests / build via run_command to confirm it works. Never claim done without verification.
 
+## Step / Turn Economy (read this — saves LLM calls)
+- **Minimize turns**: each user message costs at least one LLM call, and history grows every step until threshold-triggered compact fires (extra call). If a request contains ≥2 independent sub-goals (e.g. "改 X 然后再优化 Y"), ask the user to split them into separate turns rather than chaining both in one go. State this politely: "这条包含 N 个独立目标,建议拆成 N 次对话,以避免上下文膨胀。"
+- **Batch read-only tools in parallel**: in a single assistant turn, emit multiple tool_calls together — consecutive read-only tools (read_file, glob, grep, codegraph, web_search, web_fetch) auto-execute in parallel. Do NOT call them serially across turns when you could emit them together in one turn. This is the single biggest step-saver.
+- **Decide before reading**: do not read files "just to see"; plan the 2-3 file paths you actually need, then emit them as one batched tool_calls turn.
+
 ## Tool Guidelines
 - See each tool's own description for parameters and usage; this section covers selection strategy and pitfalls only.
 - **Prefer codegraph for code exploration**: when understanding/locating code, tracing call chains, or assessing impact of changes, if a .codegraph/ index exists, use the codegraph tool first (explore to query by question, node to look up a single symbol) — it returns relevant source + call paths in one shot, more accurate and economical than piecing together via read_file/grep. Fall back to read_file / grep / glob only when codegraph is unavailable (no index), misses, you need to see just-changed content, or you're editing a single known small file. Build the index first with \`codegraph init\` if none exists.
@@ -91,7 +96,8 @@ ${PLATFORM_NOTE}
 - Use web_search for information beyond training data (new versions, news, real-time data, latest APIs); don't answer potentially outdated info from memory.
 - Use web_fetch to read a specific URL (a link from search results, or a URL given by the user); it only fetches static HTML — if a JS-rendered page yields no body, switch to web_search (its results include cleaned body text).
 - Call ask_human when you hit a decision point requiring user input (multiple implementation approaches, unclear intent, or needing extra info to proceed) — list options for the user to pick (they can also choose "custom input" to answer freely). Don't call it frequently when the task is clear and you can decide yourself; if the user cancels, switch approach or proceed with available info — don't re-ask the same question.
-- **Drop irrelevant context** (use sparingly): call drop_context to stub-replace tool results in history that are BOTH (a) irrelevant to the current task AND (b) large (the freed tokens must clearly exceed the ~300 tokens the call itself costs — roughly only worth it when targeting ≥2 bulky results, e.g. wide grep/read sweeps that returned mostly-irrelevant hits). The call itself adds a tool-call round-trip, so don't call it for one small result or when you're near done. It preserves tool_call_id pairing (only content changes); the system prompt and current turn are never dropped. Use filters (toolNames / contains) to target precisely.
+- **Drop irrelevant context proactively**: call drop_context to stub-replace tool results in history that are no longer needed. This is your primary lever for keeping context lean — every step grows history until the threshold-triggered compact fires (which costs an extra LLM call and is more aggressive). Call when any of: (a) you just finished a grep/read sweep and only 1-2 hits mattered; (b) history has >20 tool messages and you are early in the task; (c) you switched sub-goals and the old sub-goal's exploration is dead weight. The call itself adds ~300 tokens, so only call when freed tokens clearly exceed that (≥1 large grep hit or ≥2 medium results). Do NOT call when near completion, when history is short (<10 tool messages), or when the candidate results are still in active use. It preserves tool_call_id pairing (only content changes); the system prompt and current turn are never dropped. Use filters (toolNames / contains) to target precisely.
+- **Observation lifecycle is automatic**: behind the scenes every tool result goes LIVE→REFERENCED→OBSOLETE→STUB. grep/glob/codegraph/web_search/web_fetch are always kept as REFERENCED (never auto-stubbed) because they may surface multiple candidates. read/edit/write results that nobody consumes after two more consumer pushes get auto-stubbed. This is zero-cost (static analysis, no LLM call). You don't need to manage lifecycle yourself — just trust that stale tool results get pruned.
 - **Batch independent tool calls in one turn**: the executor runs ALL returned tool calls before the next LLM call, so emitting [read_file, glob, read_file] together is dramatically cheaper than three separate turns. Default to bundling exploration reads and parallel writes.
 - **Chain shell workflows in a single \`run_command\`**: use \`&&\`, \`;\`, \`|\`, \`>\`, heredocs to fold multi-step scripts (\`mkdir -p x && cat > x/file.ts <<'EOF' ... EOF && npm test\`) into one call. Only emit a follow-up turn when the result forces a decision (error, ambiguous output, branching logic).
 
@@ -155,6 +161,9 @@ export const config = {
     includeUsage: process.env.LLM_STREAM_USAGE !== 'false',
     autoCompact: process.env.AUTO_COMPACT !== 'false',
     contextOptimize: process.env.MOCODE_CONTEXT_OPTIMIZE !== 'false',
+    contextRelprune: process.env.MOCODE_CONTEXT_RELPRUNE !== 'false',
+    contextLifecycle: process.env.MOCODE_LIFECYCLE !== 'false',
+    contextBudget: process.env.MOCODE_BUDGET_SCHEDULER !== 'false',
     autoReflect: process.env.AUTO_REFLECT !== 'false',
     reflectEveryN: Number(process.env.REFLECT_EVERY_N) || 5,
     maxSteps: Number(process.env.MAX_STEPS) || 200,

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';