@bolloon/bolloon-agent 0.2.12 → 0.2.13

package/dist/agents/pi-sdk.js

@@ -1,8 +1,14 @@
 /**
  * Pi-SDK - Agent Session for Document Processing
  * Part of OpenClaw dual-layer architecture
+ *
+ * 模块拆分 (2026-07-06):
+ *   - types        → ./pi-sdk-types.ts            (interface / type)
+ *   - session mgr  → ./pi-sdk-session-manager.ts  (PiSessionManager 类)
+ *   - tools        → ./pi-sdk-tools.ts            (registerBuiltinTools / Wallet / IdempotencyCache)
+ *   - factory      → ./pi-sdk-session-factory.ts  (createAgentSession / getAgentSession / resetAgentSession / runSelfImproveLoop)
+ *   - 本文件                                       (PiAgentSession 类: LLM 循环 / 系统提示 / 工具调用分发 / 压缩 / persistence)
  */
-import * as fs from 'fs/promises';
 import * as fsSync from 'fs';
 import * as os from 'os';
 import * as path from 'path';
@@ -13,13 +19,16 @@ import { ConstraintLayer } from './constraint-layer.js';
 import { WorkflowEngine } from './workflow-engine.js';
 import { DeepThinkingEngine, AgentCoordinator } from '@bolloon/constraint-runtime';
 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, checkWritePath } from './shell-guard.js';
+import { initDocumentReceiver } from './p2p-document-tools.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';
-import { loadSkillsFromPaths, defaultSkillPaths, describeSkill } from './skill-loader.js';
+import { SkillRegistry } from '@bolloon/constraint-runtime';
+import { loadSkillsFromPaths, defaultSkillPaths } from './skill-loader.js';
+// 拆分后的子模块 — 重新导出保 backward compat
+export { TOOL_DEFINITIONS, } from './pi-sdk-types.js';
+export { PiSessionManager } from './pi-sdk-session-manager.js';
+import { PiSessionManager } from './pi-sdk-session-manager.js';
+import { registerBuiltinTools, registerWalletTools, setupInboxListener, IdempotencyCache, } from './pi-sdk-tools.js';
+export { createAgentSession, getAgentSession, resetAgentSession, runSelfImproveLoop, } from './pi-sdk-session-factory.js';
 // Judgment 注入门 (P0): 在主对话 LLM 调起前自动拼入 Top 3 判断力
 // 失败静默, 不阻塞主对话
 import { injectJudgmentGate, recordJudgmentUsage } from '../pi-ecosystem-judgment/injection-gate.js';
@@ -31,306 +40,14 @@ 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';
-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 {
-    session;
-    state;
-    memory;
-    persona = null;
-    channels = new Map();
-    channelsPath;
-    initialized = false;
-    sessionDir;
-    cwd;
-    sharedContext;
-    agentId;
-    constructor(agentId, cwd) {
-        this.cwd = cwd;
-        this.sessionDir = path.join(cwd, '.port_sessions');
-        this.agentId = agentId;
-        const sessionId = `pi-session-${Date.now()}`;
-        this.session = new Session(sessionId);
-        this.state = {
-            id: sessionId,
-            agentId,
-            cwd,
-            startedAt: new Date().toISOString(),
-            lastActive: new Date().toISOString()
-        };
-        this.memory = {
-            workingMemory: [],
-            summarizedMemory: [],
-            fileContext: new Map()
-        };
-        this.channelsPath = path.join(SHARED_SESSION_PATH, 'pi-channels.json');
-        this.sharedContext = getGlobalSharedContext();
-    }
-    get sessionId() {
-        return this.session.sessionId;
-    }
-    get turnCount() {
-        return this.session.turnCount;
-    }
-    addSessionMessage(msg) {
-        this.session.addMessage(msg);
-        this.persistSession();
-    }
-    getSessionHistory() {
-        return this.session.history;
-    }
-    setSessionContext(key, value) {
-        this.session.setContext(key, value);
-        this.persistSession();
-    }
-    getSessionContext(key) {
-        return this.session.getContext(key);
-    }
-    persistSession() {
-        try {
-            const stored = {
-                sessionId: this.session.sessionId,
-                messages: this.session.history,
-                inputTokens: 0,
-                outputTokens: 0
-            };
-            saveSession(stored);
-        }
-        catch (e) {
-            console.warn('Failed to persist session:', e);
-        }
-    }
-    loadPersistedSession() {
-        try {
-            const sessionId = this.state.id;
-            const stored = loadSession(sessionId);
-            for (const msg of stored.messages) {
-                this.session.addMessage(msg);
-            }
-        }
-        catch {
-            // No persisted session found, start fresh
-        }
-    }
-    async initialize() {
-        if (this.initialized)
-            return;
-        await fs.mkdir(SHARED_SESSION_PATH, { recursive: true });
-        await fs.mkdir(this.sessionDir, { recursive: true });
-        this.persona = await this.loadPersona();
-        await this.loadChannels();
-        this.loadPersistedSession();
-        await this.sharedContext.initialize();
-        await this.sharedContext.registerAgent({
-            agentId: this.agentId,
-            sessionId: this.sessionId,
-            channelId: 'system',
-            capabilities: this.persona?.capabilities || [],
-            status: 'active',
-            name: this.persona?.name,
-            persona: this.persona ? {
-                name: this.persona.name,
-                description: this.persona.description,
-                capabilities: this.persona.capabilities
-            } : undefined
-        });
-        this.initialized = true;
-    }
-    async loadPersona() {
-        try {
-            const data = await fs.readFile(PERSONA_PATH, 'utf-8');
-            return JSON.parse(data);
-        }
-        catch {
-            return null;
-        }
-    }
-    async loadChannels() {
-        try {
-            const data = await fs.readFile(this.channelsPath, 'utf-8');
-            const channelsArray = JSON.parse(data);
-            this.channels.clear();
-            for (const channel of channelsArray) {
-                this.channels.set(channel.id, channel);
-            }
-        }
-        catch {
-            this.channels.clear();
-        }
-    }
-    async saveChannels() {
-        const channelsArray = Array.from(this.channels.values());
-        await fs.writeFile(this.channelsPath, JSON.stringify(channelsArray, null, 2));
-    }
-    async savePersona(persona) {
-        await fs.writeFile(PERSONA_PATH, JSON.stringify(persona, null, 2));
-        this.persona = persona;
-    }
-    getPersona() {
-        return this.persona;
-    }
-    getState() {
-        return { ...this.state, lastActive: new Date().toISOString() };
-    }
-    getMemory() {
-        return this.memory;
-    }
-    addToWorkingMemory(content) {
-        this.memory.workingMemory.push(content);
-        if (this.memory.workingMemory.length > 100) {
-            this.memory.workingMemory = this.memory.workingMemory.slice(-100);
-        }
-        this.state.lastActive = new Date().toISOString();
-    }
-    addSummarizedMemory(content) {
-        this.memory.summarizedMemory.push(content);
-        if (this.memory.summarizedMemory.length > 50) {
-            this.memory.summarizedMemory = this.memory.summarizedMemory.slice(-50);
-        }
-    }
-    addFileContext(filePath, content) {
-        this.memory.fileContext.set(filePath, content);
-        if (this.memory.fileContext.size > 20) {
-            const entries = Array.from(this.memory.fileContext.entries());
-            this.memory.fileContext = new Map(entries.slice(-20));
-        }
-    }
-    updateTokenUsage(promptTokens, completionTokens) {
-        this.state.tokenUsage = {
-            promptTokens: (this.state.tokenUsage?.promptTokens || 0) + promptTokens,
-            completionTokens: (this.state.tokenUsage?.completionTokens || 0) + completionTokens,
-            totalTokens: (this.state.tokenUsage?.totalTokens || 0) + promptTokens + completionTokens
-        };
-    }
-    async addMessage(channelId, message) {
-        await this.initialize();
-        if (!this.channels.has(channelId)) {
-            this.channels.set(channelId, {
-                id: channelId,
-                name: channelId,
-                messages: [],
-                createdAt: new Date().toISOString(),
-                updatedAt: new Date().toISOString()
-            });
-        }
-        const channel = this.channels.get(channelId);
-        channel.messages.push(message);
-        channel.updatedAt = new Date().toISOString();
-        await this.saveChannels();
-    }
-    async getChannelMessages(channelId) {
-        await this.initialize();
-        return this.channels.get(channelId)?.messages || [];
-    }
-    async createChannel(name, peerInfo, persona) {
-        await this.initialize();
-        const channelId = `ch_${Date.now()}_${Math.random().toString(36).substring(2, 8)}`;
-        const channel = {
-            id: channelId,
-            name,
-            messages: [],
-            createdAt: new Date().toISOString(),
-            updatedAt: new Date().toISOString(),
-            ...peerInfo,
-            persona: persona || undefined
-        };
-        this.channels.set(channelId, channel);
-        await this.saveChannels();
-        return channel;
-    }
-    async getOrCreatePeerChannel(peerDid, peerName, persona) {
-        await this.initialize();
-        for (const channel of this.channels.values()) {
-            if (channel.peerDid === peerDid) {
-                return channel;
-            }
-        }
-        return this.createChannel(`与 ${peerName} 的对话`, {
-            peerDid,
-            peerName
-        }, persona);
-    }
-    async setChannelInfo(channelId, info) {
-        await this.initialize();
-        const channel = this.channels.get(channelId);
-        if (channel) {
-            Object.assign(channel, info, { updatedAt: new Date().toISOString() });
-            await this.saveChannels();
-        }
-    }
-    getAllChannels() {
-        return Array.from(this.channels.values());
-    }
-    getChannelPersona(channelId) {
-        return this.channels.get(channelId)?.persona;
-    }
-    async setChannelPersona(channelId, persona) {
-        await this.initialize();
-        const channel = this.channels.get(channelId);
-        if (channel) {
-            channel.persona = persona;
-            channel.updatedAt = new Date().toISOString();
-            await this.saveChannels();
-        }
-    }
-    async addUserActionToSharedContext(content, importance) {
-        await this.initialize();
-        await this.sharedContext.addUserAction(content, this.agentId, undefined, importance);
-        await this.sharedContext.updateAgentStatus(this.agentId, 'active');
-    }
-    async addSharedKnowledge(knowledge) {
-        await this.initialize();
-        await this.sharedContext.addSharedKnowledge(knowledge);
-    }
-    async getRecentActionsSummary(count) {
-        return this.sharedContext.getRecentActionsSummary(count);
-    }
-    async getSharedKnowledge() {
-        return this.sharedContext.getSharedKnowledge();
-    }
-    async getGlobalContext() {
-        return this.sharedContext.getFullContext();
-    }
-    async getGlobalContextSummary() {
-        return this.sharedContext.getContextSummary();
-    }
-    async createCooperation(type, task, toAgentId, context) {
-        await this.initialize();
-        return this.sharedContext.createCooperation(type, this.agentId, task, toAgentId, context);
-    }
-    async getPendingCooperations() {
-        return this.sharedContext.getPendingCooperations(this.agentId);
-    }
-    async updateCooperationStatus(cooperationId, status, result) {
-        await this.sharedContext.updateCooperationStatus(cooperationId, status, result);
-    }
-    async getAllRegisteredAgents() {
-        return this.sharedContext.getAllAgents();
-    }
-    async findAgentByCapability(capability) {
-        return this.sharedContext.findAgentByCapability(capability);
-    }
-    async getCooperation(cooperationId) {
-        return this.sharedContext.getCooperation(cooperationId);
-    }
-    async updateAgentStatusInRegistry(status) {
-        await this.sharedContext.updateAgentStatus(this.agentId, status);
-    }
-}
-const TOOL_DEFINITIONS = `
-可用工具:
-1. read_document(path) - 读取文档内容，支持 .txt, .md, .pdf, .docx
-2. summarize_document(path, context?) - 总结文档内容，可选提供上下文
-3. improve_document(path, requirements) - 改进文档，需提供文件路径和改进要求
-4. list_peers() - 列出已连接的对等节点
-5. send_message(peer_id, message) - 向指定对等节点发送消息
-6. broadcast_message(message) - 向所有对等节点广播消息
-7. get_identity() - 获取当前智能体身份信息
-8. set_persona(persona_json) - 更新智能体 persona，包含 name、description、personality、greeting 等
-9. run_workflow(steps) - 执行预定义工作流
-10. get_operation_logs() - 获取操作日志
-`;
-class PiAgentSession {
+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';
+// PiSessionManager 已抽到 ./pi-sdk-session-manager.ts (2026-07-06)
+// Tool / ToolResult / Message / StreamCallback / StreamEvent / HeartbeatConfig / AgentSession / TOOL_DEFINITIONS
+//   已抽到 ./pi-sdk-types.ts (2026-07-06)
+export class PiAgentSession {
     cwd;
     peerId;
     identity;
@@ -344,11 +61,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 + 多步反思) 会被误杀
@@ -360,6 +83,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 次) */
@@ -382,6 +109,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 入口设置, 用完即清
@@ -394,6 +124,8 @@ class PiAgentSession {
     promptStartTime = 0;
     /** 当前 channel id (由 getAgentForChannel / prompt 4 参注入, 供 hook / log 使用) */
     currentChannelId = '';
+    /** 2026-07-04: 当前 agentId (server.ts 通过 createAgentSession 选项注入), 供 onSessionStart 加载 persona docs */
+    currentAgentId = '';
     /** M2.2 (2026-06-17): 当前轮的用户请求 intent, runReActLoop 拼 systemPrompt 时会读这个 */
     currentIntent = 'chitchat';
     currentIntentHint = '';
@@ -437,6 +169,10 @@ class PiAgentSession {
         this.peerId = config.peerId || 'local';
         this.identity = config.identityDoc || this.createDefaultIdentity();
         this.minimaxAvailable = this.checkMinimax();
+        // 2026-07-04: 透传 agentId (server.ts 通过 createAgentSession 选项注入)
+        this.currentAgentId = config.agentId || '';
+        // 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);
@@ -452,38 +188,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} 条历史`);
@@ -493,6 +228,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.
      *
@@ -501,23 +314,17 @@ class PiAgentSession {
      *   2. ~/.bolloon/skills/         全局用户级
      *   3. <cwd>/.bolloon/skills/     项目级
      *   4. ~/.boll/skills/            全局 (兼容 bollharness 旧用户)
-     *   5. <bolloon-repo>/src/bollharness/.boll/skills/  bolloon 仓库内置 skill
-     *      (bolloon 项目本身用 pi-sdk 写核心, 这 19 个 skill 视为项目级 builtin)
+     *
+     * 2026-07-04: 移除 18 个 bollharness builtin skill (findBolloonBuiltinSkillsPath).
+     *   历史遗留: 写 pi-sdk 时为方便演示, 把 bolloon 项目里的 19 个 skill 强制注入到 system prompt.
+     *   问题: system prompt 涨到 22K chars, LLM (minimax M3) 在 pivot loop 里反复 think 不输出
+     *          `<final gen>`, session 落盘拿不到最终回答.
+     *   现在: 只让用户放 .bolloon/skills/SKILL.md 才生效, 干净且 project-owned.
      *
      * 静默忽略不存在的目录.
      */
     loadSkills(paths) {
-        let resolved;
-        if (paths && paths.length > 0) {
-            resolved = paths;
-        }
-        else {
-            resolved = [
-                ...defaultSkillPaths(os.homedir(), this.cwd),
-                // bolloon 仓库内置 skill (相对本 npm 包的位置)
-                this.findBolloonBuiltinSkillsPath(),
-            ].filter((p) => Boolean(p));
-        }
+        const resolved = (paths && paths.length > 0) ? paths : defaultSkillPaths(os.homedir(), this.cwd);
         loadSkillsFromPaths(resolved)
             .then((skills) => {
             for (const s of skills) {
@@ -526,36 +333,17 @@ class PiAgentSession {
                 }
                 this.skillRegistry.register(s);
             }
-            console.log(`[loadSkills] 已加载 ${skills.length} 个 skill: ${skills.map(describeSkill).join(' | ')}`);
+            console.log(`[loadSkills] 已加载 ${skills.length} 个 skill from ${resolved.join(', ')}`);
+            if (skills.length > 0) {
+                for (const s of skills) {
+                    console.log(`  - ${s.name}: ${s.description.substring(0, 100)}${s.description.length > 100 ? '...' : ''}`);
+                }
+            }
         })
             .catch((err) => {
             console.error('[loadSkills] 加载失败:', err);
         });
     }
-    /**
-     * 定位 bolloon 仓库内置的 bollharness skill 目录.
-     * 向上回溯 cwd, 找第一个包含 src/bollharness/.boll/skills 的祖先.
-     * 找不到时返回 null (例如把 bolloon-agent 作为外部依赖安装时).
-     */
-    findBolloonBuiltinSkillsPath() {
-        let dir = this.cwd;
-        for (let i = 0; i < 6; i++) {
-            const candidate = path.join(dir, 'src', 'bollharness', '.boll', 'skills');
-            try {
-                if (fsSync.existsSync(candidate) && fsSync.statSync(candidate).isDirectory()) {
-                    return candidate;
-                }
-            }
-            catch {
-                // 忽略 stat 异常, 继续向上
-            }
-            const parent = path.dirname(dir);
-            if (parent === dir)
-                break;
-            dir = parent;
-        }
-        return null;
-    }
     async initHarness() {
         try {
             const { createBollharnessIntegration } = await import('../bollharness-integration/index.js');
@@ -572,634 +360,35 @@ class PiAgentSession {
         }
     }
     registerTools() {
-        this.tools.set('read_document', {
-            name: 'read_document',
-            description: '读取文档内容，支持 .txt, .md, .pdf, .docx 格式',
-            parameters: { path: 'string' },
-            execute: async (args) => {
-                try {
-                    const content = await documentReader.read(args.path);
-                    return {
-                        success: true,
-                        output: `📄 ${content.metadata.filename}\n大小: ${content.metadata.size} 字节\n\n${content.text.substring(0, 1000)}${content.text.length > 1000 ? '...' : ''}`
-                    };
-                }
-                catch (e) {
-                    return { success: false, error: String(e) };
-                }
-            }
-        });
-        this.tools.set('summarize_document', {
-            name: 'summarize_document',
-            description: '总结文档内容，分析并生成摘要',
-            parameters: { path: 'string', context: 'string' },
-            execute: async (args) => {
-                try {
-                    if (!this.minimaxAvailable) {
-                        return { success: false, error: 'LLM未初始化，请设置 MINIMAX_API_KEY' };
-                    }
-                    const result = await this.summarizeDocument(args.path, args.context);
-                    return {
-                        success: true,
-                        output: `📝 摘要:\n${result.summary}\n\n质量评分: ${(result.qualityScore * 10).toFixed(1)}/10`
-                    };
-                }
-                catch (e) {
-                    return { success: false, error: String(e) };
-                }
-            }
-        });
-        this.tools.set('improve_document', {
-            name: 'improve_document',
-            description: '根据要求改进文档内容',
-            parameters: { path: 'string', requirements: 'string' },
-            execute: async (args) => {
-                try {
-                    if (!this.minimaxAvailable) {
-                        return { success: false, error: 'LLM未初始化，请设置 MINIMAX_API_KEY' };
-                    }
-                    const result = await this.improveDocument({
-                        originalPath: args.path,
-                        requirements: args.requirements
-                    });
-                    return {
-                        success: true,
-                        output: `✅ 改进${result.improved ? '成功' : '失败'}\n质量评分: ${(result.qualityScore * 10).toFixed(1)}/10\n${result.newContent ? '\n改进内容:\n' + result.newContent.substring(0, 500) + '...' : ''}`
-                    };
-                }
-                catch (e) {
-                    return { success: false, error: String(e) };
-                }
-            }
-        });
-        this.tools.set('list_peers', {
-            name: 'list_peers',
-            description: '列出已连接的对等节点',
-            parameters: {},
-            execute: async () => {
-                const peers = p2pNetwork.getPeers();
-                if (peers.length === 0) {
-                    return { success: true, output: '当前无连接的对等节点' };
-                }
-                return { success: true, output: `已连接节点 (${peers.length}):\n${peers.map(p => `  - ${p}`).join('\n')}` };
-            }
-        });
-        this.tools.set('send_message', {
-            name: 'send_message',
-            description: '向指定对等节点发送消息',
-            parameters: { peer_id: '对等节点ID', message: '消息内容' },
-            execute: async (args) => {
-                try {
-                    await p2pNetwork.sendMessage(args.peer_id, 'message', args.message);
-                    return { success: true, output: `消息已发送到 ${args.peer_id}` };
-                }
-                catch (e) {
-                    return { success: false, error: String(e) };
-                }
-            }
-        });
-        this.tools.set('broadcast_message', {
-            name: 'broadcast_message',
-            description: '向所有对等节点广播消息',
-            parameters: { message: '消息内容' },
-            execute: async (args) => {
-                try {
-                    await p2pNetwork.broadcast('message', args.message);
-                    return { success: true, output: '消息已广播到所有节点' };
-                }
-                catch (e) {
-                    return { success: false, error: String(e) };
-                }
-            }
-        });
-        this.tools.set('get_identity', {
-            name: 'get_identity',
-            description: '获取当前智能体身份信息',
-            parameters: {},
-            execute: async () => {
-                const id = this.getIdentity();
-                const extraInfo = id.cid ? `\nCID: ${id.cid}` : '';
-                const ipnsInfo = id.ipnsName ? `\nIPNS: ${id.ipnsName}` : '';
-                return {
-                    success: true,
-                    output: `DID: ${id.did}\n名称: ${id.name}\n公钥: ${id.publicKey}${extraInfo}${ipnsInfo}\n创建时间: ${new Date(id.createdAt).toISOString()}`
-                };
-            }
-        });
-        this.tools.set('set_persona', {
-            name: 'set_persona',
-            description: '更新智能体的 persona 信息，包括名字、描述、性格等',
-            parameters: { persona_json: 'Persona JSON 对象，包含 name、description、personality、greeting 等字段' },
-            execute: async (args) => {
-                try {
-                    const personaData = typeof args.persona_json === 'string' ? JSON.parse(args.persona_json) : args.persona_json;
-                    const now = new Date().toISOString();
-                    const newPersona = {
-                        name: personaData.name || this.identity.name,
-                        description: personaData.description || '',
-                        capabilities: personaData.capabilities || [],
-                        personality: personaData.personality || '',
-                        greeting: personaData.greeting || '',
-                        interests: personaData.interests || [],
-                        createdAt: this.persona?.createdAt || now,
-                        updatedAt: now
-                    };
-                    await this.setPersona(newPersona);
-                    this.persona = newPersona;
-                    if (newPersona.name) {
-                        this.identity.name = newPersona.name;
-                    }
-                    return { success: true, output: `Persona 已更新:\n名称: ${newPersona.name}\n描述: ${newPersona.description}\n性格: ${newPersona.personality}` };
-                }
-                catch (e) {
-                    return { success: false, error: `更新 persona 失败: ${String(e)}` };
-                }
-            }
-        });
-        this.tools.set('get_operation_logs', {
-            name: 'get_operation_logs',
-            description: '获取约束层的操作日志',
-            parameters: {},
-            execute: async () => {
-                const logs = this.constraintLayer.getLogs();
-                if (logs.length === 0) {
-                    return { success: true, output: '暂无操作日志' };
-                }
-                return {
-                    success: true,
-                    output: `操作日志 (${logs.length} 条):\n${logs.slice(-10).map(l => `[${new Date(l.timestamp).toISOString()}] ${l.action} - ${l.status}`).join('\n')}`
-                };
-            }
-        });
-        // 添加文件列表工具
-        this.tools.set('list_files', {
-            name: 'list_files',
-            description: '列出目录中的文件',
-            parameters: { path: '目录路径（可选，默认为当前目录）' },
-            execute: async (args) => {
-                try {
-                    const fs = await import('fs');
-                    const path = args.path || this.cwd;
-                    const files = fs.readdirSync(path);
-                    return {
-                        success: true,
-                        output: `📁 目录 ${path} 中的文件 (${files.length} 个):\n${files.slice(0, 20).map(f => `  - ${f}`).join('\n')}${files.length > 20 ? '\n  ...' : ''}`
-                    };
-                }
-                catch (e) {
-                    return { success: false, error: String(e) };
-                }
-            }
-        });
-        // 添加目录读取工具（更完整的实现）
-        this.tools.set('read_directory', {
-            name: 'read_directory',
-            description: '读取目录内容，返回文件列表和目录结构',
-            parameters: { path: '目录路径（可选，默认为当前目录）' },
-            execute: async (args) => {
-                try {
-                    const fs = await import('fs');
-                    const pathModule = await import('path');
-                    const targetPath = args.path || this.cwd;
-                    const items = fs.readdirSync(targetPath);
-                    const result = [];
-                    for (const item of items.slice(0, 30)) {
-                        const fullPath = pathModule.join(targetPath, item);
-                        try {
-                            const stat = fs.statSync(fullPath);
-                            const type = stat.isDirectory() ? '📁' : '📄';
-                            result.push(`${type} ${item}${stat.isDirectory() ? '/' : ''}`);
-                        }
-                        catch {
-                            result.push(`📄 ${item}`);
-                        }
-                    }
-                    return {
-                        success: true,
-                        output: `📂 ${targetPath} (${items.length} 项):\n${result.join('\n')}${items.length > 30 ? '\n... 还有更多文件' : ''}`
-                    };
-                }
-                catch (e) {
-                    return { success: false, error: `无法读取目录: ${String(e)}` };
-                }
-            }
-        });
-        // P2P Document Tools
-        for (const tool of p2pDocumentTools) {
-            this.tools.set(tool.name, tool);
-        }
-        // Shell Exec 工具: 给 AI 跑受限的 shell 命令
-        // **只能** 跑白名单内的命令 (git/npm/tsc/vitest/cat/...)
-        // **不能** 改禁区路径 (见 shell-guard.ts 的 FORBIDDEN_PATH_PATTERNS)
-        // 沙箱 cwd: .bolloon-shell-sandbox/
-        this.tools.set('shell_exec', {
-            name: 'shell_exec',
-            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);
-                const timeoutMs = Number(args.timeoutMs) || 30000;
-                const result = await shellExec(cmd, argList, { timeoutMs });
-                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: result.output };
-            }
-        });
-        // self_improve 工具: AI 触发自我改进循环
-        // **必须** 在 branchPrefix 命名的分支上工作
-        // 心跳事件会自动调用; 用户对话里也能手动调
-        this.tools.set('self_improve', {
-            name: 'self_improve',
-            description: `触发自我改进循环. AI 会在分支 ${getBranchPrefix()}<timestamp> 上工作, 跑 tsc + vitest 验证, 通过后输出分支名给用户审. 冷却期由策略文件决定. 命中护栏禁区的改动会被拒.`,
-            parameters: { goal: '本轮改进目标 (1 句话)' },
-            execute: async (args) => {
-                const goal = String(args.goal || '').trim();
-                if (!goal)
-                    return { success: false, error: 'goal 必填' };
-                return await runSelfImproveLoop(goal);
-            }
-        });
-        // list_skills 工具: 列出当前 session 已加载的 skills
-        // 加载源: ~/.bolloon/skills/ → <cwd>/.bolloon/skills/ → ~/.boll/skills/
-        this.tools.set('list_skills', {
-            name: 'list_skills',
-            description: '列出当前 session 已加载的 skills 及其描述. Skills 是从 SKILL.md 文件加载的, 兼容 Anthropic Agent Skills 标准 frontmatter 和 bollharness 现有 frontmatter.',
-            parameters: {},
-            execute: async () => {
-                const skills = this.skillRegistry.list();
-                if (skills.length === 0) {
-                    return {
-                        success: true,
-                        output: '当前 session 没有加载任何 skill. 检查 ~/.bolloon/skills/ 或项目 .bolloon/skills/ 目录.',
-                    };
-                }
-                const lines = skills.map((s, i) => `${i + 1}. ${s.name} — ${s.description}`);
-                return { success: true, output: `已加载 ${skills.length} 个 skill:\n${lines.join('\n')}` };
-            }
-        });
-        // use_skill 工具: 加载指定 skill 的 body 进 LLM context
-        // Skills 协议核心: 把 SKILL.md body 作为 Markdown 指南返回, LLM 下一轮按它执行
-        this.tools.set('use_skill', {
-            name: 'use_skill',
-            description: '按名称加载一个 skill, 把它的 SKILL.md body 作为 Markdown 文档返回. 调用后 LLM 会在下一轮按 skill 指南执行. 与 shell_exec / read_document 这些 "能力工具" 不同, use_skill 是 "知识注入".',
-            parameters: { name: 'skill 名称 (用 list_skills 查可用的)' },
-            execute: async (args) => {
-                const name = String(args.name || '').trim();
-                if (!name)
-                    return { success: false, error: 'name 必填' };
-                if (!this.skillRegistry.has(name)) {
-                    const available = this.skillRegistry.list().map((s) => s.name).join(', ');
-                    return { success: false, error: `skill "${name}" 未找到. 已加载: ${available || '(无)'}` };
-                }
-                try {
-                    const body = await this.skillRegistry.execute(name, {});
-                    return { success: true, output: body };
-                }
-                catch (e) {
-                    return { success: false, error: `执行 skill 失败: ${String(e)}` };
-                }
-            }
-        });
-        // 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 || ''}` };
-            }
-        });
-        // 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',
-        ]);
+        // 2026-07-06: 工具注册抽到 ./pi-sdk-tools.ts, 这里只调 + 镜像到 ToolRegistry
+        this._inboxMessages = [];
+        const toolCtx = {
+            tools: this.tools,
+            cwd: this.cwd,
+            identity: this.identity,
+            persona: this.persona,
+            minimaxAvailable: this.minimaxAvailable,
+            setPersona: async (p) => { await this.setPersona(p); },
+            sessionManager: this.sessionManager,
+            constraintLayer: this.constraintLayer,
+            _inboxMessages: this._inboxMessages,
+        };
+        registerBuiltinTools(toolCtx);
+        registerWalletTools(toolCtx);
+        setupInboxListener(toolCtx);
+        // 镜像到 ToolRegistry (alias resolve 用)
         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;
-            };
+            this._toolRegistry.register(tool);
         }
+        // M3.3: 副作用工具走幂等性 cache
+        this._idempotencyCache.wrap(this.tools);
     }
     /** 清幂等性缓存 — 强制下次调用真正执行 (用于 agent 显式需要重新跑的场景) */
     clearIdempotencyCache() {
-        this.idempotencyCache.clear();
+        this._idempotencyCache.clear();
     }
+    /** M3.3: 工具结果缓存 — 防止 loop 重试时副作用 (写文件 / 改代码) 执行多次 */
+    _idempotencyCache = new IdempotencyCache();
     async registerP2PDocumentReceiver() {
         await initDocumentReceiver();
     }
@@ -1207,10 +396,13 @@ class PiAgentSession {
         // M2.4 (2026-06-17): 缓存 tool 定义 — registerTools() 在构造时调一次, 此后不变
         if (this.cachedToolDefinitions)
             return this.cachedToolDefinitions;
-        const defs = ['可用工具:'];
+        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})`);
         }
         this.cachedToolDefinitions = defs.join('\n');
         return this.cachedToolDefinitions;
@@ -1307,15 +499,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;
@@ -1323,11 +527,11 @@ 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(input);
+            this.currentIntent = classifyIntent(userText);
             this.currentIntentHint = intentHint(this.currentIntent);
             if (this.currentIntent !== 'chitchat') {
                 onStream({ type: 'phase', phase: 'intent_classified', detail: this.currentIntent, content: '' });
@@ -1348,14 +552,68 @@ class PiAgentSession {
         }
         // Bootstrap SessionStart: 收集项目 Context, 拼到 systemAddition 头部
         // (失败静默, 5s 限流防止循环)
+        // 2026-07-04: 透传 agentId 让 onSessionStart 加载 persona 文档
         let bootstrapAddition = '';
         try {
-            const ss = await onSessionStart({ channelId: this.currentChannelId || undefined });
+            const ss = await onSessionStart({
+                channelId: this.currentChannelId || undefined,
+                agentId: this.currentAgentId || undefined,
+            });
             bootstrapAddition = ss.systemAddition || '';
         }
         catch (err) {
             console.warn('[PiAgent] onSessionStart failed (non-fatal):', err);
         }
+        // 2026-07-07 P1-B: 注入最近 5 条项目事件日志 (L2) — 让 LLM 知道项目状态/feature 变化
+        // 失败静默, append 到 bootstrapAddition 末尾 (超 800 字截断)
+        if (this.currentChannelId) {
+            try {
+                const { getRecentEvents } = await import('../bootstrap/event-log.js');
+                const events = await getRecentEvents(this.currentChannelId, 5);
+                if (events.length > 0) {
+                    const eventBlock = [
+                        '## 最近项目事件 (最近 5 条, 倒序)',
+                        ...events.map(e => `- [${e.ts.slice(0, 16)}] [${e.type}] ${e.summary}`),
+                    ].join('\n');
+                    bootstrapAddition = (bootstrapAddition + '\n\n' + eventBlock).slice(-2000);
+                }
+            }
+            catch (err) {
+                console.warn('[PiAgent] getRecentEvents failed (non-fatal):', err);
+            }
+            // 2026-07-07 P2-C: 注入项目当前状态 (L3) — 目标/约束/待办/已完成
+            try {
+                const { readState, formatStateForPrompt } = await import('../bootstrap/project-state.js');
+                const state = await readState({ channelId: this.currentChannelId });
+                const stateText = formatStateForPrompt(state);
+                if (stateText) {
+                    bootstrapAddition = (bootstrapAddition + '\n\n' + stateText).slice(-2500);
+                }
+            }
+            catch (err) {
+                console.warn('[PiAgent] readState failed (non-fatal):', err);
+            }
+            // 2026-07-07 P2-C: 向量检索 top-3 (L4) — 按当前 channelId + userText 找历史相关片段
+            try {
+                const { searchIndex } = await import('../bootstrap/vector-index.js');
+                const indexName = `channel-${this.currentChannelId}`;
+                const results = await searchIndex({
+                    indexName,
+                    query: userText,
+                    topK: 3,
+                });
+                if (results.length > 0) {
+                    const hitBlock = [
+                        '## 相关历史片段 (top-3, TF-IDF cosine)',
+                        ...results.map((r, i) => `- [${i + 1}] score=${r.score.toFixed(3)}: ${r.text.slice(0, 200).replace(/\n/g, ' ')}`),
+                    ].join('\n');
+                    bootstrapAddition = (bootstrapAddition + '\n\n' + hitBlock).slice(-3000);
+                }
+            }
+            catch (err) {
+                // 索引不存在是常见情况 (新 channel), 不打 warn
+            }
+        }
         this.bootstrapAddition = bootstrapAddition;
         // P2: 解析当前 permission mode (BootstrapOptions > env BOLLOON_PERM_MODE > default)
         try {
@@ -1372,7 +630,7 @@ class PiAgentSession {
         if (this.usePivotLoop) {
             let pivotResult = '';
             try {
-                const lr = await this.promptWithPivotLoop(input, undefined, channelId);
+                const lr = await this.promptWithPivotLoop(userText, undefined, channelId);
                 pivotResult = lr.response || '';
                 onStream({ type: 'done', content: '' });
             }
@@ -1396,7 +654,7 @@ class PiAgentSession {
                     }
                     catch { }
                 }
-                monitorAfterReply(input, pivotResult);
+                monitorAfterReply(userText, pivotResult);
                 const stopStartTime = this.promptStartTime || Date.now();
                 onStop({
                     channelId: this.currentChannelId || 'unknown',
@@ -1407,6 +665,7 @@ class PiAgentSession {
                 this.currentOnStream = null;
                 this.currentSignal = null;
                 this.bootstrapAddition = '';
+                this.contextHintAddition = '';
                 this.promptStartTime = 0;
             }
             return pivotResult;
@@ -1540,37 +799,53 @@ class PiAgentSession {
         }
         // M2.4: persona 缓存
         if (!this.cachedPersonaSection && this.persona) {
-            this.cachedPersonaSection = `
-角色描述: ${this.persona.description || '无'}
-性格特点: ${this.persona.personality || '无'}
-问候语: ${this.persona.greeting || '无'}
+            this.cachedPersonaSection = `
+角色描述: ${this.persona.description || '无'}
+性格特点: ${this.persona.personality || '无'}
+问候语: ${this.persona.greeting || '无'}
 `;
         }
-        const systemPrompt = `${this.bootstrapAddition}你是 ${this.identity.name}，基于ReAct (Reasoning + Acting)模式工作。${this.cachedPersonaSection}
-当前工作目录: ${this.cwd}
-当前身份: ${this.identity.name} (${this.identity.did})
-${this.currentIntentHint}
-
-${this.getToolDefinitions()}
-
-工作模式:
-1. 理解用户自然语言请求
-2. 分析需要哪些工具来完成
-3. 按顺序调用工具并观察结果
-4. 根据观察结果决定下一步
-5. 最终给出完整回答
-
-重要:
-- 每次只调用一个工具
-- 仔细分析工具返回结果
-- 当任务完成时，必须在回答末尾添加 <final gen> 标记表示结束
-- 如果需要更多信息，继续调用工具${this.judgmentGateAddition}`;
+        const systemPrompt = `${this.bootstrapAddition}你是 ${this.identity.name}，基于ReAct (Reasoning + Acting)模式工作。${this.cachedPersonaSection}
+当前工作目录: ${this.cwd}
+当前身份: ${this.identity.name} (${this.identity.did})
+${this.currentIntentHint}
+
+${this.getToolDefinitions()}
+
+工作模式:
+1. 理解用户自然语言请求
+2. 分析需要哪些工具来完成
+3. 按顺序调用工具并观察结果
+4. 根据观察结果决定下一步
+5. 最终给出完整回答
+
+重要 (一次命中要求):
+- 每次只调用一个工具
+- 仔细分析工具返回结果
+- 当任务完成时，必须在回答末尾添加 <final gen> 标记表示结束
+- 如果需要更多信息，继续调用工具
+
+【工具调用格式 (严格遵守, 否则系统无法解析)】
+- 你只能输出**一个**工具调用, 不要堆叠多个 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);
+        // 2026-07-06: pivot 内 token 累计到 ~70% 时回调 (workflow-pivot-loop.ts line 270+).
+        //   pivot 的 messageHistory 是 process-local, 不和 pi-sdk 的 this.messageHistory 同步.
+        //   真正折叠需要把 pi-sdk 历史灌回 pivot 的 history 数组 — 侵入较大.
+        //   当前 priority: 临时传空实现, 让 budget 公式放够 (workflow-pivot-loop.ts line 220)
+        //   不再撞预算. 这条路径留作技术债.
+        const onCompact = async () => {
+            // no-op (best-effort hook for future pi-sdk/pivot history sync)
+        };
+        const result = await loop.execute(input, llm, systemPrompt, this.currentOnStream ?? undefined, this.currentSignal ?? undefined, onCompact);
         this.messageHistory.push({ role: 'user', content: input });
         if (result.response) {
             this.messageHistory.push({ role: 'assistant', content: result.response });
@@ -1614,10 +889,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 / 用户中断)
@@ -1631,14 +908,23 @@ ${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% 阈值时跑一次
             // 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' });
@@ -1651,11 +937,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;
             }
             // 调试日志：显示每次循环开始
@@ -1680,33 +968,33 @@ ${this.getToolDefinitions()}
             }
             // M2.4: persona section 缓存 — persona 在 loadPersona() 时一次设定, 此后不变
             if (!this.cachedPersonaSection && this.persona) {
-                this.cachedPersonaSection = `
-角色描述: ${this.persona.description || '无'}
-性格特点: ${this.persona.personality || '无'}
-问候语: ${this.persona.greeting || '无'}
+                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}
-
-工作模式:
-1. 理解用户自然语言请求
-2. 分析需要哪些工具来完成
-3. 按顺序调用工具并观察结果
-4. 根据观察结果决定下一步
-5. 最终给出完整回答
-
-重要:
-- 每次只调用一个工具
-- 仔细分析工具返回结果
-- 当任务完成时，必须在回答末尾添加 <final gen> 标记表示结束
-- 如果需要更多信息，继续调用工具${this.judgmentGateAddition}`;
+            const systemPrompt = `${this.bootstrapAddition}你是 ${this.identity.name}，基于ReAct (Reasoning + Acting)模式工作。${personaSection}
+当前工作目录: ${this.cwd}
+当前身份: ${this.identity.name} (${this.identity.did})
+${refineContext}
+${this.currentIntentHint}
+
+${toolDefs}
+
+工作模式:
+1. 理解用户自然语言请求
+2. 分析需要哪些工具来完成
+3. 按顺序调用工具并观察结果
+4. 根据观察结果决定下一步
+5. 最终给出完整回答
+
+重要:
+- 每次只调用一个工具
+- 仔细分析工具返回结果
+- 当任务完成时，必须在回答末尾添加 <final gen> 标记表示结束
+- 如果需要更多信息，继续调用工具${this.judgmentGateAddition}${this.contextHintAddition}`;
             // 3 个恢复机制 (Claude Code 论文 9-step pipeline 内部):
             //   1. max output token 升级 (最多 3 次, 每次 maxOutputTokens 翻倍)
             //   2. reactive compaction (prompt 估算超阈值, 跑压缩)
@@ -1714,18 +1002,61 @@ ${toolDefs}
             // 失败静默: 全部重试失败 → 空 reply (上层用 no tool_use 终止)
             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-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 重复犯同样错
+            // 2026-07-06: 对不可恢复的 API 错误直接终止, 不再无限重试
             if (reply.startsWith('[AI 服务调用失败]')) {
-                console.log(`[PiAgent] 收到 AI 错误 sentinel, 标记 aiFailed, 外层会自动重试整个 loop`);
-                aiFailed = true;
+                console.log(`[PiAgent] 收到 AI 错误 sentinel`);
+                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++;
+                // 2026-07-06: 检测不可恢复的 API 错误 — 这些错误 LLM 无法通过反思修复, 重试无意义
+                const isFatalApiError = reply.includes('chat content is empty') ||
+                    reply.includes('invalid params') ||
+                    reply.includes('401') ||
+                    reply.includes('403') ||
+                    reply.includes('quota') ||
+                    reply.includes('rate limit') ||
+                    reply.includes('API key') ||
+                    reply.includes('authentication') ||
+                    reply.includes('unauthorized');
+                if (isFatalApiError) {
+                    console.log(`[PiAgent] 检测到不可恢复的 API 错误, 终止 loop: ${aiFailureReason}`);
+                    if (onStream) {
+                        onStream({ type: 'error', content: `⛔ API 错误无法恢复: ${aiFailureReason}`, tool: 'system' });
+                    }
+                    finalResponse = `❌ AI 服务调用失败: ${aiFailureReason}\n\n这是一个底层 API 错误, 不是任务本身的问题。请检查 API 配置或稍后重试。`;
+                    aiFailed = true;
+                    break;
+                }
+                // 连续错误过多也终止, 防止 LLM 陷入死循环
+                if (consecutiveErrors >= 3) {
+                    console.log(`[PiAgent] 连续 ${consecutiveErrors} 次 AI 错误, 终止 loop`);
+                    if (onStream) {
+                        onStream({ type: 'error', content: `⛔ 连续 ${consecutiveErrors} 次 AI 错误, 终止循环`, tool: 'system' });
+                    }
+                    finalResponse = `❌ AI 连续调用失败 ${consecutiveErrors} 次, 已终止。\n\n失败原因: ${aiFailureReason}\n\n请检查 API 配置或简化任务后重试。`;
+                    aiFailed = true;
+                    break;
+                }
+                // 把错误当成 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}`);
@@ -1733,20 +1064,14 @@ ${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-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,
@@ -1912,7 +1237,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) {
@@ -1944,6 +1269,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) {
@@ -2015,6 +1350,36 @@ ${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
+                    // 检查回复是否包含工具结果内容（避免无限循环）
+                    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 让其继续`);
+                        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(') ||
@@ -2060,12 +1425,12 @@ ${toolDefs}
             onStream({ type: 'status', content: `✅ 处理完成，共 ${iteration - 1} 次循环`, tool: 'system' });
         }
         const now = new Date().toISOString();
-        const identityPrefix = `${this.identity.name} ｜ bolloon 智能体
-<environment_details>
-Current time: ${now}
-Working directory: ${this.cwd}
-Workspace root folder: ${this.cwd}
-</environment_details>
+        const identityPrefix = `${this.identity.name} ｜ bolloon 智能体
+<environment_details>
+Current time: ${now}
+Working directory: ${this.cwd}
+Workspace root folder: ${this.cwd}
+</environment_details>
 `;
         finalResponse = identityPrefix + finalResponse;
         this.messageHistory.push({ role: 'assistant', content: finalResponse });
@@ -2157,18 +1522,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 });
                 }
             }
@@ -2255,7 +1647,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: 不重试, 立即抛
@@ -2381,100 +1774,47 @@ Workspace root folder: ${this.cwd}
         }
     }
     isFinalResponse(content) {
-        // 只有明确输出 <final gen> 才认为是最终回答
-        return content.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) {
-        const patterns = [
-            /调用工具[：:]\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-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 = content.match(pattern);
-            if (match) {
-                const name = match[1];
-                let args = {};
-                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>
-                    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) || this.tools.has(name.replace(/_/g, '_'))) {
-                    return { name, args };
-                }
-            }
-        }
-        return null;
+        // 2026-06-30: 抽到 ./parse-tool-call.ts 作为纯函数 — 这里只构建 ctx 并调用
+        return parseToolCallImpl(content, this._parseCtx());
+    }
+    // [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 表示未识别
+     */
+    /**
+     * 把 LLM 给的工具名 (可能大小写不一, 或者 Claude Code 风格的别名) 解析为
+     * bolloon 注册的标准工具名.
+     *
+     * 2026-06-30: 委托给 ToolRegistry 模块 — alias 表在 tool-registry.ts 统一维护,
+     *   这里只做 thin wrapper 保留 backward compat (private API 但其它地方可能用).
+     */
+    resolveToolName(name) {
+        return this._toolRegistry.resolve(name);
     }
     estimateResponseQuality(response) {
         let score = 0.5;
@@ -2565,37 +1905,37 @@ Workspace root folder: ${this.cwd}
     getDefaultResponse(input) {
         const operationsRef = PiAgentSession.getOperationsReference();
         if (operationsRef) {
-            return `收到了: "${input}"
-
-我是一个判断力处理智能体，支持自然语言交互。
-
-可用操作（直接说出即可）:
-${this.extractOperationsFromRef(operationsRef)}
-
-示例请求:
-  - "读取 src/index.ts 文件"
-  - "总结一下 README.md"
-  - "查看当前连接了哪些节点"
+            return `收到了: "${input}"
+
+我是一个判断力处理智能体，支持自然语言交互。
+
+可用操作（直接说出即可）:
+${this.extractOperationsFromRef(operationsRef)}
+
+示例请求:
+  - "读取 src/index.ts 文件"
+  - "总结一下 README.md"
+  - "查看当前连接了哪些节点"
   - "向 QmABC... 发送测试消息"`;
         }
-        return `收到了: "${input}"
-
-我是一个判断力处理智能体，支持自然语言交互。
-
-可用操作（直接说出即可）:
-  - "读取 README.md" - 读取并分析文档
-  - "总结文档" - 总结文档内容
-  - "改进文档，按照X要求" - 改进文档
-  - "查看节点" - 查看已连接的对等节点
-  - "向X发送消息Y" - 向对等节点发送消息
-  - "广播消息X" - 广播消息到所有节点
-  - "查看身份" - 查看当前智能体身份
-  - "查看日志" - 查看最近操作日志
-
-示例请求:
-  - "读取 src/index.ts 文件"
-  - "总结一下 README.md"
-  - "查看当前连接了哪些节点"
+        return `收到了: "${input}"
+
+我是一个判断力处理智能体，支持自然语言交互。
+
+可用操作（直接说出即可）:
+  - "读取 README.md" - 读取并分析文档
+  - "总结文档" - 总结文档内容
+  - "改进文档，按照X要求" - 改进文档
+  - "查看节点" - 查看已连接的对等节点
+  - "向X发送消息Y" - 向对等节点发送消息
+  - "广播消息X" - 广播消息到所有节点
+  - "查看身份" - 查看当前智能体身份
+  - "查看日志" - 查看最近操作日志
+
+示例请求:
+  - "读取 src/index.ts 文件"
+  - "总结一下 README.md"
+  - "查看当前连接了哪些节点"
   - "向 QmABC... 发送测试消息"`;
     }
     extractOperationsFromRef(ref) {
@@ -2620,13 +1960,13 @@ ${this.extractOperationsFromRef(operationsRef)}
             }
         }
         return operationLines.length > 0 ? operationLines.join('\n') :
-            `  - "读取 README.md" - 读取并分析文档
-  - "总结文档" - 总结文档内容
-  - "改进文档，按照X要求" - 改进文档
-  - "查看节点" - 查看已连接的对等节点
-  - "向X发送消息Y" - 向对等节点发送消息
-  - "广播消息X" - 广播消息到所有节点
-  - "查看身份" - 查看当前智能体身份
+            `  - "读取 README.md" - 读取并分析文档
+  - "总结文档" - 总结文档内容
+  - "改进文档，按照X要求" - 改进文档
+  - "查看节点" - 查看已连接的对等节点
+  - "向X发送消息Y" - 向对等节点发送消息
+  - "广播消息X" - 广播消息到所有节点
+  - "查看身份" - 查看当前智能体身份
   - "查看日志" - 查看最近操作日志`;
     }
     async suggestRename(messages) {
@@ -2955,98 +2295,5 @@ ${this.extractOperationsFromRef(operationsRef)}
         return [...this.operationLog];
     }
 }
-let sessionInstance = null;
-let lastIdentityDid = null;
-// 独立的 session 实例缓存（用于多 session 支持）
-const independentSessions = new Map();
-export async function createAgentSession(config, forceNew) {
-    const incomingDid = config.identityDoc?.did;
-    // 如果有独立的 peerId (包含 :)，使用它作为 key
-    if (config.peerId && config.peerId.includes(':')) {
-        const key = config.peerId;
-        if (!forceNew && independentSessions.has(key)) {
-            console.log(`[createAgentSession] 找到现有独立 session, key=${key}`);
-            return independentSessions.get(key);
-        }
-        const session = new PiAgentSession(config);
-        independentSessions.set(key, session);
-        console.log(`[createAgentSession] 创建独立 session, key=${key}, DID=${incomingDid}`);
-        return session;
-    }
-    // 如果指定了 forceNew 但没有 peerId，生成带时间戳的 key
-    if (forceNew) {
-        const key = `force:${Date.now()}`;
-        const session = new PiAgentSession(config);
-        independentSessions.set(key, session);
-        console.log(`[createAgentSession] 创建强制新 session, key=${key}`);
-        return session;
-    }
-    // 如果有新的 DID，强制重建 session
-    if (sessionInstance && lastIdentityDid && incomingDid && lastIdentityDid !== incomingDid) {
-        console.log(`[createAgentSession] DID 变化 ${lastIdentityDid} -> ${incomingDid}，重建 session`);
-        sessionInstance = null;
-    }
-    if (sessionInstance) {
-        // 检查是否需要更新 identity
-        const currentDid = sessionInstance.getIdentity().did;
-        if (incomingDid && currentDid !== incomingDid) {
-            console.log(`[createAgentSession] 更新 identity: ${currentDid} -> ${incomingDid}`);
-            sessionInstance.updateIdentity({
-                did: incomingDid,
-                name: config.identityDoc?.name || sessionInstance.getIdentity().name,
-                publicKey: config.identityDoc?.publicKey || '',
-                createdAt: Date.now()
-            });
-        }
-        return sessionInstance;
-    }
-    sessionInstance = new PiAgentSession(config);
-    lastIdentityDid = config.identityDoc?.did || null;
-    console.log(`[createAgentSession] 新建 session, DID=${lastIdentityDid}`);
-    return sessionInstance;
-}
-export function getAgentSession() {
-    return sessionInstance;
-}
-export function resetAgentSession() {
-    sessionInstance = null;
-    lastIdentityDid = null;
-}
-/**
- * 自我改进循环: 在沙箱分支上工作, 输出结果给用户审.
- *
- * 不在 PiAgent 实例上的原因: 心跳回调可能没有 agent 实例, 单独函数更易复用.
- *
- * **关键不变量**:
- *   1. AI 不能 push 到 master (shell-guard 黑名单 + git 受保护分支)
- *   2. 改动必须走沙箱分支 (SELF_IMPROVE_BRANCH_PREFIX)
- *   3. 6 小时冷却期 (SELF_IMPROVE_COOLDOWN_MS)
- *   4. 写文件必须经过 shell_exec + 护栏检查
- */
-let lastSelfImproveAt = null;
-export async function runSelfImproveLoop(goal) {
-    const cooldownMs = getCooldownMs();
-    // 1. 冷却期检查
-    if (lastSelfImproveAt && Date.now() - lastSelfImproveAt < cooldownMs) {
-        const waitHrs = Math.ceil((cooldownMs - (Date.now() - lastSelfImproveAt)) / 3600000);
-        return { success: false, error: `自改冷却中, 还需要约 ${waitHrs} 小时` };
-    }
-    // 2. 选源分支 + 新分支名
-    const sourceBranch = 'master';
-    const newBranch = `${getBranchPrefix()}${Date.now()}`;
-    console.log(`[self-improve] 启动自改循环, 目标: ${goal}, 新分支: ${newBranch}`);
-    // 3. 创建分支
-    const r1 = await shellExec('git', ['checkout', sourceBranch]);
-    if (!r1.success)
-        return { success: false, error: `切换到 ${sourceBranch} 失败: ${r1.error}` };
-    const r2 = await shellExec('git', ['checkout', '-b', newBranch]);
-    if (!r2.success)
-        return { success: false, error: `创建分支失败: ${r2.error}` };
-    // 4. 走 task queue: 把"自改"作为一个 task 抛回去, AI 拿到后会用 shell_exec 改
-    //    护栏已经阻止所有禁区改动, 这里只负责登记
-    lastSelfImproveAt = Date.now();
-    return {
-        success: true,
-        output: `✅ 自改分支已创建: ${newBranch}\n目标: ${goal}\n\n**护栏已激活**:\n  - 仅允许白名单命令 (git/npm/tsc/vitest/cat/ls/...)\n  - 禁止改 src/agents/pi-sdk.ts, shell-guard.ts, src/heartbeat/, src/network/, src/pi-ecosystem-judgment/, package.json, .env 等\n  - 6 小时冷却期\n\nAI 接下来会用 shell_exec 工具改源码. 完成后你会在对话里看到 diff 摘要, 手动 git diff master..${newBranch} 审, 满意再 merge.`
-    };
-}
+// createAgentSession / getAgentSession / resetAgentSession / runSelfImproveLoop
+//   已抽到 ./pi-sdk-session-factory.ts (2026-07-06), 从顶部 import 并 re-export