@bolloon/bolloon-agent 0.2.12 → 0.2.14

package/dist/agents/parse-tool-call.js

@@ -0,0 +1,304 @@
+/**
+ * parseToolCall — 从 LLM 输出 (minimax / Hermes / Qwen / GLM / Anthropic 等)
+ * 中提取 tool_call { name, args }.
+ *
+ * 2026-06-30 抽出: 原先作为 PiAgentSession 的 private 方法藏在 4522 行类里,
+ * 测试只能复刻逻辑不能 import 真源 = 测试通过 ≠ 实际工作. 现在抽出为纯函数,
+ * 接受 ctx.tools (可用工具名集合) + 可选 ctx.resolveAlias (别名 → 真实工具名).
+ *
+ * 用法:
+ *   import { parseToolCall } from './parse-tool-call';
+ *   const r = parseToolCall(content, { tools: new Set(['shell_exec', 'read_file']) });
+ *   if (r) tool.execute(r.args);
+ */
+const SHELL_KEYWORDS = ['git', 'npx', 'npm', 'tsx', 'tsc', 'vitest', 'node', 'mkdir', 'touch', 'ls', 'echo', 'cat', 'head', 'tail', 'wc', 'pwd', 'date'];
+/**
+ * 默认的 alias resolver — Claude Code 风格 → bolloon 工具名
+ * 当 ctx.resolveAlias 缺失时使用.
+ */
+function defaultResolveAlias(name, tools) {
+    if (tools.has(name))
+        return name;
+    const lower = name.toLowerCase();
+    const aliasMap = {
+        read: 'read_file',
+        edit: 'edit_file',
+        write: 'write_file',
+        rm: 'delete_file',
+        mv: 'move_file',
+        bash: 'shell_exec',
+        shell: 'shell_exec',
+        sh: 'shell_exec',
+        cat: 'read_file',
+        test: 'vitest_run',
+        vitest: 'vitest_run',
+        typecheck: 'tsc_check',
+        tsc: 'tsc_check',
+        log: 'git_log',
+        show: 'git_show',
+        diff: 'git_diff',
+        commit: 'git_commit',
+        push: 'git_push',
+        branch: 'git_branch',
+        checkout: 'git_branch',
+        stash: 'git_stash',
+        todo_write: 'create_task',
+        todowrite: 'create_task',
+        task: 'create_task',
+    };
+    const aliased = aliasMap[lower];
+    if (aliased && tools.has(aliased))
+        return aliased;
+    if (tools.has(lower))
+        return lower;
+    return null;
+}
+/** 拆分 args.command: "git status" → { command: "git", args: "status" } */
+function autoSplitCommand(args) {
+    if (typeof args.command === 'string' && args.command.includes(' ') && !args.args) {
+        const parts = args.command.split(/\s+/);
+        args.command = parts[0];
+        args.args = parts.slice(1).join(' ');
+    }
+}
+/** 用 resolver 解析工具名 — 接受任意 resolver (默认或自定义). */
+function resolve(ctx, name) {
+    if (ctx.resolveAlias)
+        return ctx.resolveAlias(name);
+    return defaultResolveAlias(name, ctx.tools);
+}
+export function parseToolCall(content, ctx) {
+    if (!content)
+        return null;
+    // === 0. 剥离 思考块 — 必须先做, 否则旧 regex `<(\w+)>...</\1>` 会先匹配 想想标签 ===
+    const strippedContent = content.replace(/<think[\s\S]*?<\/think/g, '');
+    // === 1. JSON function-call (OpenAI / Anthropic / Minimax-style) ===
+    const jsonPatterns = [
+        // markdown json code block + OpenAI  块, 同时匹配 arguments/input 字段
+        /(?:```(?:json|json5)?\s*\n?)?\{[\s\S]*?"name"\s*:\s*["'](\w+)["']\s*,\s*["']?(?:arguments|input)["']?\s*:\s*(\{[\s\S]*?\})\s*\}/,
+    ];
+    for (const p of jsonPatterns) {
+        const m = content.match(p);
+        if (m) {
+            const name = m[1];
+            let args = {};
+            try {
+                const parsed = JSON.parse(m[2]);
+                if (parsed && typeof parsed === 'object') {
+                    args = Object.fromEntries(Object.entries(parsed).map(([k, v]) => [k, String(v)]));
+                }
+            }
+            catch {
+                /* 解析失败保持 args={} */
+            }
+            autoSplitCommand(args);
+            const resolved = resolve(ctx, name);
+            if (resolved) {
+                return { name: resolved, args };
+            }
+        }
+    }
+    // === 2. <tools:call name="X">...</tools:call> 嵌套格式 ===
+    const toolsCallMatch = content.match(/<tools:call\s+name=["'](\w+)["']>([\s\S]*?)<\/tools:call>/);
+    if (toolsCallMatch) {
+        const name = toolsCallMatch[1];
+        const inner = toolsCallMatch[2];
+        const args = {};
+        const argTags = inner.matchAll(/<tools:call\s+name=["'](\w+)["']>([\s\S]*?)<\/tools:call>/g);
+        for (const m of argTags) {
+            args[m[1]] = m[2].trim();
+        }
+        const resolved = resolve(ctx, name);
+        if (resolved) {
+            return { name: resolved, args };
+        }
+        // 兜底: 外层 tool name 不在 tools, 但内层有 command, 推断 shell_exec
+        if (args.command) {
+            const cmdFirst = args.command.split(/\s+/)[0];
+            if (SHELL_KEYWORDS.includes(cmdFirst)) {
+                return { name: 'shell_exec', args };
+            }
+        }
+    }
+    // === 3. XML 格式 (陆续检测多个 pattern) ===
+    const patterns = [
+        // minimax/Hermes 自闭合 XML 格式 <invoke name="X">...</invoke>
+        new RegExp('<invoke\\s+name=["\']([\\w]+)["\']>([\\s\\S]*?)</invoke>'),
+        // <function_calls> 包裹
+        new RegExp('<function_calls>[\\s\\S]*?<invoke\\s+name=["\']([\\w]+)["\']>([\\s\\S]*?)</invoke>[\\s\\S]*?</function_calls>'),
+        // <function_calls><tool name="X"><param name="Y">value</param></tool></function_calls>
+        new RegExp('<function_calls>[\\s\\S]*?<tool\\s+name=["\']([\\w]+)["\']>([\\s\\S]*?)</tool>[\\s\\S]*?</function_calls>'),
+        /调用工具[：:]\s*(\w+)\s*\(([^)]*)\)/,
+        /使用工具[：:]\s*(\w+)\s*\(([^)]*)\)/,
+        /tool[_\w]*[：:]\s*(\w+)\s*\(([^)]*)\)/i,
+        /(\w+)\s*\(\s*([^)]*)\s*\)/,
+        // 对象字面量格式 {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,
+        // "tool_name {json_args}" 形式 (单行, 无 name 字段)
+        /(?:^|\n)(\w+)\s+(\{[\s\S]*?\})(?=\n|$)/,
+        // XML 格式 <tool_name>...<arg>value</arg>...</tool_name>
+        /<(\w+)>([\s\S]*?)<\/\1>/,
+    ];
+    for (const pattern of patterns) {
+        const match = strippedContent.match(pattern);
+        if (!match)
+            continue;
+        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]/.test(rawArgs) && /<\/\w+>/.test(rawArgs)) {
+            // 2026-06-30 修: 检测 XML 子标签 (含带属性的 <parameter name="X"> 形式)
+            //   原文用 /<\w+>[\s\S]*<\/\w+>/ 检测, 但是 <parameter name="command"> 形式
+            //   首标签是 <parameter, 不是简单的 <command 所以原检测会 false,
+            //   路由错误走 key:value 路径. 这里放宽到任何 <...>...content...</...>
+            const paramRe = /<parameter\s+name=["'](\w+)["']>([\s\S]*?)<\/parameter>/g;
+            const paramReShort = /<param\s+name=["'](\w+)["']>([\s\S]*?)<\/param>/g;
+            let pMatch;
+            while ((pMatch = paramRe.exec(rawArgs)) !== null) {
+                const argName = pMatch[1];
+                const argValue = pMatch[2].trim();
+                if (argName && argValue) {
+                    args[argName] = argValue;
+                }
+            }
+            if (Object.keys(args).length === 0) {
+                let sMatch;
+                paramReShort.lastIndex = 0;
+                while ((sMatch = paramReShort.exec(rawArgs)) !== null) {
+                    const argName = sMatch[1];
+                    const argValue = sMatch[2].trim().replace(/^["']|["']$/g, '');
+                    if (argName && argValue) {
+                        args[argName] = argValue;
+                    }
+                }
+            }
+            if (Object.keys(args).length === 0) {
+                const xmlArgPattern = /<(\w+)>([\s\S]*?)<\/\1>/g;
+                let xmlMatch;
+                while ((xmlMatch = xmlArgPattern.exec(rawArgs)) !== null) {
+                    const argName = xmlMatch[1];
+                    const argValue = xmlMatch[2].trim();
+                    if (argName && argValue) {
+                        args[argName] = argValue;
+                    }
+                }
+            }
+        }
+        else if (rawArgs) {
+            // 形参串 key: value
+            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(':') || '';
+            }
+        }
+        // 名字 resolve: 优先 this.tools.has, 然后 alias resolver
+        const resolved = ctx.tools.has(name) ? name : resolve(ctx, name);
+        if (resolved) {
+            autoSplitCommand(args);
+            return { name: resolved, args };
+        }
+        // 名字未识别但 rawArgs 含 <command> 子标签 → 跳出, 走 fallback 按 command 推断 shell_exec
+        if (rawArgs && /<\w+>[\s\S]*<\/\w+>/.test(strippedContent)) {
+            break;
+        }
+    }
+    // === 4. Fallback: 任意 <tag><command>...</command></tag> 按 cmdFirst 推断 shell_exec ===
+    const xmlTagMatch = strippedContent.match(/<(\w+)>([\s\S]*?)<\/\1>/);
+    if (xmlTagMatch) {
+        const outerTag = xmlTagMatch[1];
+        const inner = xmlTagMatch[2];
+        if (!resolve(ctx, outerTag)) {
+            const cmdMatch = inner.match(/<command>([\s\S]*?)<\/command>/);
+            if (cmdMatch) {
+                const cmd = cmdMatch[1].trim();
+                const cmdFirst = cmd.split(/\s+/)[0];
+                if (SHELL_KEYWORDS.includes(cmdFirst)) {
+                    const args = {};
+                    const remaining = cmd.slice(cmdFirst.length).trim();
+                    if (remaining) {
+                        args.command = cmdFirst;
+                        args.args = remaining;
+                    }
+                    else {
+                        args.command = cmd;
+                    }
+                    const argsM = inner.match(/<args>([\s\S]*?)<\/args>/);
+                    if (argsM && argsM[1].trim()) {
+                        args.args = argsM[1].trim();
+                    }
+                    return { name: 'shell_exec', args };
+                }
+            }
+        }
+    }
+    return null;
+}
+/**
+ * isFinalResponse — 临时判断 LLM 是否已完结 (含 <final gen>)
+ * 2026-06-19/06-30 修: 先剥离 think, 避免思考块中提及 <final gen> 误杀
+ *                       含可解析 tool_call 则优先执行工具, 不算 final
+ */
+export function isFinalResponse(content, ctx) {
+    const stripped = content.replace(/<think[\s\S]*?<\/think/g, '');
+    if (!stripped.includes('<final gen>'))
+        return false;
+    // 用默认 ctx (无需 tool 名解析, 只看能否 parse 出来) - 但 isFinalResponse 不需要 tools 列表上下文.
+    // 如果没有传 ctx, 使用 empty set (只解析不 resolve).
+    if (ctx && parseToolCall(stripped, ctx))
+        return false;
+    if (!ctx) {
+        // 试探性 parse (不 resolve name) — 如果至少能提取 name+args 模式, 就不是 final.
+        // 这里粗略检测: stripped 中含 json "name": 或 <invoke name= 或 <function_calls> 任一
+        if (/\{[\s\S]*?"name"\s*:/.test(stripped))
+            return false;
+        if (/<invoke\s+name=/.test(stripped))
+            return false;
+        if (/<function_calls>/.test(stripped))
+            return false;
+    }
+    return true;
+}
+/** extractFinalAnswer: 去除 <final gen> 标记 + tool call 噪声. */
+export function extractFinalAnswer(content) {
+    const marker = '<final gen>';
+    const markerIndex = content.indexOf(marker);
+    if (markerIndex !== -1) {
+        const after = content.substring(markerIndex + marker.length).trim();
+        if (after) {
+            content = after;
+        }
+        else {
+            content = content.substring(0, markerIndex).trim();
+        }
+    }
+    let cleaned = content
+        .replace(/调用工具[：:]\s*\w+\s*\([^)]*\)/g, '')
+        .replace(/使用工具[：:]\s*\w+\s*\([^)]*\)/g, '')
+        .replace(/tool[_\w]*[：:]\s*\w+\s*\([^)]*\)/gi, '')
+        .trim();
+    return cleaned;
+}

package/dist/agents/peer-manifest-loader.js

@@ -0,0 +1,210 @@
+/**
+ * peer-manifest-loader.ts — 智能体相互了解的懒加载触发器
+ *
+ * 设计目的 (2026-07-05):
+ *   远程 P2P 节点的 manifest 不默认进 LLM prompt, 只在需要时拉取.
+ *   3 个触发点:
+ *     ① @-mention 远端 channel    → 立即拉对方 manifest + 对应 agent 详细描述
+ *     ② 本地 agent 连续失败       → 兜底拉对方 manifest (对方可能有解)
+ *     ③ 关键词触发                → 用户说 "持续协助" / "cooperate" 时加载
+ *
+ *   加载结果拼成 prompt 附加块 (≤2000 字符), 拼到 system prompt 尾部.
+ *   不入持久化 prompt, 不污染主对话.
+ */
+import * as fs from 'fs/promises';
+import * as peerFs from '../network/peer-fs.js';
+// ============== 主入口 ==============
+/**
+ * 加载对方的 manifest + (可选) 详细 agent 描述, 拼成 prompt 块.
+ * 行为:
+ *   1) 先看本地 ~/.bolloon/peers/<pk>/capability-index.md 缓存 — 命中且新 (≤1h) → 直接用
+ *   2) 否则调 RPC 拉 manifest → 落盘 → 读 capability-index.md
+ *   3) 如果 triggerValue 是 agent id 或 capability 名, 再发 RPC 拉详细描述
+ */
+export async function loadPeerManifest(ctx, opts) {
+    const t0 = Date.now();
+    const pk = ctx.remotePublicKey;
+    if (!pk || pk === opts.p2p.getPublicKey())
+        return null; // 自己
+    let rpcTriggered = false;
+    let idx = await peerFs.readPeerIndex(pk);
+    let capabilityIndex = await peerFs.readCapabilityIndex(pk);
+    // 缓存判断: capability-index 存在 + 索引在 TTL 内 → 跳过 RPC
+    const ttl = opts.cacheTtlMs ?? 60 * 60 * 1000;
+    if (!idx || !capabilityIndex || (idx.updatedAt && (Date.now() - new Date(idx.updatedAt).getTime()) > ttl)) {
+        // 缓存过期或不完整, 发 RPC 拉新
+        const since = idx?.manifestTs || 0;
+        const req = JSON.stringify({
+            v: 3, op: 'agent.manifest.exchange',
+            payload: { since, fromPublicKey: opts.p2p.getPublicKey() }
+        });
+        const r = await opts.p2p.sendToWithWait(pk, req, 3000);
+        if (r === 'SENT') {
+            rpcTriggered = true;
+            // 等异步处理落盘 — 这里 sleep 短时间, 不阻塞主线程太久
+            await new Promise(r => setTimeout(r, 500));
+            idx = await peerFs.readPeerIndex(pk);
+            capabilityIndex = await peerFs.readCapabilityIndex(pk);
+        }
+    }
+    if (!idx) {
+        return {
+            publicKey: pk,
+            capabilityIndex: '',
+            promptBlock: `[远端 peer ${pk.slice(0, 12)}…] 暂无 manifest 缓存 (对方未响应或本地首次连接).`,
+            agentDescriptions: [],
+            rpcTriggered,
+            durationMs: Date.now() - t0,
+        };
+    }
+    // 按 triggerValue 决定要不要拉详细 agent 描述
+    const agentDescriptions = [];
+    const lowerVal = ctx.triggerValue.toLowerCase();
+    // 1) 如果 triggerValue 看起来是 agent id (有特殊前缀/格式) → 直接拉
+    // 2) 如果是 capability 名 (编程/翻译/...) → 在 idx 里找匹配 capability 的 agent → 拉
+    const candidates = [];
+    if (ctx.triggerValue.match(/^(agent_|agt_|bot_|assist_|task_)/)) {
+        candidates.push(ctx.triggerValue);
+    }
+    else {
+        for (const a of idx.agents) {
+            if (a.capabilities.some(c => c.toLowerCase().includes(lowerVal))) {
+                candidates.push(a.id);
+            }
+        }
+    }
+    // 拉详细描述 (限 3 个, 避免 prompt 爆炸)
+    for (const agentId of candidates.slice(0, 3)) {
+        const localFile = peerFs.getPeerAgentMdPath(pk, agentId);
+        let body = '';
+        try {
+            body = await fs.readFile(localFile, 'utf-8');
+        }
+        catch { }
+        if (!body) {
+            // 本地没缓存, 拉 RPC
+            const req = JSON.stringify({
+                v: 3, op: 'agent.resource.get',
+                payload: { agentId, fromPublicKey: opts.p2p.getPublicKey() }
+            });
+            const r = await opts.p2p.sendToWithWait(pk, req, 3000);
+            if (r === 'SENT') {
+                rpcTriggered = true;
+                // 异步处理, 等 300ms
+                await new Promise(r => setTimeout(r, 300));
+                try {
+                    body = await fs.readFile(localFile, 'utf-8');
+                }
+                catch { }
+            }
+        }
+        if (body)
+            agentDescriptions.push({ agentId, body: body.slice(0, 1500) });
+    }
+    // 拼 prompt 附加块
+    const block = buildPromptBlock(ctx, capabilityIndex || '(无索引)', agentDescriptions, idx);
+    return {
+        publicKey: pk,
+        capabilityIndex: capabilityIndex || '',
+        promptBlock: block,
+        agentDescriptions,
+        rpcTriggered,
+        durationMs: Date.now() - t0,
+    };
+}
+/**
+ * 把加载结果拼成可注入 system prompt 的文本块 (≤2000 字)
+ */
+function buildPromptBlock(ctx, capabilityIndex, agentDescriptions, idx) {
+    const lines = [];
+    lines.push(`[远端 peer 临时上下文] ${ctx.reason} → ${ctx.triggerValue}`);
+    lines.push(`远端节点: ${idx.ownerName || idx.publicKey.slice(0, 12)}… (${idx.agents.length} agents)`);
+    lines.push('');
+    lines.push('## 对方能力索引');
+    lines.push(capabilityIndex);
+    lines.push('');
+    if (agentDescriptions.length > 0) {
+        lines.push('## 触发相关的 agent 详细描述');
+        for (const a of agentDescriptions) {
+            lines.push(`### ${a.agentId}`);
+            lines.push(a.body);
+            lines.push('');
+        }
+    }
+    const text = lines.join('\n').trim();
+    return text.length > 2000 ? text.slice(0, 1997) + '…' : text;
+}
+/**
+ * 检测 /message 处理后是否需要加载远端 peer manifest.
+ * 输入:
+ *   - text (用户原始输入)
+ *   - channelId (当前 channel)
+ *   - remoteChannels (远端 channel 列表 [{ id, name, _ownerPublicKey }])
+ *   - consecutiveFailures (连续 LLM 失败次数, 可选)
+ */
+export function detectLoadTrigger(opts) {
+    // 触发 ①: @-mention 远端 channel
+    const mentionRe = /@([一-龥A-Za-z0-9_\-]{1,30})/g;
+    for (const m of opts.text.matchAll(mentionRe)) {
+        const name = m[1];
+        const rc = opts.remoteChannels.find(c => c.name === name);
+        if (rc && rc._ownerPublicKey) {
+            return {
+                shouldLoad: true,
+                reason: 'mention-remote',
+                remotePublicKey: rc._ownerPublicKey,
+                triggerValue: name,
+            };
+        }
+    }
+    // 触发 ③: 关键词
+    const text = opts.text.toLowerCase();
+    const keywords = ['持续协助', '一起合作', 'cooperate', '协作', '对方能干', 'remote help', 'find peer'];
+    for (const k of keywords) {
+        if (text.includes(k.toLowerCase())) {
+            // 关键词触发 — 用第一个 known remote channel 的 owner
+            if (opts.remoteChannels.length > 0 && opts.remoteChannels[0]._ownerPublicKey) {
+                return {
+                    shouldLoad: true,
+                    reason: 'cooperate-keyword',
+                    remotePublicKey: opts.remoteChannels[0]._ownerPublicKey,
+                    triggerValue: k,
+                };
+            }
+        }
+    }
+    // 触发 ②: 连续失败 (3+ 次)
+    const fails = opts.consecutiveFailures || 0;
+    if (fails >= 3) {
+        // 用最近一次 @ 的远端 channel; 没有则取 remoteChannels[0]
+        const lastMention = [...opts.text.matchAll(mentionRe)].pop();
+        let rc = opts.remoteChannels[0];
+        if (lastMention) {
+            const found = opts.remoteChannels.find(c => c.name === lastMention[1]);
+            if (found)
+                rc = found;
+        }
+        if (rc && rc._ownerPublicKey) {
+            return {
+                shouldLoad: true,
+                reason: 'consecutive-failure',
+                remotePublicKey: rc._ownerPublicKey,
+                triggerValue: rc.name,
+            };
+        }
+    }
+    return { shouldLoad: false };
+}
+// ============== 失败计数器 (内存) ==============
+const failureCounters = new Map();
+export function recordFailure(channelId) {
+    const cur = (failureCounters.get(channelId) || 0) + 1;
+    failureCounters.set(channelId, cur);
+    return cur;
+}
+export function clearFailure(channelId) {
+    failureCounters.delete(channelId);
+}
+export function getFailures(channelId) {
+    return failureCounters.get(channelId) || 0;
+}

package/dist/agents/pi-sdk-session-factory.js

@@ -0,0 +1,110 @@
+import { shellExec } from './shell-tool.js';
+import { getBranchPrefix, getCooldownMs } from './shell-guard.js';
+/**
+ * Session factory + runSelfImproveLoop.
+ *
+ * 从 pi-sdk.ts 抽出 (2026-07-06):
+ *   - createAgentSession(config, forceNew?)
+ *   - getAgentSession()
+ *   - resetAgentSession()
+ *   - runSelfImproveLoop(goal)
+ *
+ * 三个状态变量 (module-level):
+ *   - sessionInstance: 单例 cache
+ *   - lastIdentityDid: DID 变化检测
+ *   - independentSessions: 多 session 缓存 (peerId 含 : 的场景)
+ *   - lastSelfImproveAt: 自改冷却期
+ */
+import { PiAgentSession } from './pi-sdk.js';
+let sessionInstance = null;
+let lastIdentityDid = null;
+const independentSessions = new Map();
+export async function createAgentSession(config, forceNew) {
+    const incomingDid = config.identityDoc?.did;
+    if (config.peerId && config.peerId.includes(':')) {
+        const key = config.peerId;
+        if (!forceNew && independentSessions.has(key)) {
+            console.log(`[createAgentSession] 找到现有独立 session, key=${key}`);
+            const existing = independentSessions.get(key);
+            await existing.whenReady();
+            return existing;
+        }
+        const session = new PiAgentSession(config);
+        independentSessions.set(key, session);
+        console.log(`[createAgentSession] 创建独立 session, key=${key}, DID=${incomingDid}`);
+        await session.whenReady();
+        return session;
+    }
+    if (forceNew) {
+        const key = `force:${Date.now()}`;
+        const session = new PiAgentSession(config);
+        independentSessions.set(key, session);
+        console.log(`[createAgentSession] 创建强制新 session, key=${key}`);
+        await session.whenReady();
+        return session;
+    }
+    if (sessionInstance && lastIdentityDid && incomingDid && lastIdentityDid !== incomingDid) {
+        console.log(`[createAgentSession] DID 变化 ${lastIdentityDid} -> ${incomingDid}，重建 session`);
+        sessionInstance = null;
+    }
+    if (sessionInstance) {
+        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()
+            });
+        }
+        await sessionInstance.whenReady();
+        return sessionInstance;
+    }
+    const newSession = new PiAgentSession(config);
+    sessionInstance = newSession;
+    lastIdentityDid = config.identityDoc?.did || null;
+    console.log(`[createAgentSession] 新建 session, DID=${lastIdentityDid}`);
+    await newSession.whenReady();
+    return newSession;
+}
+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();
+    if (lastSelfImproveAt && Date.now() - lastSelfImproveAt < cooldownMs) {
+        const waitHrs = Math.ceil((cooldownMs - (Date.now() - lastSelfImproveAt)) / 3600000);
+        return { success: false, error: `自改冷却中, 还需要约 ${waitHrs} 小时` };
+    }
+    const sourceBranch = 'master';
+    const newBranch = `${getBranchPrefix()}${Date.now()}`;
+    console.log(`[self-improve] 启动自改循环, 目标: ${goal}, 新分支: ${newBranch}`);
+    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}` };
+    lastSelfImproveAt = Date.now();
+    return {
+        success: true,
+        output: `✅ 自改分支已创建: ${newBranch}\n目标: ${goal}\n\n**护栏已激活**:\n  - 仅允许白名单命令\n  - 6 小时冷却期\n\nAI 接下来会用 shell_exec 工具改源码. 完成后你会在对话里看到 diff 摘要, 手动 git diff master..${newBranch} 审, 满意再 merge.`
+    };
+}