@steerable/agent-shell 0.6.50 → 0.6.52

package/dist/local-executor.js

@@ -180,11 +180,53 @@ export function isPathWithinRoot(resolvedPath, resolvedRoot) {
     const rel = path.relative(resolvedRoot, resolvedPath);
     return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
 }
+/** `~` 展开后 resolve。围栏比较前路径与根都要过这一步。 */
+export function expandFencePath(inputPath) {
+    const expanded = inputPath.startsWith('~')
+        ? path.join(os.homedir(), inputPath.slice(1))
+        : inputPath;
+    return path.resolve(expanded);
+}
+/**
+ * 可写根：项目家目录（或对话工作区）加上额外可写根（源文件夹）。
+ * 每个根都包含它自己和全部子目录。空列表表示不设围栏。
+ */
+export function writableFenceRoots(projectRoot, additionalWriteRoots) {
+    const roots = [];
+    const push = (raw) => {
+        if (!raw)
+            return;
+        const trimmed = raw.trim();
+        if (!trimmed)
+            return;
+        const resolved = expandFencePath(trimmed);
+        if (!roots.includes(resolved))
+            roots.push(resolved);
+    };
+    push(projectRoot);
+    for (const extra of additionalWriteRoots ?? [])
+        push(extra);
+    return roots;
+}
 /** 越界错误消息（给模型看，引导它把操作收回项目目录内）。 */
 export function buildProjectRootViolation(resolvedPath, resolvedRoot) {
     return (`路径越界：${resolvedPath} 不在当前对话绑定的项目目录 ${resolvedRoot} 内。` +
-        `项目模式下文件操作被限制在项目目录中——请改用项目内的相对/绝对路径；` +
-        `如确需访问目录外文件，请告知用户该限制并请其把文件放进项目目录。`);
+        `项目模式下文件操作被限制在项目目录及其子目录中——请改用项目内的相对/绝对路径；` +
+        `如确需访问目录外文件，请告知用户该限制并请其把目录附加为源文件夹。`);
+}
+/**
+ * 路径不在任一可写根（含其子目录）内时返回给模型的错误；在围栏内或未设围栏时返回 null。
+ * `resolvedPath` 与 `roots` 都应已 resolve。
+ */
+export function writableFenceViolation(resolvedPath, roots) {
+    if (roots.length === 0)
+        return null;
+    if (roots.some((root) => isPathWithinRoot(resolvedPath, root)))
+        return null;
+    if (roots.length === 1)
+        return buildProjectRootViolation(resolvedPath, roots[0]);
+    return (`路径越界：${resolvedPath} 不在可写目录内（${roots.join('、')}）。` +
+        `可写范围是这些目录及其子目录。请改用其中的路径。`);
 }
 const BUILTIN_DANGEROUS = [
     { id: 'rm_rf_root', pattern: 'rm\\s+-rf\\s+\\/(?:\\s|$)', platform: 'unix' },
@@ -480,14 +522,11 @@ export class LocalExecutor {
             return { success: false, error: message };
         }
     }
-    async writeLocalFile(request, projectRoot) {
+    async writeLocalFile(request, projectRoot, additionalWriteRoots) {
         const filePath = this.resolvePath(request.path);
-        if (projectRoot) {
-            const root = this.resolvePath(projectRoot);
-            if (!isPathWithinRoot(filePath, root)) {
-                return { success: false, error: buildProjectRootViolation(filePath, root) };
-            }
-        }
+        const violation = writableFenceViolation(filePath, writableFenceRoots(projectRoot, additionalWriteRoots));
+        if (violation)
+            return { success: false, error: violation };
         // 同文件串行化：读-改-写必须排队，否则并发写会互相覆盖（pi file-mutation-queue）。
         return this.serializeFileOp(filePath, async () => {
             try {
@@ -544,14 +583,11 @@ export class LocalExecutor {
      * read-before-write 冲突检测，再在原文上做三级模糊定位 + 逆序替换，最后
      * 原子落盘。返回新版本令牌与统一 diff。
      */
-    async editLocalFile(request, projectRoot) {
+    async editLocalFile(request, projectRoot, additionalWriteRoots) {
         const filePath = this.resolvePath(request.path);
-        if (projectRoot) {
-            const root = this.resolvePath(projectRoot);
-            if (!isPathWithinRoot(filePath, root)) {
-                return { success: false, error: buildProjectRootViolation(filePath, root) };
-            }
-        }
+        const violation = writableFenceViolation(filePath, writableFenceRoots(projectRoot, additionalWriteRoots));
+        if (violation)
+            return { success: false, error: violation };
         return this.serializeFileOp(filePath, async () => {
             try {
                 const encoding = request.encoding ?? 'utf-8';
@@ -910,8 +946,7 @@ export class LocalExecutor {
         });
     }
     resolvePath(inputPath) {
-        const expanded = inputPath.startsWith('~') ? path.join(os.homedir(), inputPath.slice(1)) : inputPath;
-        return path.resolve(expanded);
+        return expandFencePath(inputPath);
     }
     resolveCwd(cwd, shellType) {
         const resolved = this.resolvePath(cwd || os.homedir());

package/dist/product-config.d.ts

@@ -106,6 +106,16 @@ export interface ProductConfig {
         cwd?: string;
         enabled?: boolean;
     }>;
+    /**
+     * P3.1 多智能体编排六件套 (agent_spawn / agent_wait / agent_send / agent_interrupt / agent_close / agent_list)。
+     * 缺省关（仅开 delegate_subagent）；设为 true 或配置对象时在回合中启用。
+     * STEERABLE_ORCHESTRATION 环境变量（'1' 开启，'0' 显式关闭）优先级更高。
+     */
+    orchestration?: boolean | {
+        enabled?: boolean;
+        maxDepth?: number;
+        maxParallel?: number;
+    };
 }
 /** shell 内置智能体：只有产品显式 `true` 才开。 */
 export declare function isShellBuiltinAgentEnabled(id: 'local-assistant' | 'all-round-assistant', config?: ProductConfig): boolean;

package/dist/project-home.d.ts

@@ -2,7 +2,7 @@
  * 项目默认家目录：`Documents/<应用名>/<项目名>/`。
  *
  * 新建项目不再等于「选一个已有文件夹」——项目是带名字的容器，
- * 家目录由本模块分配并创建。用户另加的源文件夹是附加只读根，
+ * 家目录由本模块分配并创建。用户另加的源文件夹是额外可写根（含子目录），
  * 不替代这个家目录。
  */
 /** 把 `~` / `~/…` 展开成绝对路径；其它输入原样（已 trim）。 */

package/dist/project-home.js

@@ -2,7 +2,7 @@
  * 项目默认家目录：`Documents/<应用名>/<项目名>/`。
  *
  * 新建项目不再等于「选一个已有文件夹」——项目是带名字的容器，
- * 家目录由本模块分配并创建。用户另加的源文件夹是附加只读根，
+ * 家目录由本模块分配并创建。用户另加的源文件夹是额外可写根（含子目录），
  * 不替代这个家目录。
  */
 import fs from 'node:fs';

package/dist/project-registry.d.ts

@@ -4,8 +4,8 @@
  * 项目 = 名字 + 托管家目录 + 可选源文件夹。家目录默认建在
  * `Documents/<应用名>/<项目名>/`（见 project-home.ts）。chat 通过
  * `chat_sessions.project_id` 绑定项目；绑定后文件读写与命令执行被硬限制
- * 在家目录内（见 tool-router.ts 的 ToolExecContext.projectRoot）；源文件夹
- * 只放宽 local_read_file。
+ * 在家目录及其子目录内（见 tool-router.ts 的 ToolExecContext.projectRoot）；
+ * 源文件夹及其子目录同样可写。
  *
  * 持久化在 userData/agent-projects.json。存储通过 {@link ProjectKvStore}
  * 接口注入：main.ts 用 electron-store 实现，单测用内存实现——本模块不
@@ -18,8 +18,8 @@ export interface ProjectRecord {
     /** 托管家目录（绝对路径）。默认 `Documents/<应用名>/<项目名>/`。 */
     folderPath: string;
     /**
-     * 附加源文件夹（已有代码目录）。只放宽读取，不替代家目录，也不放宽写入。
-     * 旧记录没有此字段，读取时按空列表处理。
+     * 附加源文件夹（已有代码目录）。与家目录一样可读写，范围含各自子目录。
+     * 不替代家目录。旧记录没有此字段，读取时按空列表处理。
      */
     sourceFolders?: string[];
     /**

package/dist/project-registry.js

@@ -4,8 +4,8 @@
  * 项目 = 名字 + 托管家目录 + 可选源文件夹。家目录默认建在
  * `Documents/<应用名>/<项目名>/`（见 project-home.ts）。chat 通过
  * `chat_sessions.project_id` 绑定项目；绑定后文件读写与命令执行被硬限制
- * 在家目录内（见 tool-router.ts 的 ToolExecContext.projectRoot）；源文件夹
- * 只放宽 local_read_file。
+ * 在家目录及其子目录内（见 tool-router.ts 的 ToolExecContext.projectRoot）；
+ * 源文件夹及其子目录同样可写。
  *
  * 持久化在 userData/agent-projects.json。存储通过 {@link ProjectKvStore}
  * 接口注入：main.ts 用 electron-store 实现，单测用内存实现——本模块不

package/dist/sidecar/boot.d.ts

@@ -9,10 +9,13 @@ export interface HostSidecarDeps {
     /** W4-2 围栏：chatId → 项目家目录或无项目对话工作区。 */
     resolveProjectRoot: (chatId: string) => Promise<string | null>;
     /**
-     * 项目模式之外额外放行的只读根（会话附件目录等）。文件写入仍只受
-     * projectRoot 围栏约束；这些根只放宽 local_read_file 的读取范围。
+     * 额外只读根（会话附件目录、源文件夹）。只放宽 local_read_file，含子目录。
      */
     resolveAdditionalReadRoots?: (chatId: string) => string[] | Promise<string[]>;
+    /**
+     * 额外可写根（项目源文件夹）。放宽写入、编辑和命令 cwd，含各自子目录。
+     */
+    resolveAdditionalWriteRoots?: (chatId: string) => string[] | Promise<string[]>;
     /** W4-1 审批反向通道处理器（宿主审批弹窗的应答入口）。 */
     approvalHandler: ReturnType<typeof createApprovalBridge>['handler'];
     /**

package/dist/sidecar/boot.js

@@ -214,6 +214,7 @@ export async function startHostSidecar(deps) {
             // root so ToolRouter's cwd/path confinement applies.
             resolveProjectRoot: deps.resolveProjectRoot,
             resolveAdditionalReadRoots: deps.resolveAdditionalReadRoots,
+            resolveAdditionalWriteRoots: deps.resolveAdditionalWriteRoots,
         }));
         // W4-1: approval algebra reverse channel — the sidecar's
         // ApprovalExecutor(HostApprover) asks here; the renderer modal answers

package/dist/sidecar/reverse-approval.d.ts

@@ -29,6 +29,8 @@ export interface ApprovalPromptRequest {
     mode: string;
     category: string;
     round: number;
+    /** Chat that asked. The renderer only shows the card in that composer. */
+    chatId?: string;
 }
 export interface ApprovalBridgeDeps {
     /**

package/dist/sidecar/reverse-approval.js

@@ -43,6 +43,7 @@ export function createApprovalBridge(deps) {
                 return deny('no renderer window available to approve the call');
             }
             const requestId = randomUUID();
+            const chatId = typeof p.chatId === 'string' && p.chatId ? p.chatId : undefined;
             const prompt = {
                 requestId,
                 toolName,
@@ -52,6 +53,7 @@ export function createApprovalBridge(deps) {
                 mode: typeof p.mode === 'string' ? p.mode : 'other',
                 category: typeof p.category === 'string' ? p.category : toolName,
                 round: typeof p.round === 'number' ? p.round : 0,
+                ...(chatId ? { chatId } : {}),
             };
             deps.onLog?.(`approval: prompting for ${toolName} (${prompt.mode}/${prompt.category})`);
             return await new Promise((resolve) => {

package/dist/sidecar/reverse-tools.d.ts

@@ -21,9 +21,13 @@ export interface ReverseToolDeps {
      */
     resolveProjectRoot?: (chatId: string) => Promise<string | null>;
     /**
-     * 额外放行的只读根（会话附件目录等）。写入仍只受 projectRoot 围栏约束，
-     * 这里只放宽 local_read_file 的读取范围。
+     * 额外只读根（会话附件目录、源文件夹）。只放宽读取，含各自子目录。
      */
     resolveAdditionalReadRoots?: (chatId: string) => string[] | Promise<string[]>;
+    /**
+     * 额外可写根（项目源文件夹）。放宽写入、编辑和命令 cwd，含各自子目录。
+     * 附件目录不进这里。
+     */
+    resolveAdditionalWriteRoots?: (chatId: string) => string[] | Promise<string[]>;
 }
 export declare function createToolInvokeHandler(deps: ReverseToolDeps): SidecarReverseHandler;

package/dist/sidecar/reverse-tools.js

@@ -74,6 +74,9 @@ export function createToolInvokeHandler(deps) {
         const additionalReadRoots = p.context?.chatId
             ? await Promise.resolve(deps.resolveAdditionalReadRoots?.(p.context.chatId) ?? [])
             : [];
+        const additionalWriteRoots = p.context?.chatId
+            ? await Promise.resolve(deps.resolveAdditionalWriteRoots?.(p.context.chatId) ?? [])
+            : [];
         if (name === 'local_exec_shell') {
             const classification = classifyShellCommand(String(toolArgs.command ?? ''));
             if (classification.severity === 'critical') {
@@ -94,7 +97,11 @@ export function createToolInvokeHandler(deps) {
             ? normalizeToolPolicy(p.context.toolPolicy)
             : null;
         const toolPolicy = normalizedPolicy && normalizedPolicy.mode !== 'all' ? normalizedPolicy : null;
-        const execContext = projectRoot || additionalReadRoots.length > 0 || p.context?.chatId || toolPolicy
+        const execContext = projectRoot ||
+            additionalReadRoots.length > 0 ||
+            additionalWriteRoots.length > 0 ||
+            p.context?.chatId ||
+            toolPolicy
             ? {
                 projectRoot,
                 chatId: p.context?.chatId,
@@ -102,6 +109,7 @@ export function createToolInvokeHandler(deps) {
                 // worktree_* 工具按它把任务绑定到来源对话。
                 ...(toolPolicy ? { toolPolicy } : {}),
                 ...(additionalReadRoots.length > 0 ? { additionalReadRoots } : {}),
+                ...(additionalWriteRoots.length > 0 ? { additionalWriteRoots } : {}),
             }
             : undefined;
         try {

package/dist/sidecar/types.d.ts

@@ -333,12 +333,15 @@ export interface SidecarChatStreamRequest {
      * executor with the six-tool orchestration family (agent_spawn /
      * agent_send / agent_wait / agent_close / agent_list / agent_interrupt).
      * When delegation is also on (it is by default), both surfaces share one
-     * agent pool — one maxParallel budget, one lineage space. */
+     * agent pool — one maxParallel budget, one lineage space.
+     * `childMaxRounds` / `childMaxToolErrors` default to the parent loop's
+     * limits. */
     orchestration?: {
         enabled?: boolean;
         maxDepth?: number;
         maxParallel?: number;
         childMaxRounds?: number;
+        childMaxToolErrors?: number;
     };
     /**
      * Sub-agent delegation (delegate-on-pool). ON BY DEFAULT on the sidecar —
@@ -451,6 +454,12 @@ export interface SidecarChatStreamRequest {
         mode: 'host' | 'auto';
         timeoutMs?: number;
         storePath?: string;
+        /**
+         * Project home, source folders, and other configured write roots.
+         * File tools whose targets all sit inside these directories skip the
+         * host prompt. Independent of whether the OS exec sandbox is on.
+         */
+        writableRoots?: string[];
     };
 }
 /**

package/dist/storage/write-lease-error.js

@@ -6,9 +6,12 @@ export function acquireWriteLeaseOrExit(acquire, loadElectron = () => import('el
     }
     catch (error) {
         if (error instanceof StoreAlreadyOwnedError) {
+            console.error(`[bs] 本地数据库正在被另一个进程使用（${error.lockPath}）。\n` +
+                '[bs] 再打开一次桌面应用会回到已经打开的窗口。\n' +
+                '[bs] 如果终端里的 pnpm dev:bs 占着数据库，请先在那个终端按 Ctrl+C 停掉，再重新打开。');
             void loadElectron()
                 .then(({ app, dialog }) => {
-                dialog.showErrorBox('无法启动', '另一个实例正在运行并占用本地数据库。请先关闭该实例，再重新打开应用。');
+                dialog.showErrorBox('无法再开一个', '再打开一次应用时，会回到已经打开的窗口。\n\n这次没有回到那个窗口，是因为本地数据库正被另一个进程占用。如果终端里还在跑 pnpm dev:bs，先停掉它，再重新打开。');
                 app.exit(1);
             })
                 .catch(() => exitProcess(1));

package/dist/tool-presentation.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 一等工具的展示声明。
+ *
+ * 卡片种类和标题从这里按工具名取，不从名字前缀猜测。
+ * 未声明的名字（MCP、插件、场景包）落到 generic / other，`declared: false`。
+ * 宿主在 executed_actions 上盖 `view`，卡片读这份声明。
+ */
+export declare const TOOL_CARDS: readonly ["generic", "terminal", "diff", "search", "read", "web"];
+export type ToolCard = (typeof TOOL_CARDS)[number];
+export declare const TOOL_KINDS: readonly ["read", "edit", "delete", "move", "search", "execute", "fetch", "other"];
+export type ToolKind = (typeof TOOL_KINDS)[number];
+export interface ToolCallView {
+    card: ToolCard;
+    kind: ToolKind;
+    title: string;
+    /** 名字在声明表里。false 表示通用回退，不是从名字前缀推断出来的。 */
+    declared: boolean;
+}
+/**
+ * 取一次调用的展示。`result` 缺省时只根据参数出标题；结果到达后用同一声明补计数和状态。
+ */
+export declare function presentToolCall(name: string, args: unknown, result?: unknown): ToolCallView;
+export declare function declaredToolNames(): readonly string[];

package/dist/tool-presentation.js

@@ -0,0 +1,266 @@
+/**
+ * 一等工具的展示声明。
+ *
+ * 卡片种类和标题从这里按工具名取，不从名字前缀猜测。
+ * 未声明的名字（MCP、插件、场景包）落到 generic / other，`declared: false`。
+ * 宿主在 executed_actions 上盖 `view`，卡片读这份声明。
+ */
+export const TOOL_CARDS = ['generic', 'terminal', 'diff', 'search', 'read', 'web'];
+export const TOOL_KINDS = [
+    'read',
+    'edit',
+    'delete',
+    'move',
+    'search',
+    'execute',
+    'fetch',
+    'other',
+];
+function clip(text, max = 60) {
+    const trimmed = text.replace(/\s+/g, ' ').trim();
+    if (!trimmed)
+        return '';
+    return trimmed.length > max ? `${trimmed.slice(0, max - 1)}…` : trimmed;
+}
+function str(args, key) {
+    const value = args[key];
+    return typeof value === 'string' ? value : '';
+}
+function dataOf(result) {
+    if (!result || typeof result !== 'object')
+        return null;
+    const data = result.data;
+    if (data && typeof data === 'object' && !Array.isArray(data)) {
+        return data;
+    }
+    return result;
+}
+function failed(result) {
+    return Boolean(result && typeof result === 'object' && result.success === false);
+}
+function commandTitle(args) {
+    return clip(str(args, 'command')) || 'shell';
+}
+function pathTitle(args, fallback) {
+    return clip(str(args, 'path') || str(args, 'file') || str(args, 'target'), 72) || fallback;
+}
+function webSearchTitle(args, result) {
+    const query = str(args, 'query');
+    const head = `搜索“${clip(query, 40) || '…'}”`;
+    if (result === undefined || failed(result))
+        return head;
+    const data = dataOf(result);
+    const count = data && typeof data.result_count === 'number' ? data.result_count : null;
+    return count === null ? head : `${head} → ${count} 条结果`;
+}
+function shortUrl(raw) {
+    if (!raw)
+        return '未知地址';
+    try {
+        const url = new URL(raw);
+        const path = url.pathname === '/' ? '' : url.pathname;
+        return clip(`${url.host}${path}`, 48);
+    }
+    catch {
+        return clip(raw, 48);
+    }
+}
+function webFetchTitle(args, result) {
+    const head = `抓取 ${shortUrl(str(args, 'url'))}`;
+    if (result === undefined || failed(result))
+        return head;
+    const data = dataOf(result);
+    if (!data)
+        return head;
+    const parts = [];
+    if (typeof data.status === 'number')
+        parts.push(String(data.status));
+    if (typeof data.bytes === 'number' && Number.isFinite(data.bytes)) {
+        parts.push(data.bytes < 1024 ? `${data.bytes} B` : `${(data.bytes / 1024).toFixed(1)} KB`);
+    }
+    if (data.truncated === true)
+        parts.push('已截断');
+    return parts.length > 0 ? `${head} → ${parts.join(' · ')}` : head;
+}
+function taskRunTitle(args, result) {
+    const task = clip(str(args, 'task'));
+    if (!task)
+        return '后台任务';
+    const status = dataOf(result)?.status;
+    if (status === 'blocked')
+        return `${task} · 等待依赖`;
+    if (args.worktree === true)
+        return `${task} · 隔离工作区`;
+    return task;
+}
+function jobIdTitle(args, fallback) {
+    const id = str(args, 'job_id') || str(args, 'taskId');
+    return id ? id.slice(0, 8) : fallback;
+}
+function runCodeTitle(args, result) {
+    const description = clip(str(args, 'description'), 40) || '程序';
+    if (failed(result))
+        return `程序「${description}」失败`;
+    const calls = dataOf(result)?.calls;
+    const count = Array.isArray(calls) ? calls.length : 0;
+    return count > 0 ? `程序「${description}」· ${count} 个内层工具` : `程序「${description}」`;
+}
+function goalTitle(args, fallback) {
+    return clip(str(args, 'objective'), 72) || fallback;
+}
+const PRESENTERS = {
+    local_exec_shell: { card: 'terminal', kind: 'execute', title: commandTitle },
+    pwsh: { card: 'terminal', kind: 'execute', title: commandTitle },
+    bash: { card: 'terminal', kind: 'execute', title: commandTitle },
+    bash_session: { card: 'terminal', kind: 'execute', title: commandTitle },
+    write_stdin: {
+        card: 'terminal',
+        kind: 'execute',
+        title: (args) => clip(str(args, 'chars'), 40) || str(args, 'sessionId').slice(0, 8) || 'stdin',
+    },
+    local_run_snippet: {
+        card: 'terminal',
+        kind: 'execute',
+        title: (args) => clip(str(args, 'code'), 48) || str(args, 'language') || 'snippet',
+    },
+    local_run_script: {
+        card: 'terminal',
+        kind: 'execute',
+        title: (args) => str(args, 'scriptId') || 'script',
+    },
+    run_code: { card: 'generic', kind: 'execute', title: runCodeTitle },
+    run_js: { card: 'generic', kind: 'execute', title: runCodeTitle },
+    wait_js: {
+        card: 'generic',
+        kind: 'execute',
+        title: (args) => str(args, 'id').slice(0, 8) || 'wait_js',
+    },
+    local_read_file: { card: 'read', kind: 'read', title: (args) => pathTitle(args, 'read') },
+    read_file: { card: 'read', kind: 'read', title: (args) => pathTitle(args, 'read') },
+    view_image: { card: 'read', kind: 'read', title: (args) => pathTitle(args, 'image') },
+    capture_display: {
+        card: 'read',
+        kind: 'read',
+        title: (args) => clip(str(args, 'target'), 48) || 'display',
+    },
+    local_list_scripts: { card: 'read', kind: 'read', title: () => '已保存的脚本' },
+    local_write_file: { card: 'diff', kind: 'edit', title: (args) => pathTitle(args, 'write') },
+    write_file: { card: 'diff', kind: 'edit', title: (args) => pathTitle(args, 'write') },
+    local_edit_file: { card: 'diff', kind: 'edit', title: (args) => pathTitle(args, 'edit') },
+    edit_file: { card: 'diff', kind: 'edit', title: (args) => pathTitle(args, 'edit') },
+    apply_patch: { card: 'diff', kind: 'edit', title: () => 'apply_patch' },
+    grep: {
+        card: 'search',
+        kind: 'search',
+        title: (args) => clip(str(args, 'pattern')) || 'grep',
+    },
+    glob: {
+        card: 'search',
+        kind: 'search',
+        title: (args) => clip(str(args, 'pattern')) || 'glob',
+    },
+    tool_search: {
+        card: 'search',
+        kind: 'search',
+        title: (args) => clip(str(args, 'query')) || 'tool_search',
+    },
+    web_search: { card: 'web', kind: 'search', title: webSearchTitle },
+    web_fetch: { card: 'web', kind: 'fetch', title: webFetchTitle },
+    task_run: { card: 'generic', kind: 'other', title: taskRunTitle },
+    task_send: {
+        card: 'generic',
+        kind: 'other',
+        title: (args) => clip(str(args, 'message')) || '转达任务',
+    },
+    task_status: {
+        card: 'generic',
+        kind: 'read',
+        title: (args, result) => {
+            const id = str(args, 'taskId');
+            if (id)
+                return id.slice(0, 8);
+            const total = dataOf(result)?.total;
+            return typeof total === 'number' ? `${total} 个任务` : '本会话';
+        },
+    },
+    task_result: {
+        card: 'generic',
+        kind: 'read',
+        title: (args) => jobIdTitle(args, '收取结果'),
+    },
+    job_list: {
+        card: 'generic',
+        kind: 'read',
+        title: (_args, result) => {
+            const total = dataOf(result)?.total;
+            return typeof total === 'number' ? `${total} 个任务` : '后台任务';
+        },
+    },
+    job_output: { card: 'generic', kind: 'read', title: (args) => jobIdTitle(args, '任务输出') },
+    job_kill: { card: 'generic', kind: 'delete', title: (args) => jobIdTitle(args, '结束任务') },
+    worktree_create: {
+        card: 'generic',
+        kind: 'other',
+        title: (args) => str(args, 'name') || '新建工作区',
+    },
+    worktree_list: { card: 'read', kind: 'read', title: () => '工作区列表' },
+    worktree_remove: {
+        card: 'generic',
+        kind: 'delete',
+        title: (args) => str(args, 'name') || '移除工作区',
+    },
+    get_goal: { card: 'generic', kind: 'read', title: () => '当前目标' },
+    create_goal: { card: 'generic', kind: 'other', title: (args) => goalTitle(args, '新建目标') },
+    update_goal: {
+        card: 'generic',
+        kind: 'other',
+        title: (args) => {
+            const action = str(args, 'action');
+            const objective = clip(str(args, 'objective'), 48);
+            return objective ? `${action || 'update'} ${objective}` : action || '更新目标';
+        },
+    },
+    present_files: { card: 'generic', kind: 'other', title: () => '交付文件' },
+    local_open_path: {
+        card: 'generic',
+        kind: 'other',
+        title: (args) => pathTitle(args, 'open'),
+    },
+    todo_write: { card: 'generic', kind: 'other', title: () => '待办' },
+    ask_user: {
+        card: 'generic',
+        kind: 'other',
+        title: (args) => clip(str(args, 'intro') || str(args, 'question')) || '提问',
+    },
+    skill: { card: 'generic', kind: 'read', title: (args) => str(args, 'name') || 'skill' },
+    delegate_subagent: {
+        card: 'generic',
+        kind: 'other',
+        title: (args) => clip(str(args, 'task')) || str(args, 'subagent_type') || '子代理',
+    },
+    mcp_list_tools: { card: 'generic', kind: 'fetch', title: () => 'MCP 工具' },
+    mcp_tool_exec: {
+        card: 'generic',
+        kind: 'fetch',
+        title: (args) => str(args, 'toolName') || 'MCP',
+    },
+    plugin_list: { card: 'generic', kind: 'read', title: () => '插件' },
+    plugin_enable: { card: 'generic', kind: 'other', title: (args) => str(args, 'name') || '启用插件' },
+    plugin_disable: { card: 'generic', kind: 'delete', title: (args) => str(args, 'name') || '停用插件' },
+    plugin_reload: { card: 'generic', kind: 'other', title: (args) => str(args, 'name') || '重载插件' },
+};
+/**
+ * 取一次调用的展示。`result` 缺省时只根据参数出标题；结果到达后用同一声明补计数和状态。
+ */
+export function presentToolCall(name, args, result) {
+    const record = args && typeof args === 'object' && !Array.isArray(args) ? args : {};
+    const presenter = PRESENTERS[name];
+    if (!presenter) {
+        return { card: 'generic', kind: 'other', title: name, declared: false };
+    }
+    const title = presenter.title(record, result).trim() || name;
+    return { card: presenter.card, kind: presenter.kind, title, declared: true };
+}
+export function declaredToolNames() {
+    return Object.keys(PRESENTERS);
+}