pi-web-ui 0.92.0 → 0.93.0

package/dist/server/http-proxy.js

@@ -0,0 +1,72 @@
+/**
+ * server/http-proxy.ts
+ *
+ * Propagates HTTP proxy settings from ~/.pi/agent/settings.json and environment
+ * variables (HTTP_PROXY / HTTPS_PROXY / ALL_PROXY) to process.env and sets up
+ * undici's global dispatcher with EnvHttpProxyAgent, ensuring that Node's
+ * native fetch() and SDK HTTP calls route through the configured proxy.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { EventEmitter } from "node:events";
+import * as undici from "undici";
+/** Read proxy settings from settings.json and environment. */
+export function resolveProxySettings(agentDir) {
+    let httpProxy;
+    const settingsPath = join(agentDir, "settings.json");
+    if (existsSync(settingsPath)) {
+        try {
+            const parsed = JSON.parse(readFileSync(settingsPath, "utf-8"));
+            if (typeof parsed.httpProxy === "string" && parsed.httpProxy.trim()) {
+                httpProxy = parsed.httpProxy.trim();
+            }
+        }
+        catch {
+            /* ignore parse error */
+        }
+    }
+    return {
+        httpProxy,
+        envHttpProxy: process.env.HTTP_PROXY,
+        envHttpsProxy: process.env.HTTPS_PROXY,
+        envAllProxy: process.env.ALL_PROXY,
+    };
+}
+/**
+ * Initialize HTTP proxy support:
+ * 1. If httpProxy is present in settings.json and env is not set, populate HTTP_PROXY and HTTPS_PROXY.
+ * 2. If any proxy is configured (settings or env), set up undici's global dispatcher with EnvHttpProxyAgent
+ *    so that global fetch() uses the proxy.
+ */
+export function initHttpProxy(agentDir) {
+    const config = resolveProxySettings(agentDir);
+    if (config.httpProxy) {
+        process.env.HTTP_PROXY ??= config.httpProxy;
+        process.env.HTTPS_PROXY ??= config.httpProxy;
+    }
+    const effectiveProxy = process.env.HTTPS_PROXY || process.env.HTTP_PROXY || process.env.ALL_PROXY;
+    if (!effectiveProxy) {
+        return { active: false };
+    }
+    try {
+        const dispatcher = withUndiciErrorListener(new undici.EnvHttpProxyAgent({
+            allowH2: false,
+            proxyTunnel: true,
+            bodyTimeout: 300_000,
+            headersTimeout: 300_000,
+        }));
+        undici.setGlobalDispatcher(dispatcher);
+        undici.install?.();
+        return { active: true, proxyUrl: effectiveProxy };
+    }
+    catch (err) {
+        console.warn("[proxy] Failed to configure global undici proxy dispatcher:", err);
+        return { active: false, proxyUrl: effectiveProxy };
+    }
+}
+function withUndiciErrorListener(dispatcher) {
+    if (dispatcher instanceof EventEmitter) {
+        dispatcher.on("error", () => { });
+    }
+    return dispatcher;
+}

package/dist/server/index.js

@@ -28,6 +28,7 @@ import express from "express";
 import compression from "compression";
 import { WebSocket, WebSocketServer } from "ws";
 import { VERSION, getAgentDir } from "@earendil-works/pi-coding-agent";
+import { sdkCopies, sdkOriginNote } from "./sdk-origin.js";
 import { PROTOCOL_VERSION } from "./protocol-version.js";
 import { AgentService, workspacePath, QuiesceRejectedError } from "./agent-service.js";
 import { WS_MAX_PAYLOAD_BYTES, isAbsoluteWirePath, wireToAbs } from "./files-service.js";
@@ -49,7 +50,8 @@ import { McpBridge } from "./mcp-bridge.js";
 import { createMcpHotReload } from "./mcp-hot-reload.js";
 import { createHostMetricsSampler } from "./host-metrics.js";
 import { SchedulerStore } from "./scheduler-tasks.js";
-import { buildPiWebTokenCookie, isTlsRequest } from "./auth-cookie.js";
+import { initHttpProxy } from "./http-proxy.js";
+import { buildPiWebTokenCookie, decodeCookieToken, isTlsRequest } from "./auth-cookie.js";
 /** Strip npm-injected env (`npm start` exports `npm_config_*` / `npm_package_*` /
  *  `npm_lifecycle_*` into every child). Anything this server spawns — shells,
  *  `pi update` — would otherwise inherit `npm_config_allow_scripts`, which npm
@@ -173,6 +175,11 @@ function buildId() {
 // <SESSION_DIR_ROOT>/--<cwd>--/, shared with the pi CLI/TUI (getAgentDir
 // honors PI_CODING_AGENT_DIR).
 const SESSION_DIR_ROOT = join(getAgentDir(), "sessions");
+// Propagate pi agent's httpProxy setting and environment proxies to undici/fetch
+const proxyInfo = initHttpProxy(getAgentDir());
+if (proxyInfo.active) {
+    console.log(`[proxy] Outbound HTTP proxy enabled: ${proxyInfo.proxyUrl}`);
+}
 // Windows 轻量 bash 兜底：把 <home>/.pi-web/bin 前置到 PATH（SDK 的 bash 工具经
 // findBashOnPath 会找到其中的 bash.exe），并在无 Git Bash 时后台下载 busybox-w32。
 // 终端面板的 shell 探测链也已包含该目录（见 terminals.ts resolveShell）。
@@ -203,8 +210,17 @@ function requestTokens(req) {
     if (typeof cookie === "string") {
         for (const part of cookie.split(";")) {
             const [k, ...rest] = part.trim().split("=");
-            if (k === "pi_web_token")
-                out.push(rest.join("=").trim());
+            if (k !== "pi_web_token")
+                continue;
+            // 我们下发的是 encodeURIComponent 后的值（issue #261），而手写 / 旧客户端的
+            // 明文 cookie 也可能出现（`=` 在值里合法，按首个 = 切分）；两种候选都进池子。
+            const raw = rest.join("=").trim();
+            if (!raw)
+                continue;
+            out.push(raw);
+            const decoded = decodeCookieToken(raw);
+            if (decoded !== raw)
+                out.push(decoded);
         }
     }
     return out.filter(Boolean);
@@ -212,7 +228,9 @@ function requestTokens(req) {
 function tokenOk(req) {
     return requestTokens(req).includes(AUTH_TOKEN);
 }
-/** 请求携带的 pi_web_token cookie 值（未带/损坏时为空串）。 */
+/** 请求携带的 pi_web_token cookie 的**口令值**（未带/损坏时为空串）。
+ *  已解码：下发时是 `encodeURIComponent` 过的（issue #261），所以这里拿到的是
+ *  可直接与 `AUTH_TOKEN` 比较的原文。 */
 function cookieToken(req) {
     const cookie = req.headers.cookie;
     if (typeof cookie !== "string")
@@ -220,7 +238,7 @@ function cookieToken(req) {
     for (const part of cookie.split(";")) {
         const [k, ...rest] = part.trim().split("=");
         if (k === "pi_web_token")
-            return rest.join("=").trim();
+            return decodeCookieToken(rest.join("=").trim());
     }
     return "";
 }
@@ -247,7 +265,10 @@ if (AUTH_TOKEN) {
         // Secure 只在 TLS 连接上加：常加会让明文 HTTP（默认 loopback）收不到 cookie。
         const secure = isTlsRequest(req);
         if (ok) {
-            if (cookie !== encodeURIComponent(AUTH_TOKEN)) {
+            // cookieToken 已解码成原文（issue #261），所以直接和原始口令比 ——
+            // 以前拿 `encodeURIComponent(AUTH_TOKEN)` 比，含 `=` / 非 ASCII 的口令
+            // 永远不相等（于是每个请求都重发 cookie，且带 cookie 的请求反而 401）。
+            if (cookie !== AUTH_TOKEN) {
                 res.setHeader("Set-Cookie", buildPiWebTokenCookie(encodeURIComponent(AUTH_TOKEN), 31536000, secure));
             }
         }
@@ -284,7 +305,16 @@ const SERVICE_INFO = toServiceInfo(ORIGIN);
 const TABS = parseTabs();
 registerFileTransferRoutes(app, (clientId) => service.get(clientId)?.cwd);
 app.get("/api/health", (_req, res) => {
-    res.json({ ok: true, piVersion: VERSION, cwd: CWD, pid: process.pid, engine: ENGINE });
+    res.json({
+        ok: true,
+        piVersion: VERSION,
+        // issue #260：服务实际加载的是自带副本，不是全局 pi CLI 那份。这里把两份都报出来，
+        // 用户就不用猜「为什么升了全局 SDK 不生效」。（纯新增字段，piVersion 语义不变。）
+        piSdkCopies: sdkCopies(),
+        cwd: CWD,
+        pid: process.pid,
+        engine: ENGINE,
+    });
 });
 /**
  * Stream a workspace file over HTTP.
@@ -1498,6 +1528,17 @@ wss.on("connection", (ws) => {
             case "get_commands":
                 void cs.pushSlashCommands();
                 break;
+            case "get_tool_info":
+                // 工具卡右键菜单的「显示工具详细信息」：按需取一次工具定义（不进快照）。
+                // 引擎没实现（或旧版服务端）时回一条 unsupported，前端据此显示「不支持」
+                // 而不是永远转圈。
+                if (typeof cs.getToolInfo === "function") {
+                    void cs.getToolInfo(msg.name);
+                }
+                else {
+                    send({ type: "tool_info", name: msg.name, found: false, unsupported: true });
+                }
+                break;
             case "list_sessions":
                 void cs.refreshSessions();
                 break;
@@ -1519,6 +1560,11 @@ wss.on("connection", (ws) => {
             case "dismiss_conversation":
                 void cs.dismissConversation(msg.id, msg.withFinishedSubagents, msg.force);
                 break;
+            case "persist_conversation":
+                if (typeof cs.persistConversation === "function") {
+                    void cs.persistConversation(msg.id);
+                }
+                break;
             case "dismiss_finished_subagents":
                 void cs.dismissFinishedSubagents(msg.parentId);
                 break;
@@ -1841,6 +1887,7 @@ wss.on("connection", (ws) => {
                     terminalToolsEnabled: msg.terminalToolsEnabled,
                     terminalBash: msg.terminalBash,
                     terminalBashIdleMs: msg.terminalBashIdleMs,
+                    toolWatchdogTimeoutMs: msg.toolWatchdogTimeoutMs,
                     readDirEnabled: msg.readDirEnabled,
                     editSoftEnabled: msg.editSoftEnabled,
                     questionnaireEnabled: msg.questionnaireEnabled,
@@ -1848,6 +1895,7 @@ wss.on("connection", (ws) => {
                     goalModeEnabled: msg.goalModeEnabled,
                     thinkingWrap: msg.thinkingWrap,
                     toolsWrap: msg.toolsWrap,
+                    toolImagesEnabled: msg.toolImagesEnabled,
                     devNoCache: msg.devNoCache,
                     autoReload: msg.autoReload,
                     skillsFullText: msg.skillsFullText,
@@ -2322,6 +2370,13 @@ httpServer.listen(PORT, HOST, () => {
     console.log(`    workspace   : ${CWD}`);
     console.log(`    session dir : ${SESSION_DIR_ROOT}`);
     console.log(`    pi SDK      : v${VERSION}`);
+    // issue #260：全局那份 pi SDK 不是服务在用的那份（自带副本赢在 Node 解析顺序上）。
+    // 不提示的话，用户会以为 `npm i -g @earendil-works/pi-coding-agent@latest` 生效了。
+    const sdkNote = sdkOriginNote(sdkCopies(), VERSION);
+    if (sdkNote) {
+        console.log(`    pi SDK note : ${sdkNote}`);
+        console.log(`                  Upgrading the global pi CLI does not change this server — upgrade pi-web-ui instead.`);
+    }
     console.log(`    bind        : ${HOST}:${PORT}`);
     console.log("");
 });

package/dist/server/patch-node-pty.js

@@ -76,5 +76,16 @@ function applyPatches() {
         "                }",
         "            });",
     ].join("\n"));
+    // 3. conpty_console_list_agent: tolerate dead shell PID (AttachConsole failed)
+    //    when process already exited or was killed — return [] instead of crashing.
+    patchFile(pkgDir, "lib/conpty_console_list_agent.js", "var consoleProcessList = getConsoleProcessList(shellPid);\nprocess.send({ consoleProcessList: consoleProcessList });\nprocess.exit(0);", [
+        "try {",
+        "    var consoleProcessList = getConsoleProcessList(shellPid);",
+        "    process.send({ consoleProcessList: consoleProcessList });",
+        "} catch (e) {",
+        "    process.send({ consoleProcessList: [] });",
+        "}",
+        "process.exit(0);",
+    ].join("\n"));
 }
 applyPatches();

package/dist/server/plugins.js

@@ -185,6 +185,7 @@ const UI_SLOTS = new Set([
     "contextmenu.message",
     "contextmenu.session",
     "contextmenu.file",
+    "contextmenu.toolcall",
     "settings.pages",
     "leftpanel.sessions",
     "chat.header",

package/dist/server/protocol-version.js

@@ -8,4 +8,4 @@
  * its own copy in web/src/protocol-version.ts; scripts/check-protocol-sync.mjs
  * verifies the two never drift.
  */
-export const PROTOCOL_VERSION = 18;
+export const PROTOCOL_VERSION = 19;

package/dist/server/read-tool.js

@@ -25,6 +25,7 @@ import { stat } from "node:fs/promises";
 import { homedir } from "node:os";
 import { isAbsolute, join, resolve as nodeResolve } from "node:path";
 import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, createLsToolDefinition, createReadToolDefinition, defineTool, } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
 import { bilingual, pick } from "./i18n.js";
 const UNICODE_SPACES = /[\u00A0\u2000-\u200A\u202F\u205F\u3000]/g;
 /**
@@ -52,6 +53,34 @@ export async function isDirectoryPath(absolutePath) {
         return false;
     }
 }
+/** 覆盖定义的参数 schema：内置的 path/offset/limit + file_path 别名。 */
+const readDirSchema = Type.Object({
+    path: Type.String({
+        description: bilingual("Path to the file (or directory) to read (relative or absolute)", "要读取的文件（或目录）路径（相对或绝对）"),
+    }),
+    file_path: Type.Optional(Type.String({
+        description: bilingual("Alias of `path` — some clients/models emit file_path; if both are given, `path` wins", "`path` 的别名 —— 部分客户端/模型习惯发 file_path；两者都给时以 `path` 为准"),
+    })),
+    offset: Type.Optional(Type.Number({
+        description: bilingual("Line number to start reading from (1-indexed)", "从第几行开始读（从 1 起算）"),
+    })),
+    limit: Type.Optional(Type.Number({
+        description: bilingual("Maximum number of lines to read (for a directory path: maximum number of entries)", "最多读多少行（路径是目录时 = 最多列多少条目）"),
+    })),
+}, {});
+/**
+ * 校验前归一（SDK 的 prepareArguments 在 schema 校验前执行）：只有 file_path 时
+ * 把它当 path（path 在 schema 里仍必填），两者都给时以 path 为准。
+ */
+export function prepareReadArguments(raw) {
+    const args = raw && typeof raw === "object" && !Array.isArray(raw) ? { ...raw } : {};
+    const primary = typeof args.path === "string" ? args.path : "";
+    const alias = typeof args.file_path === "string" ? args.file_path : "";
+    if (!primary.trim() && alias.trim())
+        args.path = alias;
+    // 两者都没给时这里仍缺 path（静态类型是谎，运行时交给 schema 校验报错）。
+    return args;
+}
 /**
  * 生成「read 读目录」覆盖定义。cwd 仅供创建时固定；执行时优先 ctx.cwd
  * （会话工作区）。
@@ -63,15 +92,19 @@ export function makeReadDirTool(fallbackCwd, options = {}) {
     const getLang = options.getLang ?? (() => "en");
     return defineTool({
         ...base,
-        description: bilingual(`${base.description} If the path is a directory, its entries are listed instead of file contents (one entry per line, directories suffixed with '/'); in that case \`limit\` caps the number of entries and \`offset\` is ignored.`, `读取文件内容。支持文本文件与图片（jpg, png, gif, webp, bmp），图片作为附件发出。文本输出截断到 ${DEFAULT_MAX_LINES} 行或 ${DEFAULT_MAX_BYTES / 1024}KB（先到者为准），大文件用 offset/limit 续读。路径是目录时改为列出目录条目（一行一项，目录带 '/' 后缀；此时 limit 是条目上限，offset 忽略）。`),
+        description: bilingual(`${base.description} Also accepts \`file_path\` as an alias of \`path\`. If the path is a directory, its entries are listed instead of file contents (one entry per line, directories suffixed with '/'); in that case \`limit\` caps the number of entries and \`offset\` is ignored.`, `读取文件内容。支持文本文件与图片（jpg, png, gif, webp, bmp），图片作为附件发出。文本输出截断到 ${DEFAULT_MAX_LINES} 行或 ${DEFAULT_MAX_BYTES / 1024}KB（先到者为准），大文件用 offset/limit 续读。路径也可用 \`file_path\` 传（path 的别名，两者都给时以 path 为准）。路径是目录时改为列出目录条目（一行一项，目录带 '/' 后缀；此时 limit 是条目上限，offset 忽略）。`),
         promptSnippet: bilingual("Read file contents (a directory path lists its entries)", "读取文件内容（传目录则列出其条目）"),
         promptGuidelines: [
             ...(base.promptGuidelines ?? []),
             bilingual("Use read on a directory to list its entries — no need to shell out to `ls`", "要看目录内容直接把目录路径交给 read，不必再走 bash 的 ls"),
         ],
+        parameters: readDirSchema,
+        prepareArguments: prepareReadArguments,
         async execute(toolCallId, params, signal, onUpdate, ctx) {
             const input = (params ?? {});
-            const path = typeof input.path === "string" ? input.path : "";
+            // 兜底（不依赖 prepareArguments 一定跑过）：path 缺省/空时用 file_path。
+            const rawPath = typeof input.path === "string" && input.path.trim() ? input.path : input.file_path;
+            const path = typeof rawPath === "string" ? rawPath : "";
             if (path && dirEnabled()) {
                 const cwd = typeof ctx?.cwd === "string" ? ctx.cwd : fallbackCwd;
                 if (await isDirectoryPath(resolvePathForDirCheck(path, cwd))) {
@@ -85,7 +118,8 @@ export function makeReadDirTool(fallbackCwd, options = {}) {
                     return { content, details: undefined };
                 }
             }
-            return base.execute(toolCallId, params, signal, onUpdate, ctx);
+            // 转发内置实现时带上归一后的 path（模型可能只给了 file_path）。
+            return base.execute(toolCallId, { ...input, path }, signal, onUpdate, ctx);
         },
     });
 }

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,6 +1,15 @@
 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 推一次，
@@ -13,30 +22,38 @@ function truncate(s, 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 ?? "") };
     });
@@ -107,16 +124,37 @@ 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);
+            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,

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,7 @@ 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,
@@ -298,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,
@@ -459,6 +461,9 @@ 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;
@@ -483,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) {
@@ -630,6 +638,8 @@ export class SettingsService {
             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,
@@ -651,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.