mocode-ai 1.3.9 → 1.4.0

package/dist/agent/index.js

@@ -4,13 +4,13 @@
 // 行为与重构前的单文件 runAgent 完全一致——这是安全重构,实跑回归验证。
 import { ui } from '../ui/theme.js';
 import { Spinner } from '../ui/spinner.js';
-import { summarizeToolCall, summarizeToolResult, truncateDisplay, fmtElapsed, } from '../ui/render.js';
+import { summarizeToolCall, summarizeToolResult, truncateDisplay, fmtElapsed } from '../ui/render.js';
 import { renderFileChange } from '../ui/diff.js';
 import * as layout from '../ui/layout.js';
 import * as batch from '../ui/batch.js';
 import { beginTurn } from '../rollback/index.js';
 import { config } from '../config/index.js';
-import { runAgentCore, isMutationTool, } from './core.js';
+import { runAgentCore, isMutationTool } from './core.js';
 import { createPetHooks } from '../pet/state.js';
 import { t } from '../i18n/index.js';
 import { isToolErrorOutput } from '../tools/result.js';
@@ -39,9 +39,9 @@ function lineDelta(oldText, newText) {
     while (head < before.length && head < after.length && before[head] === after[head])
         head++;
     let tail = 0;
-    while (tail < before.length - head
-        && tail < after.length - head
-        && before[before.length - 1 - tail] === after[after.length - 1 - tail])
+    while (tail < before.length - head &&
+        tail < after.length - head &&
+        before[before.length - 1 - tail] === after[after.length - 1 - tail])
         tail++;
     return { added: after.length - head - tail, removed: before.length - head - tail };
 }
@@ -127,7 +127,7 @@ function writeToolHeader(tc) {
     }
     else {
         // 普通工具合并到 currentBatchId；同轮并行或连续无正文的工具轮次共享一个摘要行。
-        const id = currentBatchId ??= batch.beginBatch();
+        const id = (currentBatchId ??= batch.beginBatch());
         // 结果按 tool_call id 归位：并行执行时 currentBatchId 会漂移，只按“当前批”回填会漏填，
         // 摘要行就永远停在 ◇（用户实测：子 agent 跑完主侧菱形没变成实心圆）。
         batch.bindCall(tc.id, id);
@@ -166,9 +166,7 @@ function writeToolResult(tc, output, parsed, preWriteOld, editStartLine) {
         diff = renderFileChange({
             path: String(parsed.path ?? ''),
             kind: tc.name === 'edit_file' ? 'edit' : 'write',
-            oldStr: tc.name === 'edit_file'
-                ? String(parsed.old_string ?? '')
-                : preWriteOld,
+            oldStr: tc.name === 'edit_file' ? String(parsed.old_string ?? '') : preWriteOld,
             newStr: String((tc.name === 'edit_file' ? parsed.new_string : parsed.content) ?? ''),
             startLine: tc.name === 'edit_file' ? editStartLine : 1,
         });
@@ -248,7 +246,11 @@ function flushToolBatch(expandSingleEntry = false) {
  */
 export async function runAgent(history, userInput, signal, 
 /** 每步 chat() 返回后回调:repl 据此重算并重画状态行 context 用量条(运行中实时刷新,不冻结在轮首)。 */
-onContextUpdate) {
+onContextUpdate, 
+/** 本用户 turn 的自动路由工具策略。 */
+toolPolicy, 
+/** 仅真实用户 turn 传入；合成 plan 执行轮继承 policy 但不重复记录初始路由。 */
+initialToolRoute) {
     // 开新轮次(回滚用):首行截断 40,供 /rollback 轮次菜单展示。
     beginTurn(truncateDisplay(firstLineOf(userInput), 40));
     layout.contentMode(); // 防御性:运行态光标归输入框光标位供 IME 锚定(enterRunningMode 已置,这里兜底)
@@ -423,6 +425,8 @@ onContextUpdate) {
             signal,
             onContextUpdate,
             hooks: combinedHooks,
+            toolPolicy,
+            initialToolRoute,
             onTraceEvent: appendCurrentSessionTraceEvent,
         });
     }

package/dist/agent/mode.js

@@ -4,8 +4,8 @@
  * 把 `agentMode` 从 repl 的模块变量提到这里,让三方都能用、且不破坏依赖单向:
  *  - `repl/index.ts` 读写它 + 注册 onModeChange 监听器(做 applyMode 重写 history[0] +
  *    refreshStatusBase 刷状态行 modeTag),并通过 /plan / /auto / Shift+Tab(c cycleMode) 触发切换。
- *  - `agent/index.ts` 每步读它(getAgentMode)——决定 chat() 用全量 chatTools 还是 planChatTools 只读子集,
- *    以及串行分支的 plan 防御 backstop。这样切换模式后,下一次 chat() 立即看到新工具集。
+ *  - `agent/index.ts` 每步读取模式：PLAN 只暴露只读能力；AUTO 允许执行，但实际工具面由
+ *    每个真实用户 turn 的 ToolPolicy 路由并可在后续 step 单向扩容。
  *  - 模型不再持有 switch_mode 工具(已砍):模式切换只能由用户面触发。
  *
  * 依赖方向无环:本模块不 import 任何业务模块。
@@ -17,7 +17,7 @@
  */
 let currentMode = 'auto';
 let listener = null;
-/** 当前 agent 模式。auto=全工具执行;plan=只读探查 + 产出计划(写盘/命令/记忆写入工具被 schema 剔除)。 */
+/** 当前 agent 模式。auto=按任务路由能力并执行；plan=只读探查 + 产出计划。 */
 export function getAgentMode() {
     return currentMode;
 }

package/dist/agent/runtime-context.js

@@ -0,0 +1,45 @@
+/**
+ * AgentRuntimeContext:runAgentCore 的运行时依赖注入接缝。
+ *
+ * 2.0 框架化第一步(Context 参数化):把 core.ts 直读的模块级单例(config / agentMode /
+ * sessionId / sandboxRoot / token 校准 / notes mtime)收敛成一个显式接口。默认实现
+ * defaultAgentRuntimeContext 原样绑定全局单例,行为与改造前完全一致;宿主(TUI / stdio host /
+ * 子 agent / 未来多 runtime)可注入自定义实现,在同一进程内获得互不干扰的运行时视图。
+ *
+ * 本模块是叶子:只依赖各单例所在模块,不反向 import core.ts,依赖方向无环。
+ *
+ * 取舍说明:
+ *  - 用方法(getter)而非裸值字段:config.model 等会被 /model 热切,方法保证每次读取取最新值,
+ *    与改造前「每次直读全局」的语义一致。
+ *  - jailResolve / getCurrentTurnMutationState 等涉及真实 I/O 或可变返回,保持函数形态原样透传。
+ *  - 暂未覆盖 executeToolOutcome / findTool(tools registry 单例)与 checkPermission:它们属
+ *    工具系统(步骤 4 抽包时处理),本轮只收敛 agent 运行时自身的单例。
+ */
+import { config, getActiveModel, extractActivePlanSection, buildSessionStateReminder } from '../config/index.js';
+import { getAgentMode, setAgentMode } from './mode.js';
+import { getCurrentSessionId } from '../session/state.js';
+import { getCurrentTurnId, getCurrentTurnMutationState } from '../rollback/index.js';
+import { getNotesMtime } from '../session/notes.js';
+import { jailResolve } from '../sandbox/index.js';
+import { getTokenCalibration, updateTokenCalibration } from '../context/token-calibration.js';
+import { safeProviderId } from '../session/trace-sanitize.js';
+/**
+ * 默认运行时上下文:原样绑定全局单例,与改造前 runAgentCore 的直读行为完全一致。
+ * 每个方法都是对应单例函数的透传;config 是同一对象引用(字段读取热生效)。
+ */
+export const defaultAgentRuntimeContext = {
+    config,
+    getActiveModel,
+    getAgentMode,
+    setAgentMode,
+    getCurrentSessionId,
+    getCurrentTurnId,
+    getCurrentTurnMutationState,
+    buildSessionStateReminder,
+    extractActivePlanSection,
+    getNotesMtime,
+    jailResolve,
+    getTokenCalibration,
+    updateTokenCalibration,
+    safeProviderId,
+};

package/dist/agent/spawn.js

@@ -1,19 +1,18 @@
-// 子 agent 封装:runAgentCore + (TUI 激活时)实时渲染 hooks。独立 history / 可受限工具子集 / 低步数上限。
+// 子 agent 封装:runAgentCore + (TUI 激活时)实时渲染 hooks。
 // 供 task 工具(主 agent 派生子任务)调用——子 agent 的最终摘要回灌主 history。
 //
-// 与主 agent 的区别:
-//  - 主屏渲染可选:全屏 TUI 激活时(layout.isTuiActive()),把子 agent 内部工具调用实时写入
-//    主内容区并复用 batch 折叠机制(运行态逐条展开,执行完自动折叠回单行摘要,鼠标可点开查看);
-//    TUI 未激活(host 嵌入 / 非 TTY)时保持纯静默——中间过程只缓冲进 transcript,不写主屏。
-//  - 独立 history:不共享主对话,避免子任务的工具噪声污染主上下文。
-//  - 紧凑系统提示:不复制主 agent 的 memory/skills/项目快照；由 context 传入已知事实。
-//  - 工具子集:写任务默认继承主 Agent 工具（仅禁止递归 task）；只读模式按安全语义移除写工具。
-//  - 不调 beginTurn：子 agent 共享主 agent 当前轮次；其文件修改进入同一回滚事务。
-//  - 步数默认与主 Agent 相同，只作为无限循环保险，不以 token 配额提前终止有效任务。
-//  - 中断透传:opts.signal(主 agent 的 abort signal)透传给 runAgentCore → chat/executeTool,
-//    主 Ctrl+C 树杀子 agent(chat 流式 abort + run_command/web_fetch 即时取消)。
+// 子 agent 与主 agent 完全同源(无任何能力裁剪):
+//  - 同一份系统提示、同一份工具 schema、同一份对话前缀(delegation 命中前缀缓存);
+//  - 写操作直接落在工作区,进入主 agent 当前轮次的同一回滚事务(spawn 不调 beginTurn);
+//  - 步数默认与主 agent 相同,只作为无限循环保险,不以 token 配额提前终止有效任务;
+//  - 中断透传:opts.signal 透传给 runAgentCore → chat/executeTool,主 Ctrl+C 树杀子 agent。
+// 与主 agent 的唯一差别是渲染与 history 归属:
+//  - 主屏渲染可选:TUI 激活时把子 agent 内部工具调用实时写入主内容区并复用 batch 折叠;
+//    TUI 未激活(host 嵌入 / 非 TTY)时纯静默,中间过程只缓冲进 transcript。
+//  - 独立 history 分支:子任务的工具噪声不回灌主对话,只有最终摘要回灌。
 import { chatTools } from '../llm/index.js';
-import { buildMocodeCorePrompt, config, isSubAgentEnabled } from '../config/index.js';
+import { buildMocodeCorePrompt, config, isSubAgentHardDisabled } from '../config/index.js';
+import { getToolChatSchema } from '../tools/policy.js';
 import { effectiveSystemPrompt } from '../skills/index.js';
 import { ui } from '../ui/theme.js';
 import * as layout from '../ui/layout.js';
@@ -24,21 +23,18 @@ import { runAgentCore } from './core.js';
 import { summarizeToolCall, summarizeToolResult, truncateDisplay } from '../ui/render.js';
 import { t } from '../i18n/index.js';
 import { createContextState } from '../session/compact.js';
-import { inOverlay, mergeSubAgentChangeSet } from '../agents/coordinator.js';
-/** 子 agent 系统提示后缀:角色与约束。 */
+/** 子 agent 系统提示后缀(仅 legacy 直接调用路径用;共享前缀路径的系统提示直接复用父 agent)。 */
 const SUBAGENT_SUFFIX = `
 
 ## ⛯ SUB-AGENT MODE (you are a sub-agent)
-You are a sub-agent spawned by the main agent to handle an isolated sub-task. You have your own conversation history (independent of the main thread).
-- Focus solely on the assigned sub-task. Do NOT attempt to call the "sub-agent" tool (no recursive spawning).
-- Use the tools available to you to complete the sub-task.
-- When done, your final text reply will be returned to the main agent as a summary — make it concise and actionable: what you did, key findings, files changed, and any issues. The main agent will decide the next step based on your summary.`;
+You are a sub-agent spawned by the main agent to handle a delegated sub-task, with the same tools and full capabilities as the main agent.
+- Focus on the assigned sub-task and see it through to completion.
+- When done, your final text reply is returned to the main agent as the result — concise and actionable: what you did, key findings, files changed, blockers.`;
 const SUBAGENT_ROLE = `## Sub-agent execution
-You are executing one delegated sub-task with the same engineering standards and capabilities as mocode.
+You are executing one delegated sub-task with the same engineering standards and full capabilities as the main agent.
 - Treat Task context as authoritative facts already established by the main agent; do not rediscover them without evidence they are stale.
 - Focus on the delegated scope, but continue until it is genuinely complete. Do not stop to save tokens.
-- Do not recursively call sub-agent. A write task runs in an isolated overlay; the coordinator merges it safely.
-- Return concise findings, changes, checks you chose to run, and blockers to the coordinator.`;
+- Return concise findings, changes, checks you chose to run, and blockers to the main agent.`;
 /**
  * 派生一个子 agent 执行独立子任务。
  *
@@ -52,39 +48,80 @@ You are executing one delegated sub-task with the same engineering standards and
  * 子 agent 跑在主 signal 下,主 abort 即子 abort;子 agent 的 abortRestore 还原子 history + 模式。
  */
 export async function spawnAgent(opts) {
-    if (!isSubAgentEnabled()) {
+    if (isSubAgentHardDisabled()) {
         return {
             summary: null,
             completed: false,
-            transcript: 'Sub-agent execution is disabled. Enable it with /subagent on.',
-            status: 'failed', findings: [], readSet: [], changeSet: null,
+            transcript: 'Sub-agent execution is disabled by MOCODE_SUBAGENT_ENABLED=false.',
+            status: 'failed',
             usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0, cachedTokens: 0, reasoningTokens: 0 },
         };
     }
     const maxSteps = opts.maxSteps ?? config.subAgentMaxSteps;
-    // 构造窄 worker prompt；主 Agent 已知事实只通过有界 context 注入，避免重复探索与重复计费。
-    const systemPrompt = effectiveSystemPrompt(buildMocodeCorePrompt() + '\n\n' + SUBAGENT_ROLE + SUBAGENT_SUFFIX +
-        (opts.systemPromptSuffix ? `\n\n${opts.systemPromptSuffix}` : ''));
-    const taskPrompt = opts.context?.trim()
-        ? `Task context (authoritative; do not rediscover):\n${opts.context.slice(0, 4000)}\n\nSub-task:\n${opts.prompt}`
-        : opts.prompt;
-    // 写 worker 保留主 Agent 的完整能力；只读 mode 仅按调用契约移除副作用工具。
+    const requested = opts.tools === undefined ? null : new Set(opts.tools);
+    const shared = opts.delegation && opts.delegation.history.length > 0 && opts.delegation.history[0]?.role === 'system'
+        ? opts.delegation
+        : null;
     let toolsOverride;
-    const mode = opts.mode ?? 'read';
-    const requested = opts.tools?.length ? new Set(opts.tools) : null;
-    const readOnly = new Set(['read_file', 'glob', 'grep', 'web_search', 'web_fetch', 'use_skill', 'memory_search', 'memory_list']);
-    toolsOverride = chatTools.filter((tool) => tool.function.name !== 'sub-agent' &&
-        // run_skill 会再次 spawn,禁止递归(避免 fork skill 里又 run_skill 套娃)。
-        tool.function.name !== 'run_skill' &&
-        // plan_update 直写主会话 notes.md(不走 overlay),子代理不应改动主计划——统一排除。
-        tool.function.name !== 'plan_update' &&
-        (!requested || requested.has(tool.function.name)) &&
-        (mode === 'write' || readOnly.has(tool.function.name)));
-    // 独立 history(子 agent 自己持有,不共享主对话)。
-    // 只塞 system;user 消息由 runAgentCore 的 userInput 参数 push(与主 agent 一致)。
-    const history = [
-        { role: 'system', content: systemPrompt },
-    ];
+    let runtimeAllowedToolNames;
+    let history;
+    let userInput;
+    if (shared) {
+        // ── 共享前缀模式(官方 TUI/stdio 派发路径)──
+        // 系统提示 = 父 history[0](含 skills 段),工具 schema = 父 step activeTools,
+        // history = 父前缀(上游已去掉尾部「产生本次调用的 assistant tool_call 消息」)。
+        // 整条前缀与主 agent 已发送内容逐字节一致 → 命中前缀缓存;子 agent 直接看到
+        // 主 agent 已读过的文件与结论,不再重复探索。
+        // 不做任何裁剪:子 agent 的工具面就是父 step 的工具面。
+        let tools = [...shared.tools];
+        if (requested) {
+            // 显式 tools 白名单是调用方主动的特化收缩(skill allowed-tools),可裁 schema。
+            tools = tools.filter((tool) => requested.has(tool.function.name));
+        }
+        toolsOverride = tools;
+        // schema 即上限。显式给 runtimeAllowedToolNames 可让 core 跳过 legacy profile 防线,
+        // 否则旧 profile 会误删父 policy 已授予的工具(如 memory-*)——子代理必须与父同源。
+        runtimeAllowedToolNames = new Set(tools.map((tool) => tool.function.name));
+        history = [...shared.history];
+        userInput = [
+            '[Sub-agent delegation] The main agent delegated a sub-task to you. The conversation above is the shared working context — treat facts already established there as ground truth; do NOT redo exploration that is already done.',
+            opts.context?.trim() ? `Task context (authoritative; do not rediscover):\n${opts.context.slice(0, 4000)}` : '',
+            `Sub-task:\n${opts.prompt}`,
+            [
+                "You have the same tools and the same full capabilities as the main agent. Your file writes land directly in the workspace and belong to the main agent's current rollback transaction.",
+                'Your final text reply is returned to the main agent as the result — concise and actionable: what you did, key findings, files changed, blockers.',
+            ].join('\n'),
+            opts.systemPromptSuffix ?? '',
+        ]
+            .filter(Boolean)
+            .join('\n\n');
+    }
+    else {
+        // ── legacy 紧凑上下文(直接调用 / 未迁移嵌入 / 测试)──
+        // 没有父前缀可复用时自建 worker 上下文;能力面仍以父 step 上限为准,不额外收缩。
+        const systemPrompt = effectiveSystemPrompt(buildMocodeCorePrompt() +
+            '\n\n' +
+            SUBAGENT_ROLE +
+            SUBAGENT_SUFFIX +
+            (opts.systemPromptSuffix ? `\n\n${opts.systemPromptSuffix}` : ''));
+        // 子 worker 只能在父 step 的不可变 capability 上限内进一步缩小。没有父快照时以当前
+        // chatTools 为 baseline；显式 tools:[] 必须保持零工具，不能误当成"未限制"。
+        const parentNames = opts.parentAllowedToolNames
+            ? [...new Set(opts.parentAllowedToolNames)]
+            : chatTools.map((tool) => tool.function.name);
+        const effectiveNames = parentNames.filter((name) => !requested || requested.has(name));
+        toolsOverride = effectiveNames.flatMap((name) => {
+            const schema = getToolChatSchema(name);
+            return schema ? [schema] : [];
+        });
+        runtimeAllowedToolNames = new Set(toolsOverride.map((tool) => tool.function.name));
+        // 独立 history(子 agent 自己持有,不共享主对话)。
+        // 只塞 system;user 消息由 runAgentCore 的 userInput 参数 push(与主 agent 一致)。
+        history = [{ role: 'system', content: systemPrompt }];
+        userInput = opts.context?.trim()
+            ? `Task context (authoritative; do not rediscover):\n${opts.context.slice(0, 4000)}\n\nSub-task:\n${opts.prompt}`
+            : opts.prompt;
+    }
     // 静默 hooks:缓冲中间过程到 transcript,不写主屏。
     let transcript = '';
     const buf = [];
@@ -148,7 +185,9 @@ export async function spawnAgent(opts) {
         if (status)
             batch.setBatchLabel(id, status === 'complete'
                 ? t('subagent.complete')
-                : status === 'failed' ? t('subagent.failed') : t('subagent.running'));
+                : status === 'failed'
+                    ? t('subagent.failed')
+                    : t('subagent.running'));
         // 收尾:清除运行态标志,摘要行图标从「运行中 ◐」切回完成态 ●。
         batch.setBatchRunning(id, false);
         batch.endBatch(id, liveLayout());
@@ -168,7 +207,7 @@ export async function spawnAgent(opts) {
             if (s)
                 lastChar = s[s.length - 1];
         },
-        onToolCall: (name) => {
+        onToolCall: (_name) => {
             if (lastChar && lastChar !== '\n') {
                 writeBuf('\n');
                 lastChar = '\n';
@@ -192,8 +231,8 @@ export async function spawnAgent(opts) {
             if (preview)
                 writeBuf(`  ↳ ${preview}\n`);
             if (liveBatchId) {
-                // 子 agent 批无 diff(写任务走 overlay,最终由主 agent 合并);空 preview 用占位
-                // 标记 entry 已完成,避免折叠后摘要仍显示"运行中"。
+                // 子 agent 批不展示 diff(其写入已直接落工作区,由主 agent 的当前回滚事务统一追踪);
+                // 空 preview 用占位标记 entry 已完成,避免折叠后摘要仍显示"运行中"。
                 batch.recordResult(liveBatchId, tc.name, preview || t('toolSummary.noOutput'), null, output, isToolErrorOutput(output));
                 batch.showLiveBatch(liveBatchId, liveLayout());
             }
@@ -240,57 +279,33 @@ export async function spawnAgent(opts) {
     // 每个子 agent 独享统计/预算状态。不能保存再恢复模块级单例：多个 task 并发时
     // save/restore 会竞态，且 lastEstimate / schedulerLog 仍会污染主 agent。
     const localContextState = createContextState();
-    const readSet = new Set();
-    const run = () => runAgentCore({
+    // 与主 agent 完全同源:写操作直接落在工作区,进入主 agent 当前轮次的同一回滚事务
+    // (spawn 不调 beginTurn)。没有 overlay 拷贝/ChangeSet 合并这一步——那是旧 read/write
+    // 双模式的产物,子 agent 不再受限,也就不需要"先隔离再合并"。
+    const result = await runAgentCore({
         history,
-        userInput: taskPrompt,
+        userInput,
         signal: opts.signal,
         hooks,
         maxSteps,
         toolsOverride,
+        runtimeAllowedToolNames,
         contextState: localContextState,
         suppressOpeningAnalysis: true, // 子代理不注入「开场分析」:仅主线面对用户的首次响应用
-        // 子代理不注入主会话「会话状态」(plan + 笔记):systemPrompt 已用
-        // buildMocodeCorePrompt() 切掉会话私有尾段,工具表也排除了 plan_update——
-        // 灌主计划只会干扰窄 worker 并白付 token。
+        // 子代理不注入主会话「会话状态」(plan + 笔记):那是主 agent 的工作面,委派消息已带齐
+        // 子任务所需上下文,重复注入只白付 token。
         suppressSessionState: true,
-        onToolOutcome: (tool, args) => {
-            if (tool === 'read_file' && typeof args.path === 'string')
-                readSet.add(args.path);
-            else if (['glob', 'grep'].includes(tool))
-                readSet.add('workspace');
-        },
     });
-    let result;
-    let changeSet = null;
-    let mergeStatus = 'committed';
-    if (opts.mode === 'write') {
-        const isolated = await inOverlay(run);
-        result = isolated.value;
-        changeSet = isolated.changeSet;
-        const declared = new Set((opts.writeSet ?? []).map((item) => item.replaceAll('\\', '/').toLowerCase()));
-        const outsideDeclaration = declared.size > 0 && changeSet?.changes.some((change) => !declared.has(change.path.replaceAll('\\', '/').toLowerCase()));
-        if (!result.completed || outsideDeclaration)
-            mergeStatus = 'failed';
-        else
-            mergeStatus = await mergeSubAgentChangeSet(changeSet, opts.signal);
-    }
-    else {
-        result = await run();
-    }
     const status = opts.signal?.aborted || result.terminationReason === 'aborted'
         ? 'aborted'
-        : mergeStatus === 'conflict' ? 'conflict'
-            : mergeStatus === 'failed' || !result.completed ? 'failed'
-                : 'completed';
+        : result.completed
+            ? 'completed'
+            : 'failed';
     return {
         summary: result.finalText,
         completed: result.completed && status === 'completed',
         transcript: truncateDisplay(transcript, 20000), // 防过大;调试用,回灌主 history 的是 summary 不是 transcript
         status,
-        findings: result.finalText ? [result.finalText] : [],
-        readSet: [...readSet].sort(),
-        changeSet,
         usage: {
             promptTokens: result.usage?.promptTokens ?? 0,
             completionTokens: result.usage?.completionTokens ?? 0,

package/dist/agent/tool-helpers.js

@@ -0,0 +1,134 @@
+/**
+ * agent 核心循环的工具辅助纯函数(从 core.ts 提取,2.0 步骤2 阶段A)。
+ *
+ * 这些函数不依赖 runAgentCore 的循环局部状态,只接受显式参数,故可安全模块化。
+ * 它们覆盖:工具参数解析、文件编辑恢复提示、正文噪声判定、并发/锁调度分类、
+ * 权限拒绝结果构造、mutation diff 旧内容预读、tool 结果回灌 history。
+ *
+ * 依赖说明:readDiffContext 用 jailResolve 直接 import(沙箱域,留待工具系统抽包统一处理);
+ * pushToolResult 依赖 context/relevance/lifecycle/scheduler 的 metadata 登记,不改写历史正文。
+ */
+import { readFileSync } from 'node:fs';
+import { findTool, getToolCapabilities } from '../tools/registry.js';
+import { jailResolve } from '../sandbox/index.js';
+import { contextState } from '../session/compact.js';
+import { capToolResultForHistory } from '../session/compact.js';
+import { recordArtifact, knownEditTargets } from '../context/index.js';
+import { isToolResultSuccess } from '../context/utils.js';
+/** 解析工具 arguments JSON;非法或空返 null(调用方据此降级到普通 preview)。 */
+export function parseArgs(raw) {
+    try {
+        return raw.trim() ? JSON.parse(raw) : {};
+    }
+    catch {
+        return null;
+    }
+}
+/** 需要「已知编辑目标」恢复提示的文件编辑工具;其余工具的参数报错不注入该提示。 */
+const EDIT_HINT_TOOLS = new Set(['edit_file', 'write_file']);
+/** 文件编辑工具参数校验失败时的恢复提示:把系统已知仍新鲜的「最近 read_file 的
+ *  path + hash」直接递给模型照抄,替代其在长上下文里凭记忆复述。
+ *  只展示事实、不替模型填值;没有候选(从未 read_file / 全部已失效)返 undefined。 */
+export function argumentErrorHint(name, state) {
+    if (!EDIT_HINT_TOOLS.has(name))
+        return undefined;
+    const targets = knownEditTargets(state);
+    if (targets.length === 0)
+        return undefined;
+    const lines = targets.map((target) => `  path=${target.path}  expected_hash=${target.hash}`).join('\n');
+    return ('系统已知最近 read_file 且尚未被修改的文件(直接复制下面的 path / expected_hash,勿凭记忆复述):\n' +
+        `${lines}\n如目标文件不在其中,先 read_file 该文件再发起编辑。`);
+}
+/** 判定 assistant content 是否只是 "Tool results:" 这类工具结果前缀噪声。
+ *  部分模型(如 Claude)会在 tool_calls 前输出此种无意义过渡文本,写入 history
+ *  会污染后续轮次上下文并在 TUI 上泄露为孤立行。 */
+export function isToolResultsNoise(content) {
+    return /^(?:\s*Tool results:\s*)+$/i.test(content.trim());
+}
+/** 只有显式声明 parallel 且无需权限确认的工具才进入普通并发组。 */
+export function isParallelTool(name) {
+    const tool = findTool(name);
+    return !!tool && (tool.risk ?? 'safe') === 'safe' && getToolCapabilities(tool).concurrency === 'parallel';
+}
+/** resource-locked 工具先顺序完成权限预检，再依赖 canonical resource lock 并发执行。 */
+export function isResourceLockedTool(name) {
+    const tool = findTool(name);
+    return !!tool && getToolCapabilities(tool).concurrency === 'resource-locked';
+}
+export function isResourceLockedCall(call) {
+    // sub-agent 是长时全域操作(嵌套 agent 与主 agent 同权,可写任意文件/跑任意命令),
+    // 不进 mutation 并发批:逐个串行执行,避免两个子 agent 同时改工作区。
+    return call.name !== 'sub-agent' && isResourceLockedTool(call.name);
+}
+/** 权限拒绝时的结构化 ToolOutcome(供调度器统一回灌,不抛错中断循环)。 */
+export function deniedOutcome(name) {
+    return {
+        status: 'denied',
+        code: 'PERMISSION_DENIED',
+        retryable: false,
+        output: `错误:用户拒绝了工具 ${name} 的执行。`,
+    };
+}
+/** mutation 执行前读旧内容供 diff:write_file 取整文件旧内容(不存在→null=新建),
+ * edit_file 取 old_string 起始行号(供 diff 显示真实文件行号)。读不到则 diff 退化为相对行号。
+ * 非 mutation 或参数非法返 { preWriteOld: null, editStartLine: 1 }。失败不阻断。 */
+export function readDiffContext(tc, parsed) {
+    if (!parsed)
+        return { preWriteOld: null, editStartLine: 1 };
+    const p = String(parsed.path ?? '');
+    if (!p)
+        return { preWriteOld: null, editStartLine: 1 };
+    if (tc.name === 'write_file') {
+        try {
+            // jailResolve:沙箱越界(../../、绝对外圈、软链出圈)抛错 → catch 兜底返 null,不泄露牢外内容(TOCTOU)
+            return { preWriteOld: readFileSync(jailResolve(p), 'utf8'), editStartLine: 1 };
+        }
+        catch {
+            return { preWriteOld: null, editStartLine: 1 }; // 文件不存在(新建)、不可读 或 沙箱越界(不泄露)
+        }
+    }
+    if (tc.name === 'edit_file') {
+        // 行尾归一化:LLM 生成的 old_string 用 LF(\n),但 Windows 文件可能是 CRLF(\r\n),
+        // 不统一则 indexOf 必败、editStartLine 恒为 1。与 edit-file.ts 保持一致归一化为 LF。
+        const oldStr = String(parsed.old_string ?? '')
+            .replace(/\r\n/g, '\n')
+            .replace(/\r/g, '\n');
+        try {
+            // jailResolve:同上,沙箱越界抛错 → catch 兜底,不泄露牢外内容
+            const raw = readFileSync(jailResolve(p), 'utf8');
+            const data = raw.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+            const idx = oldStr ? data.indexOf(oldStr) : -1;
+            return {
+                preWriteOld: null,
+                editStartLine: idx >= 0 ? data.slice(0, idx).split('\n').length : 1,
+            };
+        }
+        catch {
+            return { preWriteOld: null, editStartLine: 1 }; // 读不到:diff 退化为相对行号(含沙箱越界)
+        }
+    }
+    return { preWriteOld: null, editStartLine: 1 };
+}
+/** 回灌 tool 结果到 history。
+ *  正常路径只做单条 hard cap;原始 output 同时供 TUI 展示,因此用户与模型
+ *  看到同一事实。Artifact/Relevance/Lifecycle 仅登记 metadata/provenance,
+ *  不在这里改写旧正文;所有自动清理与压缩统一由 80% pressure scheduler 决定。 */
+export function pushToolResult(history, tc, output, pruner, lifecycle, _scheduler, runtimeContextState = contextState, succeededOverride) {
+    const succeeded = succeededOverride ?? isToolResultSuccess(output);
+    const msg = {
+        role: 'tool',
+        tool_call_id: tc.id,
+        // Preserve evidence verbatim in normal operation; the hard per-result cap
+        // remains solely as a request-size safety rail.
+        content: capToolResultForHistory(tc.name, output),
+    };
+    history.push(msg);
+    const messageIndex = history.length - 1;
+    recordArtifact(runtimeContextState, history, messageIndex, output, succeeded);
+    // 失败 read 不得淘汰旧 read;失败 consumer 也不能改变 lifecycle 上游状态。
+    if (pruner)
+        pruner.observePush(history, msg, succeeded);
+    if (lifecycle)
+        lifecycle.pushTool(history, messageIndex, succeeded);
+    runtimeContextState.lifecycleStats = lifecycle?.stats();
+}