pi-web-ui 0.62.0 → 0.63.0

package/dist/server/agent-service.js

@@ -11,28 +11,29 @@
  * so reconnects just re-request a snapshot.
  */
 import { spawn, spawnSync } from "node:child_process";
-import { existsSync, readFileSync, rmSync, statSync, writeFileSync, mkdirSync, watch, } from "node:fs";
-import { basename, dirname, join, relative, resolve, sep } from "node:path";
+import { randomUUID } from "node:crypto";
+import { existsSync, readFileSync, rmSync, statSync, mkdirSync, watch } from "node:fs";
+import { basename, dirname, join, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
-import { createAgentSessionFromServices, createAgentSessionRuntime, createAgentSessionServices, createBashTool, createLocalBashOperations, defineTool, getAgentDir, ModelRuntime, SessionManager, VERSION, } from "@earendil-works/pi-coding-agent";
+import { createAgentSessionFromServices, createAgentSessionRuntime, createAgentSessionServices, createBashTool, createLocalBashOperations, getAgentDir, SessionManager, VERSION, } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { BgServerTracker } from "./bg-servers.js";
 import { checkAll as checkAllUpdates, collectTargets, compareVersions as compareSemver, } from "./update-check.js";
-import { hasPendingWaitSubscription, shouldRetainActive } from "./wait-subscription-scan.js";
+import { hasActiveSubagentRun, hasPendingWaitSubscription, shouldRetainActive } from "./wait-subscription-scan.js";
 import { syncPluginToolsIntoSession } from "./plugins.js";
 import { SettingsService } from "./settings-service.js";
 import { GoalService } from "./goal-service.js";
 import { SlashCommandsService, parseSlash } from "./slash-commands.js";
 import { ModelAdminService } from "./model-admin.js";
 import { FilesService, workspacePath } from "./files-service.js";
-import { isExtensionDisabled, ClientStateStore, } from "./client-state.js";
-import { saveUpload } from "./uploads.js";
+import { isExtensionDisabled, isExtensionEnabled, ClientStateStore } from "./client-state.js";
+import { SubagentTemplatesStore } from "./subagent-templates.js";
 import { applyHeadTail, makePersistentTerminalTools, makeTerminalBashTool, stripAnsi, TERMINAL_TOOLS_GUIDANCE, TERMINAL_TOOL_NAMES, } from "./terminals.js";
 import { WebUIContext } from "./webui-context.js";
-import { buildAttachmentMessages, parseModelSpec, } from "./attachments.js";
-import { serializeMessage, serializeStreamingMessage, } from "./serialize.js";
-import { loadCommands, saveCommandsFile, TerminalManager, } from "./terminals.js";
-import { buildVisionBridgePrompt, SYSTEM_PROMPT, transcribeImages, } from "./vision-bridge.js";
+import { makeSubagentTools, subagentTitle, } from "./subagents.js";
+import { buildAttachmentMessages } from "./attachments.js";
+import { serializeMessage, serializeStreamingMessage } from "./serialize.js";
+import { loadCommands, saveCommandsFile, TerminalManager } from "./terminals.js";
 const SNAPSHOT_INTERVAL_MS = 60;
 /** While assistant deltas are flowing, live rendering is carried by
  *  message_delta — full snapshots become pure reconciliation checkpoints, so
@@ -82,14 +83,14 @@ export class QuiesceRejectedError extends Error {
  *  programs wait for input that never comes. Legacy Chinese files are often
  *  GBK/GB2312 — read them with the right encoding, never paste mojibake into
  *  reasoning/answers. */
-const WINDOWS_PERSONA = `You are a coding agent running on Windows. The bash tool runs Git Bash (bash.exe), not PowerShell. Follow these rules to avoid hanging the session:
-
-
-
-- ALWAYS pass a timeout parameter to the bash tool (in seconds). There is NO default timeout — a command that never finishes (servers, watchers, infinite loops, slow downloads/installs) will hang the entire conversation indefinitely. Pick a generous timeout for long-running work, but never omit it.
-- NEVER run interactive or foreground long-running commands through the bash tool (vi, less, top, python -, node -, npm run dev, sleep 10000). For servers/daemons use background execution with output redirected to a log file, then poll the log; stop them when done.
-- In the interactive terminal (TTY) — which is Git Bash too, not PowerShell — NEVER use heredocs (<<'EOF' ... EOF) or here-strings, and NEVER start interactive programs (vi, less, python -, node -, npm init): they wait for keyboard input that never arrives and hang the terminal forever. Prefer writing a temp script file (e.g. .pi-tmp.sh) and running it non-interactively. ALWAYS pass a timeout to long-running commands (e.g. \`timeout 120 npm run dev\`).
-
+const WINDOWS_PERSONA = `You are a coding agent running on Windows. The bash tool runs Git Bash (bash.exe), not PowerShell. Follow these rules to avoid hanging the session:
+
+
+
+- ALWAYS pass a timeout parameter to the bash tool (in seconds). There is NO default timeout — a command that never finishes (servers, watchers, infinite loops, slow downloads/installs) will hang the entire conversation indefinitely. Pick a generous timeout for long-running work, but never omit it.
+- NEVER run interactive or foreground long-running commands through the bash tool (vi, less, top, python -, node -, npm run dev, sleep 10000). For servers/daemons use background execution with output redirected to a log file, then poll the log; stop them when done.
+- In the interactive terminal (TTY) — which is Git Bash too, not PowerShell — NEVER use heredocs (<<'EOF' ... EOF) or here-strings, and NEVER start interactive programs (vi, less, python -, node -, npm init): they wait for keyboard input that never arrives and hang the terminal forever. Prefer writing a temp script file (e.g. .pi-tmp.sh) and running it non-interactively. ALWAYS pass a timeout to long-running commands (e.g. \`timeout 120 npm run dev\`).
+
 Many legacy Chinese text files (.html/.txt/.md/.log, exported documents) are GBK/GB2312 encoded: the read tool decodes UTF-8 only and will show mojibake (乱码) for them. If a file's content looks garbled, read it through the terminal instead: in Git Bash use \`cat file | iconv -f GBK -t UTF-8\` (or \`iconv -f GBK -t UTF-8 file\`); in cmd use \`chcp 65001 && type file\`; in PowerShell use \`Get-Content -Encoding Default file\`. Never paste mojibake into your reasoning or answer — describe the decoded content instead.`;
 /** bash 工具输出限制/过滤管道引导：模型习惯套 `| tail/-n`、`| head`、`| grep`、`| less`
  *  等限输出。这些管道在持久终端里会①缓冲（可见终端全程哑火、看不到实时进度）②把退出码
@@ -181,9 +182,7 @@ export function makeAdaptiveBashTool(killable, terminalBacked, useTerminal) {
  */
 function pluginToolToDefinition(tool) {
     const normalize = (result) => {
-        if (result &&
-            typeof result === "object" &&
-            Array.isArray(result.content)) {
+        if (result && typeof result === "object" && Array.isArray(result.content)) {
             return result;
         }
         const text = typeof result === "string" ? result : JSON.stringify(result ?? null, null, 2);
@@ -200,9 +199,7 @@ function pluginToolToDefinition(tool) {
             properties: {},
         }),
         execute: async (toolCallId, params, signal, onUpdate) => {
-            const raw = await tool.execute(toolCallId, params, signal, onUpdate
-                ? (partial) => onUpdate(normalize(partial))
-                : undefined);
+            const raw = await tool.execute(toolCallId, params, signal, onUpdate ? (partial) => onUpdate(normalize(partial)) : undefined);
             return normalize(raw);
         },
     };
@@ -240,13 +237,10 @@ function contentFingerprint(m) {
 // with a mock theme to plain text lines, and push them to the client.
 // ---------------------------------------------------------------------------
 function extractPartialText(partial) {
-    const content = partial
-        ?.content;
+    const content = partial?.content;
     if (Array.isArray(content)) {
         const text = content
-            .map((c) => c?.type === "text"
-            ? c.text
-            : "")
+            .map((c) => (c?.type === "text" ? c.text : ""))
             .join("");
         return text.length > 0 ? text : null;
     }
@@ -531,6 +525,77 @@ export class ClientSession {
                 .catch(() => { });
         }
     }
+    /** 创建子代理 conversation（inMemory runtime + 独立 terminals），listed 入左栏，
+     *  并在其上触发一次完整回合。返回 convId（= 工具 runId）。 */
+    async spawnSubagentConversation(prompt, type, cwd, apply) {
+        const conversationId = `sa-${randomUUID().slice(0, 8)}`;
+        const terminals = this.makeTerminalManager(conversationId, cwd);
+        const runtime = await createAgentSessionRuntime(this.makeRuntimeFactory(terminals, apply), {
+            cwd,
+            agentDir: this.agentDir,
+            sessionManager: SessionManager.inMemory(cwd),
+        });
+        const conv = this.makeConversation(runtime, conversationId, terminals);
+        conv.isSubagent = true;
+        conv.subagentType = type;
+        conv.listed = true;
+        conv.title = subagentTitle(prompt);
+        this.convs.set(conv.id, conv);
+        // 扩展绑定（rpc 模式；不给 uiContext，避免与主对话的 widget 冲突）。
+        try {
+            await conv.session.bindExtensions({
+                mode: "rpc",
+                onError: (err) => this.emit({ type: "notice", level: "error", text: err.error }),
+            });
+        }
+        catch {
+            // 绑定失败不阻断运行。
+        }
+        // 触发回合（后台执行；失败转识为通知）。
+        void conv.session.sendUserMessage(prompt).catch((err) => {
+            this.emit({
+                type: "notice",
+                level: "error",
+                text: `子代理 ${conversationId} 启动失败: ${err instanceof Error ? err.message : String(err)}`,
+            });
+        });
+        this.emitConversations();
+        return conv.id;
+    }
+    getSubagentSnapshot(convId) {
+        const conv = this.convs.get(convId);
+        if (!conv?.isSubagent || !conv.session)
+            return undefined;
+        return this.toSubagentSnapshot(conv);
+    }
+    listSubagentSnapshots() {
+        return [...this.convs.values()]
+            .filter((c) => c.isSubagent)
+            .sort((a, b) => a.createdAt - b.createdAt)
+            .map((c) => this.toSubagentSnapshot(c));
+    }
+    toSubagentSnapshot(conv) {
+        const streaming = conv.session.isStreaming;
+        const state = streaming ? "running" : "done";
+        let messageCount = 0;
+        try {
+            messageCount = conv.session.getSessionStats().totalMessages;
+        }
+        catch {
+            // session being replaced — report defaults
+        }
+        return {
+            convId: conv.id,
+            type: conv.subagentType ?? "general",
+            title: conv.title,
+            prompt: "",
+            state,
+            streaming,
+            messageCount,
+            model: conv.session.model?.id,
+            output: conv.session.getLastAssistantText() ?? "",
+        };
+    }
     emitTerminal(conversationId, msg) {
         // Background conversations keep collecting output in their own PTY buffer.
         // Do not stream it into the active xterm; push the retained window on switch.
@@ -602,6 +667,45 @@ export class ClientSession {
     }
     /** Web-facing extension UI context (widgets, notifications). */
     webUi = new WebUIContext((msg) => this.emit(msg));
+    /**
+     * 第一方子代理 host（见 subagents.ts 设计头注）。子代理 = 一个标记
+     * isSubagent 的普通 Conversation：inMemory runtime（不落盘、不进
+     * 历史/resume 列表）、listed=true 出现在左栏「运行的对话」并向用户可见——
+     * 切换查看 / 输入补充（steer）/ 中止（abort）/ 移出全部复用现有对话机制。
+     */
+    subagentHost = {
+        spawnSubagent: (prompt, type, cwd, templateName) => {
+            // 模板：存在且启用时应用；传了名字但不可用 → 抛错让工具转给 AI。
+            const tpl = templateName ? this.subagentTemplates.get(templateName) : undefined;
+            if (templateName && (!tpl || !tpl.enabled)) {
+                throw new Error(`子代理模板不可用：${templateName}（不存在或已停用）`);
+            }
+            return this.spawnSubagentConversation(prompt, type, cwd, tpl);
+        },
+        getSubagent: (convId) => this.getSubagentSnapshot(convId),
+        listSubagents: () => this.listSubagentSnapshots(),
+        steerSubagent: async (convId, message) => {
+            const conv = this.convs.get(convId);
+            if (!conv?.session)
+                return;
+            await conv.session.sendUserMessage(message, conv.session.isStreaming ? { deliverAs: "steer" } : undefined);
+        },
+        stopSubagent: async (convId) => {
+            const conv = this.convs.get(convId);
+            if (conv && (conv.session.isStreaming || !conv.session.isIdle)) {
+                await this.interruptRun(conv, "用户停止子代理");
+            }
+        },
+        // 只向 AI 暴露 enabled 的模板（停用的对 AI 不可见）。
+        listTemplates: () => this.subagentTemplates
+            .list()
+            .filter((t) => t.enabled)
+            .map((t) => ({ name: t.name, description: t.description })),
+        isTemplateUsable: (name) => {
+            const t = this.subagentTemplates.get(name);
+            return !!t && t.enabled;
+        },
+    };
     widgetsTimer = null;
     /** Model-stall watchdog interval (see startStallTimer). */
     stallTimer = null;
@@ -649,11 +753,14 @@ export class ClientSession {
     gitWatchCwd = null;
     gitDirtyTimer = null;
     watchTimer = null;
+    /** 子代理模板库（全局共享，<dataDir>/subagent-templates.json）。 */
+    subagentTemplates;
     constructor(clientId, cwd, agentDir, stateStore) {
         this.clientId = clientId;
         this.cwd = cwd;
         this.agentDir = agentDir;
         this.stateStore = stateStore;
+        this.subagentTemplates = new SubagentTemplatesStore(join(stateStore.dataDir, "subagent-templates.json"));
         this.settingsSvc = new SettingsService({
             clientId,
             stateStore,
@@ -672,7 +779,7 @@ export class ClientSession {
             },
             effectiveDefaultSystemPrompt: () => this.effectiveDefaultSystemPrompt(),
             effectiveSystemPrompt: () => this.effectiveSystemPrompt(),
-        });
+        }, this.subagentTemplates);
         this.goalSvc = new GoalService({
             clientId,
             agentDir,
@@ -741,8 +848,12 @@ export class ClientSession {
      * Factory for cwd-bound runtimes. All conversations share ONE ModelRuntime
      * (the model choice is client-wide), so later conversations reuse the
      * instance created with the first one.
+     *
+     * `apply`（可选）：子代理模板 —— 会话的 system prompt / 技能 / 扩展按模板
+     * 应用（prompt replace/append + 白名单），其余（终端接管、Windows persona
+     * 等）仍跟随主会话设置。undefined = 按主会话设置（普通对话/不选模板的子代理）。
      */
-    makeRuntimeFactory(terminals) {
+    makeRuntimeFactory(terminals, apply) {
         return async ({ cwd: effectiveCwd, sessionManager }) => {
             const services = await createAgentSessionServices({
                 cwd: effectiveCwd,
@@ -751,6 +862,10 @@ export class ClientSession {
                 // 在每次 resourceLoader.reload() 时重放，且读取 this.settings 的当前
                 // 值——因此 session.reload() 即可让系统提示词 / 技能 / 插件开关生效，
                 // 新对话（新 runtime）也会自动带上当前设置。
+                // 子代理带模板（apply）时：prompt/skills/extensions 改读模板视图——
+                // replace 模式整体替换为模板提示词；append 模式把模板提示词追加到
+                // 末尾（此时主会话的自定义 prompt 不再叠加，角色由模板定义）；非空
+                // 白名单取代主会话开关（只启用这些），空白名单 = 跟随主会话。
                 resourceLoaderOptions: {
                     // 系统提示词：replace 模式整体替换；append 模式追加到提示词末尾。
                     systemPromptOverride: (base) => {
@@ -759,6 +874,9 @@ export class ClientSession {
                         if (typeof base === "string" && base) {
                             this.lastBaseSystemPrompt = base;
                         }
+                        if (apply && apply.promptMode === "replace" && apply.systemPrompt.trim()) {
+                            return apply.systemPrompt;
+                        }
                         return this.settingsSvc.current.promptMode === "replace" &&
                             this.settingsSvc.current.customSystemPrompt.trim()
                             ? this.settingsSvc.current.customSystemPrompt
@@ -766,9 +884,14 @@ export class ClientSession {
                     },
                     appendSystemPromptOverride: (base) => {
                         const out = [...base];
-                        const custom = this.settingsSvc.current.customSystemPrompt.trim();
-                        if (this.settingsSvc.current.promptMode === "append" && custom) {
-                            out.push(custom);
+                        if (apply && apply.promptMode === "append" && apply.systemPrompt.trim()) {
+                            out.push(apply.systemPrompt);
+                        }
+                        else {
+                            const custom = this.settingsSvc.current.customSystemPrompt.trim();
+                            if (this.settingsSvc.current.promptMode === "append" && custom) {
+                                out.push(custom);
+                            }
                         }
                         if (process.platform === "win32") {
                             // Windows 专属 persona：bash 工具跑 Git Bash 且无默认超时、终端
@@ -788,18 +911,30 @@ export class ClientSession {
                         out.push(PIPELESS_BASH_GUIDANCE);
                         return out;
                     },
-                    // 技能开关：禁用的技能从系统提示词和 /skill: 目录中剔除。
-                    skillsOverride: (res) => ({
-                        ...res,
-                        skills: res.skills.filter((s) => !this.settingsSvc.current.disabledSkills.includes(s.name)),
-                    }),
-                    // 插件开关：禁用的扩展整个卸载（工具 / 命令随之消失）。
+                    // 技能：模板非空白名单时只启用白名单里的；否则按主会话禁用集过滤。
+                    skillsOverride: (res) => {
+                        if (apply && apply.enabledSkills.length > 0) {
+                            const set = new Set(apply.enabledSkills);
+                            return { ...res, skills: res.skills.filter((s) => set.has(s.name)) };
+                        }
+                        return {
+                            ...res,
+                            skills: res.skills.filter((s) => !this.settingsSvc.current.disabledSkills.includes(s.name)),
+                        };
+                    },
+                    // 插件：模板非空扩展白名单时只加载白名单里的；否则按主会话禁用集过滤。
                     // 注意 SDK 在 extensionsOverride 之后才补 sourceInfo，包扩展此处只能靠路径
-                    // 匹配 —— isExtensionDisabled 同时比对 npm:<pkg> 候选键。
-                    extensionsOverride: (res) => ({
-                        ...res,
-                        extensions: res.extensions.filter((e) => !isExtensionDisabled(e, this.settingsSvc.current.disabledExtensions)),
-                    }),
+                    // 匹配 —— isExtensionDisabled / isExtensionEnabled 同时比对 npm:<pkg> 候选键。
+                    extensionsOverride: (res) => {
+                        if (apply && apply.enabledExtensions.length > 0) {
+                            const set = new Set(apply.enabledExtensions);
+                            return { ...res, extensions: res.extensions.filter((e) => isExtensionEnabled(e, [...set])) };
+                        }
+                        return {
+                            ...res,
+                            extensions: res.extensions.filter((e) => !isExtensionDisabled(e, this.settingsSvc.current.disabledExtensions)),
+                        };
+                    },
                 },
             });
             const created = await createAgentSessionFromServices({
@@ -823,6 +958,9 @@ export class ClientSession {
                     // 插件注册的 AI 工具（创建时刻的实时快照；后续注册经
                     // refreshPluginTools 动态补入已有会话）。
                     ...(this.pluginToolsProvider?.() ?? []).map(pluginToolToDefinition),
+                    // 第一方子代理工具（spawn/get_result/steer/list/stop）。子代理会话
+                    // 也注册了它们，因此可自然嵌套派发。
+                    ...makeSubagentTools(this.subagentHost),
                 ],
             });
             // 终端工具开关从创建起就生效（工具始终注册进注册表，只调活跃集）。
@@ -848,6 +986,7 @@ export class ClientSession {
         return {
             id,
             title: conversationTitle(runtime.session),
+            isSubagent: false,
             runtime,
             session: runtime.session,
             cwd: runtime.cwd,
@@ -891,13 +1030,12 @@ export class ClientSession {
     notifyInterrupted(list) {
         if (!list || list.length === 0)
             return;
-        const names = list
-            .map((r) => `「${r.title}」（${r.cwd}）`)
-            .join("、");
+        const names = list.map((r) => `「${r.title}」（${r.cwd}）`).join("、");
         this.pendingNotices.push({
             type: "notice",
             level: "warning",
             text: `上次服务重启时有 ${list.length} 个进行中的对话被中断：${names}。可在历史对话中恢复继续。`,
+            textEn: `${list.length} running conversation(s) were interrupted by the last restart: ${names}. Resume them from History.`,
         });
     }
     /** Add a socket to this client's broadcast set; flushes buffered startup notices. */
@@ -949,6 +1087,7 @@ export class ClientSession {
     emit(msg) {
         if (this.disposed)
             return;
+        // eslint-disable-next-line unicorn/no-useless-spread -- snapshot: handlers may unsubscribe mid-emit
         for (const sink of [...this.sinks])
             sink(msg);
     }
@@ -991,15 +1130,14 @@ export class ClientSession {
                 return;
             const now = Date.now();
             for (const conv of this.convs.values()) {
-                if (!conv.stallNoticed &&
-                    conv.session.isStreaming &&
-                    now - conv.lastSdkEventAt > STALL_NOTIFY_MS) {
+                if (!conv.stallNoticed && conv.session.isStreaming && now - conv.lastSdkEventAt > STALL_NOTIFY_MS) {
                     conv.stallNoticed = true;
                     const mins = Math.round((now - conv.lastSdkEventAt) / 60_000);
                     this.emit({
                         type: "notice",
                         level: "warning",
                         text: `对话「${conv.title}」已 ${mins} 分钟无任何响应，可能已失联（网络中断或服务端挂起）。可点击停止后重试。`,
+                        textEn: `Conversation "${conv.title}" has been silent for ${mins} min — possibly disconnected (network or hung server). Stop it and retry.`,
                     });
                 }
             }
@@ -1018,6 +1156,7 @@ export class ClientSession {
                 type: "notice",
                 level: "warning",
                 text: `工具执行超过 ${Math.round(TOOL_WATCHDOG_TIMEOUT_MS / 60_000)} 分钟，已自动终止（防止挂死）。可调整超时：环境变量 PI_WEB_TOOL_TIMEOUT_MS（毫秒）。`,
+                textEn: `Tool ran over ${Math.round(TOOL_WATCHDOG_TIMEOUT_MS / 60_000)} min and was auto-terminated (hang guard). Tune via PI_WEB_TOOL_TIMEOUT_MS (ms).`,
             });
             conv.toolStartTimes.delete(toolCallId);
             // Abort the run (kills the process tree via the SDK's abort signal);
@@ -1107,9 +1246,7 @@ export class ClientSession {
                     const content = event.result?.content;
                     const text = Array.isArray(content)
                         ? content
-                            .map((c) => (typeof c === "object" &&
-                            c !== null &&
-                            c.type === "text")
+                            .map((c) => typeof c === "object" && c !== null && c.type === "text"
                             ? (c.text ?? "")
                             : "")
                             .join("\n")
@@ -1153,6 +1290,7 @@ export class ClientSession {
                     type: "notice",
                     level: "info",
                     text: "正在压缩上下文…（压缩摘要将显示在消息区）",
+                    textEn: "Compacting context… (the summary will appear in the message list)",
                 });
                 break;
             }
@@ -1162,6 +1300,7 @@ export class ClientSession {
                         type: "notice",
                         level: "error",
                         text: `压缩上下文失败：${event.errorMessage}`,
+                        textEn: `Context compaction failed: ${event.errorMessage}`,
                     });
                 }
                 else if (event.aborted) {
@@ -1169,6 +1308,7 @@ export class ClientSession {
                         type: "notice",
                         level: "warning",
                         text: "压缩上下文已取消",
+                        textEn: "Context compaction cancelled",
                     });
                 }
                 else if (event.result) {
@@ -1178,6 +1318,7 @@ export class ClientSession {
                         type: "notice",
                         level: "info",
                         text: `上下文压缩完成：${tokensBefore.toLocaleString()} → ${after.toLocaleString()} tokens（摘要已插入消息区）`,
+                        textEn: `Context compacted: ${tokensBefore.toLocaleString()} → ${after.toLocaleString()} tokens (summary inserted into the message list)`,
                     });
                 }
                 break;
@@ -1263,9 +1404,7 @@ export class ClientSession {
         // Snapshot checkpoint policy: deltas carry live rendering during streaming;
         // full snapshots are reconciliation checkpoints taken immediately at
         // run/tool boundaries and on a slow timer otherwise.
-        if (event.type === "agent_end" ||
-            event.type === "tool_execution_end" ||
-            event.type === "compaction_end") {
+        if (event.type === "agent_end" || event.type === "tool_execution_end" || event.type === "compaction_end") {
             this.flushSnapshot();
         }
         else {
@@ -1309,9 +1448,7 @@ export class ClientSession {
         // timestamp alone collides in the cache and only the first one renders
         // — append a cheap content fingerprint to keep them distinct while
         // staying stable across snapshots (content never changes once persisted).
-        const key = m.role === "toolResult"
-            ? `t:${m.toolCallId}`
-            : `${m.role}:${m.timestamp}:${contentFingerprint(m)}`;
+        const key = m.role === "toolResult" ? `t:${m.toolCallId}` : `${m.role}:${m.timestamp}:${contentFingerprint(m)}`;
         let n = conv.msgIds.get(key);
         if (n === undefined) {
             n = conv.nextMsgId++;
@@ -1407,9 +1544,7 @@ export class ClientSession {
             // (the SDK only pushes it into state.messages at message_end). Surfacing
             // it here is what makes thinking + text stream into the browser at
             // ~60ms granularity instead of appearing only when the turn finishes.
-            streamingMessage: state.streamingMessage
-                ? serializeStreamingMessage(state.streamingMessage)
-                : null,
+            streamingMessage: state.streamingMessage ? serializeStreamingMessage(state.streamingMessage) : null,
             isStreaming: this.session.isStreaming,
             model: model
                 ? {
@@ -1447,10 +1582,7 @@ export class ClientSession {
             return;
         const cur = this.currentMessages();
         const prev = this.emittedMessages;
-        let incremental = !forceFull &&
-            prev !== null &&
-            this.emittedConvId === this.activeId &&
-            prev.length <= cur.length;
+        let incremental = !forceFull && prev !== null && this.emittedConvId === this.activeId && prev.length <= cur.length;
         if (incremental && prev) {
             for (let i = 0; i < prev.length; i++) {
                 if (prev[i] !== cur[i]) {
@@ -1646,10 +1778,7 @@ export class ClientSession {
      * within UPDATE_ALL_CACHE_MS; pass force=true (explicit refresh) to bypass.
      */
     async checkUpdatesAll(force = false) {
-        if (!force &&
-            this.updatesAllCache &&
-            Date.now() - this.updatesAllCache.at <
-                ClientSession.UPDATE_ALL_CACHE_MS) {
+        if (!force && this.updatesAllCache && Date.now() - this.updatesAllCache.at < ClientSession.UPDATE_ALL_CACHE_MS) {
             this.emit({
                 type: "update_status_all",
                 items: this.updatesAllCache.items,
@@ -1686,6 +1815,7 @@ export class ClientSession {
                 type: "notice",
                 level: "info",
                 text: "正在安装 pi agent CLI（npm i -g @earendil-works/pi-coding-agent）…",
+                textEn: "Installing pi agent CLI (npm i -g @earendil-works/pi-coding-agent)…",
             });
             const { code, out } = await this.runAsync("npm", ["i", "-g", "@earendil-works/pi-coding-agent"], 180_000);
             if (code === 0) {
@@ -1693,6 +1823,7 @@ export class ClientSession {
                     type: "notice",
                     level: "info",
                     text: "✅ pi agent CLI 安装完成。填入 API 密钥即可开始，或在终端运行 pi 完成登录。",
+                    textEn: "✅ pi agent CLI installed. Enter an API key to start, or run pi in a terminal to log in.",
                 });
                 this.emit({ type: "install_result", ok: true, detail: "" });
             }
@@ -1701,6 +1832,7 @@ export class ClientSession {
                     type: "notice",
                     level: "error",
                     text: `pi agent 安装失败（${code ?? "timeout"}）：${out.slice(0, 400)}`,
+                    textEn: `pi agent install failed (${code ?? "timeout"}): ${out.slice(0, 400)}`,
                 });
                 this.emit({
                     type: "install_result",
@@ -1714,6 +1846,7 @@ export class ClientSession {
                 type: "notice",
                 level: "error",
                 text: `pi agent 安装失败：${err.message}`,
+                textEn: `pi agent install failed: ${err.message}`,
             });
         }
         // The CLI may just have landed on PATH (or the install may have failed) —
@@ -1738,9 +1871,7 @@ export class ClientSession {
         // During active streaming the deltas carry live rendering — full snapshots
         // are just a periodic reconciliation checkpoint, so send them far less
         // often (they serialize the whole session; big sessions made this path OOM).
-        const interval = Date.now() - this.lastDeltaAt < DELTA_ACTIVE_WINDOW_MS
-            ? STREAMING_SNAPSHOT_INTERVAL_MS
-            : SNAPSHOT_INTERVAL_MS;
+        const interval = Date.now() - this.lastDeltaAt < DELTA_ACTIVE_WINDOW_MS ? STREAMING_SNAPSHOT_INTERVAL_MS : SNAPSHOT_INTERVAL_MS;
         this.snapshotTimer = setTimeout(() => {
             this.snapshotTimer = null;
             this.emitSnapshotNow();
@@ -1775,6 +1906,7 @@ export class ClientSession {
                     type: "notice",
                     level: "error",
                     text: `插件命令 /${name} 执行失败：${err.message}`,
+                    textEn: `Plugin command /${name} failed: ${err.message}`,
                 });
             }
             return true;
@@ -1963,6 +2095,14 @@ export class ClientSession {
     async deletePreset(name) {
         return this.settingsSvc.deletePreset(name);
     }
+    /** Upsert 一个子代理模板（全局共享）。 */
+    async saveSubagentTemplate(template) {
+        return this.settingsSvc.saveTemplate(template);
+    }
+    /** 删除一个子代理模板。 */
+    async deleteSubagentTemplate(name) {
+        return this.settingsSvc.deleteTemplate(name);
+    }
     /** Make settings effective in the running runtime（流式中则延迟到 agent_end）。 */
     async applyRuntimeSettings() {
         return this.settingsSvc.applyRuntime();
@@ -2023,6 +2163,7 @@ export class ClientSession {
             type: "notice",
             level: "error",
             text: "服务器正在排空存量工作（quiesce），已拒绝新的对话/消息/编辑。存量运行会继续跑完；用 pi-web-ui server unquiesce 可恢复。",
+            textEn: "Server is draining (quiesce) and rejected the new chat/message/edit. Existing runs continue; resume with pi-web-ui server unquiesce.",
         });
         this.flushSnapshot();
         return true;
@@ -2086,8 +2227,7 @@ export class ClientSession {
             // re-derives it from the persisted transcript when needed.
             if (conv.title === DEFAULT_CONV_TITLE && text.trim()) {
                 const trimmed = text.trim().replace(/\s+/g, " ");
-                conv.title =
-                    trimmed.length > 30 ? `${trimmed.slice(0, 30)}…` : trimmed;
+                conv.title = trimmed.length > 30 ? `${trimmed.slice(0, 30)}…` : trimmed;
                 this.emitConversations();
             }
             // Attach files as independent nextTurn context messages (asides) so the
@@ -2126,6 +2266,7 @@ export class ClientSession {
                 type: "notice",
                 level: "error",
                 text: `提示发送失败：${err.message}`,
+                textEn: `Failed to send prompt: ${err.message}`,
             });
         }
         // The active conversation (captured at prompt start — see above) has been
@@ -2206,6 +2347,7 @@ export class ClientSession {
                     type: "notice",
                     level: "error",
                     text: `重新入队插队消息失败：${err.message}`,
+                    textEn: `Failed to re-queue the steer message: ${err.message}`,
                 });
             }
         }
@@ -2218,6 +2360,7 @@ export class ClientSession {
                     type: "notice",
                     level: "error",
                     text: `重新入队排队消息失败：${err.message}`,
+                    textEn: `Failed to re-queue the queued message: ${err.message}`,
                 });
             }
         }
@@ -2246,6 +2389,7 @@ export class ClientSession {
                     type: "notice",
                     level: "info",
                     text: `后台任务「${taskId}」不存在或已结束`,
+                    textEn: `Background task "${taskId}" does not exist or has ended`,
                 });
             }
             this.bg.push();
@@ -2270,16 +2414,19 @@ export class ClientSession {
                 type: "notice",
                 level: "info",
                 text: "当前没有正在运行的 bash 命令",
+                textEn: "No bash command is running",
             });
             this.flushSnapshot();
             return;
         }
+        // eslint-disable-next-line unicorn/no-useless-spread -- snapshot: handlers may unsubscribe mid-emit
         for (const ac of [...this.bashKills])
             ac.abort();
         this.emit({
             type: "notice",
             level: "info",
             text: "已停止 bash 命令（对话继续）",
+            textEn: "Bash command stopped (conversation continues)",
         });
         // 让 AI 明确知道是用户手动停止：sendUserMessage 触发下一轮，agent
         // 会看到「命令被用户中止」而不是普通失败，并据此继续（不会困惑于
@@ -2328,6 +2475,7 @@ export class ClientSession {
                 type: "notice",
                 level: "error",
                 text: `中止失败：${err.message}`,
+                textEn: `Abort failed: ${err.message}`,
             });
         }
         // 3) abort returned but no agent_end within the settle window → the
@@ -2368,6 +2516,7 @@ export class ClientSession {
                 type: "notice",
                 level: "error",
                 text: `强制中断失败：${err.message}`,
+                textEn: `Force-stop failed: ${err.message}`,
             });
         }
     }
@@ -2410,6 +2559,7 @@ export class ClientSession {
                 type: "notice",
                 level: "warning",
                 text: `当前项目运行的对话已达上限（${MAX_OPEN_CONVERSATIONS} 个），请先打开某个对话并离开（不继续对话）以移出列表`,
+                textEn: `This project already has the max open conversations (${MAX_OPEN_CONVERSATIONS}). Open one and leave it (without continuing) to remove it from the list.`,
             });
             return;
         }
@@ -2462,6 +2612,7 @@ export class ClientSession {
                 type: "notice",
                 level: "error",
                 text: `新建对话失败：${err.message}`,
+                textEn: `Failed to create chat: ${err.message}`,
             });
         }
         this.flushSnapshot();
@@ -2489,6 +2640,12 @@ export class ClientSession {
         // Also retain when a non-expired pi-subagents wait-subscription record
         // exists on disk for this session: a finished background subagent run
         // still owes this conversation a wake-up turn.
+        // 更靠前的阶段：run 本身还在 queued/running（workflow 编排中）时释放
+        // runtime 同样杀死扩展宿主并 abort 所有 live workflow controller，比
+        // wake 订阅早一步——磁盘 .active-runs marker + status.json 探测（pi-web-ui #52）。
+        // Retain while the session has active (queued/running) pi-subagents async
+        // runs on disk — the extension host would otherwise be torn down and its
+        // workflow controllers aborted mid-flight.
         const retained = shouldRetainActive({
             reviewing: conv.goal.reviewing,
             wizardRunning: conv.wizardRunning,
@@ -2496,6 +2653,7 @@ export class ClientSession {
             openTerminals: conv.terminals.list().length,
             listed: conv.listed,
             promptedSinceActive: conv.promptedSinceActive,
+            hasActiveSubagentRun: () => hasActiveSubagentRun({ sessionId: conv.session.sessionFile }),
             hasPendingWake: () => hasPendingWaitSubscription({ sessionId: conv.session.sessionFile }),
         });
         if (retained) {
@@ -2585,6 +2743,7 @@ export class ClientSession {
                 cwd: conv.cwd,
                 messageCount,
                 isStreaming,
+                isSubagent: !!conv.isSubagent,
             });
         }
         this.emit({
@@ -2650,9 +2809,7 @@ export class ClientSession {
                     source: "web",
                 });
             }
-            const sorted = [...sessions.values()]
-                .sort((a, b) => b.modified - a.modified)
-                .slice(0, 200); // newest first — the panel shows recent history
+            const sorted = [...sessions.values()].sort((a, b) => b.modified - a.modified).slice(0, 200); // newest first — the panel shows recent history
             this.emit({ type: "sessions", sessions: sorted });
         }
         catch {
@@ -2685,6 +2842,7 @@ export class ClientSession {
                     type: "notice",
                     level: "error",
                     text: "只能删除会话目录中的对话记录",
+                    textEn: "Only transcripts inside the session directory can be deleted",
                 });
                 return;
             }
@@ -2703,6 +2861,7 @@ export class ClientSession {
                     type: "notice",
                     level: "warning",
                     text: "该对话正在后台运行，请先停止或关闭该对话再删除",
+                    textEn: "This conversation is still running — stop or close it before deleting",
                 });
                 return;
             }
@@ -2755,9 +2914,68 @@ export class ClientSession {
                 type: "notice",
                 level: "error",
                 text: `删除会话失败：${err.message}`,
+                textEn: `Failed to delete session: ${err.message}`,
             });
         }
     }
+    /** Dismiss a running conversation from the left-panel list without deleting its
+     *  transcript file. Only idle (non-streaming) conversations that are not
+     *  retained by terminal/wake/review state can be dismissed. The session stays
+     *  in history and can be reopened. */
+    async dismissConversation(id) {
+        const conv = this.convs.get(id);
+        if (!conv) {
+            this.emit({ type: "notice", level: "warning", text: "该对话不存在或已关闭" });
+            return;
+        }
+        if (id === this.activeId) {
+            this.emit({ type: "notice", level: "warning", text: "当前对话不能直接移出，请先切换到其他对话" });
+            return;
+        }
+        if (!conv.listed) {
+            // Not in list anyway — nothing to do.
+            this.emitConversations();
+            return;
+        }
+        // Streaming / retained conversations refuse dismissal — mirrors displaceActive retention.
+        const retained = shouldRetainActive({
+            reviewing: conv.goal.reviewing,
+            wizardRunning: conv.wizardRunning,
+            streaming: conv.session.isStreaming,
+            openTerminals: conv.terminals.list().length,
+            listed: conv.listed,
+            promptedSinceActive: conv.promptedSinceActive,
+            hasActiveSubagentRun: () => hasActiveSubagentRun({ sessionId: conv.session.sessionFile }),
+            hasPendingWake: () => hasPendingWaitSubscription({ sessionId: conv.session.sessionFile }),
+        });
+        if (retained) {
+            if (conv.session.isStreaming) {
+                this.emit({
+                    type: "notice",
+                    level: "warning",
+                    text: `对话「${conv.title}」仍在运行中，请先等待结束或点击停止后再移出`,
+                });
+            }
+            else if (conv.terminals.list().length > 0) {
+                this.emit({
+                    type: "notice",
+                    level: "warning",
+                    text: `对话「${conv.title}」还有未关闭的终端，请先关闭终端后再移出`,
+                });
+            }
+            else {
+                this.emit({
+                    type: "notice",
+                    level: "warning",
+                    text: `对话「${conv.title}」暂时无法移出（存在待处理的后台任务/审查）`,
+                });
+            }
+            return;
+        }
+        this.removeConversation(id);
+        this.emitConversations();
+        this.flushSnapshot();
+    }
     /** Open a persisted session as the active conversation (from listSessions).
      *
      * A persisted-session click must follow the same ownership rule as
@@ -2795,9 +3013,7 @@ export class ClientSession {
             // is known-good. This keeps a failed history open entirely non-destructive.
             const oldListed = this.conv.listed;
             const displaced = this.displaceActive();
-            const openInProject = [...this.convs.values()].filter((c) => c.cwd === targetCwd).length +
-                1 -
-                (displaced?.cwd === targetCwd ? 1 : 0);
+            const openInProject = [...this.convs.values()].filter((c) => c.cwd === targetCwd).length + 1 - (displaced?.cwd === targetCwd ? 1 : 0);
             if (openInProject > MAX_OPEN_CONVERSATIONS) {
                 // displaceActive() may have promoted a streaming conversation into the
                 // running list. Roll that presentation-only mutation back because no
@@ -2811,6 +3027,7 @@ export class ClientSession {
                     type: "notice",
                     level: "warning",
                     text: `当前项目运行的对话已达上限（${MAX_OPEN_CONVERSATIONS} 个），请先打开某个对话并离开（不继续对话）以移出列表`,
+                    textEn: `This project already has the max open conversations (${MAX_OPEN_CONVERSATIONS}). Open one and leave it (without continuing) to remove it from the list.`,
                 });
                 return;
             }
@@ -2844,6 +3061,7 @@ export class ClientSession {
                 type: "notice",
                 level: "error",
                 text: `切换会话失败：${err.message}`,
+                textEn: `Failed to switch session: ${err.message}`,
             });
         }
         this.flushSnapshot();
@@ -2896,6 +3114,7 @@ export class ClientSession {
                 type: "notice",
                 level: "warning",
                 text: "编辑内容为空，已取消",
+                textEn: "Edited content is empty — cancelled",
             });
             this.flushSnapshot();
             return;
@@ -2906,6 +3125,7 @@ export class ClientSession {
                 type: "notice",
                 level: "error",
                 text: "找不到要编辑的消息（可能已被压缩或不在当前分支）",
+                textEn: "Message to edit not found (may have been compacted or is on another branch)",
             });
             this.flushSnapshot();
             return;
@@ -2920,6 +3140,7 @@ export class ClientSession {
                     type: "notice",
                     level: "info",
                     text: "已取消编辑重问",
+                    textEn: "Edit-and-reask cancelled",
                 });
                 this.flushSnapshot();
                 return;
@@ -2941,6 +3162,7 @@ export class ClientSession {
                 type: "notice",
                 level: "info",
                 text: "已从该问题重新提问（原对话保留在会话列表中）",
+                textEn: "Re-asked from that question (the original stays in the session list)",
             });
         }
         catch (err) {
@@ -2948,6 +3170,7 @@ export class ClientSession {
                 type: "notice",
                 level: "error",
                 text: `编辑重问失败：${err.message}`,
+                textEn: `Edit-and-reask failed: ${err.message}`,
             });
         }
         this.flushSnapshot();
@@ -3059,6 +3282,7 @@ export class ClientSession {
                 type: "notice",
                 level: "error",
                 text: `切换模型失败：${err.message}`,
+                textEn: `Failed to switch model: ${err.message}`,
             });
         }
         this.flushSnapshot();
@@ -3085,6 +3309,7 @@ export class ClientSession {
                     type: "notice",
                     level: "info",
                     text: `已在工作目录：${abs}`,
+                    textEn: `Already in directory: ${abs}`,
                 });
                 this.flushSnapshot();
                 return;
@@ -3098,8 +3323,7 @@ export class ClientSession {
             // project has none open yet.
             let target;
             for (const c of this.convs.values()) {
-                if (c.cwd === abs &&
-                    (!target || c.lastActiveAt > target.lastActiveAt)) {
+                if (c.cwd === abs && (!target || c.lastActiveAt > target.lastActiveAt)) {
                     target = c;
                 }
             }
@@ -3154,6 +3378,7 @@ export class ClientSession {
                 type: "notice",
                 level: "info",
                 text: `已切换到工作目录：${abs}`,
+                textEn: `Switched to directory: ${abs}`,
             });
             void this.refreshSessions();
             void this.listFiles(undefined);
@@ -3165,6 +3390,7 @@ export class ClientSession {
                 type: "notice",
                 level: "error",
                 text: `切换工作目录失败：${err.message}`,
+                textEn: `Failed to switch directory: ${err.message}`,
             });
         }
         this.flushSnapshot();
@@ -3188,6 +3414,7 @@ export class ClientSession {
                 type: "notice",
                 level: "error",
                 text: `获取模型列表失败：${err.message}`,
+                textEn: `Failed to fetch model list: ${err.message}`,
             });
         }
     }
@@ -3245,6 +3472,7 @@ export class ClientSession {
                 type: "notice",
                 level: "error",
                 text: `切换模型失败：${err.message}`,
+                textEn: `Failed to switch model: ${err.message}`,
             });
         }
         this.flushSnapshot();
@@ -3259,6 +3487,7 @@ export class ClientSession {
                 type: "notice",
                 level: "error",
                 text: `切换思考强度失败：${err.message}`,
+                textEn: `Failed to switch thinking level: ${err.message}`,
             });
         }
         this.flushSnapshot();
@@ -3272,6 +3501,7 @@ export class ClientSession {
                 type: "notice",
                 level: "error",
                 text: `切换思考强度失败：${err.message}`,
+                textEn: `Failed to switch thinking level: ${err.message}`,
             });
         }
         this.flushSnapshot();
@@ -3292,7 +3522,7 @@ export class ClientSession {
             return;
         }
         this.emit({ type: "commands", commands, path });
-        this.emit({ type: "notice", level: "info", text: `命令已保存：${path}` });
+        this.emit({ type: "notice", level: "info", text: `命令已保存：${path}`, textEn: `Command saved: ${path}` });
     }
     async dispose() {
         this.disposed = true;
@@ -3380,9 +3610,7 @@ export class AgentService {
     }
     /** Snapshot for the control socket / status command. */
     quiesceInfo() {
-        return this.quiesced
-            ? { quiesced: true, quiescedSince: this.quiescedAt }
-            : { quiesced: false };
+        return this.quiesced ? { quiesced: true, quiescedSince: this.quiescedAt } : { quiesced: false };
     }
     /** Aggregate across every client session: conversations with in-flight runs. */
     activeConversations() {
@@ -3460,6 +3688,7 @@ export class AgentService {
                         type: "notice",
                         level: "info",
                         text: `已恢复上次的工作目录：${cwd}`,
+                        textEn: `Restored the last working directory: ${cwd}`,
                     });
                 }
             }
@@ -3508,6 +3737,7 @@ export class AgentService {
     async disposeAll() {
         // Record still-streaming conversations BEFORE tearing anything down, so
         // the next attach can tell the user what was lost (SIGTERM / update).
+        // eslint-disable-next-line unicorn/no-useless-spread -- snapshot: handlers may unsubscribe mid-emit
         for (const [clientId, cs] of [...this.clients]) {
             try {
                 const running = cs.streamingSummaries();