@youweichen/pi-harness 0.0.0-stage → 1.0.0

package/dist/server/index.js

@@ -0,0 +1,1029 @@
+import { installSystemPromptRoutes } from "./system-prompt-routes.js";
+import { installExtensionsRoutes } from "./extensions-routes.js";
+import { installCodemodeImageRoutes } from "./codemode-image-routes.js";
+import { installWikiRoutes } from "./wiki-routes.js";
+/**
+ * pi-harness server entry.
+ *
+ * - Serves the built frontend (web/dist) in production; in dev, Vite serves it
+ *   on :5173 and proxies /ws to this server.
+ * - Exposes /api/health and a WebSocket endpoint at /ws carrying the chat
+ *   protocol defined in protocol.ts.
+ *
+ * Env:
+ *   PORT            HTTP port (default 8787)
+ *   PI_WEB_CWD      workspace the agent operates in (default: process.cwd())
+ *   PI_WEB_DATA_DIR where per-client UI state is stored (client-state.json,
+ *   default: <home>/.pi-web). Chat sessions are NOT stored here — they live
+ *   in the pi agent's global TUI session dir (~/.pi/agent/sessions/--<cwd>--/)
+ *   via the SDK default, so this web UI, the dev instance, and the pi CLI/TUI
+ *   all share one conversation list per project.
+ *   PI_CODING_AGENT_DIR  pi config dir (auth/models/skills) — passed to the SDK
+ */
+import { existsSync } from "node:fs";
+import { stat } from "node:fs/promises";
+import { createServer } from "node:http";
+import { createConnection } from "node:net";
+import { basename, delimiter, dirname, join, resolve, sep } from "node:path";
+import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { randomUUID } from "node:crypto";
+import express from "express";
+import compression from "compression";
+import { WebSocket, WebSocketServer } from "ws";
+import { VERSION, getAgentDir } from "@earendil-works/pi-coding-agent";
+import { PROTOCOL_VERSION } from "./protocol-version.js";
+import { appVersion } from "./app-version.js";
+import { AgentService, workspacePath, QuiesceRejectedError, } from "./agent-service.js";
+import { isRealPathInWorkspace } from "./files-service.js";
+import { previewKind } from "./text-sniff.js";
+import { startControlServer } from "./control-socket.js";
+import { readSqlitePreview } from "./sqlite-preview.js";
+import { saveMarkdownImage } from "./markdown-images.js";
+import { scheduleUploadCleanup } from "./uploads.js";
+import { ensureWindowsBash, windowsBashDir } from "./ensure-bash.js";
+import { isValidClientId } from "./client-id.js";
+import { securityHeaders } from "./security-headers.js";
+import { needsTokenCookie, tokenCookie, tokenMatches } from "./token-auth.js";
+import { createOriginPolicy } from "./origin-policy.js";
+import { PluginManager, resolvePluginClientFile } from "./plugins.js";
+import { NodeWorkbench } from "./node-workbench.js";
+const PORT = Number(process.env.PORT ?? 8787);
+const CWD = resolve(process.env.PI_WEB_CWD ?? process.cwd());
+const DATA_DIR = resolve(process.env.PI_WEB_DATA_DIR ?? join(homedir(), ".pi-web"));
+/** Bind address. Default is loopback ONLY — the service is a local personal
+ *  tool and should not be reachable from the network unless explicitly asked
+ *  (e.g. PI_WEB_HOST=0.0.0.0 for LAN access / Docker port mapping). */
+const HOST = process.env.PI_WEB_HOST ?? "127.0.0.1";
+/** Optional strict hostname allowlist (comma-separated) — only used when set.
+ *  Origin / Host same-authority matching happens regardless. */
+const ALLOW_HOSTS = (process.env.PI_WEB_ALLOW_HOSTS ?? "")
+    .split(",")
+    .map((s) => s.trim().toLowerCase())
+    .filter(Boolean);
+/** Optional extra Origins allowed through the same-authority check (comma-
+ *  separated, e.g. reverse-proxy setups where the browser origin differs
+ *  from the Host the backend sees). */
+const ALLOW_ORIGINS = (process.env.PI_WEB_ALLOW_ORIGINS ?? "")
+    .split(",")
+    .map((s) => s.trim().toLowerCase())
+    .filter(Boolean);
+/** 可选共享口令（PI_WEB_TOKEN）：设置后所有 HTTP/WS 请求必须携带——
+ *  Authorization: Bearer / X-PI-Token 头、?token= 查询参数或 pi_web_token cookie
+ *  任一匹配即可；供 0.0.0.0 / 反代等暴露场景兜底，未设置则行为不变。 */
+const AUTH_TOKEN = process.env.PI_WEB_TOKEN?.trim() ?? "";
+// The token authenticates browsers to this server. Terminals, the agent's bash tool and
+// worker processes inherit process.env, so leaving it there would hand the secret to
+// anything the agent runs (and into model context via `env`). Nothing re-reads it.
+delete process.env.PI_WEB_TOKEN;
+// Root of the SDK default per-project session dirs — chat transcripts live in
+// <SESSION_DIR_ROOT>/--<cwd>--/, shared with the pi CLI/TUI (getAgentDir
+// honors PI_CODING_AGENT_DIR).
+const SESSION_DIR_ROOT = join(getAgentDir(), "sessions");
+// Windows 轻量 bash 兜底：把 <home>/.pi-web/bin 前置到 PATH（SDK 的 bash 工具经
+// findBashOnPath 会找到其中的 bash.exe），并在无 Git Bash 时后台下载 busybox-w32。
+// 终端面板的 shell 探测链也已包含该目录（见 terminals.ts resolveShell）。
+if (process.platform === "win32") {
+    process.env.PATH = `${windowsBashDir()}${delimiter}${process.env.PATH ?? ""}`;
+    void ensureWindowsBash();
+}
+const app = express();
+app.use(express.json({ limit: "10mb" }));
+app.use(securityHeaders);
+/** 从请求中提取候选 token：头 / 查询参数 / cookie（浏览器导航场景靠 cookie 续命）。 */
+function requestTokens(req) {
+    const out = [];
+    const auth = req.headers.authorization;
+    if (typeof auth === "string" && auth.startsWith("Bearer "))
+        out.push(auth.slice(7).trim());
+    const header = req.headers["x-pi-token"];
+    if (typeof header === "string")
+        out.push(header.trim());
+    try {
+        const q = new URL(req.url ?? "/", "http://localhost").searchParams.get("token");
+        if (q)
+            out.push(q.trim());
+    }
+    catch {
+        /* ignore malformed url */
+    }
+    const cookie = req.headers.cookie;
+    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());
+        }
+    }
+    return out.filter(Boolean);
+}
+function tokenOk(req) {
+    return tokenMatches(requestTokens(req), AUTH_TOKEN);
+}
+if (AUTH_TOKEN) {
+    // /api/health 保持开放：无敏感信息，容器/监控探针需要它
+    app.use((req, res, next) => {
+        const authenticated = tokenOk(req);
+        if (authenticated || req.path === "/api/health") {
+            // 浏览器经 ?token= 首次进入后下发 HttpOnly cookie，后续导航/资源请求免带参数。
+            // 只发给已认证的请求：匿名健康检查拿到 cookie 就等于拿到口令。
+            if (authenticated && needsTokenCookie(req.headers.cookie, AUTH_TOKEN)) {
+                const https = req.socket.encrypted === true || req.headers["x-forwarded-proto"] === "https";
+                res.setHeader("Set-Cookie", tokenCookie(AUTH_TOKEN, https));
+            }
+            next();
+            return;
+        }
+        res.status(401).send("unauthorized: PI_WEB_TOKEN required (?token=…)");
+    });
+}
+installCodemodeImageRoutes(app, () => service, originAllowed);
+installExtensionsRoutes(app, () => service, originAllowed);
+installSystemPromptRoutes(app, () => service, originAllowed);
+installWikiRoutes(app, () => service, join(DATA_DIR, "wiki"), originAllowed);
+app.get("/api/health", (_req, res) => {
+    res.json({ ok: true, piVersion: VERSION, pid: process.pid });
+});
+app.get("/api/sqlite", async (req, res) => {
+    res.setHeader("Cache-Control", "no-store");
+    if (!originAllowed(req)) {
+        res.status(403).json({ error: "Forbidden" });
+        return;
+    }
+    const { clientId, cwd, path, requestId, table, offset = "0" } = req.query;
+    if (![clientId, cwd, path, requestId, offset].every((value) => typeof value === "string") || (table !== undefined && typeof table !== "string")) {
+        res.status(400).json({ error: "Invalid request" });
+        return;
+    }
+    const cs = service.get(clientId);
+    const identity = { requestId, cwd, path };
+    if (!cs || cs.switchingWorkspace || cs.cwd !== cwd) {
+        res.status(409).json({ ...identity, error: "Workspace unavailable" });
+        return;
+    }
+    const controller = new AbortController();
+    res.once("close", () => controller.abort());
+    try {
+        const data = await readSqlitePreview({ cwd: cwd, path: path, table: table, offset: Number(offset) }, controller.signal);
+        if (controller.signal.aborted)
+            return;
+        if (cs.switchingWorkspace || cs.cwd !== cwd) {
+            res.status(409).json({ ...identity, error: "Workspace changed" });
+            return;
+        }
+        res.json({ ...identity, data });
+    }
+    catch (error) {
+        if (!controller.signal.aborted)
+            res.status(400).json({ ...identity, error: error.message });
+    }
+});
+app.post("/api/markdown-image", (req, res) => {
+    if (!originAllowed(req) || !req.is("application/json")) {
+        res.status(403).json({ error: "Forbidden" });
+        return;
+    }
+    const { clientId, cwd, path, data } = req.body ?? {};
+    if (![clientId, cwd, path, data].every((value) => typeof value === "string")) {
+        res.status(400).json({ error: "Invalid request" });
+        return;
+    }
+    const cs = service.get(clientId);
+    if (!cs || cs.switchingWorkspace || cs.cwd !== cwd || service.quiesceInfo().quiesced) {
+        res.status(409).json({ error: "Workspace unavailable" });
+        return;
+    }
+    try {
+        res.json({ path: saveMarkdownImage(cwd, path, data) });
+    }
+    catch (error) {
+        res.status(400).json({ error: error.message });
+    }
+});
+/**
+ * Stream a workspace file over HTTP.
+ *
+ * Media preview (no download param): only image/video kinds are served —
+ * text goes over the WebSocket, and exe/jar/etc. are never exposed here.
+ * express's sendFile handles Range requests, so video seeking works.
+ *
+ * Download (?download=1): any file kind is served with
+ * Content-Disposition: attachment so the browser saves it instead of
+ * rendering. Path is validated against the workspace root either way.
+ */
+app.get(["/api/tool-output", "/api/tool-output-list"], async (req, res) => {
+    if (!originAllowed(req)) {
+        res.status(403).end("Forbidden");
+        return;
+    }
+    const { clientId, conversationId, toolCallId } = req.query;
+    if (typeof clientId !== "string" || typeof conversationId !== "string" || typeof toolCallId !== "string") {
+        res.status(400).end("Invalid request");
+        return;
+    }
+    try {
+        const cs = service.get(clientId);
+        if (!cs) {
+            res.status(403).end("Output access denied");
+            return;
+        }
+        if (req.path === "/api/tool-output-list") {
+            res.json((await cs.listToolOutputs(conversationId, toolCallId)).map(({ id, name, default: isDefault }) => ({ id, name, default: isDefault })));
+            return;
+        }
+        const { handle, name } = await cs.downloadToolOutput(conversationId, toolCallId, typeof req.query.outputId === "string" ? req.query.outputId : undefined);
+        res.attachment(name);
+        res.setHeader("X-Content-Type-Options", "nosniff");
+        const stream = handle.createReadStream();
+        res.on("close", () => stream.destroy());
+        stream.on("error", () => res.destroy());
+        stream.pipe(res);
+    }
+    catch (error) {
+        const code = error.code;
+        res.status(code === "ENOENT" ? 404 : code === "EACCES" || code === "EPERM" ? 403 : 500).end(code === "ENOENT" ? "Output file may have been cleaned up" : code === "EACCES" || code === "EPERM" ? "Output access denied" : "Output server error");
+    }
+});
+app.get("/api/file", async (req, res) => {
+    if (!originAllowed(req)) {
+        res.status(403).end("Forbidden");
+        return;
+    }
+    try {
+        const raw = typeof req.query.path === "string" ? req.query.path : "";
+        // Resolve against the requesting client's workspace (the opened
+        // project), not the server's startup cwd — they can differ when the
+        // client switched projects or restored a previous workspace. Fall
+        // back to the server cwd for requests without a known client.
+        const cid = typeof req.query.clientId === "string" ? req.query.clientId : "";
+        const cs = cid ? service.get(cid) : undefined;
+        // No anonymous fallback to the server cwd: a request must belong to a live client.
+        if (!cs) {
+            res.status(403).end("unknown client");
+            return;
+        }
+        if (req.query.cwd && (cs.switchingWorkspace || req.query.cwd !== cs.cwd)) {
+            res.status(409).end("workspace changed");
+            return;
+        }
+        const wp = workspacePath(cs.cwd, raw);
+        if (!wp) {
+            res.status(400).end("path outside workspace");
+            return;
+        }
+        const abs = wp.abs;
+        if (!isRealPathInWorkspace(cs.cwd, abs)) {
+            res.status(400).end("path outside workspace");
+            return;
+        }
+        const name = basename(abs);
+        const kind = previewKind(name);
+        const isDownload = req.query.download === "1";
+        if (!isDownload && kind !== "image" && kind !== "video") {
+            res.status(400).end("not a previewable media file");
+            return;
+        }
+        const st = await stat(abs);
+        if (!st.isFile()) {
+            res.status(400).end("not a file");
+            return;
+        }
+        if (isDownload) {
+            // res.download sets Content-Disposition: attachment and RFC 5987
+            // filename* encoding for non-ASCII names.
+            res.download(abs, name);
+        }
+        else {
+            res.sendFile(abs);
+        }
+    }
+    catch {
+        res.status(404).end("not found");
+    }
+});
+// Production: serve the built frontend from web/dist. Resolve relative to this
+// module so it works when installed as a package (global/npx/Docker), not just
+// from the repo root. In dev, Vite serves the UI on :5173 and proxies /ws.
+const here = dirname(fileURLToPath(import.meta.url)); // <pkg>/dist/server or <pkg>/server
+// Resolve the package root robustly: dev runs from <repo>/server (tsx), prod
+// from <pkg>/dist/server — the ancestor that actually has package.json wins.
+function resolvePkgRoot() {
+    // PI_WEB_PKG_ROOT: Electron 桌面版打包后，server 子进程从 extraResources 目录
+    //（process.resourcesPath）加载 web/dist 和 themes。通过这个 env var 告诉
+    // server 去哪里找 pkgRoot，避免 resolvePkgRoot 的候选路径找不到 package.json。
+    if (process.env.PI_WEB_PKG_ROOT)
+        return process.env.PI_WEB_PKG_ROOT;
+    const candidates = [
+        resolve(here, ".."),
+        resolve(here, "..", ".."),
+        resolve(here, "..", "..", ".."),
+    ];
+    for (const c of candidates) {
+        if (existsSync(join(c, "package.json")))
+            return c;
+    }
+    return candidates[0];
+}
+const pkgRoot = resolvePkgRoot();
+const APP_VERSION = appVersion(pkgRoot);
+// Plugin client bundles: <dataDir>/plugins/<id>/client/* served at
+// /plugins/<id>/client/* so the frontend can import() plugin views. Only the
+// client/ subtree is exposed — manifest.json and the server-side index.mjs
+// (which may hold credentials) never leave the machine. Registered BEFORE the
+// SPA catch-all below.
+const PLUGINS_DIR = join(DATA_DIR, "plugins");
+// 插件 HTTP 路由挂载点：host.route("GET", "/inbox") 实际暴露为
+// /plugins-api/<id>/inbox。PI_WEB_TOKEN 鉴权（上方 app.use）自动覆盖；
+// 响应已在前面过了 express.json。注意不要在此 catch-all 里消费 body。
+app.all(["/plugins-api/:id/*", "/plugins-api/:id"], (req, res) => {
+    const rest = String(req.params[0] ?? "");
+    pluginMgr.handleHttp(String(req.params.id ?? ""), req.method, rest, req, res);
+});
+app.get("/plugins/:id/client/*", (req, res) => {
+    // express 4 的通配参数在运行时落在 params[0]，但类型声明里没有 —— 显式取
+    const rest = String(req.params[0] ?? "");
+    const abs = resolvePluginClientFile(PLUGINS_DIR, req.params.id, rest);
+    if (!abs) {
+        res.status(404).end("plugin not found");
+        return;
+    }
+    // .mjs 常不在老 mime 表里，手动定 Content-Type 保证 import() 可用
+    if (/\.(mjs|js)$/.test(abs)) {
+        res.setHeader("Content-Type", "text/javascript; charset=utf-8");
+    }
+    res.setHeader("Cache-Control", "no-cache"); // 开发期改文件即生效
+    res.sendFile(abs, (err) => {
+        if (err && !res.headersSent)
+            res.status(err.statusCode === 404 ? 404 : 500).end("not found");
+    });
+});
+/** Set in the env of the replacement child spawned by a self-update restart. */
+const RESTART_CHILD_ENV = "PI_WEB_RESTART_CHILD";
+const webDist = join(pkgRoot, "web", "dist");
+if (existsSync(webDist)) {
+    // gzip/deflate 响应压缩：前端 bundle ~1MB，局域网/反代场景传输量降到 ~1/4；
+    // 对 API JSON 同样生效，WS 升级不受影响
+    app.use(compression());
+    app.use(express.static(webDist, {
+        // Vite 产物文件名带内容 hash，可永久强缓存——业务发版后 hash 变化自然失效，
+        // index.html 由下方 catch-all 处理（sendFile 不走这里）
+        setHeaders(res, filePath) {
+            if (filePath.includes(`${sep}assets${sep}`)) {
+                res.setHeader("Cache-Control", "public, max-age=31536000, immutable");
+            }
+        },
+    }));
+    app.get(/^\/(?!api\/|ws).*/, (_req, res) => {
+        // Callback form: a failed stat here (npm i -g is mid-replacement of the
+        // package dir) responds 503 instead of crashing the request pipeline
+        // with an unhandled ENOENT stack trace.
+        res.sendFile(join(webDist, "index.html"), (err) => {
+            if (err && !res.headersSent) {
+                res.status(503).send("正在更新 pi-harness，请稍后刷新…");
+            }
+        });
+    });
+}
+else if (process.env[RESTART_CHILD_ENV]) {
+    // Auto-restart replacement of a self-update whose npm install did not
+    // complete (Windows: locked files / rollback can leave the global package
+    // without web/dist). Fail loudly with a repair hint instead of serving a
+    // UI-less 404 with no explanation.
+    console.error("✖ 更新后的安装不完整（缺少 web/dist/index.html）。\n" +
+        "  请手动执行 npm i -g @youweichen/pi-harness@latest 修复后重新启动。");
+    process.exit(1);
+}
+const httpServer = createServer(app);
+const wss = new WebSocketServer({
+    noServer: true,
+    // Per-message deflate: big-session snapshots serialize to multi-MB JSON
+    // strings; wire-level compression cuts that several-fold. threshold keeps
+    // tiny messages (notices/heartbeats) uncompressed to save CPU.
+    perMessageDeflate: { threshold: 16 * 1024 },
+});
+// ---------------------------------------------------------------------------
+// Origin / Host admission for WebSocket upgrades.
+//
+// Browsers attach an Origin header; non-browser clients (curl, ws scripts)
+// usually don't — they're admitted by the network layer / reverse proxy.
+// Policy lives in origin-policy.ts: Host allowlist (loopback by default when
+// bound to loopback, against DNS rebinding), then same-authority Origin match.
+//
+// Dev-mode note: the Vite dev server (:5173) proxies /ws to the backend on
+// :8788, so their authorities differ — the dev:server script sets
+// PI_WEB_ALLOW_ORIGINS=http://localhost:5173,http://127.0.0.1:5173 for that.
+// LAN / reverse-proxy setups add their own origin the same way.
+// ---------------------------------------------------------------------------
+const originPolicy = createOriginPolicy({ bindHost: HOST, allowHosts: ALLOW_HOSTS, allowOrigins: ALLOW_ORIGINS });
+function originAllowed(req) {
+    return originPolicy(req.headers);
+}
+httpServer.on("upgrade", (req, socket, head) => {
+    let pathname = "/";
+    try {
+        pathname = new URL(req.url ?? "/", "http://localhost").pathname;
+    }
+    catch {
+        /* fall through to the path check below */
+    }
+    if (pathname !== "/ws") {
+        socket.destroy();
+        return;
+    }
+    if (!originAllowed(req)) {
+        // Reject cross-origin browser pages outright. The browser sees a failed
+        // WS connect; the page's own reconnect loop then backs off and retries.
+        socket.write("HTTP/1.1 403 Forbidden\r\nConnection: close\r\nContent-Length: 0\r\n\r\n");
+        socket.destroy();
+        return;
+    }
+    if (AUTH_TOKEN && !tokenOk(req)) {
+        socket.write("HTTP/1.1 401 Unauthorized\r\nConnection: close\r\nContent-Length: 0\r\n\r\n");
+        socket.destroy();
+        return;
+    }
+    wss.handleUpgrade(req, socket, head, (ws) => {
+        wss.emit("connection", ws, req);
+    });
+});
+// Heartbeat: lets clients detect half-open connections (server killed without
+// closing sockets, sleep/wake, network partitions). Idle connections otherwise
+// carry no traffic and TCP keepalive defaults are far too slow (~2h).
+const heartbeatTimer = setInterval(() => {
+    for (const ws of wss.clients) {
+        if (ws.readyState === WebSocket.OPEN) {
+            ws.send(JSON.stringify({ type: "heartbeat" }));
+        }
+    }
+}, 10_000);
+const service = new AgentService(CWD, 
+// Per-client persisted UI state: last-used workspace + recent projects.
+join(DATA_DIR, "client-state.json"));
+const nodeWorkbench = new NodeWorkbench(DATA_DIR);
+// Optional UI plugins (<dataDir>/plugins/<id>/): scanned on every client
+// attach so freshly dropped plugins appear without a server restart.
+const pluginMgr = new PluginManager(DATA_DIR, CWD);
+// 插件扩展点：SDK 工具执行事件（bash/读文件等 start+end）转发给已注册的插件。
+service.onToolEvent = (ev) => pluginMgr.emitToolEvent(ev);
+// 插件扩展点：插件常驻后台任务（registerBackgroundTask）→ 并入「后台任务」面板。
+pluginMgr.onBgTasksChanged = () => service.refreshBackgroundServers();
+service.pluginBgTasksProvider = () => pluginMgr.bgTasks();
+service.pluginStopBgTask = (taskId) => pluginMgr.stopPluginBgTask(taskId);
+// 插件宿主工作区实时跟随当前项目：任意客户端 set_cwd 成功后同步给
+// PluginManager，编辑器等工作区跟随型插件随即切根（详见 plugins.ts notifyCwd）。
+service.onClientCwdChanged = (cwd) => pluginMgr.notifyCwd(cwd);
+// ---------------------------------------------------------------------------
+// Self-update
+// ---------------------------------------------------------------------------
+// In-app updates now run `npm i -g @youweichen/pi-harness@latest` in a visible terminal
+// tab (frontend-initiated); after it finishes the user restarts via
+// `pi-harness server restart`. The PI_WEB_RESTART_CHILD port-wait handshake
+// below stays: an externally orchestrated replacement child still needs it.
+function scheduleQuit() {
+    const isLaunchd = process.platform === "darwin" && process.ppid === 1;
+    const isSystemd = process.platform === "linux" && !!process.env.INVOCATION_ID;
+    const inDocker = existsSync("/.dockerenv");
+    if (isLaunchd || isSystemd || inDocker) {
+        setTimeout(() => {
+            console.log("pi-harness:quit — shutting down (supervisor will restart)…");
+            if (isSystemd)
+                process.exit(3);
+            void shutdown();
+        }, 300);
+        return true;
+    }
+    setTimeout(() => {
+        console.log("pi-harness:quit — shutting down (restart to reload)…");
+        void shutdown();
+    }, 300);
+    return true;
+}
+service.onQuit = scheduleQuit;
+/** 背压相对倍数：socket 未发送积压超过「最近一份 snapshot 大小 × 此倍数」时丢弃
+ *  （issue #11 及其评论区的自适应建议）。固定 1MB 阈值在长会话下单份 snapshot 可达
+ *  ~10MB——连半份都没发完就丢，前端频繁跳帧；短会话又太迟钝。相对阈值语义稳定在
+ *  「缓冲堆了约 N 份快照」，不随会话长短漂移。 */
+const SNAPSHOT_BACKPRESSURE_FACTOR = 3;
+/** 背压绝对下限：低于此积压永不丢快照（小会话的相对阈值只有几 KB，会被
+ *  正常的消息突发误伤，见 send() 内注释）。 */
+const SNAPSHOT_BACKPRESSURE_MIN_BYTES = 262_144;
+/** 背压丢弃后的延迟重发间隔。 */
+const SNAPSHOT_RETRY_MS = 250;
+/**
+ * Multi-tab serialization sharing: emit() hands the SAME message object to
+ * every socket of a client, but each send() used to JSON.stringify it
+ * separately — N open tabs serialized the same multi-MB snapshot N times per
+ * push. Keyed by object identity (WeakMap): a new snapshot is a new object,
+ * so the cache self-invalidates and never grows.
+ */
+const serializedCache = new WeakMap();
+function serializeShared(msg) {
+    let s = serializedCache.get(msg);
+    if (s === undefined) {
+        s = JSON.stringify(msg);
+        serializedCache.set(msg, s);
+    }
+    return s;
+}
+/** Async handlers are fired with `void`; a rejection there is a bug in one request,
+ *  not a reason to exit. Log with the stack so it can still be found. */
+process.on("unhandledRejection", (reason) => {
+    console.error("[server] unhandled rejection:", reason instanceof Error ? reason.stack ?? reason.message : reason);
+});
+function reportBadMessage(type, err) {
+    console.error(`[ws] handler for "${String(type)}" threw:`, err instanceof Error ? err.stack ?? err.message : err);
+}
+wss.on("connection", (ws) => {
+    // Count attached sockets (the control socket reports REAL sockets, not
+    // cached client-session objects).
+    service.noteSocketOpen();
+    let clientId = null;
+    let closed = false;
+    /** 最近一份全量 snapshot 的估算字节数（UTF-16 ×2），供背压相对阈值用（issue #11）。 */
+    let lastSnapshotBytes = 0;
+    /** Commands received while the session is still being created — replayed after attach. */
+    let pending = [];
+    /** 背压丢快照后的延迟重发定时器（去重：一次只排一个）。 */
+    let snapshotRetryTimer = null;
+    // 协议层错误（非法帧/未 masked 帧等）：不注册 handler 会作为 uncaught
+    // exception 打崩整个进程（issue #11 附带发现）。记日志并按坏连接关闭。
+    ws.on("error", (err) => {
+        console.error(`[ws] socket error${clientId ? ` (${clientId})` : ""}:`, err.message);
+        try {
+            ws.close();
+        }
+        catch {
+            /* already closing */
+        }
+    });
+    const send = (msg) => {
+        if (closed || ws.readyState !== WebSocket.OPEN)
+            return;
+        // 发送背压（issue #11）：socket 消费不过来时（前端慢/网络差），堆里会堆积
+        // 每份可达 ~10MB 的全量 snapshot 字符串，低内存主机直接 OOM。snapshot 是全量
+        // 幂等的且稍后必有更新的一份，可以安全丢弃——在序列化之前丢，连
+        // stringify 的分配都省掉。ready/notice/error/tool_delta 等消息必须送达。
+        // 阈值相对化（评论区建议）：用「最近一份 snapshot 的字节数 × 倍数」做基准，
+        // 首份无基准不丢（首次必达）。wire.length 是 UTF-16 字符数，×2 估算字节。
+        // 下限保护（小会话误伤修复）：小会话一份 snapshot 才 ~1KB，相对阈值只有几
+        // KB——前面一批 settings_state/slash_commands 的正常突发就能把 bufferedAmount
+        // 抬过阈值，把紧随其后的 snapshot_delta 静默丢掉；而丢弃后若无后续事件就
+        // 再也没有快照，客户端永远停在旧状态（前端靠 rev 缺口 get_state 自愈，
+        // 协议测试则直接卡死）。绝对下限保证小会话永不触发背压。
+        if ((msg.type === "snapshot" || msg.type === "snapshot_delta") &&
+            lastSnapshotBytes > 0 &&
+            ws.bufferedAmount > Math.max(SNAPSHOT_BACKPRESSURE_MIN_BYTES, SNAPSHOT_BACKPRESSURE_FACTOR * lastSnapshotBytes)) {
+            // 真正的慢客户端：丢弃是安全的，但不能「丢完就没了」——安排一次延迟
+            // 重发，等缓冲排空后快照最终必达（否则若此后再无事件，客户端将永久
+            // 停留在旧快照）。重发仍走 flushSnapshot：缓冲未排空则再次顺延。
+            if (!snapshotRetryTimer) {
+                snapshotRetryTimer = setTimeout(() => {
+                    snapshotRetryTimer = null;
+                    service.get(clientId ?? "")?.flushSnapshot();
+                }, SNAPSHOT_RETRY_MS);
+            }
+            return;
+        }
+        const wire = serializeShared(msg);
+        if (msg.type === "snapshot")
+            lastSnapshotBytes = wire.length * 2;
+        ws.send(wire);
+    };
+    // Plugins broadcast to every open socket; unregister on close below. The
+    // cid getter lets plugins target THIS socket via host.sendTo(clientId).
+    const removePluginSender = pluginMgr.addSender(send, () => clientId);
+    let detachNodes;
+    /** One malformed or unexpected message must never take the whole server (and every
+     *  client's running agent) down: report it to this client and keep going. */
+    const dispatch = (msg) => {
+        try {
+            dispatchUnsafe(msg);
+        }
+        catch (err) {
+            reportBadMessage(msg?.type, err);
+            send({ type: "notice", level: "error", text: `请求处理失败（${String(msg?.type)}）：${err.message}` });
+        }
+    };
+    const dispatchUnsafe = (msg) => {
+        if (!clientId) {
+            pending.push(msg);
+            return;
+        }
+        const cs = service.get(clientId);
+        if (!cs) {
+            // Session not ready yet (hello processing) — hold the command.
+            pending.push(msg);
+            return;
+        }
+        if (cs.switchingWorkspace && msg.type !== "set_cwd" && msg.type !== "get_state") {
+            if (msg.type === "prompt" && msg.requestId)
+                send({ type: "prompt_result", requestId: msg.requestId, ok: false });
+            if (msg.type === "read_file" || msg.type === "write_file")
+                send({
+                    type: "file_result", operation: msg.type === "read_file" ? "read" : "write",
+                    requestId: msg.requestId, cwd: msg.cwd ?? cs.cwd, path: msg.path,
+                    ok: false, error: "工作区切换中，请稍后重试",
+                });
+            return;
+        }
+        switch (msg.type) {
+            case "node_request":
+                void nodeWorkbench.handle(clientId, msg);
+                break;
+            case "prompt":
+                void cs.prompt(msg.text, msg.attachments, msg.queue, msg.requestId);
+                break;
+            case "abort":
+                void cs.abort();
+                break;
+            case "retry_silent_prompt":
+                void cs.retrySilentPrompt(msg.conversationId, msg.text);
+                break;
+            case "kill_background_server":
+                void cs.killBackgroundServer(msg.port, msg.taskId);
+                break;
+            case "kill_background_servers":
+                void cs.killAllBackgroundServers();
+                break;
+            case "list_bg_servers":
+                void cs.listBgServers();
+                break;
+            case "new_chat":
+                void cs.newChat();
+                break;
+            case "tree_get":
+            case "tree_content":
+            case "tree_preview":
+            case "tree_navigate":
+            case "tree_label":
+            case "session_clone":
+            case "session_fork":
+            case "session_reopen":
+                void cs.treeRequest(msg);
+                break;
+            case "edit_message":
+                void cs.editMessage(msg.messageId, msg.text, msg.attachments, msg);
+                break;
+            case "cycle_model":
+                void cs.cycleModel();
+                break;
+            case "cycle_thinking":
+                cs.cycleThinking();
+                break;
+            case "get_state":
+                // Always a FULL snapshot: the client is (re)connecting or detected
+                // a rev/seq gap — it needs an authoritative state to rebuild from.
+                cs.flushSnapshot(true);
+                break;
+            case "get_commands":
+                void cs.pushSlashCommands();
+                break;
+            case "list_sessions":
+                void cs.refreshSessions();
+                break;
+            case "list_projects":
+                void cs.pushProjects();
+                break;
+            case "remove_project":
+                void cs.removeProject(msg.path);
+                break;
+            case "delete_session":
+                void cs.deleteSession(msg.path);
+                break;
+            case "rename_session":
+                void cs.renameSession(msg.path, msg.name);
+                break;
+            case "browse_dirs":
+                void cs.browseDirs(msg.path);
+                break;
+            case "switch_session":
+                void cs.switchSession(msg.path);
+                break;
+            case "switch_conversation":
+                void cs.switchConversation(msg.id);
+                break;
+            case "list_files":
+                void cs.listFiles(msg.path);
+                break;
+            case "check_conversation_files":
+                cs.checkConversationFiles(msg.cwd, msg.reqId, msg.paths);
+                break;
+            case "search_files":
+                void cs.searchFiles(msg.query, msg.reqId);
+                break;
+            case "get_git_branch":
+                void cs.gitBranch();
+                break;
+            case "scm_diff":
+                void cs.scmQuery("diff", msg.reqId, { scope: msg.scope, base: msg.base });
+                break;
+            case "scm_status":
+                void cs.scmQuery("status", msg.reqId);
+                break;
+            case "scm_history":
+                void cs.scmQuery("history", msg.reqId);
+                break;
+            case "scm_filediff":
+                void cs.scmQuery("filediff", msg.reqId, { path: msg.path });
+                break;
+            case "scm_commit":
+                void cs.scmQuery("commit", msg.reqId, { hash: msg.hash });
+                break;
+            case "read_file":
+                void cs.readFile(msg.path, msg);
+                break;
+            case "write_file":
+                void cs.writeFile(msg.path, msg.text, msg);
+                break;
+            case "list_models":
+                void cs.listModels();
+                break;
+            case "set_model":
+                void cs.setModel(msg.modelId);
+                break;
+            case "set_thinking":
+                cs.setThinking(msg.level);
+                break;
+            case "set_cwd":
+                void cs.setCwd(msg.path, msg.requestId, msg.source);
+                break;
+            case "complete_path":
+                void cs.completePath(msg.path);
+                break;
+            case "check_component_updates":
+                void cs.checkComponentUpdates(msg.requestId);
+                break;
+            case "update_component":
+                if (service.quiesceInfo().quiesced || service.activeConversations() || service.pendingMessages()) {
+                    send({ type: "component_updates", requestId: msg.requestId, cwd: cs.cwd, phase: "error", items: [], error: "请等待所有任务结束后再更新扩展" });
+                }
+                else {
+                    service.quiesce();
+                    void cs.updateComponent(msg.requestId, msg.id).finally(() => service.unquiesce());
+                }
+                break;
+            case "check_update":
+                void cs.checkUpdate();
+                break;
+            case "queue_recall_ack":
+                cs.acknowledgeQueueRecall(msg.conversationId, msg.requestId);
+                break;
+            case "recall_queue":
+                cs.recallQueue(msg.conversationId, msg.requestId);
+                break;
+            case "cancel_recovery":
+                cs.cancelRecovery(msg.conversationId, msg.operationId);
+                break;
+            case "set_run_settings":
+                cs.setRunSettings(msg);
+                break;
+            case "dialog_response":
+                cs.resolveDialog(msg.conversationId, msg.id, msg.value);
+                break;
+            case "install_pi_agent":
+                void cs.installPiAgent();
+                break;
+            case "logout_provider":
+                void cs.providerAuth.logout(msg.provider);
+                break;
+            case "native_mcp_request":
+                void cs.nativeMcpRequest(msg);
+                break;
+            case "login_provider":
+                void cs.providerAuth.login(msg.provider);
+                break;
+            case "cancel_provider_login":
+                cs.providerAuth.cancel(msg.requestId);
+                break;
+            case "provider_auth_response":
+                cs.providerAuth.respond(msg.requestId, msg.promptId, msg.value);
+                break;
+            case "set_provider_api_key":
+                void cs.setProviderApiKey(msg.provider, msg.apiKey);
+                break;
+            case "clear_provider_api_key":
+                void cs.clearProviderApiKey(msg.provider);
+                break;
+            case "list_models_config":
+                void cs.listModelsConfig();
+                break;
+            case "save_model_config":
+                void cs.saveModelConfig(msg.providerId, msg.config);
+                break;
+            case "delete_model_config":
+                void cs.deleteModelConfig(msg.providerId);
+                break;
+            case "list_providers":
+                void cs.listProviders();
+                break;
+            case "fetch_models":
+                void cs.fetchModelsList(msg.reqId, msg.baseUrl, msg.apiKey, msg.authHeader, msg.api);
+                break;
+            case "refresh_provider_models":
+                void cs.refreshProviderModels(msg.providerId, msg.reqId);
+                break;
+            case "clone_provider":
+                void cs.cloneProvider(msg.provider, msg.reqId);
+                break;
+            case "terminal_create": {
+                const tm = cs.getTerminalManager(msg.conversationId);
+                if (tm)
+                    tm.create(msg.terminalId, msg.cwd, msg.cols, msg.rows, cs.getTerminalCwd(msg.conversationId));
+                break;
+            }
+            case "terminal_input":
+                cs.getTerminalManager(msg.conversationId)?.input(msg.terminalId, msg.data);
+                break;
+            case "terminal_resize":
+                cs.getTerminalManager(msg.conversationId)?.resize(msg.terminalId, msg.cols, msg.rows);
+                break;
+            case "terminal_kill":
+                cs.getTerminalManager(msg.conversationId)?.kill(msg.terminalId);
+                break;
+            case "run_command":
+                cs.getTerminalManager(msg.conversationId)?.runCommand(msg.terminalId, msg.command, msg.cols, msg.rows, cs.getTerminalCwd(msg.conversationId));
+                break;
+            case "list_commands":
+                void cs.listCommands();
+                break;
+            case "save_commands":
+                void cs.saveCommands(msg.commands);
+                break;
+            case "set_plan_enabled":
+                void cs.setPlanEnabled(msg.enabled, msg.conversationId).catch(error => send({ type: "notice", level: "error", text: String(error.message ?? error) }));
+                break;
+            case "get_settings":
+                cs.pushSettings();
+                break;
+            case "set_settings":
+                void cs.setSettings({
+                    editResendNewSession: msg.editResendNewSession,
+                    disabledPlugins: msg.disabledPlugins,
+                    thinkingWrap: msg.thinkingWrap,
+                    toolsWrap: msg.toolsWrap,
+                });
+                break;
+            case "extensions_reload":
+                void cs.reloadExtensions();
+                break;
+            case "plugin_message":
+                pluginMgr.handleMessage(msg.pluginId, msg.payload, clientId ?? undefined);
+                break;
+            case "plugin_settings": {
+                const r = pluginMgr.savePluginSettings(msg.pluginId, msg.values ?? {});
+                if (r.error) {
+                    cs?.emitNotice("error", `插件设置保存失败：${r.error}`);
+                }
+                else {
+                    cs?.emitNotice("info", "插件设置已保存");
+                }
+                break;
+            }
+            case "plugins_reload":
+                void pluginMgr.reload().then(() => pluginMgr.pushToAll());
+                break;
+            default:
+                break;
+        }
+    };
+    ws.on("message", (data) => {
+        let msg;
+        try {
+            msg = JSON.parse(data.toString());
+        }
+        catch {
+            return;
+        }
+        if (msg.type === "hello") {
+            if (msg.clientId !== undefined && msg.clientId !== "" && !isValidClientId(msg.clientId)) {
+                ws.close(4400, "invalid clientId");
+                return;
+            }
+            const cid = msg.clientId || randomUUID();
+            clientId = cid;
+            service
+                .attach(cid, send)
+                .then((cs) => {
+                if (closed)
+                    return;
+                detachNodes?.();
+                detachNodes = nodeWorkbench.attach(cid, send);
+                send({
+                    type: "ready",
+                    clientId: cid,
+                    serverVersion: APP_VERSION,
+                    protocolVersion: PROTOCOL_VERSION,
+                });
+                cs.flushSnapshot();
+                // Plugin catalog: re-scan + activate new dirs on every attach so
+                // freshly dropped plugins show up without a server restart.
+                pluginMgr
+                    .ensureLoaded()
+                    .then((plugins) => {
+                    send({ type: "plugins", plugins, epoch: pluginMgr.epoch });
+                    // 让各插件向新接入的客户端推送自身初始状态（onAttach 钩子）——
+                    // 插件不要依赖客户端挂载后自己拉（见 plugins.ts onAttach 注释）。
+                    pluginMgr.notifyAttach(cid);
+                    // 插件命令可能在本客户端 attach 过程中才注册（首载竞态）——
+                    // 重推一次目录，保证选择器完整。
+                })
+                    .catch(() => { });
+                // Replay anything that arrived while the session was starting.
+                const queued = pending;
+                pending = [];
+                for (const m of queued)
+                    dispatch(m);
+            })
+                .catch((err) => {
+                // Admission refused (quiesce): close the socket so the browser
+                // reconnect loop keeps retrying until admission reopens. Do NOT
+                // leave a half-alive connection that can only show an error.
+                if (err instanceof QuiesceRejectedError) {
+                    closed = true;
+                    if (ws.readyState === WebSocket.OPEN) {
+                        ws.close(4403, "quiesced");
+                    }
+                    ws.terminate?.();
+                    return;
+                }
+                // Real init failure (bad agent dir etc.) — keep the connection
+                // open so the user can see the error and fix it.
+                send({
+                    type: "notice",
+                    level: "error",
+                    text: `会话初始化失败：${err.message}`,
+                });
+            });
+            return;
+        }
+        dispatch(msg);
+    });
+    ws.on("close", () => {
+        service.noteSocketClose();
+        closed = true;
+        pending = [];
+        removePluginSender();
+        detachNodes?.();
+        if (snapshotRetryTimer) {
+            clearTimeout(snapshotRetryTimer);
+            snapshotRetryTimer = null;
+        }
+        if (clientId)
+            service.detach(clientId, send);
+    });
+});
+// When spawned by the old process as an auto-restart replacement, wait for
+// the old instance to release the port before binding (it exits right after
+// spawning us). Probe by attempting a connection: refused = free.
+if (process.env[RESTART_CHILD_ENV] === "1") {
+    const deadline = Date.now() + 20_000;
+    const portFree = () => new Promise((resolve) => {
+        const sock = createConnection({ port: PORT, host: "127.0.0.1" });
+        sock.once("connect", () => {
+            sock.destroy();
+            resolve(false); // busy — old instance still up
+        });
+        sock.once("error", () => resolve(true)); // refused → free
+        sock.setTimeout(500, () => {
+            sock.destroy();
+            resolve(false);
+        });
+    });
+    while (Date.now() < deadline) {
+        if (await portFree())
+            break;
+        await new Promise((r) => setTimeout(r, 300));
+    }
+}
+httpServer.listen(PORT, HOST, () => {
+    console.log("");
+    console.log("  ⚡ pi-harness — web chat for the pi coding agent");
+    console.log(`    http://localhost:${PORT}`);
+    console.log(`    workspace   : ${CWD}`);
+    console.log(`    session dir : ${SESSION_DIR_ROOT}`);
+    console.log(`    pi SDK      : v${VERSION}`);
+    console.log(`    bind        : ${HOST}:${PORT}`);
+    console.log("");
+});
+// 上传文件保留期清理：启动扫一次 + 每 6 小时一次（best-effort，见 uploads.ts）
+scheduleUploadCleanup();
+// Local control socket (status / quiesce / unquiesce) — same data dir the
+// CLI uses, so `pi-harness server status|quiesce|unquiesce` just works.
+const stopControl = startControlServer({ service, dataDir: DATA_DIR, port: PORT });
+let shuttingDown = false;
+async function shutdown() {
+    if (shuttingDown)
+        return;
+    shuttingDown = true;
+    console.log("\nshutting down…");
+    clearInterval(heartbeatTimer);
+    stopControl();
+    nodeWorkbench.dispose();
+    pluginMgr.dispose();
+    await service.disposeAll();
+    wss.close();
+    httpServer.close();
+    process.exit(0);
+}
+process.on("SIGINT", () => void shutdown());
+process.on("SIGTERM", () => void shutdown());