@bolloon/bolloon-agent 0.1.41 → 0.2.0

package/dist/agents/pi-sdk.js

@@ -15,7 +15,7 @@ import { DeepThinkingEngine, AgentCoordinator } from '@bolloon/constraint-runtim
 import { WorkflowPivotLoop, createDefaultPivotConfig } from './workflow-pivot-loop.js';
 import { p2pDocumentTools, initDocumentReceiver } from './p2p-document-tools.js';
 import { shellExec } from './shell-tool.js';
-import { getBranchPrefix, getCooldownMs } from './shell-guard.js';
+import { getBranchPrefix, getCooldownMs, checkWritePath } from './shell-guard.js';
 import { DiscoveredAgentsManager, createSocialHeartbeat } from '../social/heartbeat.js';
 import { getGlobalSharedContext } from '../social/global-shared-context.js';
 import { Session, SkillRegistry, saveSession, loadSession } from '@bolloon/constraint-runtime';
@@ -345,6 +345,10 @@ class PiAgentSession {
     messageHistory = [];
     tools = new Map();
     skillRegistry = new SkillRegistry();
+    /** M2.4: 缓存 tool 列表, registerTools() 之后不变, runReActLoop 多次循环复用 */
+    cachedToolDefinitions = '';
+    /** M2.4: 缓存 persona section */
+    cachedPersonaSection = '';
     // 2026-06-16 修: 父要求把 ReAct loop 上限放大到 "几乎无限", 靠自动压缩上下文 + fail-safe 兜底
     // 默认 10000 — 正常任务永远跑不到, 但作为防 LLM 死循环 / 防 OOM 的最后一道闸
     // 旧默认 100 写死导致中等复杂度任务 (10-50 个 tool call + 多步反思) 会被误杀
@@ -356,6 +360,10 @@ class PiAgentSession {
     /** 2026-06-16 新增: 累计错误总数兜底 (不管是否同工具, 累计 N 次就强制退出)
      *  防 LLM 轮换工具名绕开 MAX_SAME_TOOL_FAILURES 的死循环攻击 */
     MAX_TOTAL_ERRORS = 20;
+    /** 2026-06-19: 记录 loop 内成功执行的工具结果, 失败退出时汇总给用户 */
+    successfulToolResults = [];
+    /** 2026-06-19: Agent Mesh 通信 — 本地 + 远端 inbox 缓存, 给 check_inbox 工具读 */
+    _inboxMessages = [];
     /** 2026-06-16 新增: loop 内自动压缩触发阈值 (相对 60K 阈值的比例) */
     LOOP_COMPACT_RATIO = 0.8;
     /** P1: max output token 升级重试 (LLM 截断时重试, 最多 3 次) */
@@ -378,6 +386,9 @@ class PiAgentSession {
      */
     judgmentGateAddition = '';
     judgmentGateUsedIds = [];
+    // 2026-06-18: 来自 web server markedPrompt 外的 contextHint (channel/judgment/distill/remote channels),
+    //   拼到 systemPrompt 末尾, 别再混进 user message
+    contextHintAddition = '';
     /**
      * 当前 onStream 引用 + abort signal (computeJudgmentGate 需要 onStream 广播 phase)
      * 每次 prompt / promptStream / promptWithPivotLoop 入口设置, 用完即清
@@ -390,6 +401,9 @@ class PiAgentSession {
     promptStartTime = 0;
     /** 当前 channel id (由 getAgentForChannel / prompt 4 参注入, 供 hook / log 使用) */
     currentChannelId = '';
+    /** M2.2 (2026-06-17): 当前轮的用户请求 intent, runReActLoop 拼 systemPrompt 时会读这个 */
+    currentIntent = 'chitchat';
+    currentIntentHint = '';
     /**
      * 算 judgment 注入门: 失败静默, 不阻塞主对话
      * 期间通过 currentOnStream 广播 phase 事件, 前端可显示 "正在检索判断力..." 状态
@@ -441,6 +455,50 @@ class PiAgentSession {
         this.registerTools();
         this.loadSkills(config.skillsPaths);
         this.initHarness();
+        // M2.3 (2026-06-17): 重启后 LLM 恢复记忆 — 从 session JSON 加载历史到 messageHistory
+        //   之前 messageHistory 是空的, 服务重启后 LLM 看到的是新对话
+        //   现在 loadSessionKey 形如 "channel-xxx:default" 走 ~/.bolloon/sessions/cache/<key>.json
+        if (config.loadSessionKey) {
+            this.hydrateMessageHistory(config.loadSessionKey, config.loadSessionMaxMessages ?? 30);
+        }
+    }
+    /**
+     * M2.3: 从 session JSON 加载历史, 转成 messageHistory 格式
+     * - 失败静默 (历史加载失败不应该阻塞 agent 启动)
+     * - 限制 max 条数, 防止 context 爆
+     * - user 消息 role=user, ai 消息 role=assistant
+     * - 跳过 metadata 中含 error 的 (错误消息会污染 LLM)
+     */
+    async hydrateMessageHistory(sessionKey, maxMessages) {
+        try {
+            const sessionPath = path.join(os.homedir(), '.bolloon', 'sessions', 'cache', `${sessionKey}.json`);
+            const content = await fs.readFile(sessionPath, 'utf-8');
+            const session = JSON.parse(content);
+            const messages = Array.isArray(session?.messages) ? session.messages : [];
+            // 保留最后 N 条, 转换 role 字段
+            const tail = messages.slice(-maxMessages);
+            const hydrated = [];
+            for (const m of tail) {
+                // 跳过错误的 AI 消息 (M1.2 之后, AI 错误时 reply 是 [AI 服务调用失败] 字符串, 不该进 history)
+                if (m?.type === 'ai' && typeof m.content === 'string' && m.content.startsWith('[AI 服务调用失败]'))
+                    continue;
+                if (m?.type === 'ai' && typeof m.content === 'string' && m.content.startsWith('[错误:'))
+                    continue;
+                if (!m?.content)
+                    continue;
+                const role = m.type === 'user' ? 'user' : m.type === 'ai' ? 'assistant' : null;
+                if (!role)
+                    continue;
+                hydrated.push({ role, content: String(m.content) });
+            }
+            if (hydrated.length > 0) {
+                this.messageHistory = hydrated;
+                console.log(`[PiAgent] 从 ${sessionKey} 回灌 ${hydrated.length} 条历史`);
+            }
+        }
+        catch (err) {
+            console.warn(`[PiAgent] hydrateMessageHistory 失败 (non-fatal): ${err.message?.slice(0, 100)}`);
+        }
     }
     /**
      * 从 SKILL.md 目录加载 skills 进 skillRegistry.
@@ -621,6 +679,162 @@ class PiAgentSession {
                 }
             }
         });
+        // 2026-06-19: 本地 + 远端智能体通信工具集 (Agent Mesh 通信层)
+        //   解决"另一个智能体发消息"的能力缺口:
+        //   - 本地 channel: 走 PiSessionManager.getAllChannels / addMessage / getChannelMessages
+        //   - 远端 P2P: 走 p2pNetwork.sendMessage
+        this._inboxMessages = [];
+        this._setupInboxListener();
+        // list_local_channels: 列出本 session 内所有 channel
+        this.tools.set('list_local_channels', {
+            name: 'list_local_channels',
+            description: '列出当前 PiAgentSession 注册的所有 channel. 每个 channel 是 bolloon 内的智能体会话, 可含 messages[] / peerDid(对端 DID) / peerName. 供 send_to_channel 选 channel_id.',
+            parameters: {},
+            execute: async () => {
+                const channels = this.sessionManager.getAllChannels();
+                if (channels.length === 0) {
+                    return { success: true, output: '📭 当前 session 没有注册任何 channel (用 send_to_channel 留空 channel_id 会自动创建一个)' };
+                }
+                const lines = channels.map((ch, i) => {
+                    const peer = ch.peerDid ? ` peer=${ch.peerDid.substring(0, 20)}` : (ch.peerName ? ` peer="${ch.peerName}"` : '');
+                    const msgCount = ch.messages?.length || 0;
+                    return `  ${i + 1}. ${ch.id} name="${ch.name}" msgs=${msgCount}${peer}`;
+                });
+                return { success: true, output: `📬 当前 session 有 ${channels.length} 个 channel:\n${lines.join('\n')}` };
+            }
+        });
+        // send_to_channel: 把消息发到指定 channel (本地 + 如果 channel 有关联 peerDid 也走 P2P 转发)
+        this.tools.set('send_to_channel', {
+            name: 'send_to_channel',
+            description: '发送消息到指定 channel. channel_id 留空会自动创建一个. 如果 channel 已关联 peerDid, 会同时通过 P2P 转发到对端 agent.',
+            parameters: { channel_id: '目标 channel id (留空自动创建)', message: '消息内容 (必填)', peer_did: '可选 创建新 channel 时绑定的对端 DID (e.g. did:key:...)' },
+            execute: async (args) => {
+                const message = String(args.message || '').trim();
+                if (!message)
+                    return { success: false, error: 'message 必填' };
+                let channelId = String(args.channel_id || '').trim();
+                const peerDid = args.peer_did ? String(args.peer_did) : undefined;
+                if (!channelId) {
+                    // 自动创建 channel
+                    const ch = await this.sessionManager.getOrCreatePeerChannel(peerDid || 'auto-created', 'auto-created');
+                    channelId = ch.id;
+                }
+                // 用 AgentSession 接口方法发消息 (它会自动设置 type/agentId/timestamp)
+                await this.sendSocialMessage(channelId, message);
+                // 如果 channel 关联了 peer, 走 P2P 转发
+                const ch = this.sessionManager.getAllChannels().find(c => c.id === channelId);
+                if (ch?.peerDid) {
+                    try {
+                        const peerId = ch.peerDid.replace(/^did:key:/, '').replace(/^did:pi:/, '');
+                        await p2pNetwork.sendMessage(peerId, 'channel-message', JSON.stringify({ channelId, content: message, from: this.identity.did, timestamp: new Date().toISOString() }));
+                        return { success: true, output: `📨 消息已存到 channel ${channelId} + P2P 转发到 ${ch.peerDid.substring(0, 30)}...` };
+                    }
+                    catch (e) {
+                        return { success: true, output: `📨 消息已存到 channel ${channelId} (P2P 转发失败: ${String(e).slice(0, 100)})` };
+                    }
+                }
+                return { success: true, output: `📨 消息已存到 channel ${channelId}` };
+            }
+        });
+        // check_channel_inbox: 读指定 channel 的所有 messages
+        this.tools.set('check_channel_inbox', {
+            name: 'check_channel_inbox',
+            description: '读取指定 channel 的所有 messages, 按时间排序. channel_id 必填, 来自 list_local_channels.',
+            parameters: { channel_id: '目标 channel id (必填)', max: '可选, 最多返回 N 条 (默认 50)' },
+            execute: async (args) => {
+                const channelId = String(args.channel_id || '').trim();
+                if (!channelId)
+                    return { success: false, error: 'channel_id 必填' };
+                const max = Number(args.max) || 50;
+                const messages = await this.sessionManager.getChannelMessages(channelId);
+                const channel = this.sessionManager.getAllChannels().find(c => c.id === channelId);
+                const channelName = channel?.name || channelId;
+                if (messages.length === 0) {
+                    return { success: true, output: `📭 channel "${channelName}" (${channelId}) 空, 0 条消息` };
+                }
+                const slice = messages.slice(-max);
+                const lines = slice.map((m, i) => {
+                    const from = m.sender || m.from || m.fromDid || m.agentId || '?';
+                    const ts = m.timestamp || m.createdAt || '?';
+                    const content = (m.content || m.text || '').substring(0, 200);
+                    return `  ${i + 1}. [${m.type || 'text'}] from=${from} time=${ts}\n     ${content}`;
+                });
+                return { success: true, output: `📬 channel "${channelName}" (${channelId}) 有 ${slice.length} 条消息 (共 ${messages.length}):\n${lines.join('\n')}` };
+            }
+        });
+        // check_inbox: 兼容旧名, 实际走 check_channel_inbox
+        this.tools.set('check_inbox', {
+            name: 'check_inbox',
+            description: "兼容旧名: 默认读第一个 channel 的 messages. 推荐用 list_local_channels + check_channel_inbox(channel_id)",
+            parameters: { max: '可选, 最多返回 N 条 (默认 50)' },
+            execute: async (args) => {
+                const channels = this.sessionManager.getAllChannels();
+                if (channels.length === 0) {
+                    return { success: true, output: '📭 当前 session 没有 channel, 0 条消息' };
+                }
+                const first = channels[0];
+                // 直接调 check_channel_inbox 复用逻辑
+                return await this.tools.get('check_channel_inbox').execute({ channel_id: first.id, max: String(args.max || 50) });
+            }
+        });
+        // send_to_peer: 发送结构化消息到指定 P2P 节点
+        this.tools.set('send_to_peer', {
+            name: 'send_to_peer',
+            description: '发送结构化消息到指定 P2P 节点 (远端 bolloon 实例). 对方会通过远端 channel 收到.',
+            parameters: { peer_id: '目标 P2P 节点 publicKey (用 list_peers 查)', message: '消息内容 (任意字符串)', type: '可选, 消息类型标签 (默认 agent-message)' },
+            execute: async (args) => {
+                const peerId = String(args.peer_id || '').trim();
+                const msg = String(args.message || '').trim();
+                const type = String(args.type || 'agent-message').trim();
+                if (!peerId)
+                    return { success: false, error: 'peer_id 必填' };
+                if (!msg)
+                    return { success: false, error: 'message 必填' };
+                try {
+                    await p2pNetwork.sendMessage(peerId, type, msg);
+                    return { success: true, output: `✅ 消息已发送到 ${peerId.substring(0, 16)}...` };
+                }
+                catch (e) {
+                    return { success: false, error: `发送失败: ${String(e)}` };
+                }
+            }
+        });
+        // p2p_broadcast: 广播给所有 P2P 节点
+        this.tools.set('p2p_broadcast', {
+            name: 'p2p_broadcast',
+            description: '广播消息到所有连接的 P2P 节点',
+            parameters: { message: '消息内容', type: '可选, 消息类型标签 (默认 agent-broadcast)' },
+            execute: async (args) => {
+                const msg = String(args.message || '').trim();
+                const type = String(args.type || 'agent-broadcast').trim();
+                if (!msg)
+                    return { success: false, error: 'message 必填' };
+                try {
+                    await p2pNetwork.broadcast(type, msg);
+                    return { success: true, output: `📡 已广播 type=${type}` };
+                }
+                catch (e) {
+                    return { success: false, error: `广播失败: ${String(e)}` };
+                }
+            }
+        });
+        // agent_call: RPC 风格远端 agent 任务调用
+        this.tools.set('agent_call', {
+            name: 'agent_call',
+            description: 'RPC: 让远端 P2P agent 跑一个任务, 等待结果返回. 远端 agent 会基于 task 描述自主完成, 完成后回复. (RPC 结果回收机制待实现)',
+            parameters: { peer_id: '目标 P2P 节点', task: '任务描述 (远端 agent 收到的 prompt)', timeoutMs: '可选 超时 (ms, 默认 30000)' },
+            execute: async (args) => {
+                const peerId = String(args.peer_id || '').trim();
+                const task = String(args.task || '').trim();
+                if (!peerId)
+                    return { success: false, error: 'peer_id 必填' };
+                if (!task)
+                    return { success: false, error: 'task 必填' };
+                const requestId = `rpc-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+                await p2pNetwork.sendMessage(peerId, 'agent-call', JSON.stringify({ requestId, task, from: this.identity?.did }));
+                return { success: true, output: `📞 RPC 任务已发送给 ${peerId.substring(0, 16)}...\n   requestId=${requestId}` };
+            }
+        });
         this.tools.set('get_identity', {
             name: 'get_identity',
             description: '获取当前智能体身份信息',
@@ -743,13 +957,38 @@ class PiAgentSession {
         // 沙箱 cwd: .bolloon-shell-sandbox/
         this.tools.set('shell_exec', {
             name: 'shell_exec',
-            description: '在沙箱里跑 shell 命令. 仅支持白名单内命令: git, npm, npx, tsx, tsc, vitest, cat, head, tail, ls, wc, echo, pwd, date, mkdir, touch. 禁止管道/重定向/rm -rf/sudo. 命中护栏黑名单会被拒.',
+            description: '在 cwd (process.cwd(), 即 bolloon 当前工作目录) 跑 shell 命令. 仅支持白名单内命令: git, npm, npx, tsx, tsc, vitest, cat, head, tail, ls, wc, echo, pwd, date, mkdir, touch. 禁止管道/重定向/rm -rf/sudo. 命中护栏黑名单会被拒. 注意: cwd 是真正的 git repo 工作目录, git add/commit/push 等命令会作用于本仓库, 不是 sandbox.',
             parameters: { command: '可执行文件 (必填, 必须在白名单)', args: '参数数组, 逗号分隔', timeoutMs: '超时毫秒, 默认 30000' },
             execute: async (args) => {
                 const cmd = String(args.command || '').trim();
                 if (!cmd)
                     return { success: false, error: 'command 必填' };
-                const argList = String(args.args || '').split(',').map(s => s.trim()).filter(Boolean);
+                // 2026-06-19: 支持多种 args 格式
+                //   1. JSON 数组: ["checkout", "-b", "branch"] (LLM 偏好)
+                //   2. 逗号分隔: "checkout,-b,branch" (旧格式)
+                //   3. 字符串: "checkout -b branch" (单参数)
+                let argList = [];
+                const rawArgs = args.args;
+                if (Array.isArray(rawArgs)) {
+                    argList = rawArgs.map((s) => String(s).trim()).filter(Boolean);
+                }
+                else if (typeof rawArgs === 'string') {
+                    const trimmed = rawArgs.trim();
+                    if (trimmed.startsWith('[') && trimmed.endsWith(']')) {
+                        // JSON 数组字符串
+                        try {
+                            const parsed = JSON.parse(trimmed);
+                            if (Array.isArray(parsed)) {
+                                argList = parsed.map((s) => String(s).trim()).filter(Boolean);
+                            }
+                        }
+                        catch { /* fall through to comma split */ }
+                    }
+                    if (argList.length === 0) {
+                        // 逗号分隔 或 单字符串
+                        argList = trimmed.split(',').map(s => s.trim()).filter(Boolean);
+                    }
+                }
                 const timeoutMs = Number(args.timeoutMs) || 30000;
                 const result = await shellExec(cmd, argList, { timeoutMs });
                 if (result.deniedByGuard) {
@@ -816,17 +1055,620 @@ class PiAgentSession {
                 }
             }
         });
+        // M2.1 (2026-06-17): 注册 4 个长期缺失的工具 — 让 agent 真正能"修改 + 提交"代码
+        // 路径限制走 shell-guard 同款 allowlist (复用 checkWritePath / checkCommand)
+        // 这些工具之前在 tool-gate 白名单 + tool-manifest 中存在, 但 pi-sdk 未注册 — 修复孤儿
+        this.tools.set('write_file', {
+            name: 'write_file',
+            description: '写入一个文件. 路径必须在白名单 (src/web/*, src/agents/workflow-*, *.md, docs/**, src/test/**, src/agents/pi-sdk.ts 等). 大文件 (> 100KB) 会被拒. 命中护栏黑名单 (shell-guard.ts, package.json, .env, .git, .bolloon, dist) 会拒.',
+            parameters: { path: '相对路径 (必填, 相对 cwd)', content: '文件内容 (必填)' },
+            execute: async (args) => {
+                const relPath = String(args.path || '').trim();
+                const content = String(args.content ?? '');
+                if (!relPath)
+                    return { success: false, error: 'path 必填' };
+                if (content.length > 100_000)
+                    return { success: false, error: `内容过大 (${content.length} > 100000 字节), 请分块写` };
+                // 路径检查: 复用 shell-guard 的 checkWritePath
+                const pathResult = checkWritePath(relPath);
+                if (!pathResult.allowed) {
+                    return { success: false, error: `路径被护栏拒: ${pathResult.reason}` };
+                }
+                try {
+                    const absPath = path.resolve(this.cwd, relPath);
+                    await fs.mkdir(path.dirname(absPath), { recursive: true });
+                    await fs.writeFile(absPath, content, 'utf-8');
+                    return { success: true, output: `✅ wrote ${relPath} (${content.length} bytes)` };
+                }
+                catch (e) {
+                    return { success: false, error: `写文件失败: ${String(e)}` };
+                }
+            }
+        });
+        this.tools.set('edit_file', {
+            name: 'edit_file',
+            description: '编辑一个文件: 在 path 处查找 old_text, 替换为 new_text. 找不到 old_text 会失败 (避免静默不替换). 路径同样受护栏限制.',
+            parameters: { path: '相对路径 (必填)', old_text: '要替换的文本 (必填, 全文匹配)', new_text: '新文本 (必填)' },
+            execute: async (args) => {
+                const relPath = String(args.path || '').trim();
+                const oldText = String(args.old_text ?? '');
+                const newText = String(args.new_text ?? '');
+                if (!relPath)
+                    return { success: false, error: 'path 必填' };
+                if (!oldText)
+                    return { success: false, error: 'old_text 必填' };
+                const pathResult = checkWritePath(relPath);
+                if (!pathResult.allowed) {
+                    return { success: false, error: `路径被护栏拒: ${pathResult.reason}` };
+                }
+                try {
+                    const absPath = path.resolve(this.cwd, relPath);
+                    const original = await fs.readFile(absPath, 'utf-8');
+                    if (!original.includes(oldText)) {
+                        return { success: false, error: `old_text 在 ${relPath} 中未找到, 拒绝静默写入. 请先用 read_document 读最新内容.` };
+                    }
+                    const updated = original.replace(oldText, newText);
+                    await fs.writeFile(absPath, updated, 'utf-8');
+                    return { success: true, output: `✅ edited ${relPath} (${oldText.length} → ${newText.length} 字节)` };
+                }
+                catch (e) {
+                    return { success: false, error: `编辑文件失败: ${String(e)}` };
+                }
+            }
+        });
+        this.tools.set('git_diff', {
+            name: 'git_diff',
+            description: '查看 git diff. 默认显示未提交改动 (staged + unstaged), 可指定 ref1..ref2 看两个 commit/分支之间的 diff. 输出会截到 8000 字符避免超长.',
+            parameters: { range: '可选. e.g. "HEAD~3..HEAD" 或 "master..agent/feat-x". 省略则看未提交改动.' },
+            execute: async (args) => {
+                const range = String(args.range || '').trim();
+                const argv = range ? ['diff', range] : ['diff'];
+                const result = await shellExec('git', argv, { timeoutMs: 10_000 });
+                if (result.deniedByGuard)
+                    return { success: false, error: result.error };
+                if (!result.success)
+                    return { success: false, error: result.error, output: result.output };
+                const out = (result.output || '').slice(0, 8000);
+                return { success: true, output: out || '(空 diff — 没有未提交改动)' };
+            }
+        });
+        this.tools.set('git_commit', {
+            name: 'git_commit',
+            description: 'git add -A + git commit. 提交信息由 LLM 提供. 不会 push — push 是 agent 显式调 git_commit_and_push 触发. 命中护栏 (push to master/main, force-push) 仍会被拒. 内部自动设 BOLLOON_AUTO_EVOLVE=1 让 pre-commit hook 跳过 vitest/tsc (auto-evolve 模式, CI 兜底).',
+            parameters: { message: 'commit message (必填, 用 HEREDOC 多行)' },
+            execute: async (args) => {
+                const message = String(args.message || '').trim();
+                if (!message)
+                    return { success: false, error: 'message 必填' };
+                // M3.4 (2026-06-17): agent git_commit 自动设 BOLLOON_AUTO_EVOLVE=1, 让 lefthook pre-commit 跳过 vitest/tsc
+                //   这样频繁 commit 不会被 30s+ 的 pre-commit 阻塞. CI 会兜底 (push 后 GitHub Actions 跑测试)
+                // 先 add
+                const addResult = await shellExec('git', ['add', '-A'], { timeoutMs: 10_000 });
+                if (addResult.deniedByGuard)
+                    return { success: false, error: addResult.error };
+                if (!addResult.success)
+                    return { success: false, error: `git add 失败: ${addResult.error}` };
+                // 再 commit (message 用 -m, 避免 HEREDOC 注入)
+                // Windows shell 不支持 inline env var, 改用 child_process 直接 spawn
+                // 简单方案: 用 spawn + 临时设 env
+                try {
+                    const { spawn: spawnFn } = await import('child_process');
+                    const env = { ...process.env, BOLLOON_AUTO_EVOLVE: '1' };
+                    const output = await new Promise((resolve, reject) => {
+                        const proc = spawnFn('git', ['commit', '-m', message], {
+                            cwd: this.cwd, env, stdio: ['ignore', 'pipe', 'pipe'],
+                        });
+                        let stdout = '';
+                        let stderr = '';
+                        proc.stdout.on('data', (d) => stdout += d.toString());
+                        proc.stderr.on('data', (d) => stderr += d.toString());
+                        proc.on('close', (code) => code === 0 ? resolve(stdout) : reject(new Error(stderr || `git commit exited ${code}`)));
+                        proc.on('error', reject);
+                    });
+                    return { success: true, output: `✅ committed: ${message.split('\n')[0]}\n${output}` };
+                }
+                catch (e) {
+                    return { success: false, error: `git commit 失败: ${String(e.message || e).slice(0, 500)}` };
+                }
+            }
+        });
+        // M3.4: git_push — 改完直接 push (Q3-B 决策, 修改了 pre-push hook 让它别卡)
+        // 命中护栏 (push to master/main, force-push) 仍会被拒 — 这两条底线不变
+        this.tools.set('git_push', {
+            name: 'git_push',
+            description: 'git push 当前分支到 origin. 命中护栏 (push to master/main, --force) 仍会被拒. 用于长期项目自动 commit + push 循环.',
+            parameters: { remote: '可选, 默认 origin', branch: '可选, 默认当前分支' },
+            execute: async (args) => {
+                const remote = String(args.remote || 'origin').trim();
+                const branch = String(args.branch || '').trim();
+                const argv = branch ? ['push', remote, branch] : ['push', remote];
+                const result = await shellExec('git', argv, { timeoutMs: 60_000 });
+                if (result.deniedByGuard)
+                    return { success: false, error: result.error };
+                if (!result.success)
+                    return { success: false, error: result.error, output: result.output };
+                return { success: true, output: `✅ pushed to ${remote}${branch ? `/${branch}` : ''}\n${result.output || ''}` };
+            }
+        });
+        // M3.4: git_branch — 创建/切换分支 (用于多任务并行隔离)
+        this.tools.set('git_branch', {
+            name: 'git_branch',
+            description: 'git checkout -b <name> 或 git checkout <name>. 用于多任务并行隔离 — 改前先 checkout 到 agent/<task-id> 分支.',
+            parameters: { name: '分支名 (必填, e.g. "agent/task-123")', create: '可选, "true" 表示创建新分支 (默认 false = 切到已有)' },
+            execute: async (args) => {
+                const name = String(args.name || '').trim();
+                const create = String(args.create || 'false') === 'true';
+                if (!name)
+                    return { success: false, error: 'name 必填' };
+                const argv = create ? ['checkout', '-b', name] : ['checkout', name];
+                const result = await shellExec('git', argv, { timeoutMs: 10_000 });
+                if (result.deniedByGuard)
+                    return { success: false, error: result.error };
+                if (!result.success)
+                    return { success: false, error: result.error, output: result.output };
+                return { success: true, output: `✅ ${create ? 'created + checked out' : 'checked out'} ${name}\n${result.output || ''}` };
+            }
+        });
+        // 2026-06-19: 实用代码修改工具集 (M4) — 补全 read/delete/mkdir/move + grep/git log/show
+        //   这些是 LLM 自主完成代码修改的最小工具集, 之前只能通过 shell_exec 间接调用
+        // 通用文件读取 (支持任意扩展名, 跟 read_document 区别是后者只支持 txt/md/pdf/docx)
+        this.tools.set('read_file', {
+            name: 'read_file',
+            description: '读取任意文件内容 (相对 cwd). 与 read_document 区别: 不限制文件类型. 受 shell-guard 路径白名单保护.',
+            parameters: { path: '相对路径 (必填, e.g. "src/agents/pi-sdk.ts")', startLine: '起始行号 (可选, 默认 0)', maxLines: '最大行数 (可选, 默认 500)' },
+            execute: async (args) => {
+                const relPath = String(args.path || '').trim();
+                if (!relPath)
+                    return { success: false, error: 'path 必填' };
+                const pathResult = checkWritePath(relPath);
+                if (!pathResult.allowed)
+                    return { success: false, error: `路径被护栏拒: ${pathResult.reason}` };
+                try {
+                    const absPath = path.resolve(this.cwd, relPath);
+                    const content = fsSync.readFileSync(absPath, 'utf-8');
+                    const start = Math.max(0, parseInt(String(args.startLine || '0')) || 0);
+                    const max = parseInt(String(args.maxLines || '500')) || 500;
+                    const lines = content.split('\n');
+                    const slice = lines.slice(start, start + max);
+                    return { success: true, output: `📄 ${relPath} (第 ${start + 1}-${start + slice.length} 行, 共 ${lines.length} 行):\n${slice.map((l, i) => `${String(start + i + 1).padStart(4)} | ${l}`).join('\n')}` };
+                }
+                catch (e) {
+                    return { success: false, error: `读取失败: ${e.message}` };
+                }
+            }
+        });
+        // 删除文件
+        this.tools.set('delete_file', {
+            name: 'delete_file',
+            description: '删除一个文件. 受 shell-guard 路径白名单保护. 不可恢复, 调用前请确认.',
+            parameters: { path: '相对路径 (必填)' },
+            execute: async (args) => {
+                const relPath = String(args.path || '').trim();
+                if (!relPath)
+                    return { success: false, error: 'path 必填' };
+                const pathResult = checkWritePath(relPath);
+                if (!pathResult.allowed)
+                    return { success: false, error: `路径被护栏拒: ${pathResult.reason}` };
+                try {
+                    const absPath = path.resolve(this.cwd, relPath);
+                    if (!fsSync.existsSync(absPath))
+                        return { success: false, error: `文件不存在: ${relPath}` };
+                    fsSync.unlinkSync(absPath);
+                    return { success: true, output: `✅ deleted ${relPath}` };
+                }
+                catch (e) {
+                    return { success: false, error: `删除失败: ${e.message}` };
+                }
+            }
+        });
+        // 创建目录
+        this.tools.set('mkdir', {
+            name: 'mkdir',
+            description: '创建一个或多个目录. 自动 mkdir -p (父目录不存在也创建).',
+            parameters: { path: '目录路径 (必填, 相对 cwd)' },
+            execute: async (args) => {
+                const relPath = String(args.path || '').trim();
+                if (!relPath)
+                    return { success: false, error: 'path 必填' };
+                const pathResult = checkWritePath(relPath);
+                if (!pathResult.allowed)
+                    return { success: false, error: `路径被护栏拒: ${pathResult.reason}` };
+                try {
+                    const absPath = path.resolve(this.cwd, relPath);
+                    fsSync.mkdirSync(absPath, { recursive: true });
+                    return { success: true, output: `✅ mkdir ${relPath}` };
+                }
+                catch (e) {
+                    return { success: false, error: `创建失败: ${e.message}` };
+                }
+            }
+        });
+        // 移动/重命名文件
+        this.tools.set('move_file', {
+            name: 'move_file',
+            description: '移动或重命名文件. 源和目标路径都在白名单内才允许.',
+            parameters: { from: '源路径 (必填)', to: '目标路径 (必填)' },
+            execute: async (args) => {
+                const from = String(args.from || '').trim();
+                const to = String(args.to || '').trim();
+                if (!from || !to)
+                    return { success: false, error: 'from 和 to 都必填' };
+                const fromCheck = checkWritePath(from);
+                if (!fromCheck.allowed)
+                    return { success: false, error: `from 路径被护栏拒: ${fromCheck.reason}` };
+                const toCheck = checkWritePath(to);
+                if (!toCheck.allowed)
+                    return { success: false, error: `to 路径被护栏拒: ${toCheck.reason}` };
+                try {
+                    const fromAbs = path.resolve(this.cwd, from);
+                    const toAbs = path.resolve(this.cwd, to);
+                    if (!fsSync.existsSync(fromAbs))
+                        return { success: false, error: `源文件不存在: ${from}` };
+                    fsSync.mkdirSync(path.dirname(toAbs), { recursive: true });
+                    fsSync.renameSync(fromAbs, toAbs);
+                    return { success: true, output: `✅ ${from} → ${to}` };
+                }
+                catch (e) {
+                    return { success: false, error: `移动失败: ${e.message}` };
+                }
+            }
+        });
+        // 文件内搜索 (类似 grep)
+        this.tools.set('grep_files', {
+            name: 'grep_files',
+            description: '在文件中搜索匹配 pattern 的行. 类似 grep -rn. 路径必须在白名单.',
+            parameters: { pattern: '搜索 pattern (必填, 字符串, 不是正则)', path: '搜索目录 (可选, 默认 .)', filePattern: '文件名 glob (可选, e.g. "*.ts")' },
+            execute: async (args) => {
+                const pattern = String(args.pattern || '').trim();
+                if (!pattern)
+                    return { success: false, error: 'pattern 必填' };
+                const searchPath = String(args.path || '.').trim();
+                const pathResult = checkWritePath(searchPath);
+                if (!pathResult.allowed)
+                    return { success: false, error: `路径被护栏拒: ${pathResult.reason}` };
+                try {
+                    const { execFile } = await import('child_process');
+                    const { promisify } = await import('util');
+                    const pExecFile = promisify(execFile);
+                    const argv = ['-rn', '--include=' + (args.filePattern || '*'), pattern, searchPath];
+                    const { stdout, stderr } = await pExecFile('grep', argv, { cwd: this.cwd, maxBuffer: 1024 * 1024 });
+                    const lines = stdout.split('\n').filter(Boolean).slice(0, 50);
+                    return { success: true, output: `🔍 grep "${pattern}" in ${searchPath} (${args.filePattern || '*'}, 最多 50 行):\n${lines.join('\n')}${lines.length === 50 ? '\n... (truncated)' : ''}` };
+                }
+                catch (e) {
+                    if (e.code === 1)
+                        return { success: true, output: `🔍 grep "${pattern}" in ${searchPath}: 0 matches` };
+                    return { success: false, error: `grep 失败: ${e.message}` };
+                }
+            }
+        });
+        // glob 找文件
+        this.tools.set('glob_files', {
+            name: 'glob_files',
+            description: '用 glob pattern 找文件. 例如 "**/*.test.ts".',
+            parameters: { pattern: 'glob pattern (必填, e.g. "src/**/*.ts")' },
+            execute: async (args) => {
+                const pattern = String(args.pattern || '').trim();
+                if (!pattern)
+                    return { success: false, error: 'pattern 必填' };
+                try {
+                    const pathResult = checkWritePath(pattern.replace(/\*\*.*$/, '').replace(/\/\*.*$/, '') || '.');
+                    if (!pathResult.allowed && pattern !== '**/*' && pattern !== '*')
+                        return { success: false, error: `路径被护栏拒: ${pathResult.reason}` };
+                    const { execFile } = await import('child_process');
+                    const { promisify } = await import('util');
+                    const pExecFile = promisify(execFile);
+                    // 用 shell 的 find + glob (避免引入额外依赖)
+                    const { stdout } = await pExecFile('find', [this.cwd, '-path', `*${pattern.replace(/\*\*\//, '*').replace(/\*\*$/, '*').replace(/\*$/, '*')}`, '-type', 'f'], { maxBuffer: 1024 * 1024 });
+                    const files = stdout.split('\n').filter(Boolean).slice(0, 100);
+                    const relFiles = files.map(f => path.relative(this.cwd, f));
+                    return { success: true, output: `🔍 glob "${pattern}" 找到 ${relFiles.length} 个文件${relFiles.length === 100 ? ' (truncated)' : ''}:\n${relFiles.join('\n')}` };
+                }
+                catch (e) {
+                    return { success: false, error: `glob 失败: ${e.message}` };
+                }
+            }
+        });
+        // git log
+        this.tools.set('git_log', {
+            name: 'git_log',
+            description: '查看 git log. 默认 --oneline -10. 支持过滤和范围.',
+            parameters: { range: '可选, e.g. "HEAD~5..HEAD" 或分支名', maxCount: '可选, 默认 10', oneline: '可选, "true" 用 --oneline (默认 true)' },
+            execute: async (args) => {
+                const range = String(args.range || '').trim();
+                const maxCount = parseInt(String(args.maxCount || '10')) || 10;
+                const oneline = String(args.oneline || 'true') === 'true';
+                const argv = ['log'];
+                if (oneline)
+                    argv.push('--oneline');
+                if (maxCount > 0)
+                    argv.push(`-n`, String(maxCount));
+                if (range)
+                    argv.push(range);
+                const result = await shellExec('git', argv, { timeoutMs: 10_000 });
+                if (result.deniedByGuard)
+                    return { success: false, error: result.error };
+                if (!result.success)
+                    return { success: false, error: result.error, output: result.output };
+                return { success: true, output: `📜 git log:\n${result.output || '(empty)'}` };
+            }
+        });
+        // git show
+        this.tools.set('git_show', {
+            name: 'git_show',
+            description: '查看 commit 内容. 默认 HEAD. 支持 --stat 看统计, --patch 看 diff.',
+            parameters: { ref: '可选, 默认 HEAD', stat: '可选, "true" 只看 stat (默认 false)' },
+            execute: async (args) => {
+                const ref = String(args.ref || 'HEAD').trim();
+                const argv = ['show', ref];
+                if (String(args.stat || 'false') === 'true')
+                    argv.push('--stat');
+                const result = await shellExec('git', argv, { timeoutMs: 15_000 });
+                if (result.deniedByGuard)
+                    return { success: false, error: result.error };
+                if (!result.success)
+                    return { success: false, error: result.error, output: result.output };
+                return { success: true, output: `📜 git show ${ref}:\n${result.output || '(empty)'}` };
+            }
+        });
+        // git stash
+        this.tools.set('git_stash', {
+            name: 'git_stash',
+            description: 'git stash 暂存当前未提交改动. action: save/pop/list/apply/drop. 支持 message.',
+            parameters: { action: '动作 (必填, "save" | "pop" | "list" | "apply" | "drop")', message: '可选, save 时的描述', index: '可选, apply/pop/drop 的 stash index (e.g. "0")' },
+            execute: async (args) => {
+                const action = String(args.action || '').trim();
+                if (!['save', 'pop', 'list', 'apply', 'drop'].includes(action)) {
+                    return { success: false, error: `action 必须是 save/pop/list/apply/drop 之一, 收到: ${action}` };
+                }
+                const argv = ['stash', action];
+                if (action === 'save' && args.message)
+                    argv.push('-m', String(args.message));
+                if ((action === 'apply' || action === 'drop' || action === 'pop') && args.index) {
+                    argv.push('stash@{' + String(args.index) + '}');
+                }
+                const result = await shellExec('git', argv, { timeoutMs: 10_000 });
+                if (result.deniedByGuard)
+                    return { success: false, error: result.error };
+                if (!result.success)
+                    return { success: false, error: result.error, output: result.output };
+                return { success: true, output: `✅ git stash ${action}\n${result.output || ''}` };
+            }
+        });
+        // vitest 跑测试
+        this.tools.set('vitest_run', {
+            name: 'vitest_run',
+            description: '跑 vitest 测试. 自动 bail (失败就停). 默认 60s timeout.',
+            parameters: { pattern: '可选, 文件 glob e.g. "src/agents/pi-sdk.test.ts"', timeoutMs: '可选, 默认 60000' },
+            execute: async (args) => {
+                const argv = ['vitest', 'run', '--reporter=default', '--no-color', '--bail=1'];
+                if (args.pattern)
+                    argv.push(String(args.pattern));
+                const timeoutMs = parseInt(String(args.timeoutMs || '60000')) || 60000;
+                const result = await shellExec('npx', argv, { timeoutMs });
+                if (result.deniedByGuard)
+                    return { success: false, error: result.error };
+                if (!result.success)
+                    return { success: false, error: result.error || 'vitest 失败', output: result.output };
+                return { success: true, output: `✅ vitest 通过:\n${(result.output || '').slice(0, 2000)}` };
+            }
+        });
+        // tsc 编译检查
+        this.tools.set('tsc_check', {
+            name: 'tsc_check',
+            description: '跑 tsc --noEmit 检查 TypeScript 编译. 默认 60s timeout.',
+            parameters: { project: '可选, tsconfig 路径 (默认 tsconfig.json)', timeoutMs: '可选, 默认 60000' },
+            execute: async (args) => {
+                const argv = ['tsc', '--noEmit'];
+                if (args.project)
+                    argv.push('-p', String(args.project));
+                else
+                    argv.push('-p', 'tsconfig.json');
+                const timeoutMs = parseInt(String(args.timeoutMs || '60000')) || 60000;
+                const result = await shellExec('npx', argv, { timeoutMs });
+                if (result.deniedByGuard)
+                    return { success: false, error: result.error };
+                if (!result.success)
+                    return { success: false, error: result.error || 'tsc 失败', output: result.output };
+                return { success: true, output: `✅ tsc 通过:\n${(result.output || 'no errors').slice(0, 1000)}` };
+            }
+        });
+        // M3.2: 任务状态机工具 — 让 agent 自己维护 multi_step 任务的状态
+        this.tools.set('create_task', {
+            name: 'create_task',
+            description: '创建一个新多步任务, 初始 steps 列表由 LLM 给出. 返回 task-id, 后续用 update_task / get_task 跟踪进度. 任务状态写 ~/.bolloon/tasks/<id>.yaml 持久化.',
+            parameters: {
+                goal: '任务目标 (1 句话, 必填)',
+                steps: '步骤列表 (数组, 必填, 至少 1 步)',
+                sessionKey: '可选, 关联的 session key (channel:sessionId)',
+                branch: '可选, 关联的 git 分支名',
+            },
+            execute: async (args) => {
+                const goal = String(args.goal || '').trim();
+                const stepsRaw = args.steps;
+                if (!goal)
+                    return { success: false, error: 'goal 必填' };
+                let steps = [];
+                if (Array.isArray(stepsRaw)) {
+                    steps = stepsRaw.map((s) => String(s).trim()).filter(Boolean);
+                }
+                else if (typeof stepsRaw === 'string') {
+                    // 支持 "step1\nstep2\nstep3" 或 "step1,step2,step3"
+                    steps = stepsRaw.split(/[\n,]/).map(s => s.trim()).filter(Boolean);
+                }
+                if (steps.length === 0)
+                    return { success: false, error: 'steps 必填且至少 1 步' };
+                const sessionKey = String(args.sessionKey || '').trim() || undefined;
+                const branch = String(args.branch || '').trim() || undefined;
+                try {
+                    const { createTask } = await import('./task-state.js');
+                    const task = await createTask({ goal, steps, sessionKey, branch });
+                    return { success: true, output: `✅ task created: ${task.id}\nbranch: ${branch || '(未指定)'}\nsteps:\n${steps.map((s, i) => `  ${i + 1}. ${s}`).join('\n')}` };
+                }
+                catch (e) {
+                    return { success: false, error: `create_task 失败: ${String(e)}` };
+                }
+            }
+        });
+        this.tools.set('update_task', {
+            name: 'update_task',
+            description: '更新任务的某一步状态 (pending → running → done/failed/skipped). 系统会自动推进下一步 pending → running (当当前步 done 时).',
+            parameters: {
+                task_id: '任务 id (必填)',
+                step_id: '步骤 id (必填, e.g. "step-1")',
+                status: '新状态 (running | done | failed | skipped)',
+                result_summary: '可选, 结果摘要',
+                error: '可选, 失败原因 (status=failed 时填)',
+            },
+            execute: async (args) => {
+                const taskId = String(args.task_id || '').trim();
+                const stepId = String(args.step_id || '').trim();
+                const status = String(args.status || '').trim();
+                if (!taskId || !stepId)
+                    return { success: false, error: 'task_id + step_id 必填' };
+                if (!['running', 'done', 'failed', 'skipped'].includes(status)) {
+                    return { success: false, error: `status 必须是 running|done|failed|skipped` };
+                }
+                try {
+                    const { updateStep } = await import('./task-state.js');
+                    const patch = { status };
+                    if (args.result_summary)
+                        patch.resultSummary = String(args.result_summary);
+                    if (args.error)
+                        patch.error = String(args.error);
+                    const updated = await updateStep(taskId, stepId, patch);
+                    if (!updated)
+                        return { success: false, error: `任务 ${taskId} 未找到` };
+                    const nextRunning = updated.steps.find((s) => s.status === 'running');
+                    return {
+                        success: true,
+                        output: `✅ step ${stepId} → ${status}\ntask 状态: ${updated.status}${nextRunning ? `\n下一步: ${nextRunning.id} — ${nextRunning.description}` : ''}`,
+                    };
+                }
+                catch (e) {
+                    return { success: false, error: `update_task 失败: ${String(e)}` };
+                }
+            }
+        });
+        this.tools.set('get_task', {
+            name: 'get_task',
+            description: '查任务的当前状态和步骤进度. 用于跨 loop / 跨 session 恢复.',
+            parameters: { task_id: '任务 id (必填)' },
+            execute: async (args) => {
+                const taskId = String(args.task_id || '').trim();
+                if (!taskId)
+                    return { success: false, error: 'task_id 必填' };
+                try {
+                    const { getTask } = await import('./task-state.js');
+                    const t = await getTask(taskId);
+                    if (!t)
+                        return { success: false, error: `任务 ${taskId} 未找到` };
+                    const lines = [
+                        `任务: ${t.id}`,
+                        `目标: ${t.goal}`,
+                        `状态: ${t.status}`,
+                        `branch: ${t.branch || '(未指定)'}`,
+                        `sessionKey: ${t.sessionKey || '(未指定)'}`,
+                        `创建: ${t.createdAt}`,
+                        `更新: ${t.updatedAt}`,
+                        ``,
+                        `步骤:`,
+                        ...t.steps.map((s) => `  ${s.status === 'done' ? '✅' : s.status === 'running' ? '🔄' : s.status === 'failed' ? '❌' : s.status === 'skipped' ? '⏭️' : '⏳'} ${s.id} — ${s.description}${s.resultSummary ? `\n     结果: ${s.resultSummary}` : ''}${s.error ? `\n     错误: ${s.error}` : ''}`),
+                    ];
+                    return { success: true, output: lines.join('\n') };
+                }
+                catch (e) {
+                    return { success: false, error: `get_task 失败: ${String(e)}` };
+                }
+            }
+        });
+        this.tools.set('list_tasks', {
+            name: 'list_tasks',
+            description: '列出最近 N 个任务 (默认 10). 用于多任务并行管理.',
+            parameters: { limit: '可选, 默认 10' },
+            execute: async (args) => {
+                const limit = Number(args.limit) || 10;
+                try {
+                    const { listTasks } = await import('./task-state.js');
+                    const tasks = await listTasks(limit);
+                    if (tasks.length === 0) {
+                        return { success: true, output: '当前没有任务. 用 create_task 创建一个.' };
+                    }
+                    const lines = tasks.map((t) => {
+                        const done = t.steps.filter((s) => s.status === 'done').length;
+                        const total = t.steps.length;
+                        return `${t.status === 'completed' ? '✅' : t.status === 'failed' ? '❌' : '🔄'} ${t.id} — ${t.goal} (${done}/${total} steps, branch: ${t.branch || '-'})`;
+                    });
+                    return { success: true, output: `最近 ${tasks.length} 个任务:\n${lines.join('\n')}` };
+                }
+                catch (e) {
+                    return { success: false, error: `list_tasks 失败: ${String(e)}` };
+                }
+            }
+        });
+        // M3.3 (2026-06-17): 工具幂等性 — 显式 cache 防止重试时副作用执行两次
+        // 设计: 在 registerTools 末尾 wrap 所有 this.tools, 每个调用走 cache:
+        //   - 算 (toolName + JSON.stringify(args)) 的 hash
+        //   - 命中 cache → 返缓存结果 (不重跑副作用, 关键对 write_file / edit_file / shell_exec)
+        //   - 失败结果不缓存 (避免缓存 transient 错误)
+        //   - 缓存容量 200 条, 超过就清空
+        this.wrapToolsWithIdempotency();
+    }
+    /** M3.3: 工具结果缓存 — 防止 loop 重试时副作用 (写文件 / 改代码) 执行多次 */
+    idempotencyCache = new Map();
+    IDEMPOTENCY_TTL_MS = 5 * 60 * 1000; // 5 分钟内同 (tool, args) 走 cache
+    IDEMPOTENCY_MAX = 200;
+    wrapToolsWithIdempotency() {
+        // 只 wrap 会产生副作用的工具 — 读类工具 (list_files, read_document, get_task) 不 wrap
+        //   (让 LLM 拿到最新数据, 不会因为缓存读到旧 task 状态)
+        const SIDE_EFFECT_TOOLS = new Set([
+            'write_file', 'edit_file', 'shell_exec', 'git_commit', 'git_push', 'git_branch',
+            'create_task', 'update_task',
+        ]);
+        for (const [name, tool] of this.tools.entries()) {
+            if (!SIDE_EFFECT_TOOLS.has(name))
+                continue;
+            const original = tool.execute;
+            tool.execute = async (args) => {
+                const key = `${name}|${JSON.stringify(args)}`;
+                const cached = this.idempotencyCache.get(key);
+                if (cached && Date.now() - cached.ts < this.IDEMPOTENCY_TTL_MS) {
+                    // 命中 — 加标记让 LLM 知道这是 cache (不会真执行副作用)
+                    return { ...cached.result, output: (cached.result.output || '') + '\n[↻ idempotency cache hit]' };
+                }
+                const result = await original(args);
+                // 只缓存成功结果, 避免缓存 transient 错误
+                if (result && result.success) {
+                    if (this.idempotencyCache.size >= this.IDEMPOTENCY_MAX) {
+                        this.idempotencyCache.clear();
+                    }
+                    this.idempotencyCache.set(key, { result, ts: Date.now() });
+                }
+                return result;
+            };
+        }
+    }
+    /** 清幂等性缓存 — 强制下次调用真正执行 (用于 agent 显式需要重新跑的场景) */
+    clearIdempotencyCache() {
+        this.idempotencyCache.clear();
     }
     async registerP2PDocumentReceiver() {
         await initDocumentReceiver();
     }
     getToolDefinitions() {
-        const defs = ['可用工具:'];
+        // M2.4 (2026-06-17): 缓存 tool 定义 — registerTools() 在构造时调一次, 此后不变
+        if (this.cachedToolDefinitions)
+            return this.cachedToolDefinitions;
+        const defs = ['可用工具 (name(params) - 简介):'];
         for (const tool of this.tools.values()) {
-            const params = Object.entries(tool.parameters).map(([k, v]) => `${k}: ${v}`).join(', ');
-            defs.push(`- ${tool.name}(${params}) - ${tool.description}`);
+            // 2026-06-19: 压缩 tool 定义 — 只显示参数名 (不显示描述, 减少 60% 长度)
+            //   完整 description 在 history 第一轮注入 (getToolDefinitionsFull 调用), 后续轮只看简短
+            //   避免 system prompt 太大导致 minimax 撞 max_tokens 输出空
+            const paramNames = Object.keys(tool.parameters).join(',');
+            defs.push(`- ${tool.name}(${paramNames})`);
         }
-        return defs.join('\n');
+        this.cachedToolDefinitions = defs.join('\n');
+        return this.cachedToolDefinitions;
     }
     async initSession() {
         await this.sessionManager.initialize();
@@ -869,6 +1711,17 @@ class PiAgentSession {
         this.currentSignal = options?.signal ?? null;
         this.currentOnStream = options?.onStream ?? null;
         await this.computeJudgmentGate(input);
+        // M2.2 (2026-06-17): intent 分类 — prompt() 路径也跑 (跟 promptStream 对齐)
+        try {
+            const { classifyIntent, intentHint } = await import('./intent-classifier.js');
+            this.currentIntent = classifyIntent(input);
+            this.currentIntentHint = intentHint(this.currentIntent);
+        }
+        catch (err) {
+            console.warn('[PiAgent] classifyIntent in prompt() failed:', err);
+            this.currentIntent = 'chitchat';
+            this.currentIntentHint = '';
+        }
         // P2: 解析当前 permission mode
         try {
             const { resolvePermissionMode } = await import('./permission-mode.js');
@@ -878,6 +1731,22 @@ class PiAgentSession {
             console.warn('[PiAgent] resolvePermissionMode failed (non-fatal):', err);
             this.currentPermissionMode = 'default';
         }
+        // M3.1 (2026-06-17): 跟 promptStream 一样, usePivotLoop 时走 pivotLoop 路径
+        //   之前 prompt() 永远跑老 runReActLoop, CLI/web 行为不一致
+        if (this.usePivotLoop) {
+            try {
+                const lr = await this.promptWithPivotLoop(input, undefined, options?.channelId);
+                return lr.response || '';
+            }
+            finally {
+                if (this.judgmentGateUsedIds.length > 0) {
+                    recordJudgmentUsage(this.judgmentGateUsedIds, { userInput: input }).catch((err) => console.warn('[PiAgent] recordJudgmentUsage failed:', err));
+                }
+                this.clearJudgmentGate();
+                this.currentSignal = null;
+                this.currentOnStream = null;
+            }
+        }
         try {
             // 2026-06-16: runReActLoop 现在返回 { reply, aiFailed, aiFailureReason } — 这里只需 reply 字符串
             const loopResult = await this.runReActLoop(undefined, options?.signal);
@@ -893,15 +1762,27 @@ class PiAgentSession {
         }
     }
     async promptStream(input, onStream, signal, channelId) {
+        console.log(`[PiAgent.promptStream] ENTRY, channelId=${channelId}, input chars=${input.length}`);
         this.minimaxAvailable = this.checkMinimax();
+        console.log(`[PiAgent.promptStream] minimaxAvailable=${this.minimaxAvailable}`);
         this.currentChannelId = channelId ?? this.currentChannelId;
+        // 2026-06-18 (supervisor): web server 把 46K markedPrompt 喂过来
+        //   (【本轮用户请求】\n<text>\n【请求结束】\n\n<contextHint>).
+        //   整个 input 走下游, pivot loop 之前拿 47K buildContext 当 user message 发出去,
+        //   模型撞 context window. 提取 userText 替代 input, contextHint 拼到 systemPrompt 末尾.
+        const markerMatch = input.match(/【本轮用户请求】\s*([\s\S]*?)\s*【请求结束】/);
+        const userText = markerMatch ? markerMatch[1].trim() : input;
+        const contextHint = markerMatch ? input.replace(markerMatch[0], '').trim() : '';
+        console.log(`[PiAgent.promptStream] marker matched=${!!markerMatch}, userText chars=${userText.length}, contextHint chars=${contextHint.length}`);
         this.messageHistory.push({
             role: 'user',
-            content: input
+            content: userText
         });
+        // 2026-06-18: web server 喂的 markedPrompt 外的 contextHint 拼到 system 末尾 (而不是当 user message)
+        this.contextHintAddition = contextHint;
         onStream({ type: 'thinking', content: '🤔 开始思考...' });
         if (!this.minimaxAvailable) {
-            const response = await this.handleFallback(input);
+            const response = await this.handleFallback(userText);
             this.messageHistory.push({ role: 'assistant', content: response });
             onStream({ type: 'done', content: '' });
             return response;
@@ -909,7 +1790,21 @@ class PiAgentSession {
         // P0 注入门: 缓存 onStream + signal, computeJudgmentGate 用 currentOnStream 广播 phase
         this.currentOnStream = onStream;
         this.currentSignal = signal ?? null;
-        await this.computeJudgmentGate(input);
+        await this.computeJudgmentGate(userText);
+        // M2.2 (2026-06-17): intent 分类 — 0 LLM 成本, 5 行 keyword 匹配
+        try {
+            const { classifyIntent, intentHint } = await import('./intent-classifier.js');
+            this.currentIntent = classifyIntent(userText);
+            this.currentIntentHint = intentHint(this.currentIntent);
+            if (this.currentIntent !== 'chitchat') {
+                onStream({ type: 'phase', phase: 'intent_classified', detail: this.currentIntent, content: '' });
+            }
+        }
+        catch (err) {
+            console.warn('[PiAgent] classifyIntent failed (non-fatal):', err);
+            this.currentIntent = 'chitchat';
+            this.currentIntentHint = '';
+        }
         // P1.1: 异步跑 Auto-Compact (LLM 摘要, 仅在 budget 超限时触发, 失败静默)
         // 复用 computeJudgmentGate 的 onStream 广播 phase, 跟 judgment 注入门风格一致
         try {
@@ -939,6 +1834,51 @@ class PiAgentSession {
             this.currentPermissionMode = 'default';
         }
         this.promptStartTime = Date.now();
+        // M3.1 (2026-06-17): 走 WorkflowPivotLoop (usePivotLoop: true)
+        //   pivot loop 自带 quality scoring / 30 iter cap / complexity analysis — 比老 runReActLoop 鲁棒
+        if (this.usePivotLoop) {
+            let pivotResult = '';
+            try {
+                const lr = await this.promptWithPivotLoop(userText, undefined, channelId);
+                pivotResult = lr.response || '';
+                onStream({ type: 'done', content: '' });
+            }
+            catch (err) {
+                if (signal?.aborted || err?.name === 'AbortError') {
+                    console.log(`[chat] pivot aborted channel=${channelId}`);
+                }
+                else {
+                    console.error(`[chat] pivot 失败 channel=${channelId}:`, err);
+                    pivotResult = `[错误: pivot loop 失败] ${String(err?.message || err).slice(0, 300)}`;
+                    try {
+                        onStream({ type: 'error', content: pivotResult, tool: 'system' });
+                    }
+                    catch { }
+                }
+            }
+            finally {
+                if (this.judgmentGateUsedIds.length > 0) {
+                    try {
+                        onStream({ type: 'used_judgments', usedIds: this.judgmentGateUsedIds, content: '' });
+                    }
+                    catch { }
+                }
+                monitorAfterReply(userText, pivotResult);
+                const stopStartTime = this.promptStartTime || Date.now();
+                onStop({
+                    channelId: this.currentChannelId || 'unknown',
+                    durationMs: Date.now() - stopStartTime,
+                    usedJudgmentIds: [...this.judgmentGateUsedIds],
+                }).catch((err) => console.warn('[PiAgent] onStop failed:', err));
+                this.clearJudgmentGate();
+                this.currentOnStream = null;
+                this.currentSignal = null;
+                this.bootstrapAddition = '';
+                this.contextHintAddition = '';
+                this.promptStartTime = 0;
+            }
+            return pivotResult;
+        }
         // 2026-06-16: loop 自动重试 — runReActLoop 内部遇到 [AI 服务调用失败] sentinel 时,
         //   会设 aiFailed=true 并提前 break. 这里在外层重跑整个 loop (不是单次 LLM 调用),
         //   临时网络抖动 / 配额瞬时超限可自愈. 最多 3 次, 指数退避 1s/2s/4s.
@@ -1057,14 +1997,27 @@ class PiAgentSession {
         }
         // P0 注入门: 在构造 systemPrompt 之前算一次, 拼到末尾
         await this.computeJudgmentGate(input);
-        const personaSection = this.persona ? `
+        // M2.2 (2026-06-17): intent 分类 — pivot loop 也要拿到 hint
+        try {
+            const { classifyIntent, intentHint } = await import('./intent-classifier.js');
+            this.currentIntent = classifyIntent(input);
+            this.currentIntentHint = intentHint(this.currentIntent);
+        }
+        catch (err) {
+            console.warn('[PiAgent] classifyIntent in pivot failed:', err);
+        }
+        // M2.4: persona 缓存
+        if (!this.cachedPersonaSection && this.persona) {
+            this.cachedPersonaSection = `
 角色描述: ${this.persona.description || '无'}
 性格特点: ${this.persona.personality || '无'}
 问候语: ${this.persona.greeting || '无'}
-` : '';
-        const systemPrompt = `${this.bootstrapAddition}你是 ${this.identity.name}，基于ReAct (Reasoning + Acting)模式工作。${personaSection}
+`;
+        }
+        const systemPrompt = `${this.bootstrapAddition}你是 ${this.identity.name}，基于ReAct (Reasoning + Acting)模式工作。${this.cachedPersonaSection}
 当前工作目录: ${this.cwd}
 当前身份: ${this.identity.name} (${this.identity.did})
+${this.currentIntentHint}
 
 ${this.getToolDefinitions()}
 
@@ -1075,14 +2028,24 @@ ${this.getToolDefinitions()}
 4. 根据观察结果决定下一步
 5. 最终给出完整回答
 
-重要:
+重要 (一次命中要求):
 - 每次只调用一个工具
 - 仔细分析工具返回结果
 - 当任务完成时，必须在回答末尾添加 <final gen> 标记表示结束
-- 如果需要更多信息，继续调用工具${this.judgmentGateAddition}`;
+- 如果需要更多信息，继续调用工具
+
+【工具调用格式 (严格遵守, 否则系统无法解析)】
+- 你只能输出**一个**工具调用, 不要堆叠多个 invoke
+- 工具调用格式: {"name":"<tool_name>","input":{"arg1":"value1"}}
+- 用 markdown json code block 包裹: \`\`\`json\n{"name":"X","input":{...}}\n\`\`\`
+- 工具调用前可以简短思考 (1-2 句话), 但**不要写长篇 thinking** (会撞 max_tokens)
+- 工具调用后必须等结果, 不要在同一个回复里继续输出
+- <final gen> 只在**真完成所有任务**时输出, 不要在工具调用前/中输出${this.judgmentGateAddition}${this.contextHintAddition}`;
         // 2026-06-15: 把 currentOnStream 传给 loop, 让 step-timeline 在 pivot 循环里也能 emit step_start/done
         //   之前 loop.execute() 不接 streamCallback, 导致 step-timeline 只能看到老 runReActLoop 路径
         //   promptWithPivotLoop 路径 0 step events — UI 显示 timeline 但永远是空
+        // 2026-06-17: 透传 signal 让 abort 工作 — loop.execute() 当前不接 signal 参数,
+        //   所以 abort 行为通过 this.currentSignal 共享给 loop 内部读 (后续 M3.2 接 task plan 时一起加)
         const result = await loop.execute(input, llm, systemPrompt, this.currentOnStream ?? undefined);
         this.messageHistory.push({ role: 'user', content: input });
         if (result.response) {
@@ -1144,7 +2107,15 @@ ${this.getToolDefinitions()}
             if (totalErrors >= this.MAX_TOTAL_ERRORS) {
                 console.warn(`[PiAgent] 累计错误 ${totalErrors} >= ${this.MAX_TOTAL_ERRORS}, 强制终止 (防死循环)`);
                 onStream?.({ type: 'error', content: `⛔ 累计 ${totalErrors} 次错误, 强制终止 (防止 LLM 死循环)`, tool: 'loop' });
-                finalResponse = finalResponse || `(本轮 ReAct 循环累计 ${totalErrors} 次错误, 强制结束。请换个思路或简化任务重试。)`;
+                // 2026-06-19: 即使 LLM 一直失败, 也汇总之前成功执行的 tool result 给用户
+                if (this.successfulToolResults.length > 0) {
+                    finalResponse = `✅ 之前步骤成功执行了 ${this.successfulToolResults.length} 个工具 (但 LLM 后续 ${totalErrors} 次调用失败):\n` +
+                        this.successfulToolResults.map((r, i) => `  ${i + 1}. ${r.tool}: ${r.outputPreview}`).join('\n') +
+                        `\n\n⚠️ (LLM 连续失败, 可能是 minimax 上游限流/网络问题, 工具已成功执行但 LLM 没能继续总结)`;
+                }
+                else {
+                    finalResponse = finalResponse || `(本轮 ReAct 循环累计 ${totalErrors} 次错误, 强制结束。请换个思路或简化任务重试。)`;
+                }
                 break;
             }
             // 2026-06-16 新增: loop 内自动压缩 — token 超 80% 阈值时跑一次
@@ -1177,6 +2148,10 @@ ${this.getToolDefinitions()}
                 onStream({ type: 'status', content: `🔄 循环 ${iteration}/${this.MAX_REACT_ITERATIONS}`, tool: 'loop' });
             }
             const context = this.buildContext();
+            // M3.5 (2026-06-17): 也构造 messages 数组版本, 让 LLM 看到结构化 tool 角色
+            //   buildContext() 把 history 序列化成字符串 — LLM 看不到 tool 调用的真实结果
+            //   新版用 messages 数组直接喂给 LLM, 保留 role 语义 (user/assistant/tool/system)
+            const messages = this.buildMessages();
             const toolDefs = this.getToolDefinitions();
             // 动态构建 refine 上下文
             let refineContext = '';
@@ -1187,15 +2162,20 @@ ${this.getToolDefinitions()}
             if (consecutiveErrors > 0) {
                 refineContext += `\n【错误提示】上轮发生 ${consecutiveErrors} 次错误，请重新分析问题或换一种方式处理。`;
             }
-            const personaSection = this.persona ? `
+            // M2.4: persona section 缓存 — persona 在 loadPersona() 时一次设定, 此后不变
+            if (!this.cachedPersonaSection && this.persona) {
+                this.cachedPersonaSection = `
 角色描述: ${this.persona.description || '无'}
 性格特点: ${this.persona.personality || '无'}
 问候语: ${this.persona.greeting || '无'}
-` : '';
+`;
+            }
+            const personaSection = this.cachedPersonaSection;
             const systemPrompt = `${this.bootstrapAddition}你是 ${this.identity.name}，基于ReAct (Reasoning + Acting)模式工作。${personaSection}
 当前工作目录: ${this.cwd}
 当前身份: ${this.identity.name} (${this.identity.did})
 ${refineContext}
+${this.currentIntentHint}
 
 ${toolDefs}
 
@@ -1210,26 +2190,35 @@ ${toolDefs}
 - 每次只调用一个工具
 - 仔细分析工具返回结果
 - 当任务完成时，必须在回答末尾添加 <final gen> 标记表示结束
-- 如果需要更多信息，继续调用工具${this.judgmentGateAddition}`;
+- 如果需要更多信息，继续调用工具${this.judgmentGateAddition}${this.contextHintAddition}`;
             // 3 个恢复机制 (Claude Code 论文 9-step pipeline 内部):
             //   1. max output token 升级 (最多 3 次, 每次 maxOutputTokens 翻倍)
             //   2. reactive compaction (prompt 估算超阈值, 跑压缩)
             //   3. prompt-too-long (LLM 报错 4xxx token 错误, 跑 reactive compaction 再试 1 次)
             // 失败静默: 全部重试失败 → 空 reply (上层用 no tool_use 终止)
-            const response = await this.callLlmWithRecovery(llm, context, systemPrompt, signal, onStream);
+            const response = await this.callLlmWithRecovery(llm, messages, systemPrompt, signal, onStream);
             const reply = (response.reply || '').trim();
-            // 2026-06-16: 看到 [AI 服务调用失败] sentinel → 不再立即 break,
-            // 而是设 aiFailed=true, 让外层 promptStream 自动重跑整个 loop 最多 N 次
-            // (LLM API 401 / 网络错 / 配额满时, pi-ai 返回这个 prefix;
-            //  自动 retry 兜底: 临时网络抖动可自愈, 真挂 N 次后才报失败)
+            // 2026-06-19 架构 fix: 不再因 [AI 服务调用失败] break
+            //   旧逻辑: sentinel → aiFailed=true → break → 外层 retry 整个 loop (重置 history)
+            //   新逻辑: 把错误当 tool_result push 进 history → 下一轮 LLM 看到错误能反思重试
+            //   这是 dive-into 文档的"fail-open error recovery" — 错误进入 context, 不让 LLM 重复犯同样错
             if (reply.startsWith('[AI 服务调用失败]')) {
-                console.log(`[PiAgent] 收到 AI 错误 sentinel, 标记 aiFailed, 外层会自动重试整个 loop`);
-                aiFailed = true;
+                console.log(`[PiAgent] 收到 AI 错误 sentinel, 推到 history 让 LLM 反思, 继续 loop`);
                 aiFailureReason = reply.length > 200 ? reply.substring(0, 200) : reply;
+                totalErrors++;
+                consecutiveErrors++;
+                // 把错误当成 tool 结果 push 进 history, 这样下一轮 LLM 看到错误能调整
+                this.messageHistory.push({
+                    role: 'system',
+                    content: `[Loop 错误恢复 ${totalErrors}/${this.MAX_TOTAL_ERRORS}] ${aiFailureReason}\n\n请基于上轮工具结果继续完成任务, 不要重复调用同一失败操作. 如果工具已成功执行, 请基于 result.output 给用户总结; 如果工具失败, 请换其他方式或重试.`
+                });
                 if (onStream) {
-                    onStream({ type: 'status', content: `⚠️ AI 调用失败, 将自动重试整个 loop`, tool: 'system' });
+                    onStream({ type: 'status', content: `⚠️ AI 调用失败 ${totalErrors}/${this.MAX_TOTAL_ERRORS}, 已 push 错误到 history 让 LLM 反思`, tool: 'system' });
                 }
-                break;
+                // 退避 2s 后继续 — 临时 minimax 限流避开, 不让 loop 终止
+                await new Promise(resolve => setTimeout(resolve, 2000));
+                // 关键: 不设 aiFailed=true, 让外层不重试整个 loop (重置 history), 继续内层循环
+                continue;
             }
             console.log(`[PiAgent] LLM 回复长度: ${reply.length}, 内容预览: "${reply.substring(0, 80)}..."`);
             console.log(`[PiAgent] LLM 完整回复:\n${reply}`);
@@ -1237,19 +2226,12 @@ ${toolDefs}
             if (onStream) {
                 onStream({ type: 'token', content: reply.substring(0, 100) });
             }
-            if (this.isFinalResponse(reply)) {
-                // 检查质量分数
-                lastQualityScore = this.estimateResponseQuality(reply);
-                // 如果质量太低且还有改进机会，进入改进循环
-                if (lastQualityScore < this.QUALITY_THRESHOLD && refineAttempts < this.MAX_REFINE_ATTEMPTS) {
-                    refineAttempts++;
-                    console.log(`[PiAgent] 质量评分 ${(lastQualityScore * 10).toFixed(1)}/10 < ${(this.QUALITY_THRESHOLD * 10).toFixed(1)}/10，自动改进中 (${refineAttempts}/${this.MAX_REFINE_ATTEMPTS})`);
-                    continue;
-                }
-                finalResponse = this.extractFinalAnswer(reply);
-                break;
-            }
+            // 2026-06-19 架构 fix: parseToolCall 优先于 isFinalResponse
+            //   之前: 思考块里的 "<final gen>" 触发 isFinalResponse 提前 break, 工具从未真正执行
+            //   现在: 先尝试解析 tool_call, 有就执行; 没有才检查是不是真正的 final gen
             const toolCall = this.parseToolCall(reply);
+            // 2026-06-19 修: 即便 reply 含 <final gen>, 只要 parseToolCall 命中, 就执行工具
+            //   (之前 isFinalResponse break 会先于 parseToolCall 触发, 思考块里有 final gen 字符串就误杀)
             if (toolCall) {
                 this.messageHistory.push({
                     role: 'assistant',
@@ -1448,6 +2430,16 @@ ${toolDefs}
                     }
                     if (result.success) {
                         consecutiveErrors = 0; // 重置连续错误计数
+                        // 2026-06-19: 记录成功结果, 用于 LLM 失败退出时汇总给用户
+                        if (result.output) {
+                            this.successfulToolResults.push({
+                                tool: toolCall.name,
+                                outputPreview: result.output.substring(0, 200) + (result.output.length > 200 ? '...' : '')
+                            });
+                        }
+                        else {
+                            this.successfulToolResults.push({ tool: toolCall.name, outputPreview: '(无输出)' });
+                        }
                         // 检查工具执行质量
                         lastQualityScore = this.estimateToolResultQuality(result);
                         if (lastQualityScore < this.QUALITY_THRESHOLD && refineAttempts < this.MAX_REFINE_ATTEMPTS) {
@@ -1519,6 +2511,29 @@ ${toolDefs}
                 if (onStream) {
                     onStream({ type: 'token', content: reply.substring(0, 150) });
                 }
+                // 2026-06-19 架构 fix: 只有 strip <think> 后才检查 isFinalResponse
+                //   (parseToolCall 已先尝试, 既然没解析出 tool_call, 现在检查 final gen 是否真的在最终回答区)
+                if (this.isFinalResponse(reply)) {
+                    // 2026-06-19 dive-into 风格修复: 如果还有 successful tool results 没汇报,
+                    //   LLM 不能提前 final_gen — harness 自动注入"请汇报剩余工具结果" hint 再 continue
+                    //   这是 dive-into 文档"step 9 stop condition check" 的具体化:
+                    //   stop condition = (有工具结果未汇报) ? continue : break
+                    if (this.successfulToolResults.length > 0 && iteration < this.MAX_REACT_ITERATIONS) {
+                        const unreported = this.successfulToolResults.length;
+                        console.log(`[PiAgent] LLM 想 final_gen 但还有 ${unreported} 个工具结果未汇报, push hint 让其继续`);
+                        this.messageHistory.push({
+                            role: 'system',
+                            content: `[dive-into stop condition] 你之前已成功执行了 ${unreported} 个工具, 但当前回复里没把它们的结果告诉用户. 请基于已有的工具结果 (在 history 里) 写一个完整总结回复给用户, 用 <final gen> 结尾. 不要再调工具.`
+                        });
+                        if (onStream) {
+                            onStream({ type: 'status', content: `🔄 还有 ${unreported} 个工具结果未汇报, 让 LLM 继续总结`, tool: 'system' });
+                        }
+                        continue;
+                    }
+                    lastQualityScore = this.estimateResponseQuality(reply);
+                    finalResponse = this.extractFinalAnswer(reply);
+                    break;
+                }
                 // 检查是否需要继续循环处理
                 // 更严格的判断：只有当回复明确表示需要更多信息时才继续
                 const containsToolCallIntent = reply.includes('调用工具') || reply.includes('tool(') ||
@@ -1646,6 +2661,44 @@ Workspace root folder: ${this.cwd}
             return m.content;
         }).join('\n');
     }
+    /**
+     * M3.5 (2026-06-17): 把 history 转成 messages 数组, 给 llm.chat() 用.
+     *   不再用 buildContext() 把所有 role 压成字符串 — LLM 看不到 tool 调用结果.
+     *   messages 数组保留 role 语义, tool role 单独传递, LLM 能看到完整 tool 结果.
+     *
+     * 取最近 N 条, 同步压缩前 3 层 (跟 buildContext 同步).
+     * 跳过 projectedHistory 路径 — messages 数组必须真实, 不能用投影.
+     */
+    buildMessages() {
+        try {
+            const recentMessages = this.compressHistorySync(this.messageHistory).slice(-15);
+            const out = [];
+            for (const m of recentMessages) {
+                const role = m.role;
+                let content = m.content;
+                // tool role: 用 toolResult 序列化 (跟 buildContext 一样)
+                if (role === 'tool') {
+                    const result = m.toolResult ? JSON.stringify(m.toolResult) : content;
+                    content = `[工具结果] ${result}`;
+                }
+                // system role (router hint 等) 直接保留
+                if (role === 'system') {
+                    out.push({ role: 'system', content });
+                    continue;
+                }
+                // assistant / user / tool 直接转
+                if (role === 'user' || role === 'assistant' || role === 'tool') {
+                    out.push({ role, content });
+                }
+            }
+            return out;
+        }
+        catch (err) {
+            console.warn('[PiAgent] buildMessages failed (silent, falling back to text):', err);
+            // 退化: 用 buildContext 字符串包装成单 user message
+            return [{ role: 'user', content: this.buildContext() }];
+        }
+    }
     /**
      * 估算 messageHistory 的 token 数 (4 字符 ≈ 1 token, 与 context-compaction 同步).
      * 失败静默: 任何异常 → 0 (不阻塞)
@@ -1667,7 +2720,7 @@ Workspace root folder: ${this.cwd}
      *
      * 失败静默: 全部失败 → 返回空 reply, 让上层 no-tool_use 终止
      */
-    async callLlmWithRecovery(llm, context, systemPrompt, signal, onStream) {
+    async callLlmWithRecovery(llm, contextOrMessages, systemPrompt, signal, onStream) {
         // Reactive compaction 预检: 估算 token 超 80% 阈值, 跑一次
         const estimated = this.estimateHistoryTokens();
         if (estimated > this.MAX_OUTPUT_TOKEN_ESCALATION_THRESHOLD * 0.8) {
@@ -1684,41 +2737,93 @@ Workspace root folder: ${this.cwd}
                 console.warn('[PiAgent] reactive compaction pre-check failed:', err);
             }
         }
-        // 主调用 + 3 个恢复路径
+        // 错误分级 (M1.3, 2026-06-17):
+        //   - 401/403/400 (认证/请求错误): 不重试, 直接 fail-fast
+        //   - 429 (rate limit): 重试 2 次, 指数退避
+        //   - 5xx (上游错误): 重试 2 次, 指数退避
+        //   - network (ECONNRESET / fetch failed / abort/timeout): 重试 2 次
+        //   - 4xx prompt-too-long: 走 reactive compaction
+        // 这样以前所有错误都触发整个 runReActLoop 重跑(浪费 token),现在 4xx 直接失败
+        //   让上层把失败原因广播给用户,而不是闷在 loop 里 retry 3 次后给空回复
+        const classifyError = (err) => {
+            const msg = String(err?.message || err || '');
+            // 401/403: 认证失败
+            if (/401|unauthor|invalid api key|api_key|forbidden|403/i.test(msg))
+                return 'auth';
+            // 400 prompt-too-long
+            if (/token|too long|exceed|length|context|4000|413/i.test(msg))
+                return 'prompt_too_long';
+            // 429 rate limit
+            if (/429|rate.?limit|too many requests/i.test(msg))
+                return 'rate_limit';
+            // 5xx
+            if (/5\d\d|internal server|bad gateway|service unavailable|gateway timeout|cloudflare|502|503|504/i.test(msg))
+                return 'server';
+            // network
+            if (/econnreset|econnrefused|enotfound|etimedout|fetch failed|network|aborted|timeout/i.test(msg))
+                return 'network';
+            return 'other';
+        };
+        const isRetryable = (cls) => cls === 'rate_limit' || cls === 'server' || cls === 'network' || cls === 'prompt_too_long';
+        const maxAttempts = (cls) => isRetryable(cls) ? 3 : 1;
+        const backoffMs = (attempt) => Math.min(1000 * 2 ** attempt, 8000); // 1s, 2s, 4s, 8s cap
         let lastErr = null;
-        for (let attempt = 0; attempt <= this.MAX_OUTPUT_TOKEN_ESCALATION_RETRIES; attempt++) {
+        let lastClass = 'other';
+        for (let attempt = 0; attempt < 4; attempt++) { // 最多 4 次尝试
             try {
-                const response = await llm.chat(context, systemPrompt, signal);
+                // M3.5 (2026-06-17): 传 messages 数组 (如果 contextOrMessages 是数组) 或字符串
+                //   数组版让 LLM 看到结构化的 user/assistant/tool role, 而不是把 history 拼成单字符串
+                const response = await llm.chat(contextOrMessages, systemPrompt, signal);
                 return { reply: response.reply || '' };
             }
             catch (err) {
+                // 用户主动 abort: 不重试, 立即抛
+                if (signal?.aborted || err?.name === 'AbortError')
+                    throw err;
                 lastErr = err;
-                const errMsg = String(err?.message || err || '');
-                const isPromptTooLong = /token|too long|exceed|length|context|4000|413|429/i.test(errMsg);
-                if (isPromptTooLong) {
-                    console.warn(`[PiAgent] prompt-too-long 触发 (attempt ${attempt + 1}), 跑 reactive compaction`);
-                    onStream?.({ type: 'status', content: `⚠️ prompt-too-long 触发 (attempt ${attempt + 1}/${this.MAX_OUTPUT_TOKEN_ESCALATION_RETRIES + 1})`, tool: 'recovery' });
+                lastClass = classifyError(err);
+                const errMsg = String(err?.message || err || '').slice(0, 200);
+                const attempts = maxAttempts(lastClass);
+                if (attempt + 1 >= attempts) {
+                    console.warn(`[PiAgent] LLM 调用失败, 不再重试 (class=${lastClass}, attempt=${attempt + 1}/${attempts}): ${errMsg}`);
+                    break;
+                }
+                console.warn(`[PiAgent] LLM 调用失败 (class=${lastClass}, attempt=${attempt + 1}/${attempts}), ${backoffMs(attempt)}ms 后重试: ${errMsg}`);
+                onStream?.({ type: 'status', content: `⚠️ LLM 调用失败 (${lastClass}), 重试 ${attempt + 2}/${attempts}...`, tool: 'recovery' });
+                if (lastClass === 'prompt_too_long') {
                     try {
                         await this.maybeAutoCompact(onStream, signal);
                     }
                     catch (compactionErr) {
                         console.warn('[PiAgent] reactive compaction on prompt-too-long failed:', compactionErr);
                     }
-                    // 重新生成 context (compressHistorySync + projected)
-                    context = this.buildContext();
+                    // 重新生成 context (重试 prompt_too_long 时重建 messages — 包含压缩后的 history)
+                    if (Array.isArray(contextOrMessages)) {
+                        contextOrMessages = this.buildMessages();
+                    }
+                    else {
+                        contextOrMessages = this.buildContext();
+                    }
                 }
                 else {
-                    // 非 prompt-too-long 错误, 1 次重试就放弃
-                    if (attempt === 0) {
-                        console.warn(`[PiAgent] LLM 调用失败 (non-prompt-too-long), 1 次重试:`, err);
-                        continue;
-                    }
-                    break;
+                    // 指数退避
+                    await new Promise((r) => setTimeout(r, backoffMs(attempt)));
                 }
             }
         }
-        console.warn('[PiAgent] callLlmWithRecovery 全失败 (silent):', lastErr);
-        return { reply: '' };
+        // 失败: 返回结构化错误 reply (而不是空字符串), 上层可识别 + UI 可显示
+        const errMsg = String(lastErr?.message || lastErr || '').slice(0, 300);
+        const userMsg = lastClass === 'auth'
+            ? `[AI 服务调用失败] 认证错误: ${errMsg}\n请检查 API key 配置 (env: OPENAI_API_KEY / ANTHROPIC_API_KEY 等)`
+            : lastClass === 'rate_limit'
+                ? `[AI 服务调用失败] 上游限流 (429): ${errMsg}\n请稍后重试`
+                : lastClass === 'server'
+                    ? `[AI 服务调用失败] 上游错误: ${errMsg}\n已重试 2 次仍失败, 可稍后重试`
+                    : lastClass === 'network'
+                        ? `[AI 服务调用失败] 网络错误: ${errMsg}\n请检查网络连接`
+                        : `[AI 服务调用失败] ${errMsg}`;
+        console.warn(`[PiAgent] callLlmWithRecovery 全部失败 (class=${lastClass}): ${errMsg}`);
+        return { reply: userMsg };
     }
     /**
      * 同步压缩: 跑前 3 层 (Budget Reduction / Snip / Microcompact).
@@ -1795,8 +2900,11 @@ Workspace root folder: ${this.cwd}
         }
     }
     isFinalResponse(content) {
-        // 只有明确输出 <final gen> 才认为是最终回答
-        return content.includes('<final gen>');
+        // 2026-06-19 修: 先剥离 <think>...</think> 思考块, 再判断 <final gen>.
+        //   之前用 includes('<final gen>') 误杀: LLM 思考块里说"先看看当前状态再 <final gen>"
+        //   也会被识别成终止信号, 工具调用直接跳过了.
+        const stripped = content.replace(/<think>[\s\S]*?<\/think>/g, '');
+        return stripped.includes('<final gen>');
     }
     extractFinalAnswer(content) {
         // 提取 <final gen> 后的内容作为最终回答
@@ -1822,7 +2930,89 @@ Workspace root folder: ${this.cwd}
         return cleaned;
     }
     parseToolCall(content) {
+        // 2026-06-19 修: JSON function-call (OpenAI/Anthropic/Minimax-style) 优先 — match[1] 是 name 字段, match[2] 是 arguments/input 对象
+        //   LLM 实际产出变体:
+        //     {"name": "shell_exec", "arguments": {"command": "git", "args": ["status"]}}  (OpenAI 标准)
+        //     {"name": "shell_exec", "input": {"command": "git", "args": ["status"]}}      (Anthropic/Minimax 风格)
+        //   常见包裹: ```json\n{...}\n``` (markdown code block), <tool_call>{...}</tool_call> (OpenAI Hermes)
+        const jsonPatterns = [
+            // markdown json code block + OpenAI <tool_call> 块, 同时匹配 arguments/input 字段
+            /(?:```(?:json|json5)?\s*\n?)?\{[\s\S]*?"name"\s*:\s*["'](\w+)["']\s*,\s*["']?(?:arguments|input)["']?\s*:\s*(\{[\s\S]*?\})\s*\}/,
+        ];
+        for (const p of jsonPatterns) {
+            const m = content.match(p);
+            if (m) {
+                const name = m[1];
+                let args = {};
+                try {
+                    const parsed = JSON.parse(m[2]);
+                    if (parsed && typeof parsed === 'object') {
+                        args = Object.fromEntries(Object.entries(parsed).map(([k, v]) => [k, String(v)]));
+                    }
+                }
+                catch { /* 解析失败保持 args={} */ }
+                const resolved = this.resolveToolName(name);
+                if (resolved) {
+                    return { name: resolved, args };
+                }
+            }
+        }
+        // 2026-06-19 修: fallback — LLM 有时输出 <tool_name>shell_exec</tool_name> 这种伪 XML 标签
+        //   旧正则 /<(\w+)>([\s\S]*?)<\/\1>/ 会匹配, 但 name="tool_name" 不在 tools 里
+        //   这里 detect 内容是否像 tool_call (有 <command>/<args>/<path> 子标签) 然后按 <command> 第一词推断工具
+        const xmlTagMatch = content.match(/<(\w+)>([\s\S]*?)<\/\1>/);
+        if (xmlTagMatch) {
+            const outerTag = xmlTagMatch[1];
+            const inner = xmlTagMatch[2];
+            // 如果外层标签不在 tools 里但有 <command>/<args> 子标签, 尝试按内容推断
+            if (!this.resolveToolName(outerTag)) {
+                const cmdMatch = inner.match(/<command>(\w+)<\/command>/);
+                if (cmdMatch) {
+                    const cmd = cmdMatch[1];
+                    // 推测工具: git/npx/npm/tsx → shell_exec; cat/head/tail → read_document
+                    if (['git', 'npx', 'npm', 'tsx', 'tsc', 'vitest', 'node', 'mkdir', 'touch', 'ls', 'echo', 'cat', 'head', 'tail', 'wc', 'pwd', 'date'].includes(cmd)) {
+                        const args = {};
+                        const argsMatch = inner.match(/<args>([\s\S]*?)<\/args>/);
+                        if (argsMatch)
+                            args.args = argsMatch[1].trim();
+                        const cmdsMatch = inner.match(/<command>([\s\S]*?)<\/command>/);
+                        if (cmdsMatch)
+                            args.command = cmdsMatch[1].trim();
+                        return { name: 'shell_exec', args };
+                    }
+                }
+            }
+        }
+        // 2026-06-19 修: <tools:call name="X">...</tools:call> 嵌套格式
+        //   LLM 实际产出变体: <tools:call name="shell_exec"><tools:call name="command">git</tools:call>...</tools:call>
+        const toolsCallMatch = content.match(/<tools:call\s+name=["'](\w+)["']>([\s\S]*?)<\/tools:call>/);
+        if (toolsCallMatch) {
+            const name = toolsCallMatch[1];
+            const inner = toolsCallMatch[2];
+            const args = {};
+            const argTags = inner.matchAll(/<tools:call\s+name=["'](\w+)["']>([\s\S]*?)<\/tools:call>/g);
+            for (const m of argTags) {
+                args[m[1]] = m[2].trim();
+            }
+            const resolved = this.resolveToolName(name);
+            if (resolved) {
+                return { name: resolved, args };
+            }
+            // 兜底: 如果外层 tool name 不在 tools, 但内层有 command, 推断 shell_exec
+            if (args.command) {
+                const cmdFirst = args.command.split(/\s+/)[0];
+                if (['git', 'npx', 'npm', 'tsx', 'tsc', 'vitest', 'node', 'mkdir', 'touch', 'ls', 'echo', 'cat', 'head', 'tail', 'wc', 'pwd', 'date'].includes(cmdFirst)) {
+                    return { name: 'shell_exec', args };
+                }
+            }
+        }
         const patterns = [
+            // 2026-06-19 修: minimax/Hermes 自闭合 XML 格式 <invoke name="X">...</invoke>
+            //   实际 LLM 习惯: <invoke name="shell_exec"><command>sed</command><args>["-n","1060,1095p"]</args></invoke>
+            //   必须放在最前 — 旧正则 /<(\w+)>([\s\S]*?)<\/\1>/ 会匹配到外层 <invoke> 但 name 是 "invoke" 而不是 "shell_exec"
+            new RegExp('<invoke\\s+name=["\']([\\w]+)["\']>([\\s\\S]*?)</invoke>'),
+            // 2026-06-19 修: <function_calls> 包裹
+            new RegExp('<function_calls>[\\s\\S]*?<invoke\\s+name=["\']([\\w]+)["\']>([\\s\\S]*?)</invoke>[\\s\\S]*?</function_calls>'),
             /调用工具[：:]\s*(\w+)\s*\(([^)]*)\)/,
             /使用工具[：:]\s*(\w+)\s*\(([^)]*)\)/,
             /tool[_\w]*[：:]\s*(\w+)\s*\(([^)]*)\)/i,
@@ -1833,6 +3023,10 @@ Workspace root folder: ${this.cwd}
             /\btool\s*=>\s*["'](\w+)["']/,
             // 兼容: [TOOL_CALL] 块内 JSON 形式 {"name": "x", "args": {...}}
             /\[TOOL_CALL\][\s\S]*?\{\s*"name"\s*:\s*"(\w+)"\s*,\s*"args"\s*:\s*(\{[\s\S]*?\})/i,
+            // 2026-06-19: 兼容 LLM 输出 "tool_name {json_args}" 形式 (单行, 无 name 字段)
+            //   实际输出: write_file {"path":"docs/test.md","content":"..."}
+            //   只在行首/新行匹配, 避免误匹配普通文本里的 "foo {...}"
+            /(?:^|\n)(\w+)\s+(\{[\s\S]*?\})(?=\n|$)/,
             // 2026-06-15 修: 兼容 LLM 输出的 XML 格式 <tool_name>...<arg>value</arg>...</tool_name>
             //   实际 LLM 习惯: <shell_exec>\n<command>ls</command>\n<args>["-la", "..."]</args>\n</shell_exec>
             /<(\w+)>([\s\S]*?)<\/\1>/,
@@ -1864,15 +3058,28 @@ Workspace root folder: ${this.cwd}
                 else if (rawArgs && /<\w+>[\s\S]*<\/\w+>/.test(rawArgs)) {
                     // 2026-06-15 修: XML 格式, 解析内嵌子标签 <argname>value</argname>
                     //   例: <command>ls</command>\n<args>["-la","~/.bolloon/skills"]</args>
-                    const xmlArgPattern = /<(\w+)>([\s\S]*?)<\/\1>/g;
-                    let xmlMatch;
-                    while ((xmlMatch = xmlArgPattern.exec(rawArgs)) !== null) {
-                        const argName = xmlMatch[1];
-                        const argValue = xmlMatch[2].trim();
+                    // 2026-06-19 修: 也支持 <parameter name="X">value</parameter> 形式 (OpenAI Hermes function_call)
+                    const paramRe = /<parameter\s+name=["'](\w+)["']>([\s\S]*?)<\/parameter>/g;
+                    let pMatch;
+                    while ((pMatch = paramRe.exec(rawArgs)) !== null) {
+                        const argName = pMatch[1];
+                        const argValue = pMatch[2].trim();
                         if (argName && argValue) {
                             args[argName] = argValue;
                         }
                     }
+                    // 如果没匹配到 <parameter>, 用普通 XML 子标签
+                    if (Object.keys(args).length === 0) {
+                        const xmlArgPattern = /<(\w+)>([\s\S]*?)<\/\1>/g;
+                        let xmlMatch;
+                        while ((xmlMatch = xmlArgPattern.exec(rawArgs)) !== null) {
+                            const argName = xmlMatch[1];
+                            const argValue = xmlMatch[2].trim();
+                            if (argName && argValue) {
+                                args[argName] = argValue;
+                            }
+                        }
+                    }
                 }
                 else if (rawArgs) {
                     // 形参串, 形如 key: value, key2: value2
@@ -1883,13 +3090,157 @@ Workspace root folder: ${this.cwd}
                             args[key] = valueParts.join(':') || '';
                     }
                 }
-                if (this.tools.has(name) || this.tools.has(name.replace(/_/g, '_'))) {
+                if (this.tools.has(name)) {
                     return { name, args };
                 }
+                const resolved = this.resolveToolName(name);
+                if (resolved) {
+                    return { name: resolved, args };
+                }
             }
         }
         return null;
     }
+    // [debug-2026-06-19] 临时: 打印 parseToolCall 输入和返回
+    _dbgParseToolCall(content) {
+        const r = this.parseToolCall(content);
+        console.log('[DBG parseToolCall] result:', JSON.stringify(r), 'content head:', JSON.stringify(content.substring(0, 200)));
+        return r;
+    }
+    /**
+     * 2026-06-19: 工具名大小写不敏感 + Claude Code 风格别名映射
+  
+    /**
+     * 2026-06-19: 工具名大小写不敏感 + Claude Code 风格别名映射
+     *   LLM 实际产出 Read/Edit/Write/Bash/Grep/Glob 等大写名 (Claude Code 工具命名)
+     *   bolloon 注册的是 read_document / edit_file / write_file / shell_exec / list_files
+     *   返回 this.tools 里的标准名, 或 null 表示未识别
+     */
+    resolveToolName(name) {
+        if (this.tools.has(name))
+            return name;
+        const lower = name.toLowerCase();
+        const aliasMap = {
+            // Claude Code 风格 → bolloon 工具
+            read: 'read_file',
+            edit: 'edit_file',
+            write: 'write_file',
+            rm: 'delete_file',
+            mv: 'move_file',
+            bash: 'shell_exec',
+            shell: 'shell_exec',
+            sh: 'shell_exec',
+            // grep / glob 现在是独立工具
+            cat: 'read_file',
+            // 测试/编译 → 独立工具
+            test: 'vitest_run',
+            vitest: 'vitest_run',
+            typecheck: 'tsc_check',
+            tsc: 'tsc_check',
+            // git 操作
+            log: 'git_log',
+            show: 'git_show',
+            diff: 'git_diff',
+            commit: 'git_commit',
+            push: 'git_push',
+            branch: 'git_branch',
+            checkout: 'git_branch',
+            stash: 'git_stash',
+            // 任务管理 (todo)
+            todo_write: 'create_task',
+            todowrite: 'create_task',
+            task: 'create_task',
+        };
+        const aliased = aliasMap[lower];
+        if (aliased && this.tools.has(aliased))
+            return aliased;
+        if (this.tools.has(lower))
+            return lower;
+        return null;
+    }
+    /**
+     * 2026-06-19: 注册 P2P 消息 listener, 把收到的消息存到 _inboxMessages 供 check_inbox 读.
+     *   监听 type='message' (send_to_peer) 和 type='agent-message' (P2P 远端 agent).
+     *   失败静默, 不阻塞 PiAgentSession 构造.
+     */
+    _setupInboxListener() {
+        if (!p2pNetwork || typeof p2pNetwork.onMessage !== 'function')
+            return;
+        try {
+            // 监听所有 type 的消息, 存储到 inbox
+            p2pNetwork.onMessage('*', (msg, from, did) => {
+                try {
+                    const text = new TextDecoder().decode(msg);
+                    // 解析 DID:|type:payload 格式
+                    let type = 'message';
+                    let payload = text;
+                    if (text.startsWith('DID:')) {
+                        const pipeIdx = text.indexOf('|');
+                        if (pipeIdx > 0) {
+                            const rest = text.substring(pipeIdx + 1);
+                            const colonIdx = rest.indexOf(':');
+                            if (colonIdx > 0) {
+                                type = rest.substring(0, colonIdx);
+                                payload = rest.substring(colonIdx + 1);
+                            }
+                            else {
+                                type = rest;
+                                payload = '';
+                            }
+                        }
+                    }
+                    else {
+                        const colonIdx = text.indexOf(':');
+                        if (colonIdx > 0) {
+                            type = text.substring(0, colonIdx);
+                            payload = text.substring(colonIdx + 1);
+                        }
+                    }
+                    this._inboxMessages.push({
+                        id: `p2p-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+                        from: from.substring(0, 32),
+                        fromDid: did,
+                        type,
+                        payload,
+                        timestamp: Date.now(),
+                        source: 'p2p',
+                    });
+                    // 限制 inbox 大小, 防止内存泄漏
+                    if (this._inboxMessages.length > 1000) {
+                        this._inboxMessages = this._inboxMessages.slice(-1000);
+                    }
+                }
+                catch (err) {
+                    console.warn('[PiAgent] inbox listener decode error:', err);
+                }
+            });
+        }
+        catch (err) {
+            console.warn('[PiAgent] _setupInboxListener failed (non-fatal):', err);
+        }
+        // 监听本地 inbox bus 投递 (send_to_local_agent)
+        try {
+            const { LocalInboxBus } = require('../network/local-inbox-bus.js');
+            const myRole = process.env.BOLLOON_ROLE || 'default';
+            LocalInboxBus.getInstance().subscribe(myRole, (msg) => {
+                this._inboxMessages.push({
+                    id: `local-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+                    from: msg.from || 'unknown',
+                    fromDid: msg.fromDid,
+                    type: msg.type || 'agent-local-message',
+                    payload: msg.payload || '',
+                    timestamp: msg.timestamp || Date.now(),
+                    source: 'local',
+                });
+                if (this._inboxMessages.length > 1000) {
+                    this._inboxMessages = this._inboxMessages.slice(-1000);
+                }
+            });
+        }
+        catch (err) {
+            // LocalInboxBus 可能还没创建, 不阻塞
+        }
+    }
     estimateResponseQuality(response) {
         let score = 0.5;
         if (response.length > 50)