pi-web-ui 0.91.0 → 0.93.0

package/dist/server/resolve-global-sdk.js

@@ -0,0 +1,72 @@
+/**
+ * resolve-global-sdk — 可选的「优先用全局/祖先那份 pi SDK」解析钩子（issue #260）。
+ *
+ * 背景：pi-web-ui 依赖 `@earendil-works/pi-coding-agent`，而 npm 全局安装会把依赖
+ * **嵌在** `<npm root -g>/pi-web-ui/node_modules/`（不 hoist，实测），Node 又「嵌套优先于
+ * 祖先」—— 于是用户 `npm i -g @earendil-works/pi-coding-agent@latest` 改的是全局那份，
+ * 服务加载的仍是自带那份，表现为「升了 0.86.1，横幅和 /api/health 还显示 0.85.1」。
+ *
+ * 本模块把解析顺序反过来，但**只在显式开启时**：
+ *
+ *   PI_WEB_SDK=global   → 祖先链上存在一份版本**更新**的 SDK 时，把裸标识符重定向到它；
+ *                         否则原样不动（同版本也不折腾 —— 没意义）。
+ *   （缺省 / 其它值）    → 什么都不做，用自带副本。
+ *
+ * 为什么默认关：服务运行的 SDK 版本会变成「用户机器上装了什么」，同一个 pi-web-ui 版本在
+ * 不同机器上跑不同 SDK，报 bug 时无法复现；自带副本可复现、且是 CI 覆盖的那一份。
+ *
+ * 为什么只做「必须更新」这一道门：仓库没有 semver 依赖，手写完整范围解析容易出错，
+ * 「祖先那份比自带那份新」是保守且够用的判据（旧的 / 同版本的都不采用）。
+ *
+ * 安全约定：整个注册流程包在 try/catch 里，任何异常都退回默认解析 —— 这个模块**绝不允许**
+ * 让服务起不来。它必须在任何 SDK 静态 import **之前**被加载（`--import <本文件>`，
+ * 或前台启动时在 import 服务入口之前先 import 它）。
+ */
+import { registerHooks } from "node:module";
+import { pathToFileURL } from "node:url";
+import { compareVersions, sdkCopies } from "./sdk-origin.js";
+const PKG = "@earendil-works/pi-coding-agent";
+/**
+ * 该用哪一份对外解析（纯函数，便于单测）。
+ * `copies` 按 Node 的解析顺序（[0] = 自带的、实际会被用到的），返回 null = 保持默认。
+ */
+export function pickGlobalSdk(copies, mode) {
+    if ((mode ?? "bundled").trim().toLowerCase() !== "global")
+        return null;
+    const bundled = copies[0];
+    // 只考虑祖先链上的副本，且必须是**更新**的（旧的或同版本都不折腾）。
+    return copies.slice(1).find((c) => !bundled || compareVersions(c.version, bundled.version) > 0) ?? null;
+}
+/** 注册钩子；返回实际选中的副本（null = 没启用 / 没找到可用的）。 */
+export function registerGlobalSdkPreference(mode = process.env.PI_WEB_SDK, fromFile = import.meta.url) {
+    try {
+        const copies = sdkCopies(fromFile);
+        const chosen = pickGlobalSdk(copies, mode);
+        if (!chosen)
+            return null;
+        registerHooks({
+            resolve(specifier, context, nextResolve) {
+                if (specifier !== PKG)
+                    return nextResolve(specifier, context);
+                // 以目标副本的 package.json 为父重新解析：Node 从那里往上找，
+                // 第一个命中的就是它自己 —— 等价于「从那个包内部 import 自己」。
+                try {
+                    return nextResolve(specifier, { ...context, parentURL: pathToFileURL(chosen.path).href });
+                }
+                catch {
+                    return nextResolve(specifier, context);
+                }
+            },
+        });
+        return chosen;
+    }
+    catch {
+        // 钩子注册失败（Node 太老 / 环境怪异）→ 静默退回默认解析，绝不影响启动。
+        return null;
+    }
+}
+// ---- 副作用：被 `--import` 加载时立刻生效 --------------------------------
+const used = registerGlobalSdkPreference();
+if (used) {
+    console.log(`[pi-web-ui] PI_WEB_SDK=global → using the pi SDK at ${used.path} (v${used.version})`);
+}

package/dist/server/sdk-origin.js

@@ -0,0 +1,64 @@
+/**
+ * sdk-origin — 本进程实际加载的是哪一份 pi SDK，以及被它遮蔽的副本（issue #260）。
+ *
+ * 背景：npm 全局安装会把依赖**嵌在** `<npm root -g>/pi-web-ui/node_modules/`（不 hoist，
+ * 实测），而 Node 的解析顺序是「嵌套优先于祖先」。于是用户按更新面板/README 的提示
+ * `npm i -g @earendil-works/pi-coding-agent@latest` 升级全局那份时，服务实际加载的
+ * 仍是自带副本 —— 表现为「升了 0.86.1，横幅和 /api/health 还显示 0.85.1」。
+ *
+ * 这里把「所有能被解析到的副本」按 Node 的顺序算出来（[0] = 生效的那份），
+ * 让启动横幅与健康检查说实话，而不是让用户去猜。
+ *
+ * 纯函数 + 零副作用，便于单测（见 tests/unit/sdk-origin.test.ts）。
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+const PKG = "@earendil-works/pi-coding-agent";
+/** 从某个文件出发，逐级向上查找 `<dir>/node_modules/<pkg>/package.json`。
+ *  `fromFile` 收 URL（`import.meta.url`）或普通文件路径（便于单测）。 */
+export function sdkCopies(fromFile = import.meta.url) {
+    const out = [];
+    let dir = dirname(fromFile.startsWith("file:") ? fileURLToPath(fromFile) : fromFile);
+    for (;;) {
+        const pj = join(dir, "node_modules", PKG, "package.json");
+        if (existsSync(pj)) {
+            try {
+                const version = JSON.parse(readFileSync(pj, "utf8")).version;
+                if (typeof version === "string" && version)
+                    out.push({ path: pj, version });
+            }
+            catch {
+                // 坏 JSON：跳过这一份，不影响其它候选（best-effort，同 process-utils 的口径）
+            }
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return out;
+}
+/** 点分版本号比较（够用即可：只比数字段，缺位当 0）。 */
+export function compareVersions(a, b) {
+    const pa = a.split(".");
+    const pb = b.split(".");
+    for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+        const na = Number.parseInt(pa[i] ?? "0", 10) || 0;
+        const nb = Number.parseInt(pb[i] ?? "0", 10) || 0;
+        if (na !== nb)
+            return na < nb ? -1 : 1;
+    }
+    return 0;
+}
+/**
+ * 启动横幅要打印的一行（不含前缀），以及是否需要提示「你升的不是服务在用的那份」。
+ * `effective` 为空时（没找到副本）返回空串，调用方照旧只打印版本号。
+ */
+export function sdkOriginNote(copies, effectiveVersion) {
+    const shadowed = copies.slice(1);
+    const newer = shadowed.filter((c) => compareVersions(c.version, effectiveVersion) > 0);
+    if (newer.length === 0)
+        return null;
+    return `a newer pi SDK is installed elsewhere (${newer.map((c) => `v${c.version}`).join(", ")}) but pi-web-ui runs its own bundled copy (v${effectiveVersion}).`;
+}

package/dist/server/serialize.js

@@ -1,35 +1,59 @@
 const TEXT_CAP = 200_000;
 const TOOL_OUTPUT_CAP = 100_000;
 const ARGS_CAP = 20_000;
+/**
+ * toolResult 里单张图片进快照的上限（dataUrl 字符数 ≈ 1.5MB 二进制）。
+ * 视口/元素截图随便过；超大整页截图回落成占位文本（模型侧不受影响 —— 图它
+ * 已经看过，只是浏览器这边的缩略图不带）。超限截断 base64 会得到一张坏图，
+ * 所以是整张丢、不是截一半。
+ */
+const TOOL_RESULT_IMAGE_CAP = 2_000_000;
+/** 单条 toolResult 最多带几张图进快照（防图片刷屏把快照撑爆）。 */
+const TOOL_RESULT_IMAGE_MAX = 8;
+/**
+ * toolResult.details 的体积上限。details 是给 UI 用的结构化元数据（如
+ * present_files 的卡片数据、ask_user_question 的答案），快照每 60ms 推一次，
+ * 不能无节制。超过上限时**整个丢掉**（而不是截断 —— 截断后的 JSON 不可解析，
+ * 前端还得写容错）；工具作者应自己封顶（见 present-files-tool.ts 的摘录预算）。
+ */
+const TOOL_DETAILS_CAP = 64_000;
 function truncate(s, cap) {
     if (s.length <= cap)
         return { text: s, truncated: false };
     return { text: `${s.slice(0, cap)}\n\n… [truncated]`, truncated: true };
 }
+/**
+ * SDK/工具的图片块 → 前端可直接 <img> 的 UiImageBlock。
+ * Canonical ImageContent shape is { type, data, mimeType }; tolerate the
+ * legacy { source } wrapper too.
+ * cap: dataUrl 超过该字符数回 undefined（调用方按占位文本处理）；默认不限
+ * （用户粘贴图走 image-paste 的缩放管线，尺寸本来就有界）。
+ */
+function imageBlockToUi(b, cap = Number.POSITIVE_INFINITY) {
+    const img = b;
+    if (typeof img.data === "string" && img.data.length > 0) {
+        const dataUrl = `data:${img.mimeType ?? "image/png"};base64,${img.data}`;
+        if (dataUrl.length > cap)
+            return undefined;
+        return { type: "image", dataUrl, mimeType: img.mimeType };
+    }
+    const src = img.source;
+    if (src?.type === "base64" && src.data) {
+        const dataUrl = `data:${src.mediaType ?? "image/png"};base64,${src.data}`;
+        if (dataUrl.length > cap)
+            return undefined;
+        return { type: "image", dataUrl, mimeType: src.mediaType };
+    }
+    if (typeof src?.url === "string" && src.url)
+        return { type: "image", dataUrl: src.url };
+    return undefined;
+}
 function serializeUserContent(content) {
     if (typeof content === "string")
         return [{ type: "text", text: content }];
     return content.map((b) => {
         if (b.type === "image") {
-            const img = b;
-            // Canonical ImageContent shape is { type, data, mimeType }; tolerate the
-            // legacy { source } wrapper too.
-            if (typeof img.data === "string" && img.data.length > 0) {
-                return {
-                    type: "image",
-                    dataUrl: `data:${img.mimeType ?? "image/png"};base64,${img.data}`,
-                    mimeType: img.mimeType,
-                };
-            }
-            const src = img.source;
-            if (src?.type === "base64" && src.data) {
-                return {
-                    type: "image",
-                    dataUrl: `data:${src.mediaType ?? "image/png"};base64,${src.data}`,
-                    mimeType: src.mediaType,
-                };
-            }
-            return { type: "image", dataUrl: src?.url };
+            return imageBlockToUi(b) ?? { type: "image", dataUrl: undefined };
         }
         return { type: "text", text: String(b.text ?? "") };
     });
@@ -100,21 +124,55 @@ export function serializeMessage(m, seq) {
                 timestamp: m.timestamp,
                 model: m.model,
                 provider: m.provider,
+                usageCost: typeof m.usage?.cost?.total === "number" ? m.usage.cost.total : undefined,
                 stopReason: m.stopReason,
                 errorMessage: m.errorMessage,
             };
         case "toolResult": {
-            const raw = m.content.map((c) => (c.type === "text" ? c.text : "[image result]")).join("\n");
+            // 工具结果里的图片（web_shot 截图、read 读到的图……）要下发浏览器：
+            // 卡片里直接显示缩略图、点开放大（见 ToolCallBlock）。以前这里统一丢成
+            // "[image result]"，用户只能看到占位文本。超限/超数的图仍回落占位文本。
+            const textParts = [];
+            const images = [];
+            for (const c of m.content) {
+                if (c.type === "text") {
+                    textParts.push(c.text);
+                    continue;
+                }
+                if (c.type === "image" && images.length < TOOL_RESULT_IMAGE_MAX) {
+                    const ui = imageBlockToUi(c, TOOL_RESULT_IMAGE_CAP);
+                    if (ui) {
+                        images.push(ui);
+                        continue;
+                    }
+                }
+                textParts.push("[image result]");
+            }
+            const raw = textParts.join("\n");
             const { text, truncated } = truncate(raw, TOOL_OUTPUT_CAP);
-            return {
+            const content = raw || images.length === 0 ? [{ type: "text", text, truncated }, ...images] : [...images];
+            const msg = {
                 id: `t-${m.toolCallId}`,
                 role: "toolResult",
-                content: [{ type: "text", text, truncated }],
+                content,
                 toolCallId: m.toolCallId,
                 toolName: m.toolName,
                 isError: m.isError,
                 timestamp: m.timestamp,
             };
+            // 结构化元数据（tool result details）也要下发：present_files 的预览卡片
+            // 就靠它拿 kind/size/excerpt（前端不能靠再打一次 HTTP 才知类型），
+            // ask_user_question/todo_list 同理。体积封顶，超限整丢（见 TOOL_DETAILS_CAP）。
+            if (m.details !== undefined) {
+                try {
+                    if (JSON.stringify(m.details).length <= TOOL_DETAILS_CAP)
+                        msg.details = m.details;
+                }
+                catch {
+                    // 循环引用等序列化不了的值：details 是附加信息，丢掉不影响消息本体。
+                }
+            }
+            return msg;
         }
         case "bashExecution": {
             const { text, truncated } = truncate(m.output, TOOL_OUTPUT_CAP);

package/dist/server/settings-service.js

@@ -9,7 +9,7 @@
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { extensionKey, normalizeDisabledPluginTools, normalizeRetryMaxAttempts, normalizeSkillList, normalizeUiLayout, } from "./client-state.js";
+import { extensionKey, normalizeDisabledPluginTools, normalizeRetryMaxAttempts, normalizeSkillList, normalizeToolWatchdogTimeoutMs, normalizeUiLayout, } from "./client-state.js";
 import { normalizeSoftCapByModel, normalizeSoftCapTokens } from "./soft-cap.js";
 import { findVisionModels, SYSTEM_PROMPT } from "./vision-bridge.js";
 import { COMMITMSG_SYSTEM_PROMPT } from "./scm-commitmsg.js";
@@ -289,6 +289,8 @@ export class SettingsService {
                 terminalToolsEnabled: legacyTools.terminalToolsEnabled,
                 terminalBash: this.settings.terminalBash,
                 terminalBashIdleMs: this.settings.terminalBashIdleMs,
+                toolWatchdogTimeoutMs: this.settings.toolWatchdogTimeoutMs,
+                readDirEnabled: this.settings.readDirEnabled !== false,
                 editSoftEnabled: legacyTools.editSoftEnabled,
                 questionnaireEnabled: legacyTools.questionnaireEnabled,
                 parallelReminderEnabled: this.settings.parallelReminderEnabled ?? true,
@@ -297,6 +299,7 @@ export class SettingsService {
                 autoReload: this.settings.autoReload ?? this.defaultDevNoCache(),
                 thinkingWrap: this.settings.thinkingWrap,
                 toolsWrap: this.settings.toolsWrap,
+                toolImagesEnabled: this.settings.toolImagesEnabled ?? true,
                 visionBridgeEnabled: this.settings.visionBridgeEnabled,
                 visionBridgeModel: this.settings.visionBridgeModel,
                 visionBridgePromptMode: this.settings.visionBridgePromptMode,
@@ -458,6 +461,13 @@ export class SettingsService {
         if (partial.terminalBashIdleMs !== undefined) {
             this.settings.terminalBashIdleMs = Math.max(0, Math.floor(partial.terminalBashIdleMs) || 0);
         }
+        if (partial.toolWatchdogTimeoutMs !== undefined) {
+            this.settings.toolWatchdogTimeoutMs = normalizeToolWatchdogTimeoutMs(partial.toolWatchdogTimeoutMs);
+        }
+        // read 读目录开关：覆盖定义每次调用实时读取，改动即时生效，无需 reload。
+        if (partial.readDirEnabled !== undefined) {
+            this.settings.readDirEnabled = partial.readDirEnabled;
+        }
         // 目标模式总开关：运行时无需重载（goal bar / 服务端入口实时读取）。
         if (partial.goalModeEnabled !== undefined) {
             this.settings.goalModeEnabled = partial.goalModeEnabled;
@@ -478,6 +488,9 @@ export class SettingsService {
         if (partial.toolsWrap !== undefined) {
             this.settings.toolsWrap = partial.toolsWrap;
         }
+        if (partial.toolImagesEnabled !== undefined) {
+            this.settings.toolImagesEnabled = partial.toolImagesEnabled;
+        }
         // 编排模式 / skill 全文注入：before_agent_start 逐 run 实时读取（agent-service
         // composeInputs + 指导块追加），开关下一轮即生效，无需 reload runtime。
         if (partial.skillsFullText !== undefined) {
@@ -623,6 +636,10 @@ export class SettingsService {
             // 终端接管偏好随预设走；旧预设缺字段时保留当前值。
             terminalBash: p.terminalBash ?? this.settings.terminalBash,
             terminalBashIdleMs: p.terminalBashIdleMs ?? this.settings.terminalBashIdleMs,
+            // read 读目录是纯运行行为开关，不进预设——保留当前值。
+            readDirEnabled: this.settings.readDirEnabled !== false,
+            // toolWatchdogTimeoutMs 是纯运行行为参数，不进预设——保留当前值。
+            toolWatchdogTimeoutMs: this.settings.toolWatchdogTimeoutMs,
             editSoftEnabled: presetLegacy.editSoftEnabled,
             // 重试次数随预设走；旧预设缺字段时保留当前值，应用后即时注入各会话。
             retryMaxAttempts: p.retryMaxAttempts ?? this.settings.retryMaxAttempts,
@@ -644,6 +661,7 @@ export class SettingsService {
             autoReload: this.settings.autoReload,
             thinkingWrap: this.settings.thinkingWrap,
             toolsWrap: this.settings.toolsWrap,
+            toolImagesEnabled: this.settings.toolImagesEnabled ?? true,
             // UI 布局偏好也不进预设——保留当前值。
             uiLayout: normalizeUiLayout(this.settings.uiLayout),
             // Presets don't capture vision-bridge prefs — keep the current ones.

package/dist/server/skill-tool.js

@@ -21,6 +21,7 @@ import { statSync, readFileSync } from "node:fs";
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { bilingual, pick } from "./i18n.js";
+import { SKILL_TOOL_NAME } from "./tool-manager.js";
 import { decodeText } from "./text-sniff.js";
 /** 单文件正文上限（与 agent-service fillSkillContents 同口径：8KB）。 */
 export const SKILL_TOOL_FILE_CAP = 8192;
@@ -58,7 +59,7 @@ export function makeSkillTool(host, lang) {
         details,
     });
     return defineTool({
-        name: "skill",
+        name: SKILL_TOOL_NAME,
         label: "Load a skill",
         description: bilingual("Load a skill's full text by its exact name (see the <available_skills> catalog in the system prompt). " +
             "Prefer this over reading the skill file with the read tool — no path guessing needed. " +

package/dist/server/subagents.js

@@ -61,7 +61,7 @@ export function subagentTitle(prompt) {
 export function withSubagentOwner(host, ownerId) {
     return {
         ...host,
-        spawnSubagent: (prompt, type, cwd, templateName, model) => host.spawnSubagent(prompt, type, cwd, templateName, model, ownerId),
+        spawnSubagent: (prompt, type, cwd, templateName, model, _parentId, persist) => host.spawnSubagent(prompt, type, cwd, templateName, model, ownerId, persist),
     };
 }
 /**
@@ -125,6 +125,11 @@ export function makeSubagentTools(host, lang, selfConvId) {
                 cwd: Type.Optional(Type.String({
                     description: bilingual("Subagent working directory (relative/absolute). Defaults to the main session's cwd.", "子代理工作目录（相对/绝对）。默认继承主会话工作目录。"),
                 })),
+                persist: Type.Optional(Type.Boolean({
+                    description: bilingual("Optional: persist this conversation to disk as a regular session (saved in history, resumable). " +
+                        "Default false (lightweight in-memory subagent). Use true for tasks that need long-term retention or human follow-up.", "可选：是否将该对话持久化落盘为普通对话（保存在历史会话中，可随时回顾与继续）。" +
+                        "默认 false（轻量内存子代理）。需要长期留存或后续人工跟进的任务建议设为 true。"),
+                })),
             }),
             execute: async (_id, p, _signal, _onUpdate, ctx) => {
                 if (p.template && !host.isTemplateUsable(p.template)) {
@@ -134,7 +139,7 @@ export function makeSubagentTools(host, lang, selfConvId) {
                 // host 抛错）：转成返回文本而不是直接抛，让 AI 能读到原因并调整重试。
                 let convId;
                 try {
-                    convId = await host.spawnSubagent(p.prompt, p.type ?? "general", p.cwd ?? ctx.cwd, p.template, p.model);
+                    convId = await host.spawnSubagent(p.prompt, p.type ?? "general", p.cwd ?? ctx.cwd, p.template, p.model, undefined, p.persist);
                 }
                 catch (err) {
                     const msg = err instanceof Error ? err.message : String(err);
@@ -151,8 +156,10 @@ export function makeSubagentTools(host, lang, selfConvId) {
                 const templateLineEn = p.template ? `\nTemplate: ${p.template}` : "";
                 const modelLineZh = p.model ? `\n模型：${p.model}` : "";
                 const modelLineEn = p.model ? `\nModel: ${p.model}` : "";
-                return text(pick(getLang(), `子代理已启动（运行列表可见）：${convId}\n类型：${subagentType} · 标题：${subagentTitleText}${templateLineZh}${modelLineZh}` +
-                    `\n用 subagent_wait_all 一次等全部完成（不用轮询），subagent_get_result 取单个结果，subagent_list 看运行态，subagent_steer 改向，subagent_stop 停止。`, `Subagent started (visible in the running list): ${convId}\nType: ${subagentType} · Title: ${subagentTitleText}${templateLineEn}${modelLineEn}` +
+                const kindLabelZh = p.persist ? "普通持久化对话" : "子代理";
+                const kindLabelEn = p.persist ? "Persistent conversation" : "Subagent";
+                return text(pick(getLang(), `${kindLabelZh}已启动（运行列表可见）：${convId}\n类型：${subagentType} · 标题：${subagentTitleText}${templateLineZh}${modelLineZh}` +
+                    `\n用 subagent_wait_all 一次等全部完成（不用轮询），subagent_get_result 取单个结果，subagent_list 看运行态，subagent_steer 改向，subagent_stop 停止。`, `${kindLabelEn} started (visible in the running list): ${convId}\nType: ${subagentType} · Title: ${subagentTitleText}${templateLineEn}${modelLineEn}` +
                     `\nUse subagent_wait_all to wait for all at once (no polling), subagent_get_result for a single result, subagent_list for live status, subagent_steer to redirect, subagent_stop to stop.`, "subagents.spawn.started", {
                     convId: convId,
                     subagentType: subagentType,
@@ -163,7 +170,7 @@ export function makeSubagentTools(host, lang, selfConvId) {
                     templateLineEn: templateLineEn,
                     modelLineZh: modelLineZh,
                     modelLineEn: modelLineEn,
-                }), { convId, template: p.template, model: p.model });
+                }), { convId, template: p.template, model: p.model, persisted: !!p.persist });
             },
         }),
         defineTool({
@@ -220,16 +227,24 @@ export function makeSubagentTools(host, lang, selfConvId) {
         defineTool({
             name: "subagent_list",
             label: "List subagents",
-            description: bilingual("List all subagents and their live status: convId, type, state, title, message count (errors/aborts are marked in the state).", "列出全部子代理的运行态：convId、类型、状态、标题、消息数（报错/中止的会在状态里标出）。"),
+            description: bilingual("List all subagents and managed conversations with their live status: convId, type, state, title, message count (errors/aborts are marked in the state).", "列出全部子代理及受控对话的运行态：convId、类型、状态、标题、消息数（报错/中止的会在状态里标出）。"),
             promptSnippet: "list all subagents and their live status",
-            parameters: Type.Object({}),
-            execute: async () => {
-                const list = host.listSubagents();
+            parameters: Type.Object({
+                kind: Type.Optional(Type.String({
+                    enum: ["all", "subagent", "persistent"],
+                    description: bilingual("Filter: all (default) = all managed tasks; subagent = only ephemeral in-memory subagents; persistent = only persistent conversations.", "过滤类型：all（默认）= 全部受控对话；subagent = 仅临时内存子代理；persistent = 仅持久化普通对话。"),
+                })),
+            }),
+            execute: async (_id, p) => {
+                const list = host.listSubagents(p.kind);
                 if (list.length === 0)
-                    return text(pick(getLang(), "当前没有子代理。", "No subagents running.", "subagents.list.empty"));
+                    return text(pick(getLang(), "当前没有运行中的对话/子代理。", "No managed conversations or subagents running.", "subagents.list.empty"));
                 const tLang = getLang();
-                const lines = list.map((r) => `- ${r.convId} · ${r.type} · ${subagentVerdict(r, tLang)} · ${r.title}` +
-                    (tLang === "zh" ? `（msg: ${r.messageCount}）` : ` (msg: ${r.messageCount})`));
+                const lines = list.map((r) => {
+                    const tag = r.persisted ? (tLang === "zh" ? "持久化" : "persistent") : tLang === "zh" ? "子代理" : "subagent";
+                    return (`- ${r.convId} · ${r.type} · ${subagentVerdict(r, tLang)} · ${r.title}` +
+                        (tLang === "zh" ? `（${tag} · msg: ${r.messageCount}）` : ` (${tag} · msg: ${r.messageCount})`));
+                });
                 return text(lines.join("\n"));
             },
         }),
@@ -374,7 +389,9 @@ export function makeSubagentTools(host, lang, selfConvId) {
                     const emptyLang = getLang();
                     return text(pick(emptyLang, "没有需要等待的子代理（调用者自身与祖先不计入等待；子代理无参时只等自己的后代）。", "No subagents to wait for (the calling session itself and its ancestors are never waited on; a subagent without runIds only waits for its own descendants).", "subagents.wait.empty"));
                 }
-                const timeoutMs = Math.min(Math.max(p.timeoutSeconds ?? 600, 1), Math.floor(WAIT_CAP_MS / 1000)) * 1000;
+                const currentWatchdogMs = host.getWatchdogTimeoutMs?.() ?? WAIT_CAP_MS;
+                const currentWaitCapMs = currentWatchdogMs > 0 ? Math.max(60_000, Math.floor(currentWatchdogMs * 0.8)) : 3600_000;
+                const timeoutMs = Math.min(Math.max(p.timeoutSeconds ?? 600, 1), Math.floor(currentWaitCapMs / 1000)) * 1000;
                 const waitStart = Date.now();
                 const deadline = waitStart + timeoutMs;
                 // 已到终态的、（或已被移出找不到的）直接归位；剩下的阻塞轮询到

package/dist/server/terminals.js

@@ -1295,10 +1295,16 @@ export class TerminalManager {
             w.cb(null);
         entry.exitCode = exitCode;
         this.terms.delete(id);
+        // 进程已退出，立即释放底层的 PTY 句柄（Windows ConPTY / HPCON / sockets 等），
+        // 避免已退出的终端长期占用 ConPTY 与 MSYS2 控制台资源（issue #269）。
+        this.killNative(entry);
         while (this.history.size >= MAX_TERMINAL_HISTORY) {
             const oldest = this.history.keys().next().value;
             if (typeof oldest !== "string")
                 break;
+            const oldEntry = this.history.get(oldest);
+            if (oldEntry)
+                this.killNative(oldEntry);
             this.history.delete(oldest);
         }
         this.history.set(id, entry);
@@ -1339,8 +1345,13 @@ export class TerminalManager {
             this.emitList();
             return;
         }
-        if (this.history.delete(id))
+        const histEntry = this.history.get(id);
+        if (histEntry) {
+            this.killNative(histEntry);
+            this.history.delete(id);
             this.emitList();
+            return;
+        }
     }
     /** Rename a terminal tab (live or retained history). Empty names ignored. */
     rename(id, title) {
@@ -1354,27 +1365,33 @@ export class TerminalManager {
         this.emitList();
     }
     /**
-     * Kill the native PTY (issue #215：Windows ConPTY 关机死锁）。
+     * Kill the native PTY (issue #215：Windows ConPTY 关机死锁；issue #269：MSYS2 控制台耗尽死锁）。
      *
-     * Windows 下 `pty.kill()` 底层走 `ClosePseudoConsole`，管道有未排空数据时会
-     * 内核级同步死锁，直接冻住单线程事件循环（进程内 setTimeout 看门狗与二次
-     * Ctrl+C 全灭）。所以 Windows 先走 Node 原生的 `process.kill(pid)`
-     *（TerminateProcess，从不阻塞）把 shell 干掉：
-     * - 关机（shutdown=true）：到此为止，不再调 `pty.kill()`。进程马上就
-     *   `process.exit`，HPC 句柄由 OS 回收；再调只会自找死锁。
-     * - 日常（tab 关闭/移出对话）：子进程已死、管道见 EOF 后再调 `pty.kill()`
-     *   释放 HPC 句柄，此时不再阻塞（长驻服务必须释放句柄，不能像关机那样一走了之）。
-     * 非 Windows 原样直调 `pty.kill()`。
+     * Windows 下：
+     * 1. 若进程已经退出（entry.exited）：绝不可再调用 Node 的 process.kill(pid)，
+     *    直接调 pty.kill() 释放 HPCON 句柄（子进程已死、管道见 EOF，绝不会死锁）。
+     * 2. 若进程尚未退出（!entry.exited）：
+     *    先尝试优雅关闭（向 PTY 写入 \x03exit\r），让 bash 正常触发清理钩子；
+     *    若仍未退出才以 process.kill(pid)（TerminateProcess）强制兜底。
+     * 3. 关机（shutdown=true）：跳过 pty.kill()，由 OS 回收。
+     * 非 Windows 原样直调 pty.kill()。
      */
     killNative(entry, shutdown = false) {
         if (process.platform === "win32") {
-            const pid = entry.pty.pid;
-            if (typeof pid === "number") {
-                try {
-                    process.kill(pid);
-                }
-                catch {
-                    // already dead
+            if (!entry.exited) {
+                const pid = entry.pty.pid;
+                if (typeof pid === "number") {
+                    try {
+                        // 优雅关闭：先发 Ctrl+C，再发 exit\r
+                        entry.pty.write("\x03exit\r");
+                    }
+                    catch { }
+                    try {
+                        process.kill(pid);
+                    }
+                    catch {
+                        // already dead
+                    }
                 }
             }
             if (shutdown)
@@ -1410,6 +1427,9 @@ export class TerminalManager {
                 w.cb(null);
             entry.watches = [];
         }
+        for (const entry of this.history.values()) {
+            this.killNative(entry, shutdown);
+        }
         this.terms.clear();
         this.history.clear();
         this.emitList();

package/dist/server/text-sniff.js

@@ -20,6 +20,10 @@ const PREVIEW_IMAGE_EXTS = new Set([
     "tiff",
 ]);
 const PREVIEW_VIDEO_EXTS = new Set(["mp4", "webm", "mov", "mkv", "avi", "m4v", "ogv", "mpg", "mpeg", "wmv", "flv"]);
+/** 浏览器 <audio> 能直接播放的音频容器（present_files 的卡片与 /api/file 白名单
+ *  共用这一份）：不在表里的（wma/aiff/midi/…）一律按二进制处理，让用户下载或
+ *  本地打开，而不是给一个永远播不出来的播放器。 */
+const PREVIEW_AUDIO_EXTS = new Set(["mp3", "wav", "wave", "ogg", "oga", "opus", "m4a", "aac", "flac", "weba"]);
 const PREVIEW_TEXT_EXTS = new Set([
     // code
     "ts",
@@ -151,6 +155,17 @@ export function previewKind(name) {
         return "text";
     return "none";
 }
+/**
+ * 扩展名是否为浏览器可直接播放的音频。与 previewKind 分开：PreviewKind 只有
+ * image/video/text/none 四档（右栏图标、附件、预览弹窗都按它分支），把音频塞进去
+ * 要动整条链路；而 /api/file 的媒体白名单与 present_files 的卡片只需要一个
+ * 「能不能 inline 播」的布尔判断。
+ */
+export function isAudioFile(name) {
+    const dot = name.lastIndexOf(".");
+    const ext = dot > 0 ? name.slice(dot + 1).toLowerCase() : "";
+    return PREVIEW_AUDIO_EXTS.has(ext);
+}
 /**
  * Content sniff for the preview: any data that has no NUL bytes and no
  * meaningful control-char ratio is treated as text — so files with unknown

package/dist/server/themes.js

@@ -22,9 +22,24 @@ const ID_RE = /^[A-Za-z0-9_-]+$/;
  *  filename stays ASCII (id must match ID_RE). */
 const THEME_NAME_RE = /\/\*\s*theme-name:\s*(.+?)\s*\*\//;
 const THEME_NAME_EN_RE = /\/\*\s*theme-name-en:\s*(.+?)\s*\*\//;
+const THEME_GROUP_RE = /\/\*\s*theme-group:\s*(.+?)\s*\*\//;
+/** 从主题 CSS 头部读取 color-scheme（浅/暗），无法识别时返回 undefined。 */
+const THEME_SCHEME_RE = /color-scheme:\s*(dark|light)/i;
+function readScheme(path) {
+    try {
+        const head = readFileSync(path, "utf8").slice(0, 800);
+        const m = head.match(THEME_SCHEME_RE);
+        if (m && (m[1] === "dark" || m[1] === "light"))
+            return m[1];
+    }
+    catch {
+        // ignore
+    }
+    return undefined;
+}
 function readDisplayName(path, fallback) {
     try {
-        const head = readFileSync(path, "utf8").slice(0, 300);
+        const head = readFileSync(path, "utf8").slice(0, 400);
         return head.match(THEME_NAME_RE)?.[1]?.trim() || fallback;
     }
     catch {
@@ -33,13 +48,25 @@ function readDisplayName(path, fallback) {
 }
 function readDisplayNameEn(path) {
     try {
-        const head = readFileSync(path, "utf8").slice(0, 300);
+        const head = readFileSync(path, "utf8").slice(0, 400);
         return head.match(THEME_NAME_EN_RE)?.[1]?.trim() || undefined;
     }
     catch {
         return undefined;
     }
 }
+function readGroup(path) {
+    try {
+        const head = readFileSync(path, "utf8").slice(0, 400);
+        const g = head.match(THEME_GROUP_RE)?.[1]?.trim();
+        if (g === "classic")
+            return "classic";
+    }
+    catch {
+        // ignore
+    }
+    return "builtin";
+}
 export function listThemes(builtinDir, userDir) {
     const scan = (dir, builtin) => {
         if (!existsSync(dir))
@@ -53,10 +80,13 @@ export function listThemes(builtinDir, userDir) {
             const id = f.slice(0, -4);
             const name = readDisplayName(path, id);
             const nameEn = readDisplayNameEn(path);
+            const group = readGroup(path);
             return {
                 id,
                 name,
                 builtin,
+                group,
+                scheme: readScheme(path),
                 ...(nameEn ? { nameEn } : {}),
             };
         });