@bolloon/bolloon-agent 0.2.2 → 0.2.4

package/dist/agents/pi-sdk.js

@@ -31,6 +31,10 @@ import { onPostToolUse } from '../bootstrap/lifecycle-hooks.js';
 import { budgetReduce, snip, microcompact } from '../context-compaction/index.js';
 // React Harness: 8-gate + 4-guard (防越权 / 防 prompt 注入)
 import { ReactHarness } from '../security/react-harness.js';
+import { parseToolCall as parseToolCallImpl, isFinalResponse as isFinalResponseImpl, extractFinalAnswer as extractFinalAnswerImpl } from './parse-tool-call.js';
+import { sessionStore as defaultSessionStore } from './session-store.js';
+import { ToolRegistry } from './tool-registry.js';
+import { decideMaxIterations, decideContextOverflow, shouldCompactBeforeIteration } from './react-loop.js';
 const SHARED_SESSION_PATH = path.join(process.env.HOME || '/tmp', '.bolloon', 'sessions');
 const PERSONA_PATH = path.join(process.env.HOME || '/tmp', '.bolloon', 'persona.json');
 export class PiSessionManager {
@@ -344,11 +348,17 @@ class PiAgentSession {
     socialHeartbeat = null;
     messageHistory = [];
     tools = new Map();
+    /** 2026-06-30: tool registry 模块 — 独立 alias resolve, 测试可消融. */
+    _toolRegistry = new ToolRegistry();
     skillRegistry = new SkillRegistry();
     /** M2.4: 缓存 tool 列表, registerTools() 之后不变, runReActLoop 多次循环复用 */
     cachedToolDefinitions = '';
     /** M2.4: 缓存 persona section */
     cachedPersonaSection = '';
+    /** 2026-06-30: 持久化层 — 默认走 ~/.bolloon/sessions/cache/, 测试可注入临时目录. */
+    _sessionStore;
+    /** 构造期间 fire-and-forget 任务的 promise — whenReady() 等它 */
+    _readyPromise = null;
     // 2026-06-16 修: 父要求把 ReAct loop 上限放大到 "几乎无限", 靠自动压缩上下文 + fail-safe 兜底
     // 默认 10000 — 正常任务永远跑不到, 但作为防 LLM 死循环 / 防 OOM 的最后一道闸
     // 旧默认 100 写死导致中等复杂度任务 (10-50 个 tool call + 多步反思) 会被误杀
@@ -444,6 +454,8 @@ class PiAgentSession {
         this.peerId = config.peerId || 'local';
         this.identity = config.identityDoc || this.createDefaultIdentity();
         this.minimaxAvailable = this.checkMinimax();
+        // 2026-06-30: 持久化层可注入 — 测试传 tmpDir, 业务用默认 ~/.bolloon/sessions/cache/
+        this._sessionStore = config.sessionStore ?? defaultSessionStore;
         this.constraintLayer = new ConstraintLayer();
         this.workflowEngine = new WorkflowEngine(this.constraintLayer);
         this.sessionManager = new PiSessionManager(this.identity.did, this.cwd);
@@ -459,38 +471,37 @@ class PiAgentSession {
         //   之前 messageHistory 是空的, 服务重启后 LLM 看到的是新对话
         //   现在 loadSessionKey 形如 "channel-xxx:default" 走 ~/.bolloon/sessions/cache/<key>.json
         if (config.loadSessionKey) {
-            this.hydrateMessageHistory(config.loadSessionKey, config.loadSessionMaxMessages ?? 30);
+            this._readyPromise = this.hydrateMessageHistory(config.loadSessionKey, config.loadSessionMaxMessages ?? 30).catch((err) => {
+                // 失败静默, 但不让 whenReady 永久 hang
+                console.warn(`[PiAgent] hydrateMessageHistory failed: ${err.message?.slice(0, 100)}`);
+            });
         }
     }
     /**
-     * M2.3: 从 session JSON 加载历史, 转成 messageHistory 格式
+     * 2026-06-30: 让外部 await 构造期间的 hydrate 完成.
+     * 解决 fire-and-forget 让 messageHistory 不可预测的问题.
+     * 不传 loadSessionKey 时立即返回.
+     */
+    whenReady() {
+        return this._readyPromise ?? Promise.resolve();
+    }
+    /**
+     * M2.3 (2026-06-30 重构): 从 SessionStore 加载历史, 转成 messageHistory 格式
      * - 失败静默 (历史加载失败不应该阻塞 agent 启动)
      * - 限制 max 条数, 防止 context 爆
-     * - user 消息 role=user, ai 消息 role=assistant
-     * - 跳过 metadata 中含 error 的 (错误消息会污染 LLM)
+     * - 跳过错误消息 ([AI 服务调用失败] / [错误:...]) 不污染 LLM
+     * - 委托 SessionStore 完成 IO, 保证 save/load 路径对称
+     *
+     * 历史格式兼容旧 schema ({type, content}) 和新 schema (PersistedMessage[])
      */
     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) });
+            const loaded = await this._sessionStore.loadMessages(sessionKey);
+            if (!loaded) {
+                console.log(`[PiAgent] hydrate: 没有 ${sessionKey} 的历史`);
+                return;
             }
+            const hydrated = this._filterToMessage(loaded).slice(-maxMessages);
             if (hydrated.length > 0) {
                 this.messageHistory = hydrated;
                 console.log(`[PiAgent] 从 ${sessionKey} 回灌 ${hydrated.length} 条历史`);
@@ -500,6 +511,84 @@ class PiAgentSession {
             console.warn(`[PiAgent] hydrateMessageHistory 失败 (non-fatal): ${err.message?.slice(0, 100)}`);
         }
     }
+    /**
+     * 2026-06-30: 把当前 messageHistory 持久化到 SessionStore.
+     * 公开方法 — claude code / 外部 harness 在每次 prompt 完成后调一下,
+     *   即可获得"重启 / 跨进程接续"的语义.
+     */
+    async saveCurrentSession(key) {
+        const persisted = this.messageHistory.map((m) => ({
+            role: m.role,
+            content: m.content,
+            toolCall: m.toolCall,
+            toolResult: m.toolResult,
+            toolCallId: m.toolCallId,
+            timestamp: Date.now(),
+            source: 'pi-session',
+        }));
+        await this._sessionStore.saveMessages(key, persisted);
+    }
+    /**
+     * 2026-06-30: 从 disk 拉历史覆盖当前 messageHistory.
+     * 返回加载条数 — 失败或空则返回 0.
+     * 与 loadSessionKey (构造时读) 不同: 这个是 session 已建好后再读.
+     */
+    async resumeSession(key, maxMessages = 30) {
+        const before = this.messageHistory.length;
+        await this.hydrateMessageHistory(key, maxMessages);
+        return this.messageHistory.length - before;
+    }
+    /**
+     * 2026-06-30: 读历史不修改 messageHistory.
+     * 给 claude code / 测试做"先看一下历史"用 — 不破坏当前会话.
+     * 返回 Message[] 数组 (空数组表示无历史).
+     */
+    async peekSessionHistory(key, maxMessages = 30) {
+        try {
+            const loaded = await this._sessionStore.loadMessages(key);
+            if (!loaded)
+                return [];
+            return this._filterToMessage(loaded).slice(-maxMessages);
+        }
+        catch {
+            return [];
+        }
+    }
+    /** hydrateMessageHistory 用的过滤逻辑 — 提到外面复用 */
+    _filterToMessage(loaded) {
+        const hydrated = [];
+        const VALID_ROLES = new Set(['user', 'assistant', 'tool', 'system']);
+        for (const m of loaded) {
+            // role 必须合法 (拒绝旧 schema {type:'user'} 没 role 字段的)
+            if (!VALID_ROLES.has(m.role))
+                continue;
+            // 跳过污染消息
+            if (typeof m.content === 'string' && m.content.startsWith('[AI 服务调用失败]'))
+                continue;
+            if (typeof m.content === 'string' && m.content.startsWith('[错误:'))
+                continue;
+            // 注意: '!m.content' 会跳过 content='' 的 tool call 消息 (assistant role + toolCall 字段),
+            //   这种是合法的 (LLM 输出只有 tool call, 没有正文) — 必须保留.
+            //   这里只跳过"无内容 + 也没 tool call/tool result"的废消息.
+            if (!m.content && !m.toolCall && !m.toolResult)
+                continue;
+            // 跳过空 tool role (tool result 占位但没有任何内容)
+            if (m.role === 'tool' && !m.toolResult)
+                continue;
+            hydrated.push({
+                role: m.role,
+                content: m.content ?? '',
+                toolCall: m.toolCall,
+                toolResult: m.toolResult,
+                toolCallId: m.toolCallId,
+            });
+        }
+        return hydrated;
+    }
+    /** 暴露 store 给测试 / 高级集成用. */
+    get sessionStoreInstance() {
+        return this._sessionStore;
+    }
     /**
      * 从 SKILL.md 目录加载 skills 进 skillRegistry.
      *
@@ -1617,6 +1706,11 @@ class PiAgentSession {
         //   - 失败结果不缓存 (避免缓存 transient 错误)
         //   - 缓存容量 200 条, 超过就清空
         this.wrapToolsWithIdempotency();
+        // 2026-06-30: 镜像到 ToolRegistry — resolveToolName 走 registry 的 alias 表.
+        //   被 wrap 的 tool (idempotency cache) 也直接拿来用, registry 不重复 wrap.
+        for (const [name, tool] of this.tools.entries()) {
+            this._toolRegistry.register(tool);
+        }
     }
     /** M3.3: 工具结果缓存 — 防止 loop 重试时副作用 (写文件 / 改代码) 执行多次 */
     idempotencyCache = new Map();
@@ -2094,10 +2188,12 @@ ${this.getToolDefinitions()}
         while (iteration < this.MAX_REACT_ITERATIONS) {
             iteration++;
             // 停止条件 1: max turns (fail-safe 10000, 正常任务永远跑不到)
-            if (iteration >= this.MAX_REACT_ITERATIONS) {
+            //   2026-07-01 (v0.2.4 子任务 1): 委托给 react-loop.decideMaxIterations 纯函数
+            const maxIterDecision = decideMaxIterations(iteration, this.MAX_REACT_ITERATIONS);
+            if (maxIterDecision.shouldExit) {
                 console.warn(`[PiAgent] 达到最大循环数 ${this.MAX_REACT_ITERATIONS}, 强制终止 (fail-safe)`);
                 onStream?.({ type: 'error', content: `⏹️ 达到最大循环数 (${this.MAX_REACT_ITERATIONS}, fail-safe)`, tool: 'loop' });
-                finalResponse = finalResponse || '(本轮 ReAct 循环达到最大步数, 强制结束)';
+                finalResponse = finalResponse || maxIterDecision.finalAnswer;
                 break;
             }
             // 停止条件 2: signal.aborted (显式 abort / 用户中断)
@@ -2124,9 +2220,10 @@ ${this.getToolDefinitions()}
             }
             // 2026-06-16 新增: loop 内自动压缩 — token 超 80% 阈值时跑一次
             // compact 失败走 C 路径: 不强行 break, 让现有 60K 阈值兜底 (后面有检查)
+            //   2026-07-01 (v0.2.4 子任务 1): 触发判定走 shouldCompactBeforeIteration 纯函数
             const compactThreshold = this.MAX_OUTPUT_TOKEN_ESCALATION_THRESHOLD * this.LOOP_COMPACT_RATIO;
             const estimatedTokensBefore = this.estimateHistoryTokens();
-            if (estimatedTokensBefore > compactThreshold) {
+            if (shouldCompactBeforeIteration(estimatedTokensBefore, compactThreshold)) {
                 const tokensBeforeCompact = estimatedTokensBefore;
                 console.log(`[PiAgent] loop 入口 token ${tokensBeforeCompact} > ${compactThreshold}, 触发自动压缩`);
                 onStream?.({ type: 'status', content: `🗜️ loop 自动压缩 (token ${tokensBeforeCompact} > ${compactThreshold})`, tool: 'compactor' });
@@ -2139,11 +2236,13 @@ ${this.getToolDefinitions()}
                 }
             }
             // 停止条件 3: context overflow (compact 后还超, 强制终止)
+            //   2026-07-01 (v0.2.4 子任务 1): 委托给 react-loop.decideContextOverflow 纯函数
             const estimatedTokens = this.estimateHistoryTokens();
-            if (estimatedTokens > this.MAX_OUTPUT_TOKEN_ESCALATION_THRESHOLD) {
+            const overflowDecision = decideContextOverflow(estimatedTokens, this.MAX_OUTPUT_TOKEN_ESCALATION_THRESHOLD);
+            if (overflowDecision.shouldExit) {
                 console.warn(`[PiAgent] context overflow (${estimatedTokens} tokens > ${this.MAX_OUTPUT_TOKEN_ESCALATION_THRESHOLD})`);
                 onStream?.({ type: 'error', content: `⏹️ 上下文溢出 (${estimatedTokens} tokens, 阈值 ${this.MAX_OUTPUT_TOKEN_ESCALATION_THRESHOLD})`, tool: 'loop' });
-                finalResponse = finalResponse || '(本轮 ReAct 循环因上下文溢出终止)';
+                finalResponse = finalResponse || overflowDecision.finalAnswer;
                 break;
             }
             // 调试日志：显示每次循环开始
@@ -2202,12 +2301,16 @@ ${toolDefs}
             // 失败静默: 全部重试失败 → 空 reply (上层用 no tool_use 终止)
             const response = await this.callLlmWithRecovery(llm, messages, systemPrompt, signal, onStream);
             const reply = (response.reply || '').trim();
+            // 2026-06-30: OpenAI 协议 native tool_calls (LLM 真产了 tool_call 时, minimax/M3 会返回 id)
+            const nativeToolCalls = response.toolCalls;
             // 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, 推到 history 让 LLM 反思, 继续 loop`);
+                console.log(`[sentinel DEBUG] 完整 reply: ${reply}`);
+                console.log(`[sentinel DEBUG] 上一轮 messages 数量: ${Array.isArray(messages) ? messages.length : 'N/A'}, systemPrompt 长度: ${systemPrompt.length}`);
                 aiFailureReason = reply.length > 200 ? reply.substring(0, 200) : reply;
                 totalErrors++;
                 consecutiveErrors++;
@@ -2234,9 +2337,10 @@ ${toolDefs}
             //   之前: 思考块里的 "<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 字符串就误杀)
+            // 2026-06-30 修: 给 toolCall 分配稳定 id, 让后续 tool result 能引用同一个 id
+            //   OpenAI 协议要求 messages 里 tool result 必须有对应的 tool_call_id, 否则 400
             if (toolCall) {
+                toolCall.id = `call_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
                 this.messageHistory.push({
                     role: 'assistant',
                     content: reply,
@@ -2402,7 +2506,7 @@ ${toolDefs}
                     catch (err) {
                         console.warn('[PiAgent] reactHarness.postToolCall failed (non-fatal, allowing):', err);
                     }
-                    this.messageHistory.push({ role: 'tool', content: JSON.stringify(result), toolResult: result });
+                    this.messageHistory.push({ role: 'tool', content: JSON.stringify(result), toolResult: result, toolCallId: toolCall.id || `call_${Date.now()}_${Math.random().toString(36).slice(2, 8)}` });
                     this.logToHarness(toolCall.name, toolCall.args, result);
                     // 通知前端工具执行结果
                     if (onStream) {
@@ -2522,6 +2626,13 @@ ${toolDefs}
                     //   LLM 不能提前 final_gen — harness 自动注入"请汇报剩余工具结果" hint 再 continue
                     //   这是 dive-into 文档"step 9 stop condition check" 的具体化:
                     //   stop condition = (有工具结果未汇报) ? continue : break
+                    // 检查回复是否包含工具结果内容（避免无限循环）
+                    const hasToolResultContent = this.successfulToolResults.some(r => reply.includes(r.tool) || reply.includes(r.outputPreview.substring(0, 50)));
+                    // 如果回复包含工具结果内容，清除 successfulToolResults
+                    if (hasToolResultContent) {
+                        console.log(`[PiAgent] 回复包含工具结果内容, 清除 successfulToolResults (${this.successfulToolResults.length} 个)`);
+                        this.successfulToolResults = [];
+                    }
                     if (this.successfulToolResults.length > 0 && iteration < this.MAX_REACT_ITERATIONS) {
                         const unreported = this.successfulToolResults.length;
                         console.log(`[PiAgent] LLM 想 final_gen 但还有 ${unreported} 个工具结果未汇报, push hint 让其继续`);
@@ -2680,18 +2791,45 @@ Workspace root folder: ${this.cwd}
             for (const m of recentMessages) {
                 const role = m.role;
                 let content = m.content;
-                // tool role: 用 toolResult 序列化 (跟 buildContext 一样)
+                // 2026-06-30 修: OpenAI 协议 tool role 必须带 tool_call_id, 否则 minimax (OpenAI-compatible) 报 400
+                //   bolloon 之前把所有 tool result 包成 "[工具结果] ..." 当 user/assistant role 发, minimax 严格校验失败
+                //   现在: 保留 role='tool' + 加 tool_call_id 字段 (用 messageHistory 里自己生成的 id)
                 if (role === 'tool') {
                     const result = m.toolResult ? JSON.stringify(m.toolResult) : content;
                     content = `[工具结果] ${result}`;
+                    // MiniMax 等 API 不支持 tool role, 转为 user role
+                    out.push({ role: 'user', content });
+                    continue;
                 }
                 // system role (router hint 等) 直接保留
                 if (role === 'system') {
                     out.push({ role: 'system', content });
                     continue;
                 }
-                // assistant / user / tool 直接转
-                if (role === 'user' || role === 'assistant' || role === 'tool') {
+                // 2026-06-30 修: assistant 消息如果带 toolCall (bolloon 内部对象), emit OpenAI 协议的 tool_calls 数组
+                //   minimax 严格要求 assistant 消息含 tool_calls 字段, 后续 tool result 才能引用 tool_call_id
+                if (role === 'assistant') {
+                    const tc = m.toolCall;
+                    if (tc && tc.id) {
+                        out.push({
+                            role: 'assistant',
+                            content: content || '',
+                            tool_calls: [{
+                                    id: tc.id,
+                                    type: 'function',
+                                    function: {
+                                        name: tc.name,
+                                        arguments: JSON.stringify(tc.args || {}),
+                                    },
+                                }],
+                        });
+                    }
+                    else {
+                        out.push({ role, content });
+                    }
+                    continue;
+                }
+                if (role === 'user') {
                     out.push({ role, content });
                 }
             }
@@ -2778,7 +2916,8 @@ Workspace root folder: ${this.cwd}
                 // 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 || '' };
+                // 2026-06-30: 透传 toolCalls (OpenAI 协议 native) 给上层, 让 assistant message 能 emit 真 id
+                return { reply: response.reply || '', toolCalls: response.toolCalls };
             }
             catch (err) {
                 // 用户主动 abort: 不重试, 立即抛
@@ -2904,225 +3043,22 @@ Workspace root folder: ${this.cwd}
         }
     }
     isFinalResponse(content) {
-        // 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>');
+        // 2026-06-30: 抽到 ./parse-tool-call.ts 作为纯函数 — 这里只构建 ctx 并调用
+        return isFinalResponseImpl(content, this._parseCtx());
     }
     extractFinalAnswer(content) {
-        // 提取 <final gen> 后的内容作为最终回答
-        const marker = '<final gen>';
-        const markerIndex = content.indexOf(marker);
-        if (markerIndex !== -1) {
-            const after = content.substring(markerIndex + marker.length).trim();
-            // v3 修复: 如果 <final gen> 之后是空, fallback 用 marker 之前的内容 (去掉 marker)
-            // 否则 LLM 写了 <final gen> 在末尾时, 用户看到空回复 + error
-            if (after) {
-                content = after;
-            }
-            else {
-                content = content.substring(0, markerIndex).trim();
-            }
-        }
-        // 移除任何 tool call 标记
-        let cleaned = content
-            .replace(/调用工具[：:]\s*\w+\s*\([^)]*\)/g, '')
-            .replace(/使用工具[：:]\s*\w+\s*\([^)]*\)/g, '')
-            .replace(/tool[_\w]*[：:]\s*\w+\s*\([^)]*\)/gi, '')
-            .trim();
-        return cleaned;
+        // 抽取实现已挪到 ./parse-tool-call.ts (纯函数, 易测)
+        return extractFinalAnswerImpl(content);
+    }
+    _parseCtx() {
+        return {
+            tools: new Set(Array.from(this.tools.keys())),
+            resolveAlias: (name) => this.resolveToolName(name),
+        };
     }
     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);
-            console.log(`[parseToolCall DEBUG] jsonPattern match: ${m ? `name=${m[1]}, args=${JSON.stringify(m[2]).slice(0, 80)}` : 'null'}`);
-            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={} */ }
-                // 2026-06-19: 自动 split command 字段 — LLM 常把 "git status" 整体当 command
-                //   shell_exec execute 要求 command="git", args="status" 拆分形式
-                //   这里检测 command 含空格且 args 字段空, 自动按空格 split
-                if (typeof args.command === 'string' && args.command.includes(' ') && !args.args) {
-                    const parts = args.command.split(/\s+/);
-                    args.command = parts[0];
-                    args.args = parts.slice(1).join(' ');
-                }
-                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 };
-                }
-            }
-        }
-        // 2026-06-19 修: 先剥离 <think>...</think> 思考块, 避免旧正则 `<(\w+)>([\s\S]*?)<\/\1>` 优先匹配到 <think>
-        //   之前 LLM 输出含 <think>...</think><invoke name="X">...</invoke> 时, <think> 先 match, name="think" 不在 tools → return null → 后续 <invoke> 没机会 match
-        const strippedContent = content.replace(/<think>[\s\S]*?<\/think>/g, '');
-        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,
-            /(\w+)\s*\(\s*([^)]*)\s*\)/,
-            // 兼容 LLM 输出的对象字面量格式: {tool => "get_identity", args => {...}}
-            /\{\s*tool\s*=>\s*["'](\w+)["']\s*(?:,\s*args\s*=>\s*(\{[\s\S]*?\}))?\s*\}/,
-            // 兼容: tool => "get_identity"  (无 args 包裹)
-            /\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>/,
-        ];
-        for (const pattern of patterns) {
-            const match = strippedContent.match(pattern);
-            if (match) {
-                const name = match[1];
-                let args = {};
-                console.log(`[parseToolCall DEBUG] pattern matched: name=${name}, rawArgs=${(match[2] || '').slice(0, 100)}`);
-                const rawArgs = match[2] || '';
-                if (rawArgs && rawArgs.trim().startsWith('{')) {
-                    // JSON 形式, 尝试解析
-                    try {
-                        const parsed = JSON.parse(rawArgs);
-                        if (parsed && typeof parsed === 'object') {
-                            args = Object.fromEntries(Object.entries(parsed).map(([k, v]) => [k, String(v)]));
-                        }
-                    }
-                    catch {
-                        // 解析失败就当字符串处理
-                        const argPairs = rawArgs.split(',').map(s => s.trim()).filter(Boolean);
-                        for (const pair of argPairs) {
-                            const [key, ...valueParts] = pair.split(':').map(s => s.trim().replace(/['"]/g, ''));
-                            if (key)
-                                args[key] = valueParts.join(':') || '';
-                        }
-                    }
-                }
-                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>
-                    // 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
-                    const argPairs = rawArgs.split(',').map(s => s.trim()).filter(Boolean);
-                    for (const pair of argPairs) {
-                        const [key, ...valueParts] = pair.split(':').map(s => s.trim().replace(/['"]/g, ''));
-                        if (key)
-                            args[key] = valueParts.join(':') || '';
-                    }
-                }
-                if (this.tools.has(name)) {
-                    // 2026-06-19: auto-split command field — shell_exec expects command='git', args='status' split
-                    if (typeof args.command === 'string' && args.command.includes(' ') && !args.args) {
-                        const parts = args.command.split(/\s+/);
-                        args.command = parts[0];
-                        args.args = parts.slice(1).join(' ');
-                    }
-                    return { name, args };
-                }
-                const resolved = this.resolveToolName(name);
-                if (resolved) {
-                    return { name: resolved, args };
-                }
-            }
-        }
-        return null;
+        // 2026-06-30: 抽到 ./parse-tool-call.ts 作为纯函数 — 这里只构建 ctx 并调用
+        return parseToolCallImpl(content, this._parseCtx());
     }
     // [debug-2026-06-19] 临时: 打印 parseToolCall 输入和返回
     _dbgParseToolCall(content) {
@@ -3384,47 +3320,15 @@ Workspace root folder: ${this.cwd}
      *   bolloon 注册的是 read_document / edit_file / write_file / shell_exec / list_files
      *   返回 this.tools 里的标准名, 或 null 表示未识别
      */
+    /**
+     * 把 LLM 给的工具名 (可能大小写不一, 或者 Claude Code 风格的别名) 解析为
+     * bolloon 注册的标准工具名.
+     *
+     * 2026-06-30: 委托给 ToolRegistry 模块 — alias 表在 tool-registry.ts 统一维护,
+     *   这里只做 thin wrapper 保留 backward compat (private API 但其它地方可能用).
+     */
     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;
+        return this._toolRegistry.resolve(name);
     }
     /**
      * 2026-06-19: 注册 P2P 消息 listener, 把收到的消息存到 _inboxMessages 供 check_inbox 读.
@@ -3999,11 +3903,14 @@ export async function createAgentSession(config, forceNew) {
         const key = config.peerId;
         if (!forceNew && independentSessions.has(key)) {
             console.log(`[createAgentSession] 找到现有独立 session, key=${key}`);
-            return independentSessions.get(key);
+            const existing = independentSessions.get(key);
+            await existing.whenReady();
+            return existing;
         }
         const session = new PiAgentSession(config);
         independentSessions.set(key, session);
         console.log(`[createAgentSession] 创建独立 session, key=${key}, DID=${incomingDid}`);
+        await session.whenReady();
         return session;
     }
     // 如果指定了 forceNew 但没有 peerId，生成带时间戳的 key
@@ -4012,6 +3919,7 @@ export async function createAgentSession(config, forceNew) {
         const session = new PiAgentSession(config);
         independentSessions.set(key, session);
         console.log(`[createAgentSession] 创建强制新 session, key=${key}`);
+        await session.whenReady();
         return session;
     }
     // 如果有新的 DID，强制重建 session
@@ -4031,11 +3939,13 @@ export async function createAgentSession(config, forceNew) {
                 createdAt: Date.now()
             });
         }
+        await sessionInstance.whenReady();
         return sessionInstance;
     }
     sessionInstance = new PiAgentSession(config);
     lastIdentityDid = config.identityDoc?.did || null;
     console.log(`[createAgentSession] 新建 session, DID=${lastIdentityDid}`);
+    await sessionInstance.whenReady();
     return sessionInstance;
 }
 export function getAgentSession() {