@bolloon/bolloon-agent 0.4.9 → 0.4.11

package/dist/agents/pi-sdk-tools.js

@@ -34,6 +34,84 @@ export const SIDE_EFFECT_TOOLS = new Set([
     'write_file', 'edit_file', 'shell_exec', 'git_commit', 'git_push', 'git_branch',
     'create_task', 'update_task', 'terminal', 'process',
 ]);
+/** 2026-08-12 (TaskA): 探测可用的命令 (跨平台: Windows 无 python3, 有 python). 返回 [cmd, ...] 或 null. */
+async function detectRunner(candidates) {
+    const { spawn } = await import('child_process');
+    for (const c of candidates) {
+        try {
+            const ok = await new Promise((resolve) => {
+                const p = spawn(c, ['--version'], { stdio: 'ignore', windowsHide: true });
+                p.on('close', (code) => resolve(code === 0));
+                p.on('error', () => resolve(false));
+            });
+            if (ok)
+                return [c];
+        }
+        catch { /* 下一个 */ }
+    }
+    return null;
+}
+export async function runCodeSnippet(opts) {
+    const code = String(opts.code ?? '').trim();
+    if (!code)
+        return { success: false, error: 'code 必填' };
+    const lang = String(opts.language || '').trim().toLowerCase();
+    // 语言 → (扩展名, 解释器命令)
+    const ext = lang === 'python' || lang === 'py' ? 'py'
+        : lang === 'javascript' || lang === 'js' || lang === 'node' ? 'js'
+            : lang === 'typescript' || lang === 'ts' ? 'ts'
+                : lang === 'shell' || lang === 'bash' || lang === 'sh' ? 'sh'
+                    : lang === 'html' ? 'html'
+                        : 'txt';
+    const runner = lang === 'python' || lang === 'py' ? await detectRunner(['python3', 'python'])
+        : lang === 'javascript' || lang === 'js' || lang === 'node' ? await detectRunner(['node'])
+            : lang === 'typescript' || lang === 'ts' ? ['npx', 'tsx']
+                : lang === 'shell' || lang === 'bash' || lang === 'sh' ? ['bash']
+                    : null;
+    if (!runner) {
+        if (['python', 'py', 'js', 'javascript', 'node', 'ts', 'typescript', 'shell', 'bash', 'sh'].includes(lang)) {
+            return { success: false, error: `解释器未找到 (${lang}), 请装对应运行时或改用 command` };
+        }
+        return { success: false, error: `不支持的语言 '${lang}', 支持: python/js/ts/shell/html` };
+    }
+    const { tmpdir } = await import('os');
+    const tmpDir = opts.tmpDir ?? tmpdir();
+    const file = `${tmpDir}/bolloon-code-${Date.now()}-${Math.random().toString(36).slice(2, 8)}.${ext}`;
+    const fsMod = await import('fs/promises');
+    await fsMod.writeFile(file, code, 'utf-8');
+    try {
+        const { spawn } = await import('child_process');
+        const timeoutMs = opts.timeoutMs ?? 30000;
+        const result = await new Promise((resolve) => {
+            const proc = spawn(runner[0], [...runner.slice(1), file], {
+                cwd: opts.cwd ?? process.cwd(),
+                env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+                windowsHide: true,
+            });
+            let stdout = '';
+            let stderr = '';
+            const timer = setTimeout(() => {
+                try {
+                    proc.kill('SIGKILL');
+                }
+                catch { /* 忽略 */ }
+                resolve({ success: false, error: `代码执行超时 (>${timeoutMs}ms)`, output: (stdout + (stderr ? `\n[stderr]\n${stderr}` : '')).trim().slice(0, 8000) });
+            }, timeoutMs);
+            proc.stdout.on('data', (d) => { stdout += d.toString(); });
+            proc.stderr.on('data', (d) => { stderr += d.toString(); });
+            proc.on('error', (e) => { clearTimeout(timer); resolve({ success: false, error: `启动失败: ${e.message}` }); });
+            proc.on('close', (code) => {
+                clearTimeout(timer);
+                const output = (stdout + (stderr ? `\n[stderr]\n${stderr}` : '')).trim().slice(0, 8000) || '(无输出)';
+                resolve({ success: code === 0, output, exitCode: code, language: lang, script: file });
+            });
+        });
+        return result;
+    }
+    finally {
+        await fsMod.rm(file, { force: true }).catch(() => { });
+    }
+}
 export async function runTerminalCommand(raw, opts = {}) {
     const { checkTerminalCommand } = await import('./shell-guard.js');
     const timeoutMs = opts.timeoutMs ?? 30000;
@@ -716,14 +794,20 @@ export function registerBuiltinTools(ctx) {
     //   与 shell_exec 的区别: 直接接受完整 shell 命令字符串, 更适合模型自主写命令.
     ctx.tools.set('terminal', {
         name: 'terminal',
-        description: '执行完整 shell 命令 (支持管道/重定向/写文件/跑脚本). 护栏只挡高危破坏操作 (sudo/格式化/rm -rf 根目录/写 ~/.bolloon 数据), 其余灵活放行. 适合: 写 HTML 文件、跑 python/node 脚本、查系统状态、装依赖. 多条命令用 commands 数组并行执行. 长命令 (服务器/构建/后台任务) 设 background=true 后台执行不阻塞对话.',
-        parameters: { command: '完整 shell 命令 (必填, 如: echo "<html>" > /tmp/site/index.html && ls /tmp/site)', commands: '可选: 多条命令数组 (并行执行), 每条独立字符串', timeoutMs: '超时毫秒, 默认 30000', background: '可选: true 后台执行, 立即返回 session_id (用 process 工具 poll/wait/kill)' },
+        description: '执行完整 shell 命令 (支持管道/重定向/写文件/跑脚本). 护栏只挡高危破坏操作 (sudo/格式化/rm -rf 根目录/写 ~/.bolloon 数据), 其余灵活放行. 适合: 写 HTML 文件、跑 python/node 脚本、查系统状态、装依赖. 多条命令用 commands 数组并行执行. 长命令 (服务器/构建/后台任务) 设 background=true 后台执行不阻塞对话. 也可直接传 code+language 自动写脚本执行 (便捷代码运行: python/js/ts/shell/html).',
+        parameters: { command: '完整 shell 命令 (可选, 如: echo "<html>" > /tmp/site/index.html && ls /tmp/site)', commands: '可选: 多条命令数组 (并行执行), 每条独立字符串', code: '可选: 一段代码, 传 code+language 时自动写脚本执行 (便捷代码运行)', language: '可选: code 的语言 (python/js/ts/shell/html), 默认自动', timeoutMs: '超时毫秒, 默认 30000', background: '可选: true 后台执行, 立即返回 session_id (用 process 工具 poll/wait/kill)' },
         execute: async (args) => {
+            const timeoutMs = Number(args.timeoutMs) || 30000;
+            // 便捷代码运行: 传 code → 自动写脚本执行
+            const code = String(args.code ?? '').trim();
+            if (code) {
+                const lang = String(args.language || '').trim().toLowerCase();
+                return await runCodeSnippet({ code, language: lang, timeoutMs, cwd: ctx.cwd });
+            }
             const raw = String(args.command || '').trim();
             const commands = Array.isArray(args.commands) ? args.commands.map((c) => String(c || '').trim()).filter(Boolean) : [];
             if (!raw && commands.length === 0)
-                return { success: false, error: 'command 或 commands 必填' };
-            const timeoutMs = Number(args.timeoutMs) || 30000;
+                return { success: false, error: 'command/code/commands 至少一个必填' };
             return await runTerminalCommand(raw, { timeoutMs, cwd: ctx.cwd, commands: commands.length > 0 ? commands : undefined, background: String(args.background).toLowerCase() === 'true' });
         }
     });
@@ -2131,6 +2215,53 @@ export function registerBuiltinTools(ctx) {
             }
         }
     });
+    // 2026-08-12: MCP 驱动前端 UI 工具 — agent 理解用户意图后调用, 通过 SSE 广播驱动前端组件.
+    //   复用 ui-tools (dispatchUiAction → broadcast {type:'ui'}), 前端订阅 /events 执行.
+    const registerUiAgentTools = async () => {
+        const ui = await import('../pi-ecosystem-mcp/ui-tools.js');
+        // 注册到 MCP 系统 (供 mcp_list_tools 可见) + 注册为 agent 工具
+        ui.registerUiControlTools();
+        const uiTools = [
+            { name: 'ui_switch_tab', description: '驱动前端切换底部 tab (微信/通讯录/发现/我). 用户想"去通讯录/去设置/去我的"时调用.', params: { tab: 'wechat|contacts|discover|me (必填)' }, map: (a) => ({ action: 'switchTab', data: { tab: String(a.tab || '') } }) },
+            { name: 'ui_open_chat', description: '驱动前端打开某个智能体聊天页. 用户想"打开和 X 的聊天"时调用.', params: { channelId: '目标 channel id (必填)' }, map: (a) => ({ action: 'openChat', data: { channelId: String(a.channelId || '') } }) },
+            { name: 'ui_open_settings', description: '驱动前端打开设置页.', params: {}, map: () => ({ action: 'openSettings', data: {} }) },
+            { name: 'ui_open_wallet', description: '驱动前端打开钱包.', params: {}, map: () => ({ action: 'openWallet', data: {} }) },
+            { name: 'ui_open_add_friend', description: '驱动前端打开添加好友.', params: {}, map: () => ({ action: 'openAddFriend', data: {} }) },
+            { name: 'ui_show_toast', description: '驱动前端顶部显示提示 (toast).', params: { message: '提示内容 (必填)' }, map: (a) => ({ action: 'showToast', data: { message: String(a.message || '') } }) },
+            { name: 'ui_go_back', description: '驱动前端返回上一页.', params: {}, map: () => ({ action: 'goBack', data: {} }) },
+        ];
+        for (const t of uiTools) {
+            ctx.tools.set(t.name, {
+                name: t.name,
+                description: t.description,
+                parameters: t.params,
+                execute: async (args) => {
+                    const r = ui.dispatchUiAction(t.map(args));
+                    return r.success ? { success: true, output: r.output } : { success: false, error: r.output };
+                },
+            });
+        }
+    };
+    registerUiAgentTools().catch(() => { });
+    // 2026-08-12: A2UI (Agent to UI) 工具 — agent 生成 A2UI 消息 (createSurface/updateComponents),
+    //   经 SSE 广播, 前端用 @a2ui/react renderer 渲染. 见 src/pi-ecosystem-a2ui/.
+    (async () => {
+        try {
+            const a2ui = await import('../pi-ecosystem-a2ui/index.js');
+            for (const t of a2ui.A2UI_TOOL_DEFS) {
+                ctx.tools.set(t.name, {
+                    name: t.name,
+                    description: t.description,
+                    parameters: t.params,
+                    execute: async (args) => {
+                        const r = a2ui.dispatchA2uiMessage(t.build(args));
+                        return r.success ? { success: true, output: r.output } : { success: false, error: r.output };
+                    },
+                });
+            }
+        }
+        catch { /* A2UI 工具注册失败静默 */ }
+    })();
     // ============================================================
     // publish_did (2026-08-03) — 把当前 agent 的 DID 发布到 IPFS + IPNS
     // 全自动: 自动安装/启动本地 Kubo → 上传 DID 文档 → 发布 IPNS name

package/dist/agents/python-exec.js

@@ -0,0 +1,115 @@
+/**
+ * python-exec.ts — Python 代码执行引擎 (2026-08-12, TaskP)
+ *
+ * 借鉴 hermes code_execution_tool: 让 agent 输入 Python 代码运行操作, 而非逐条 shell 命令.
+ * 设计:
+ *   - 把 LLM 给的 Python 代码写到临时文件, 用 python3 子进程执行 (隔离, 不污染主进程)
+ *   - 带超时 + kill (子进程跑太久强制终止)
+ *   - stdout/stderr 合并捕获 + 截断 (head+tail, 显式 truncation 标记 — hermes 模式)
+ *   - 依赖检测: 找不到 python3 返回明确错误
+ *
+ * 安全: 不 eval (子进程隔离); 代码里若含高危 shell (os.system("rm -rf /") 等) 走 checkTerminalCommand 预检 (最佳努力).
+ */
+import { spawn } from 'child_process';
+import * as fs from 'fs/promises';
+import * as os from 'os';
+import * as path from 'path';
+const MAX_OUTPUT = 16000; // 捕获输出上限 (head+tail)
+/** 探测可用的 python 解释器 (python3 / python) */
+async function detectPython() {
+    const candidates = process.platform === 'win32' ? ['python', 'py'] : ['python3', 'python'];
+    for (const c of candidates) {
+        try {
+            await new Promise((resolve, reject) => {
+                const p = spawn(c, ['--version'], { stdio: 'ignore', windowsHide: true });
+                p.on('close', (code) => (code === 0 ? resolve() : reject(new Error('exit ' + code))));
+                p.on('error', reject);
+            });
+            return c;
+        }
+        catch { /* 下一个 */ }
+    }
+    return null;
+}
+/**
+ * 截断输出: 保留 head + tail, 中间省略, 返回截断标记 (hermes 模式).
+ */
+export function truncateOutput(text) {
+    if (text.length <= MAX_OUTPUT)
+        return { text, truncated: false };
+    const head = text.slice(0, 4000);
+    const tail = text.slice(-4000);
+    return { text: `${head}\n…[输出截断 ${text.length - 8000} 字节]…\n${tail}`, truncated: true };
+}
+/** 最佳努力: 代码里明显的高危 shell 调用预检 (防 os.system("rm -rf /") 等) */
+function checkDangerousCode(code) {
+    const dangerous = [
+        { re: /os\.system\s*\(\s*["']\s*rm\s+(-[a-z]*f[a-z]*\s+)?-[a-z]*r[a-z]*\s+\//, reason: '禁止递归删除根目录' },
+        { re: /shutil\.rmtree\s*\(\s*["']\s*\//, reason: '禁止删除根目录' },
+        { re: /os\.system\s*\(\s*["']\s*(sudo|mkfs|dd\s+if=.*of=\/dev)/, reason: '禁止高危系统命令' },
+    ];
+    for (const { re, reason } of dangerous) {
+        if (re.test(code))
+            return { allowed: false, reason };
+    }
+    return { allowed: true };
+}
+/**
+ * 执行一段 Python 代码 (隔离子进程 + 超时 + 输出截断).
+ */
+export async function executePython(opts) {
+    const code = String(opts.code ?? '').trim();
+    if (!code)
+        return { success: false, error: 'code 必填', output: '' };
+    // 高危代码预检 (最佳努力)
+    const d = checkDangerousCode(code);
+    if (!d.allowed)
+        return { success: false, error: `[python-guard] ${d.reason}`, deniedByGuard: true, output: '' };
+    // 探测 python
+    const python = await detectPython();
+    if (!python) {
+        return { success: false, error: '未找到 python3/python 解释器, 无法执行 Python 代码', output: '' };
+    }
+    // 写临时文件
+    const tmpFile = path.join(os.tmpdir(), `bolloon-py-${Date.now()}-${Math.random().toString(36).slice(2, 8)}.py`);
+    await fs.writeFile(tmpFile, code, 'utf-8');
+    const timeoutMs = opts.timeoutMs ?? 30000;
+    try {
+        const result = await new Promise((resolve) => {
+            const proc = spawn(python, [tmpFile], {
+                cwd: opts.cwd ?? process.cwd(),
+                env: { ...process.env, GIT_TERMINAL_PROMPT: '0', PYTHONIOENCODING: 'utf-8' },
+                windowsHide: true,
+            });
+            let stdout = '';
+            let stderr = '';
+            const timer = setTimeout(() => {
+                try {
+                    proc.kill('SIGKILL');
+                }
+                catch { /* 忽略 */ }
+                resolve({ success: false, output: '', error: `Python 执行超时 (>${timeoutMs}ms), 已终止`, exitCode: -1, python });
+            }, timeoutMs);
+            proc.stdout.on('data', (d) => { stdout += d.toString(); });
+            proc.stderr.on('data', (d) => { stderr += d.toString(); });
+            proc.on('error', (e) => { clearTimeout(timer); resolve({ success: false, output: '', error: `启动失败: ${e.message}`, python }); });
+            proc.on('close', (code) => {
+                clearTimeout(timer);
+                const raw = (stdout + (stderr ? `\n[stderr]\n${stderr}` : '')).trim();
+                const { text, truncated } = truncateOutput(raw || '(无输出)');
+                resolve({
+                    success: code === 0,
+                    output: text,
+                    stdoutTruncated: truncated,
+                    exitCode: code,
+                    error: code === 0 ? undefined : `exit code ${code}`,
+                    python,
+                });
+            });
+        });
+        return result;
+    }
+    finally {
+        await fs.rm(tmpFile, { force: true }).catch(() => { });
+    }
+}

package/dist/pi-ecosystem-a2ui/index.js

@@ -0,0 +1,81 @@
+/**
+ * a2ui.ts — A2UI (Agent to UI) 协议集成 (2026-08-12)
+ *
+ * bolloon agent 生成 A2UI 消息 (createSurface / updateComponents / updateDataModel / deleteSurface),
+ * 经 SSE 广播给前端 (web / 手机端 Capacitor), 前端用 @a2ui/react renderer 渲染.
+ *
+ * 参考: https://a2ui.org/specification/v1.0-a2ui/ + D:\AI\A2UI (本地 spec 源码)
+ *
+ * 机制:
+ *   - agent 工具 (a2ui_create_surface 等) 生成 A2UI JSON 消息
+ *   - dispatchA2uiMessage → broadcast({ type: 'a2ui', message }) 给前端
+ *   - 前端 MessageProcessor 接收渲染 (A2uiSurface)
+ */
+/** broadcast 注入点 (server 调用 setA2uiBroadcast 注入, 关联 SSE /events) */
+let a2uiBroadcast = null;
+export function setA2uiBroadcast(fn) {
+    a2uiBroadcast = fn;
+}
+/** 广播一条 A2UI 消息给所有前端 */
+export function broadcastA2uiMessage(message) {
+    if (!a2uiBroadcast)
+        return false;
+    a2uiBroadcast({ type: 'a2ui', message });
+    return true;
+}
+/** 校验 + 广播一条 A2UI 消息 (agent 工具 execute 调用) */
+export function dispatchA2uiMessage(message) {
+    const type = message?.type;
+    const surfaceId = String(message?.surfaceId || '').trim();
+    if (!type || !['createSurface', 'updateComponents', 'updateDataModel', 'deleteSurface'].includes(type)) {
+        return { success: false, output: 'type 必须是 createSurface/updateComponents/updateDataModel/deleteSurface' };
+    }
+    if (!surfaceId)
+        return { success: false, output: 'surfaceId 必填' };
+    const ok = broadcastA2uiMessage({ type, surfaceId, ...message });
+    return { success: ok, output: ok ? `已广播 A2UI ${type} (surface=${surfaceId})` : 'A2UI 广播未连接' };
+}
+/**
+ * agent 工具注册表 (a2ui-* 工具定义). 由 pi-sdk-tools 注册为 agent 工具.
+ */
+export const A2UI_TOOL_DEFS = [
+    {
+        name: 'a2ui_create_surface',
+        description: '创建 A2UI surface (前端渲染区). surfaceId: 渲染区标识. 用户想要一个动态 UI 面板/表单/卡片时先创建 surface.',
+        params: { surfaceId: '渲染区 id (必填)', title: 'surface 标题 (可选)' },
+        build: (a) => ({ type: 'createSurface', surfaceId: String(a.surfaceId || ''), title: String(a.title || '') }),
+    },
+    {
+        name: 'a2ui_update_components',
+        description: '向 A2UI surface 添加/更新组件 (componentTree JSON). 前端用 @a2ui/react 渲染. components: 组件树 JSON 数组 (Text/Column/Button 等 basicCatalog 组件).',
+        params: { surfaceId: '渲染区 id (必填)', components: '组件树 JSON (必填, e.g. [{"type":"text","data":{"text":"你好"}}])' },
+        build: (a) => {
+            let components = a.components;
+            if (typeof components === 'string') {
+                try {
+                    components = JSON.parse(components);
+                }
+                catch {
+                    components = [];
+                }
+            }
+            return { type: 'updateComponents', surfaceId: String(a.surfaceId || ''), components };
+        },
+    },
+    {
+        name: 'a2ui_update_data',
+        description: '更新 A2UI surface 的数据模型. path: 数据路径 (如 /user/name), value: 数据值.',
+        params: { surfaceId: '渲染区 id (必填)', path: '数据路径 (必填)', value: '数据值' },
+        build: (a) => ({ type: 'updateDataModel', surfaceId: String(a.surfaceId || ''), path: String(a.path || ''), value: a.value }),
+    },
+    {
+        name: 'a2ui_delete_surface',
+        description: '删除 A2UI surface (移除前端渲染区). surfaceId: 渲染区 id.',
+        params: { surfaceId: '渲染区 id (必填)' },
+        build: (a) => ({ type: 'deleteSurface', surfaceId: String(a.surfaceId || '') }),
+    },
+];
+/** 工具名 → build 函数 */
+export function a2uiToolDef(name) {
+    return A2UI_TOOL_DEFS.find((t) => t.name === name);
+}

package/dist/pi-ecosystem-mcp/ui-tools.js

@@ -0,0 +1,108 @@
+/**
+ * ui-tools.ts — MCP 驱动的前端 UI 控制工具 (2026-08-12)
+ *
+ * 目标: bolloon 作为 MCP server 暴露 UI 控制工具, agent 理解用户意图后
+ * 通过 MCP 调用这些工具, 驱动前端 (web / 手机端 Capacitor) 的 UI 组件.
+ *
+ * 机制:
+ *   - 注册一组 UI 控制工具到 MCP 系统 (registerTool), 供 agent 用 mcp_tool 调用
+ *   - 工具 execute 时通过注入的 broadcast 回调, 广播 { type: 'ui', action, data } 给前端 (SSE /events)
+ *   - 前端订阅 /events, 收到 ui 指令执行对应组件 (switchTab/openChat/openSettings 等)
+ *
+ * 设计: UI 工具不走外部 MCP server (executeTool 硬依赖 server), 而是本地 handler + broadcast.
+ */
+import { registerTool, listTools } from './index.js';
+/** broadcast 注入点 (由 server 调用 setUiBroadcast 注入, 广播给前端 SSE) */
+let uiBroadcast = null;
+/** 注入广播函数 (server 启动时调用, 关联到 SSE /events) */
+export function setUiBroadcast(fn) {
+    uiBroadcast = fn;
+}
+/** 广播一条 UI 控制指令给所有前端 */
+export function broadcastUiAction(action, data) {
+    if (!uiBroadcast)
+        return false;
+    uiBroadcast({ type: 'ui', action, data: data ?? {} });
+    return true;
+}
+/** 把一次 UI 工具调用 (agent 意图理解后发起) 广播给前端 */
+export function dispatchUiAction(call) {
+    const { action, data } = call || {};
+    if (!action)
+        return { success: false, output: 'action 必填 (switchTab/openChat/openSettings 等)' };
+    const ok = broadcastUiAction(action, data);
+    return { success: ok, output: ok ? `已驱动前端: ${action}` : 'UI 广播未连接' };
+}
+/** 注册 UI 控制工具到 MCP 系统 (供 agent mcp_tool 调用) */
+export function registerUiControlTools() {
+    const toolDefs = [
+        {
+            name: 'ui_switch_tab',
+            description: '驱动前端切换底部 tab. 用户想"去通讯录/去我的/去设置"时调用. tab: wechat|contacts|discover|me',
+            inputSchema: { type: 'object', properties: { tab: { type: 'string' } }, required: ['tab'] },
+        },
+        {
+            name: 'ui_open_chat',
+            description: '驱动前端打开某个智能体聊天页. 用户想"打开和 X 的聊天"时调用. channelId: 目标 channel',
+            inputSchema: { type: 'object', properties: { channelId: { type: 'string' } }, required: ['channelId'] },
+        },
+        {
+            name: 'ui_open_settings',
+            description: '驱动前端打开设置页. 用户想"打开设置/配置"时调用.',
+            inputSchema: { type: 'object', properties: {} },
+        },
+        {
+            name: 'ui_open_wallet',
+            description: '驱动前端打开钱包. 用户想"看钱包/支付"时调用.',
+            inputSchema: { type: 'object', properties: {} },
+        },
+        {
+            name: 'ui_open_add_friend',
+            description: '驱动前端打开添加好友. 用户想"添加好友"时调用.',
+            inputSchema: { type: 'object', properties: {} },
+        },
+        {
+            name: 'ui_send_message',
+            description: '驱动前端在当前聊天发送消息. channelId: 目标 channel, text: 要发的消息文本.',
+            inputSchema: { type: 'object', properties: { channelId: { type: 'string' }, text: { type: 'string' } }, required: ['channelId', 'text'] },
+        },
+        {
+            name: 'ui_show_toast',
+            description: '在前端顶部显示一条提示 (toast). message: 提示内容.',
+            inputSchema: { type: 'object', properties: { message: { type: 'string' } }, required: ['message'] },
+        },
+        {
+            name: 'ui_go_back',
+            description: '驱动前端返回上一页. 用户想"返回/回去"时调用.',
+            inputSchema: { type: 'object', properties: {} },
+        },
+    ];
+    let count = 0;
+    for (const t of toolDefs) {
+        // 已注册则跳过 (幂等)
+        if (listTools().some((x) => x.name === t.name))
+            continue;
+        registerTool({
+            name: t.name,
+            description: t.description,
+            inputSchema: t.inputSchema,
+            serverName: 'ui', // 本地 UI 工具 (不走外部 server; 由 agent 调用方 dispatch)
+        });
+        count++;
+    }
+    return count;
+}
+/** agent 工具 (pi-sdk-tools 注册) 的 execute 适配: name → UiAction */
+export function uiToolNameToAction(name) {
+    switch (name) {
+        case 'ui_switch_tab': return 'switchTab';
+        case 'ui_open_chat': return 'openChat';
+        case 'ui_open_settings': return 'openSettings';
+        case 'ui_open_wallet': return 'openWallet';
+        case 'ui_open_add_friend': return 'openAddFriend';
+        case 'ui_send_message': return 'sendMessage';
+        case 'ui_show_toast': return 'showToast';
+        case 'ui_go_back': return 'goBack';
+        default: return null;
+    }
+}