@youweichen/pi-web-ui 0.45.0

package/dist/server/agent-service.js

@@ -0,0 +1,2975 @@
+/**
+ * AgentService — wraps the pi SDK (@earendil-works/pi-coding-agent) for the web
+ * frontend. Each browser client (identified by a persistent clientId) gets its
+ * own AgentSessionRuntime, but sessions live in the SDK default per-project
+ * directory (<agentDir>/sessions/--<cwd>--/) — the same transcript files the
+ * pi CLI/TUI use — so every conversation of a folder shows up everywhere.
+ *
+ * Streaming model: the SDK emits AgentSessionEvents; we forward lightweight
+ * `tool_delta` messages for live tool output and schedule throttled full-state
+ * snapshots. The frontend is snapshot-driven (server is the source of truth),
+ * so reconnects just re-request a snapshot.
+ */
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync, readFileSync, rmSync, statSync, writeFileSync, mkdirSync, watch, } from "node:fs";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createAgentSessionFromServices, createAgentSessionRuntime, createAgentSessionServices, createBashTool, createLocalBashOperations, defineTool, getAgentDir, ModelRuntime, SessionManager, VERSION, } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { BgServerTracker } from "./bg-servers.js";
+import { syncPluginToolsIntoSession } from "./plugins.js";
+import { SettingsService } from "./settings-service.js";
+import { GoalService } from "./goal-service.js";
+import { SlashCommandsService, parseSlash } from "./slash-commands.js";
+import { ModelAdminService } from "./model-admin.js";
+import { FilesService, workspacePath } from "./files-service.js";
+import { isExtensionDisabled, ClientStateStore, } from "./client-state.js";
+import { saveUpload } from "./uploads.js";
+import { makePersistentTerminalTools, makeTerminalBashTool, stripAnsi, TERMINAL_TOOLS_GUIDANCE, TERMINAL_TOOL_NAMES, } from "./terminals.js";
+import { WebUIContext } from "./webui-context.js";
+import { buildAttachmentMessages, parseModelSpec, } from "./attachments.js";
+import { serializeMessage, serializeStreamingMessage, } from "./serialize.js";
+import { loadCommands, saveCommandsFile, TerminalManager, } from "./terminals.js";
+import { buildVisionBridgePrompt, SYSTEM_PROMPT, transcribeImages, } from "./vision-bridge.js";
+const SNAPSHOT_INTERVAL_MS = 60;
+/** While assistant deltas are flowing, live rendering is carried by
+ *  message_delta — full snapshots become pure reconciliation checkpoints, so
+ *  send them on a slow event-driven cadence (see flushSnapshot call-sites:
+ *  agent_end / tool_execution_end always checkpoint immediately). */
+const STREAMING_SNAPSHOT_INTERVAL_MS = 2000;
+/** Deltas newer than this keep the streaming (low-frequency) snapshot cadence. */
+const DELTA_ACTIVE_WINDOW_MS = 1500;
+const WIDGET_REFRESH_MS = 2000;
+/** Model-stall watchdog: warn (don't abort — deep thinking can be legitimately
+ *  quiet for minutes) when a streaming run produced NO SDK events for this long.
+ *  Covers the failure class the per-tool watchdog cannot see: half-open API
+ *  connections / hung proxies where no tool is running and no error is thrown.
+ *  Override: PI_WEB_STALL_NOTIFY_MS (milliseconds; 0 disables). */
+const STALL_NOTIFY_MS = (() => {
+    const v = Number(process.env.PI_WEB_STALL_NOTIFY_MS);
+    return Number.isFinite(v) && v >= 0 ? v : 180_000;
+})();
+/** Serialization-cache cap per conversation (see serializeCached): cached
+ *  UiMessage objects are pure-function results, so eviction only costs a
+ *  recompute on next access. Bounds memory for marathon sessions. */
+const UI_MESSAGE_CACHE_CAP = 4096;
+/** Preview panel cap: only the first 512KB of a file is ever read/sent. */
+/** Thrown when the service is quiesced (draining) and the request is NEW work
+ *  the admission controller refuses: a brand-new client attach, a prompt,
+ *  a fork, a session resume, or a goal wizard start. index.ts closes the
+ *  WebSocket with 4403 so the browser reconnect loop can retry after the
+ *  server reopens admission (see AgentService.quiesce). */
+export class QuiesceRejectedError extends Error {
+    code = "QUIESCED";
+    constructor(detail) {
+        super(`服务器正在排空存量工作（quiesce）——${detail}`);
+        this.name = "QuiesceRejectedError";
+    }
+}
+// ---------------------------------------------------------------------------
+// Preview kind classification. The preview panel only opens image / video /
+// text-editable files; everything else (exe, jar, archives, …) is refused so
+// it is never read or sent to the browser. Media files are served over the
+// /api/file HTTP endpoint instead of the WebSocket, so they are classified
+// here but never read into the snapshot path.
+// ---------------------------------------------------------------------------
+/** Windows persona appendix — appended to the SDK system prompt on win32 only.
+ *  Two failure modes it guards against: (1) the SDK bash tool has NO default
+ *  timeout, so a long-running command hangs the whole conversation forever;
+ *  (2) the in-app terminal is an interactive TTY where heredocs / interactive
+ *  programs wait for input that never comes. Legacy Chinese files are often
+ *  GBK/GB2312 — read them with the right encoding, never paste mojibake into
+ *  reasoning/answers. */
+const WINDOWS_PERSONA = `You are a coding agent running on Windows. The bash tool runs Git Bash (bash.exe), not PowerShell. Follow these rules to avoid hanging the session:
+
+
+
+- ALWAYS pass a timeout parameter to the bash tool (in seconds). There is NO default timeout — a command that never finishes (servers, watchers, infinite loops, slow downloads/installs) will hang the entire conversation indefinitely. Pick a generous timeout for long-running work, but never omit it.
+- NEVER run interactive or foreground long-running commands through the bash tool (vi, less, top, python -, node -, npm run dev, sleep 10000). For servers/daemons use background execution with output redirected to a log file, then poll the log; stop them when done.
+- In the interactive terminal (TTY) — which is Git Bash too, not PowerShell — NEVER use heredocs (<<'EOF' ... EOF) or here-strings, and NEVER start interactive programs (vi, less, python -, node -, npm init): they wait for keyboard input that never arrives and hang the terminal forever. Prefer writing a temp script file (e.g. .pi-tmp.sh) and running it non-interactively. ALWAYS pass a timeout to long-running commands (e.g. \`timeout 120 npm run dev\`).
+
+Many legacy Chinese text files (.html/.txt/.md/.log, exported documents) are GBK/GB2312 encoded: the read tool decodes UTF-8 only and will show mojibake (乱码) for them. If a file's content looks garbled, read it through the terminal instead: in Git Bash use \`cat file | iconv -f GBK -t UTF-8\` (or \`iconv -f GBK -t UTF-8 file\`); in cmd use \`chcp 65001 && type file\`; in PowerShell use \`Get-Content -Encoding Default file\`. Never paste mojibake into your reasoning or answer — describe the decoded content instead.`;
+/**
+ * Killable bash tool: wraps the SDK bash tool with operations that register
+ * their own AbortController into a client-level set. abortBash() aborts only
+ * those controllers → the command's process tree is killed while the agent
+ * run and the conversation continue (the tool returns an aborted error and
+ * the model moves on). Injected as a customTool overriding the builtin bash.
+ */
+function makeKillableBashTool(cwd, kills) {
+    const base = createLocalBashOperations();
+    const tool = createBashTool(cwd, {
+        operations: {
+            exec: async (command, c, opts) => {
+                const ac = new AbortController();
+                kills.add(ac);
+                try {
+                    const signals = [opts.signal, ac.signal].filter((s) => s !== undefined);
+                    return await base.exec(command, c, {
+                        ...opts,
+                        signal: signals.length > 1 ? AbortSignal.any(signals) : signals[0],
+                    });
+                }
+                finally {
+                    kills.delete(ac);
+                }
+            },
+        },
+    });
+    // AgentTool → ToolDefinition (same fields; customTools expects definitions).
+    return {
+        name: tool.name,
+        label: tool.label,
+        description: tool.description,
+        parameters: tool.parameters,
+        prepareArguments: tool.prepareArguments,
+        executionMode: tool.executionMode,
+        execute: (toolCallId, params, signal, onUpdate) => tool.execute(toolCallId, params, signal, onUpdate),
+    };
+}
+/**
+ * 动态分流 bash：调用时按设置决定走哪套实现——「终端接管 bash」开关因此
+ * 即时生效（customTools 在 runtime 创建时固定，不能在创建时二选一）。
+ */
+function makeAdaptiveBashTool(killable, terminalBacked, useTerminal) {
+    return {
+        ...killable,
+        execute: (id, params, signal, onUpdate, ctx) => (useTerminal() ? terminalBacked : killable).execute(id, params, signal, onUpdate, ctx),
+    };
+}
+/**
+ * 插件结构化工具 → SDK ToolDefinition。
+ * execute 返回值宽容处理：{content,details} 原样收编；字符串/对象包成文本块。
+ */
+function pluginToolToDefinition(tool) {
+    const normalize = (result) => {
+        if (result &&
+            typeof result === "object" &&
+            Array.isArray(result.content)) {
+            return result;
+        }
+        const text = typeof result === "string" ? result : JSON.stringify(result ?? null, null, 2);
+        return { content: [{ type: "text", text }] };
+    };
+    return {
+        name: tool.name,
+        label: tool.label ?? tool.name,
+        description: tool.description,
+        promptSnippet: tool.promptSnippet,
+        promptGuidelines: tool.promptGuidelines,
+        parameters: (tool.parameters ?? {
+            type: "object",
+            properties: {},
+        }),
+        execute: async (toolCallId, params, signal, onUpdate) => {
+            const raw = await tool.execute(toolCallId, params, signal, onUpdate
+                ? (partial) => onUpdate(normalize(partial))
+                : undefined);
+            return normalize(raw);
+        },
+    };
+}
+/**
+ * Cheap per-message discriminator for the serialization cache key. Persisted
+ * message content never changes, so this is stable across snapshots, while
+ * several same-role messages created within one millisecond (attachment
+ * asides) get distinct keys. Text blocks are fingerprinted by a short hash of
+ * their head (paths embedded in <file> tags can share long prefixes — e.g.
+ * uploads created in the same millisecond differ only at the tail); image
+ * payloads by data length (identical lengths within the same ms are far too
+ * unlikely to matter).
+ */
+function contentFingerprint(m) {
+    const content = m.content;
+    if (!Array.isArray(content) || content.length === 0)
+        return "empty";
+    const first = content[0];
+    if (first?.type === "image") {
+        return `img:${(first.data ?? "").length}`;
+    }
+    const text = typeof first?.text === "string" ? first.text : "";
+    // djb2 — fast enough to run per snapshot, distinct enough for asides.
+    let h = 5381;
+    for (let i = 0; i < text.length && i < 512; i++) {
+        h = ((h << 5) + h + text.charCodeAt(i)) >>> 0;
+    }
+    return `txt:${h.toString(36)}:${text.length}`;
+}
+// ---------------------------------------------------------------------------
+// Web UI context adapter — bridges extension UI calls (setWidget/notify) to the
+// browser. Extensions like rpiv-todo render a TUI widget via
+// `ui.setWidget(key, (tui, theme) => comp)`; we capture the component, render it
+// with a mock theme to plain text lines, and push them to the client.
+// ---------------------------------------------------------------------------
+function extractPartialText(partial) {
+    const content = partial
+        ?.content;
+    if (Array.isArray(content)) {
+        const text = content
+            .map((c) => c?.type === "text"
+            ? c.text
+            : "")
+            .join("");
+        return text.length > 0 ? text : null;
+    }
+    return null;
+}
+export { workspacePath };
+/** Hard cap on how long ONE tool call may run before the watchdog aborts the
+ *  session. The SDK bash tool has NO default timeout, so a command that never
+ *  finishes (servers, watchers, infinite loops) would otherwise hang the whole
+ *  conversation indefinitely. Override with the PI_WEB_TOOL_TIMEOUT_MS env var
+ *  (milliseconds). */
+const TOOL_WATCHDOG_TIMEOUT_MS = (() => {
+    const v = Number(process.env.PI_WEB_TOOL_TIMEOUT_MS);
+    return Number.isFinite(v) && v > 0 ? v : 20 * 60_000;
+})();
+/** Cap on simultaneously open conversations of ONE project (each keeps a full
+ *  runtime alive; conversations of other projects keep their own lists). */
+const MAX_OPEN_CONVERSATIONS = 8;
+const DEFAULT_CONV_TITLE = "新对话";
+/** First user text in a session, truncated for the conversation list. */
+function conversationTitle(session) {
+    try {
+        for (const m of session.agent.state.messages) {
+            if (m.role !== "user")
+                continue;
+            const content = m.content;
+            let text = "";
+            if (typeof content === "string") {
+                text = content;
+            }
+            else if (Array.isArray(content)) {
+                for (const p of content) {
+                    if (p &&
+                        typeof p === "object" &&
+                        p.type === "text" &&
+                        typeof p.text === "string") {
+                        text = p.text;
+                        break;
+                    }
+                }
+            }
+            const trimmed = text.trim().replace(/\s+/g, " ");
+            if (trimmed.length > 0) {
+                return trimmed.length > 30 ? `${trimmed.slice(0, 30)}…` : trimmed;
+            }
+        }
+    }
+    catch {
+        // best-effort
+    }
+    return DEFAULT_CONV_TITLE;
+}
+export class ClientSession {
+    clientId;
+    /** Set by AgentService.attach: reflects the SERVICE-wide quiesce flag
+     *  (server draining — new work rejected). Default false for direct use. */
+    isQuiesced = () => false;
+    cwd;
+    /** pi config dir (auth/models/skills). */
+    agentDir;
+    /** Persisted per-client UI state (last workspace + recent projects). */
+    stateStore;
+    /** Open conversations — each owns its OWN runtime, so starting a new chat
+     *  or switching chats never interrupts an in-flight run. `runtime` and
+     *  `session` accessors below target the ACTIVE conversation. */
+    convs = new Map();
+    activeId = "";
+    convSeq = 0;
+    /** One ModelRuntime shared by all conversations — the model chosen in the
+     *  top bar applies to every chat, not just the one that set it. Seeded by
+     *  the first conversation and reused by later ones. */
+    sharedModelRuntime;
+    // -----------------------------------------------------------------------
+    // Goal / review / wizard —— 自包含模块，见 goal-service.ts。每个对话有独立
+    // 的 GoalStatus，审查可并发；宿主回调在构造函数里接入。
+    // -----------------------------------------------------------------------
+    goalSvc;
+    /** Settings-panel state (system prompt + disabled skills/extensions) —
+     *  自包含模块，见 settings-service.ts。resource-loader overrides 在每次
+     *  reload() 时读 current 的最新值，session.reload() 即可应用到运行中 runtime。 */
+    settingsSvc; // 构造函数里创建（需要 clientId/stateStore）
+    /** How long a hard abort waits for session.abort() to make the run idle
+     *  before force-resetting the conversation (model streams that ignore the
+     *  abort signal would otherwise leave the chat stuck forever). */
+    static HARD_ABORT_TIMEOUT_MS = 15_000;
+    /** Extra settle window after session.abort() returns: the run is only
+     *  considered stopped once its agent_end event arrives. If it doesn't
+     *  (model stream stuck before the run even started), force-reset. */
+    static HARD_ABORT_SETTLE_MS = 8_000;
+    /** Live AbortControllers of THIS client's running bash tool calls — aborting
+     *  them kills only the command (agent run and conversation continue). */
+    bashKills = new Set();
+    /** Background-server tracking (port snapshots + 后台任务 panel state) —
+     *  自包含模块，见 bg-servers.ts。列表按 CLIENT 存活，不随对话切换/结束消失。 */
+    /** 文件树 / 预览读写 / SCM 查询 / watcher —— 自包含模块，见 files-service.ts。 */
+    files = new FilesService({
+        emit: (msg) => this.emit(msg),
+        isDisposed: () => this.disposed,
+        getCwd: () => this.cwd,
+        getActiveCwd: () => this.conv?.cwd ?? this.cwd,
+    });
+    bg = new BgServerTracker({
+        emit: (msg) => this.emit(msg),
+        flushSnapshot: () => this.flushSnapshot(),
+        isDisposed: () => this.disposed,
+        // 插件注册的常驻任务（host.registerBackgroundTask）并入同一「后台任务」面板。
+        pluginTasks: () => this.pluginBgTasksProvider?.() ?? [],
+    });
+    /** index.ts 注入（经 AgentService 拷贝到每个新会话）：把 SDK 工具执行事件转发给
+     *  插件（PluginManager.emitToolEvent）。未设置时不做任何事。 */
+    onToolEvent = undefined;
+    /** index.ts 注入：读取插件当前注册的 AI 工具（attach 时拷贝到每个新会话）。 */
+    pluginToolsProvider = undefined;
+    /** index.ts 注入：读取插件当前注册的斜杠命令（目录展示 + prompt 拦截执行）。 */
+    pluginCommandsProvider = undefined;
+    /** index.ts 注入：读取插件注册的常驻后台任务（并入 bg_servers 面板）。 */
+    pluginBgTasksProvider = undefined;
+    /** index.ts 注入：停止插件任务（kill_background_server with taskId）。 */
+    pluginStopBgTask = undefined;
+    /** 上一轮注入会话的插件工具名集合（用于检测注销/移除）。 */
+    appliedPluginToolNames = new Set();
+    /** The active conversation (all session operations target it). */
+    get conv() {
+        const conv = this.convs.get(this.activeId);
+        if (!conv)
+            throw new Error("no active conversation");
+        return conv;
+    }
+    /** Runtime of the active conversation. */
+    get runtime() {
+        return this.conv.runtime;
+    }
+    /** Session of the active conversation. */
+    get session() {
+        return this.conv.session;
+    }
+    /** PTYs are owned by individual conversations; this getter targets the active one
+     * for compatibility with the existing terminal-panel dispatch path. */
+    get terminals() {
+        return this.conv.terminals;
+    }
+    getTerminalManager(conversationId) {
+        return (conversationId ? this.convs.get(conversationId) : this.conv)?.terminals;
+    }
+    getTerminalCwd(conversationId) {
+        return (conversationId ? this.convs.get(conversationId) : this.conv)?.cwd ?? this.cwd;
+    }
+    makeTerminalManager(conversationId, cwd) {
+        const mgr = new TerminalManager((msg) => this.emitTerminal(conversationId, msg), cwd);
+        // 终端活力检测：AI 触碰过的终端静默 ≥ 阈值（PI_WEB_TERMINAL_IDLE_MS，
+        // 默认 15s）且该对话正在运行时，注入一条 steer 消息唤醒 AI 去检查。
+        mgr.onAgentIdle = (terminalId, idleMs, title) => this.notifyTerminalIdle(conversationId, terminalId, idleMs, title);
+        return mgr;
+    }
+    /** 终端活力提醒：仅在该对话正在流式运行时注入（sendUserMessage 在流式中
+     *  即 steer 语义——当前回合结算后送达，agent 立即响应）；空闲时不打扰。
+     *  一次性语义由 TerminalManager 保证（触发后解除武装，agent 再次触碰才
+     *  重新计时），不会反复刷屏。 */
+    notifyTerminalIdle(conversationId, terminalId, idleMs, title) {
+        const conv = this.convs.get(conversationId);
+        if (!conv || this.disposed)
+            return;
+        if (!conv.runtime.session.isStreaming)
+            return;
+        const seconds = Math.max(1, Math.round(idleMs / 1000));
+        void conv.runtime.session
+            .sendUserMessage(`（系统自动提醒：你启动的终端「${title}」已连续 ${seconds} 秒没有任何新输出。` +
+            `进程可能在等待输入、卡住或已挂起。请用 terminal_read 查看它的当前状态；` +
+            `若在等交互就用 terminal_input / terminal_key 回应；确认不再需要就 terminal_close 关掉它。）`)
+            .catch(() => {
+            // best effort —— 注入失败不影响终端本身
+        });
+    }
+    /**
+     * 终端接管的 bash 静默转后台后的完成通知：命令真正结束时主动告诉 AI。
+     * 流式中 → sendUserMessage（steer，立即唤醒处理）；空闲时 → sendCustomMessage
+     * nextTurn 排队（不唤醒 agent、不耗 token，下次对话自动带上）。
+     */
+    notifyTerminalBashDone(terminals, info) {
+        const conv = [...this.convs.values()].find((c) => c.terminals === terminals);
+        if (!conv || this.disposed)
+            return;
+        let tail = "";
+        try {
+            const end = terminals.endCursor(info.terminalId);
+            if (end !== null) {
+                tail = terminals.read(info.terminalId, Math.max(0, end - 4000))?.data ?? "";
+            }
+        }
+        catch {
+            // 终端可能已被关闭
+        }
+        const exitText = info.exitCode === null ? "终端已关闭" : `退出码 ${info.exitCode}`;
+        const cmdShort = info.command.length > 120 ? `${info.command.slice(0, 120)}…` : info.command;
+        const text = `（系统：你之前在终端 ${info.terminalId} 后台运行的命令已结束（${exitText}）：${cmdShort}\n` +
+            `最后输出：\n${stripAnsi(tail).trim() || "（无输出）"}）`;
+        const session = conv.runtime.session;
+        if (session.isStreaming) {
+            void session.sendUserMessage(text).catch(() => { });
+        }
+        else {
+            // 空闲时不唤醒 agent——排队为 nextTurn 上下文，下次对话自动可见。
+            void session
+                .sendCustomMessage({
+                customType: "terminal-bash-done",
+                content: [{ type: "text", text }],
+                display: true,
+            })
+                .catch(() => { });
+        }
+    }
+    emitTerminal(conversationId, msg) {
+        // Background conversations keep collecting output in their own PTY buffer.
+        // Do not stream it into the active xterm; push the retained window on switch.
+        if (msg.type === "terminal_output" && conversationId !== this.activeId)
+            return;
+        if (msg.type === "terminal_output" || msg.type === "terminal_exit" || msg.type === "terminal_list") {
+            this.emit({ ...msg, conversationId });
+            return;
+        }
+        this.emit(msg);
+    }
+    pushTerminals(conversation = this.conv) {
+        this.emit({
+            type: "terminal_list",
+            conversationId: conversation.id,
+            terminals: conversation.terminals.list(),
+        });
+        for (const output of conversation.terminals.replay()) {
+            this.emit({
+                type: "terminal_output",
+                conversationId: conversation.id,
+                terminalId: output.terminalId,
+                data: output.data,
+            });
+        }
+    }
+    /**
+     * Vision-bridge transcript cache (batch hash → text). A re-sent / re-asked
+     * prompt with the same images skips the vision API call entirely — editing
+     * a question doesn't re-burn tokens on re-transcribing identical screenshots.
+     */
+    /** Most recent built-in (default) system prompt observed by the
+     *  resource-loader override — surfaced via settings_state so the
+     *  replace-mode editor can show the prompt it would otherwise replace.
+     *  Only non-empty when the user has a system-prompt file. */
+    lastBaseSystemPrompt = "";
+    /** The system prompt the replace-mode editor should show as its seed:
+     *  the user's system-prompt file content if one exists, otherwise the
+     *  SDK's built-in default actually in effect (agent.state.systemPrompt,
+     *  which the loader rebuilds at session init). If the user HAS a custom
+     *  prompt the seed is only cosmetic — an unmodified seed is saved as
+     *  empty and the server falls back to the true base. */
+    effectiveDefaultSystemPrompt() {
+        if (this.lastBaseSystemPrompt)
+            return this.lastBaseSystemPrompt;
+        try {
+            const sp = this.session.agent.state.systemPrompt;
+            if (typeof sp === "string" && sp)
+                return sp;
+        }
+        catch {
+            // Session not ready yet.
+        }
+        return "";
+    }
+    /** The FULL system prompt actually in effect right now (AgentSession getter,
+     *  includes the append/replace override + auto-appended sections like
+     *  project context, skills and tool guidance). Read-only view source for
+     *  the settings panel. */
+    effectiveSystemPrompt() {
+        try {
+            const sp = this.session.systemPrompt;
+            return typeof sp === "string" ? sp : "";
+        }
+        catch {
+            // Session not ready yet.
+            return "";
+        }
+    }
+    /** Web-facing extension UI context (widgets, notifications). */
+    webUi = new WebUIContext((msg) => this.emit(msg));
+    widgetsTimer = null;
+    /** Model-stall watchdog interval (see startStallTimer). */
+    stallTimer = null;
+    /** Connected sockets for this client (multiple tabs share the session). */
+    sinks = new Set();
+    pendingNotices = [];
+    snapshotTimer = null;
+    /** Timestamp of the most recent message_delta push — while fresh, snapshots
+     *  use the slower STREAMING_SNAPSHOT_INTERVAL_MS cadence. */
+    lastDeltaAt = 0;
+    sessionsTimer = null;
+    version = 0;
+    /** Snapshot revision counter (see emitSnapshotNow / protocol snapshot_delta). */
+    snapRev = 0;
+    /** Messages array as of the last emitted snapshot/delta — identity-walked
+     *  against the current array to detect append-only growth. */
+    emittedMessages = null;
+    /** Conversation whose messages emittedMessages belongs to. A conversation
+     *  switch (set_cwd / new_chat / switch_*) must fall back to a FULL snapshot:
+     *  two empty conversations have identical (empty) arrays, so the identity
+     *  walk alone would misread the switch as "nothing changed" → delta. */
+    emittedConvId = null;
+    /** snapRev value at which emittedMessages was captured. */
+    emittedRev = 0;
+    /**
+     * Per-conversation serialization caches (stable message ids, UiMessage
+     * object cache, message-array signature, queue counts) live inside each
+     * Conversation — see Conversation above.
+     */
+    disposed = false;
+    /** pi-config readiness check, cached briefly so 60ms snapshots don't hit disk. */
+    piCheckCache = null;
+    /** fs.watch on the currently-listed directory — file changes push an instant
+     *  refresh (`file_changed`) so the tree updates without waiting for the 10s
+     *  poll. Only the listed directory is watched (one level); navigating
+     *  re-watches the new target. fs.watch isn't available on every platform /
+     *  filesystem — failures silently fall back to the poll. */
+    fsWatcher = null;
+    watchPath = null;
+    /** fs.watch on the active repo's git dir — external changes (CLI commit,
+     *  IDE branch switch) push `scm_changed` so the panel refreshes itself.
+     *  One watcher per client session, re-targeted when the queried cwd
+     *  changes; failures (bare repo, unsupported fs) silently disable it. */
+    gitWatcher = null;
+    gitWatchCwd = null;
+    gitDirtyTimer = null;
+    watchTimer = null;
+    constructor(clientId, cwd, agentDir, stateStore) {
+        this.clientId = clientId;
+        this.cwd = cwd;
+        this.agentDir = agentDir;
+        this.stateStore = stateStore;
+        this.settingsSvc = new SettingsService({
+            clientId,
+            stateStore,
+            emit: (msg) => this.emit(msg),
+            flushSnapshot: () => this.flushSnapshot(),
+            isDisposed: () => this.disposed,
+            getSession: () => this.session,
+            cwd: () => this.cwd,
+            agentDir: () => this.agentDir,
+            isStreaming: () => this.session.isStreaming,
+            reloadSession: async () => {
+                await this.session.reload();
+                // reload() 会把 custom 工具重新加回活跃集——重放终端开关。
+                this.applyTerminalToolGating(this.session);
+                await this.pushSlashCommands();
+            },
+            effectiveDefaultSystemPrompt: () => this.effectiveDefaultSystemPrompt(),
+            effectiveSystemPrompt: () => this.effectiveSystemPrompt(),
+        });
+        this.goalSvc = new GoalService({
+            clientId,
+            agentDir,
+            stateStore,
+            webUi: this.webUi,
+            emit: (msg) => this.emit(msg),
+            flushSnapshot: () => this.flushSnapshot(),
+            isDisposed: () => this.disposed,
+            quiesceBlocked: () => this.quiesceBlocked(),
+            activeConvId: () => this.activeId,
+            activeConv: () => this.conv,
+            getConv: (id) => this.convs.get(id),
+            cwd: () => this.cwd,
+            reviewSettings: () => this.settingsSvc.reviewPrefs,
+            gitDiff: (dir) => this.gitDiff(dir),
+        });
+        this.modelAdmin = new ModelAdminService({
+            agentDir,
+            emit: (msg) => this.emit(msg),
+            flushSnapshot: () => this.flushSnapshot(),
+            isDisposed: () => this.disposed,
+            modelRuntime: () => this.runtime.services.modelRuntime,
+            invalidatePiConfig: () => {
+                this.piCheckCache = null;
+            },
+            pushModels: async () => this.listModels(),
+        });
+        // Prune dead background tasks every 30s (only spawns netstat/lsof while
+        // the list is non-empty). unref: must not keep the process alive.
+        this.bg.start();
+    }
+    static async create(clientId, cwd, stateStore) {
+        const agentDir = process.env.PI_CODING_AGENT_DIR ?? getAgentDir();
+        const cs = new ClientSession(clientId, cwd, agentDir, stateStore);
+        const conversationId = cs.nextConversationId();
+        const terminals = cs.makeTerminalManager(conversationId, cwd);
+        const runtime = await createAgentSessionRuntime(cs.makeRuntimeFactory(terminals), {
+            cwd,
+            agentDir,
+            // Resume the most recent session for this project — the SDK default
+            // per-project dir (<agentDir>/sessions/--<cwd>--/, shared with the
+            // pi CLI/TUI) — or start a fresh one on first visit.
+            sessionManager: SessionManager.continueRecent(cwd),
+        });
+        // First conversation = the resumed session; it also seeds the shared
+        // ModelRuntime that every later conversation reuses.
+        cs.sharedModelRuntime = runtime.services.modelRuntime;
+        const conv = cs.makeConversation(runtime, conversationId, terminals);
+        cs.convs.set(conv.id, conv);
+        cs.activeId = conv.id;
+        for (const d of runtime.diagnostics) {
+            if (d.type !== "info") {
+                cs.pendingNotices.push({
+                    type: "notice",
+                    level: d.type,
+                    text: d.message,
+                });
+            }
+        }
+        await cs.bindSession();
+        return cs;
+    }
+    /**
+     * Factory for cwd-bound runtimes. All conversations share ONE ModelRuntime
+     * (the model choice is client-wide), so later conversations reuse the
+     * instance created with the first one.
+     */
+    makeRuntimeFactory(terminals) {
+        return async ({ cwd: effectiveCwd, sessionManager }) => {
+            const services = await createAgentSessionServices({
+                cwd: effectiveCwd,
+                modelRuntime: this.sharedModelRuntime,
+                // 设置面板钩子（官方 SDK 的 resourceLoader overrides）：三个 override
+                // 在每次 resourceLoader.reload() 时重放，且读取 this.settings 的当前
+                // 值——因此 session.reload() 即可让系统提示词 / 技能 / 插件开关生效，
+                // 新对话（新 runtime）也会自动带上当前设置。
+                resourceLoaderOptions: {
+                    // 系统提示词：replace 模式整体替换；append 模式追加到提示词末尾。
+                    systemPromptOverride: (base) => {
+                        // Remember the built-in default so the settings panel can show
+                        // it when the user edits in replace mode.
+                        if (typeof base === "string" && base) {
+                            this.lastBaseSystemPrompt = base;
+                        }
+                        return this.settingsSvc.current.promptMode === "replace" &&
+                            this.settingsSvc.current.customSystemPrompt.trim()
+                            ? this.settingsSvc.current.customSystemPrompt
+                            : base;
+                    },
+                    appendSystemPromptOverride: (base) => {
+                        const out = [...base];
+                        const custom = this.settingsSvc.current.customSystemPrompt.trim();
+                        if (this.settingsSvc.current.promptMode === "append" && custom) {
+                            out.push(custom);
+                        }
+                        if (process.platform === "win32") {
+                            // Windows 专属 persona：bash 工具跑 Git Bash 且无默认超时、终端
+                            // 是交互式 TTY——注入约束避免 heredoc/交互/长驻命令挂死整个会话；
+                            // GBK 老中文文件让模型改用终端按正确编码读（iconv/chcp/Get-Content）。
+                            out.push(WINDOWS_PERSONA);
+                        }
+                        if (this.settingsSvc.current.terminalToolsEnabled !== false) {
+                            // 终端工具使用引导（全平台）：告诉模型什么场景该用持久终端
+                            // 而不是一次性 bash——没有这段模型几乎从不主动选终端工具。
+                            out.push(TERMINAL_TOOLS_GUIDANCE);
+                        }
+                        return out;
+                    },
+                    // 技能开关：禁用的技能从系统提示词和 /skill: 目录中剔除。
+                    skillsOverride: (res) => ({
+                        ...res,
+                        skills: res.skills.filter((s) => !this.settingsSvc.current.disabledSkills.includes(s.name)),
+                    }),
+                    // 插件开关：禁用的扩展整个卸载（工具 / 命令随之消失）。
+                    // 注意 SDK 在 extensionsOverride 之后才补 sourceInfo，包扩展此处只能靠路径
+                    // 匹配 —— isExtensionDisabled 同时比对 npm:<pkg> 候选键。
+                    extensionsOverride: (res) => ({
+                        ...res,
+                        extensions: res.extensions.filter((e) => !isExtensionDisabled(e, this.settingsSvc.current.disabledExtensions)),
+                    }),
+                },
+            });
+            const created = await createAgentSessionFromServices({
+                services,
+                sessionManager,
+                // 可手动停止的 bash 工具：覆盖 SDK 内置 bash（customTools 按 name
+                // 覆盖），执行时把自己的 AbortController 注册进客户端集合——
+                // abortBash() 只杀这些命令，agent run 与对话继续。
+                customTools: [
+                    // bash 双实现动态分流：「终端接管」开启时命令跑进持久可见终端
+                    // （保留 shell 状态、静默自动转后台），关闭时是原生 killable bash。
+                    makeAdaptiveBashTool(makeKillableBashTool(effectiveCwd, this.bashKills), makeTerminalBashTool(terminals, {
+                        cwd: effectiveCwd,
+                        idleMs: () => this.settingsSvc.current.terminalBash
+                            ? Math.max(0, Math.floor(this.settingsSvc.current.terminalBashIdleMs) ||
+                                0)
+                            : 0,
+                        kills: this.bashKills,
+                        notifyBackgroundDone: (info) => this.notifyTerminalBashDone(terminals, info),
+                    }), () => this.settingsSvc.current.terminalBash),
+                    ...makePersistentTerminalTools(terminals, effectiveCwd),
+                    // 插件注册的 AI 工具（创建时刻的实时快照；后续注册经
+                    // refreshPluginTools 动态补入已有会话）。
+                    ...(this.pluginToolsProvider?.() ?? []).map(pluginToolToDefinition),
+                ],
+            });
+            // 终端工具开关从创建起就生效（工具始终注册进注册表，只调活跃集）。
+            this.applyTerminalToolGating(created.session);
+            return {
+                ...created,
+                services,
+                diagnostics: services.diagnostics,
+            };
+        };
+    }
+    /** Create independent goal state for one conversation. Preferences are
+     * client-wide defaults, while goal text/review progress is not shared. */
+    makeGoalStatus() {
+        return this.goalSvc.makeGoalStatus();
+    }
+    /** Allocate a stable conversation id before constructing its runtime/tools. */
+    nextConversationId() {
+        return `c${++this.convSeq}`;
+    }
+    /** Wrap a fresh runtime as a new conversation record. */
+    makeConversation(runtime, id, terminals) {
+        return {
+            id,
+            title: conversationTitle(runtime.session),
+            runtime,
+            session: runtime.session,
+            cwd: runtime.cwd,
+            createdAt: Date.now(),
+            // A brand-new conversation is not yet in the running list — it enters
+            // only when it is displaced to the background while still streaming.
+            listed: false,
+            promptedSinceActive: false,
+            lastActiveAt: Date.now(),
+            lastSdkEventAt: Date.now(),
+            stallNoticed: false,
+            goal: this.makeGoalStatus(),
+            goalGeneration: 0,
+            goalReviewGeneration: 0,
+            wizardRunning: false,
+            deltaSeq: 0,
+            terminals,
+            msgIds: new Map(),
+            nextMsgId: 1,
+            userSeqByTs: new Map(),
+            uiMessageCache: new Map(),
+            lastMessagesSig: "",
+            lastMessagesArray: [],
+            queueSteering: [],
+            queueFollowUp: [],
+            toolStartTimes: new Map(),
+            toolWatchdogs: new Map(),
+        };
+    }
+    /** Summaries of conversations currently streaming — captured at shutdown
+     *  so the next attach can tell the user their run was interrupted. */
+    streamingSummaries() {
+        const out = [];
+        for (const conv of this.convs.values()) {
+            if (conv.session.isStreaming)
+                out.push({ title: conv.title, cwd: conv.cwd });
+        }
+        return out;
+    }
+    /** Tell the user about runs lost to the last server restart (once). */
+    notifyInterrupted(list) {
+        if (!list || list.length === 0)
+            return;
+        const names = list
+            .map((r) => `「${r.title}」（${r.cwd}）`)
+            .join("、");
+        this.pendingNotices.push({
+            type: "notice",
+            level: "warning",
+            text: `上次服务重启时有 ${list.length} 个进行中的对话被中断：${names}。可在历史对话中恢复继续。`,
+        });
+    }
+    /** Add a socket to this client's broadcast set; flushes buffered startup notices. */
+    attachSink(send) {
+        this.sinks.add(send);
+        for (const msg of this.pendingNotices)
+            send(msg);
+        this.pendingNotices = [];
+        // Replay current extension widgets (setWidget may have fired during
+        // session creation, before any socket was attached).
+        const widgets = this.webUi.snapshot();
+        if (widgets.length > 0)
+            send({ type: "widgets", widgets });
+        const statuses = this.webUi.statusSnapshot();
+        if (statuses.length > 0)
+            send({ type: "statuses", statuses });
+        // Reconnect: push the current project's running-conversation list so the
+        // left panel shows every background chat (a fresh socket never got the
+        // newChat/switch pushes).
+        this.emitConversations();
+        // Reconnect: same for the slash-command catalog (the picker needs it even
+        // before the client asks).
+        void this.pushSlashCommands();
+        // Reconnect: push the remembered goal prefs (model choice, rounds cap,
+        // locked) so the goal bar restores them on reload — "全局记忆".
+        this.goalSvc.emitGoalStatus();
+        // Reconnect: push the settings panel state (prompt text/mode, skill &
+        // extension toggles, saved presets).
+        this.pushSettings();
+        // Reconnect: push the background-task list — it must survive reconnects
+        // and outlive the conversation that started the tasks.
+        this.bg.push();
+        // PTYs are conversation-owned and survive a socket reconnect.
+        this.pushTerminals();
+    }
+    detachSink(send) {
+        this.sinks.delete(send);
+        // PTYs intentionally survive a socket drop: they are owned by the
+        // conversation and can be inspected after reconnecting. Only conversation
+        // disposal or server shutdown kills them.
+        if (this.sinks.size === 0) {
+            this.files.unwatchDir();
+        }
+    }
+    /** Broadcast to every connected socket of this client. */
+    emit(msg) {
+        if (this.disposed)
+            return;
+        for (const sink of [...this.sinks])
+            sink(msg);
+    }
+    /** (Re)attach event plumbing to the ACTIVE conversation's session. */
+    async bindSession() {
+        const conv = this.conv;
+        conv.unsubscribe?.();
+        conv.session = conv.runtime.session;
+        await conv.session.bindExtensions({
+            mode: "rpc",
+            uiContext: this.webUi,
+            onError: (err) => {
+                this.emit({ type: "notice", level: "error", text: err.error });
+            },
+        });
+        conv.unsubscribe = conv.session.subscribe((event) => this.onEvent(conv, event));
+        this.scheduleSnapshot();
+        this.webUi.refresh();
+        this.startWidgetsTimer();
+        this.startStallTimer();
+    }
+    /** Poll extension widgets so TUI-only overlays (e.g. rpiv-todo) stay live. */
+    startWidgetsTimer() {
+        if (this.widgetsTimer)
+            return;
+        this.widgetsTimer = setInterval(() => {
+            if (!this.disposed)
+                this.webUi.refresh();
+        }, WIDGET_REFRESH_MS);
+    }
+    /** Model-stall watchdog: warn when a streaming run went completely silent
+     *  (no SDK events at all) for STALL_NOTIFY_MS. Deliberately does NOT abort:
+     *  deep-thinking models can legitimately be quiet for minutes — the notice
+     *  just tells the user the run looks stuck so they can Stop it themselves. */
+    startStallTimer() {
+        if (this.stallTimer || STALL_NOTIFY_MS === 0)
+            return;
+        this.stallTimer = setInterval(() => {
+            if (this.disposed)
+                return;
+            const now = Date.now();
+            for (const conv of this.convs.values()) {
+                if (!conv.stallNoticed &&
+                    conv.session.isStreaming &&
+                    now - conv.lastSdkEventAt > STALL_NOTIFY_MS) {
+                    conv.stallNoticed = true;
+                    const mins = Math.round((now - conv.lastSdkEventAt) / 60_000);
+                    this.emit({
+                        type: "notice",
+                        level: "warning",
+                        text: `对话「${conv.title}」已 ${mins} 分钟无任何响应，可能已失联（网络中断或服务端挂起）。可点击停止后重试。`,
+                    });
+                }
+            }
+        }, 30_000);
+    }
+    /** Arm the hang-guard for a tool call: if it is still running after
+     *  TOOL_WATCHDOG_TIMEOUT_MS, abort the session instead of letting the
+     *  conversation hang forever (the SDK bash tool has no default timeout). */
+    armToolWatchdog(conv, toolCallId) {
+        const t = setTimeout(() => {
+            conv.toolWatchdogs.delete(toolCallId);
+            // The tool finished before the deadline — nothing to do.
+            if (!conv.toolStartTimes.has(toolCallId))
+                return;
+            this.emit({
+                type: "notice",
+                level: "warning",
+                text: `工具执行超过 ${Math.round(TOOL_WATCHDOG_TIMEOUT_MS / 60_000)} 分钟，已自动终止（防止挂死）。可调整超时：环境变量 PI_WEB_TOOL_TIMEOUT_MS（毫秒）。`,
+            });
+            conv.toolStartTimes.delete(toolCallId);
+            // Abort the run (kills the process tree via the SDK's abort signal);
+            // agent_end will fire with stopReason "aborted" and existing logic
+            // clears any goal / review loop. interruptRun adds a force-reset
+            // fallback in case the model stream ignores the abort signal.
+            void this.interruptRun(conv, "工具执行超时");
+        }, TOOL_WATCHDOG_TIMEOUT_MS);
+        t.unref?.();
+        conv.toolWatchdogs.set(toolCallId, t);
+    }
+    /** Cancel a tool's watchdog — called when the tool finishes normally. */
+    clearToolWatchdog(conv, toolCallId) {
+        const t = conv.toolWatchdogs.get(toolCallId);
+        if (t) {
+            clearTimeout(t);
+            conv.toolWatchdogs.delete(toolCallId);
+        }
+    }
+    /** Cancel every watchdog of a conversation (removeConversation / dispose). */
+    clearAllToolWatchdogs(conv) {
+        for (const t of conv.toolWatchdogs.values())
+            clearTimeout(t);
+        conv.toolWatchdogs.clear();
+    }
+    onEvent(conv, event) {
+        // Any SDK event proves the run is alive — feeds the stall watchdog below.
+        conv.lastSdkEventAt = Date.now();
+        conv.stallNoticed = false;
+        switch (event.type) {
+            case "bash_execution_update": {
+                if (event.id) {
+                    this.emit({
+                        type: "tool_delta",
+                        conversationId: conv.id,
+                        seq: ++conv.deltaSeq,
+                        toolCallId: event.id,
+                        toolName: "bash",
+                        delta: event.delta,
+                    });
+                }
+                break;
+            }
+            case "tool_execution_start": {
+                // Record the moment the tool actually starts so tool_status can
+                // report real execution time (vs. time spent waiting on the model).
+                conv.toolStartTimes.set(event.toolCallId, Date.now());
+                // Snapshot listeners before a bash run — the post-run diff catches
+                // servers the agent started in the background.
+                if (event.toolName === "bash") {
+                    this.bg.snapshotBefore();
+                }
+                this.armToolWatchdog(conv, event.toolCallId);
+                // 插件扩展点：工具开始执行（异常由 emitToolEvent 隔离）。
+                this.onToolEvent?.({ phase: "start", toolName: event.toolName, conversationId: conv.id });
+                break;
+            }
+            case "tool_execution_end": {
+                const startedAt = conv.toolStartTimes.get(event.toolCallId);
+                conv.toolStartTimes.delete(event.toolCallId);
+                this.clearToolWatchdog(conv, event.toolCallId);
+                // Bash finished — wait briefly for background servers to bind their
+                // ports, then diff against the pre-run snapshot and record them.
+                if (event.toolName === "bash")
+                    void this.bg.trackAfterBash();
+                const durationMs = startedAt !== undefined ? Date.now() - startedAt : undefined;
+                // 插件扩展点：工具结束执行（带耗时与错误标志）。
+                this.onToolEvent?.({
+                    phase: "end",
+                    toolName: event.toolName,
+                    conversationId: conv.id,
+                    ...(durationMs !== undefined ? { durationMs } : {}),
+                    isError: event.isError,
+                });
+                // The bash tool does not put its exit code in result.details — on
+                // failure it throws "Command exited with code N" and the agent
+                // wraps that into the error result text. Try details first (future
+                // tools / SDK changes), then parse the error text.
+                const details = event.result?.details;
+                let exitCode;
+                if (typeof details === "object" &&
+                    details !== null &&
+                    typeof details.exitCode === "number") {
+                    exitCode = details.exitCode;
+                }
+                else if (event.isError) {
+                    const content = event.result?.content;
+                    const text = Array.isArray(content)
+                        ? content
+                            .map((c) => (typeof c === "object" &&
+                            c !== null &&
+                            c.type === "text")
+                            ? (c.text ?? "")
+                            : "")
+                            .join("\n")
+                        : "";
+                    const m = text.match(/exited with code (\d+)/);
+                    if (m)
+                        exitCode = Number(m[1]);
+                }
+                this.emit({
+                    type: "tool_status",
+                    toolCallId: event.toolCallId,
+                    toolName: event.toolName,
+                    isError: event.isError,
+                    exitCode,
+                    durationMs,
+                });
+                break;
+            }
+            case "tool_execution_update": {
+                const text = extractPartialText(event.partialResult);
+                if (text) {
+                    this.emit({
+                        type: "tool_delta",
+                        conversationId: conv.id,
+                        seq: ++conv.deltaSeq,
+                        toolCallId: event.toolCallId,
+                        toolName: event.toolName,
+                        delta: text,
+                    });
+                }
+                break;
+            }
+            case "queue_update":
+                conv.queueSteering = [...event.steering];
+                conv.queueFollowUp = [...event.followUp];
+                break;
+            // A run finished or a new entry was persisted — keep the session list fresh
+            // (new chat + first message, completed turns, compaction, etc.).
+            case "agent_end": {
+                this.scheduleSessionsRefresh();
+                // Manual interrupt (Stop button / abort): the last assistant message
+                // carries stopReason "aborted". A half-finished run should NOT be
+                // reviewed (it would fail and inject a revision, only to be stopped
+                // again → an endless review loop). Clear the goal so the review loop
+                // stops too, then let the user give a fresh instruction.
+                const aborted = event.messages.some((m) => {
+                    const a = m;
+                    return a.role === "assistant" && a.stopReason === "aborted";
+                });
+                if (aborted) {
+                    const stopNotice = this.goalSvc.onAgentEnd(conv, true);
+                    if (stopNotice) {
+                        this.emit({ type: "notice", level: "warning", text: stopNotice });
+                    }
+                    break;
+                }
+                // Goal review hook lives in GoalService.onAgentEnd(conv, false).
+                this.goalSvc.onAgentEnd(conv, false);
+                // Deferred settings reload: settings (system prompt / skills /
+                // extensions) changed while the run was streaming — applying now
+                // would have torn down the in-flight run.
+                if (this.settingsSvc.hasPendingReload() && !this.disposed) {
+                    this.settingsSvc.consumePendingReload();
+                    void this.applySettingsReload();
+                }
+                break;
+            }
+            case "entry_appended":
+                this.scheduleSessionsRefresh();
+                break;
+            case "message_update": {
+                // Live assistant-message increment, deliberately OUTSIDE the snapshot
+                // channel: send() drops snapshots under backpressure (big sessions),
+                // but this small message must always get through or the UI freezes on
+                // stale state. Only the ACTIVE conversation streams to the browser —
+                // background conversations would clobber the streaming view; their
+                // state arrives via snapshot when switched to.
+                if (conv.id !== this.conv.id)
+                    break;
+                const ame = event.assistantMessageEvent;
+                const m = event.message;
+                this.lastDeltaAt = Date.now();
+                this.emit({
+                    type: "message_delta",
+                    conversationId: conv.id,
+                    seq: ++conv.deltaSeq,
+                    // Must match serializeStreamingMessage()'s stable id so deltas
+                    // patch onto the snapshot's streamingMessage and reconcile.
+                    messageId: `stream-${m?.timestamp ?? 0}`,
+                    usage: (() => {
+                        try {
+                            const t = this.session.getSessionStats().tokens;
+                            return t ? { input: t.input, output: t.output, total: t.total } : null;
+                        }
+                        catch {
+                            return null;
+                        }
+                    })(),
+                    // Strip `partial` (the cumulative message): re-serializing it per
+                    // token is exactly what we're trying to avoid. The next snapshot
+                    // carries the authoritative full message anyway.
+                    assistantMessageEvent: {
+                        type: ame.type,
+                        contentIndex: "contentIndex" in ame ? ame.contentIndex : undefined,
+                        delta: "delta" in ame ? ame.delta : undefined,
+                    },
+                });
+                break;
+            }
+            default:
+                break;
+        }
+        // Snapshot checkpoint policy: deltas carry live rendering during streaming;
+        // full snapshots are reconciliation checkpoints taken immediately at
+        // run/tool boundaries and on a slow timer otherwise.
+        if (event.type === "agent_end" || event.type === "tool_execution_end") {
+            this.flushSnapshot();
+        }
+        else {
+            this.scheduleSnapshot();
+        }
+    }
+    /** Debounced push of the persisted session list + open conversations. */
+    scheduleSessionsRefresh() {
+        if (this.sessionsTimer)
+            return;
+        this.sessionsTimer = setTimeout(() => {
+            this.sessionsTimer = null;
+            if (this.disposed)
+                return;
+            this.emitConversations();
+            void this.pushSessions();
+        }, 800);
+        // pushSessions no-ops unless the client opted in via list_sessions.
+    }
+    /** Serialize a persisted message with a STABLE id + cached object reference. */
+    serializeCached(m) {
+        const conv = this.conv;
+        // toolResult messages are keyed by toolCallId; everything else by
+        // role+timestamp. A single prompt can emit several same-role messages
+        // within the SAME millisecond (multiple attachment asides), so the
+        // timestamp alone collides in the cache and only the first one renders
+        // — append a cheap content fingerprint to keep them distinct while
+        // staying stable across snapshots (content never changes once persisted).
+        const key = m.role === "toolResult"
+            ? `t:${m.toolCallId}`
+            : `${m.role}:${m.timestamp}:${contentFingerprint(m)}`;
+        let n = conv.msgIds.get(key);
+        if (n === undefined) {
+            n = conv.nextMsgId++;
+            conv.msgIds.set(key, n);
+        }
+        const cacheKey = `${key}#${n}`;
+        const cached = conv.uiMessageCache.get(cacheKey);
+        if (cached)
+            return cached;
+        // User-message id suffix is a 1-based count of user messages sharing
+        // this timestamp (that's what resolveUserMessageEntryId() expects). n is
+        // a global per-conversation counter across ALL roles, so it can't be
+        // reused as the seq — otherwise editing anything but the first question
+        // fails to resolve ("找不到要编辑的消息").
+        let seq = n;
+        if (m.role === "user") {
+            const ts = m.timestamp ?? 0;
+            seq = (conv.userSeqByTs.get(ts) ?? 0) + 1;
+            conv.userSeqByTs.set(ts, seq);
+        }
+        const msg = serializeMessage(m, seq);
+        if (msg) {
+            conv.uiMessageCache.set(cacheKey, msg);
+            // Bound the cache (marathon sessions otherwise grow without limit;
+            // single messages can reach TEXT_CAP = 200K chars). Map iteration is
+            // insertion order, so dropping from the front evicts the oldest —
+            // recent messages (the ones every snapshot touches) always survive.
+            // Safe: a miss just recomputes an identical object on next access.
+            let excess = conv.uiMessageCache.size - UI_MESSAGE_CACHE_CAP;
+            while (excess-- > 0) {
+                const oldest = conv.uiMessageCache.keys().next().value;
+                if (oldest === undefined)
+                    break;
+                conv.uiMessageCache.delete(oldest);
+            }
+        }
+        return msg;
+    }
+    /** Current messages array (with the existing sig-reuse optimization).
+     *  Element objects are reference-stable (serializeCached cache), which is
+     *  what lets emitSnapshotNow detect append-only growth via identity walk. */
+    currentMessages() {
+        const conv = this.conv;
+        const rawMessages = conv.session.agent.state.messages
+            .map((m) => this.serializeCached(m))
+            .filter((m) => m !== null);
+        // Reuse the previous array when nothing changed: the element objects are
+        // cached (reference-stable) anyway, and a stable array reference lets the
+        // frontend memoize derived maps instead of rebuilding them every 60ms.
+        const sig = rawMessages.map((m) => m.id).join("\u0001");
+        const messages = conv.lastMessagesSig === sig ? conv.lastMessagesArray : rawMessages;
+        conv.lastMessagesSig = sig;
+        conv.lastMessagesArray = rawMessages;
+        return messages;
+    }
+    /** Build every UiState field EXCEPT messages (the expensive part). */
+    buildLightState(rev) {
+        const conv = this.conv;
+        const state = conv.session.agent.state;
+        const model = state.model;
+        let stats = {
+            totalMessages: 0,
+            tokens: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+            cost: 0,
+            contextUsage: { tokens: null, contextWindow: 0, percent: null },
+        };
+        try {
+            const s = this.session.getSessionStats();
+            stats = {
+                totalMessages: s.totalMessages,
+                tokens: s.tokens,
+                cost: s.cost,
+                contextUsage: s.contextUsage
+                    ? {
+                        tokens: s.contextUsage.tokens,
+                        contextWindow: s.contextUsage.contextWindow,
+                        percent: s.contextUsage.percent,
+                    }
+                    : stats.contextUsage,
+            };
+        }
+        catch {
+            // stats are best-effort
+        }
+        return {
+            clientId: this.clientId,
+            cwd: this.cwd,
+            sessionId: this.session.sessionId,
+            sessionFile: this.session.sessionFile,
+            conversationId: this.activeId,
+            rev,
+            // The in-progress assistant message lives in state.streamingMessage
+            // (the SDK only pushes it into state.messages at message_end). Surfacing
+            // it here is what makes thinking + text stream into the browser at
+            // ~60ms granularity instead of appearing only when the turn finishes.
+            streamingMessage: state.streamingMessage
+                ? serializeStreamingMessage(state.streamingMessage)
+                : null,
+            isStreaming: this.session.isStreaming,
+            model: model
+                ? {
+                    id: model.id,
+                    name: model.name,
+                    provider: model.provider,
+                    vision: model.input?.includes("image") ?? false,
+                }
+                : null,
+            thinkingLevel: state.thinkingLevel,
+            // Only the levels the current model actually supports — the SDK clamps
+            // anything else, so the UI must not offer (or must disable) the rest.
+            availableThinkingLevels: this.session.getAvailableThinkingLevels(),
+            queue: { steering: conv.queueSteering, followUp: conv.queueFollowUp },
+            errorMessage: state.errorMessage,
+            tools: state.tools.map((t) => t.name),
+            version: ++this.version,
+            piConfigured: this.isPiConfigured(),
+            piAgentInstalled: this.isPiCliInstalled(),
+            stats,
+        };
+    }
+    /** Emit one snapshot update — incremental when possible, full otherwise.
+     *
+     *  Persisted messages are content-immutable with reference-stable objects
+     *  (serializeCached), so an IDENTITY WALK over the previous array detects
+     *  append-only growth in O(n) pointer compares. Appends travel as
+     *  snapshot_delta carrying only the new tail + light fields; any mid-array
+     *  change/truncation (switch session, edit fork, compaction) or a forced
+     *  resync falls back to a full snapshot. The 10MB-stringify-per-checkpoint
+     *  cost of big sessions collapses to a few hundred bytes for the common
+     *  "nothing but stats/version changed" checkpoint. */
+    emitSnapshotNow(forceFull = false) {
+        if (this.disposed)
+            return;
+        const cur = this.currentMessages();
+        const prev = this.emittedMessages;
+        let incremental = !forceFull &&
+            prev !== null &&
+            this.emittedConvId === this.activeId &&
+            prev.length <= cur.length;
+        if (incremental && prev) {
+            for (let i = 0; i < prev.length; i++) {
+                if (prev[i] !== cur[i]) {
+                    incremental = false;
+                    break;
+                }
+            }
+        }
+        const rev = ++this.snapRev;
+        if (incremental && prev) {
+            const baseRev = this.emittedRev;
+            this.emittedMessages = cur;
+            this.emittedConvId = this.activeId;
+            this.emittedRev = rev;
+            this.emit({
+                type: "snapshot_delta",
+                conversationId: this.activeId,
+                rev,
+                baseRev,
+                appended: cur.slice(prev.length),
+                state: this.buildLightState(rev),
+            });
+        }
+        else {
+            this.emittedMessages = cur;
+            this.emittedConvId = this.activeId;
+            this.emittedRev = rev;
+            this.emit({
+                type: "snapshot",
+                state: { ...this.buildLightState(rev), messages: cur },
+            });
+        }
+    }
+    /** Resolve a browser-bridged dialog (select/confirm/input) for this session. */
+    resolveDialog(id, value) {
+        this.webUi.resolveDialog(id, value);
+    }
+    /**
+     * Whether the pi agent config looks ready: the agent dir exists and
+     * auth.json has at least one provider credential. Cached for 2s.
+     */
+    isPiConfigured() {
+        const now = Date.now();
+        const cached = this.piCheckCache;
+        if (cached && now - cached.at < 2000)
+            return cached.configured;
+        let configured = false;
+        try {
+            const authPath = join(this.agentDir, "auth.json");
+            if (existsSync(authPath)) {
+                const data = JSON.parse(readFileSync(authPath, "utf8"));
+                configured =
+                    typeof data === "object" &&
+                        data !== null &&
+                        Object.keys(data).length > 0;
+            }
+        }
+        catch {
+            configured = false;
+        }
+        this.piCheckCache = { at: now, configured };
+        return configured;
+    }
+    /**
+     * Whether the pi CLI binary is installed and runnable (`pi --version`
+     * probe). Cached machine-wide (same binary for every client) for 10s —
+     * the check is only rerun after install or when the cache expires.
+     */
+    static piCliProbe = null;
+    static PI_CLI_PROBE_TTL_MS = 10_000;
+    isPiCliInstalled() {
+        const now = Date.now();
+        const cached = ClientSession.piCliProbe;
+        if (cached && now - cached.at < ClientSession.PI_CLI_PROBE_TTL_MS)
+            return cached.installed;
+        let installed = false;
+        try {
+            const res = spawnSync("pi", ["--version"], {
+                timeout: 5000,
+                stdio: "ignore",
+                // Windows: `pi` resolves to a pi.cmd shim — spawnSync can only
+                // exec those through a shell (else ENOENT).
+                shell: process.platform === "win32",
+            });
+            installed = !res.error && res.status === 0;
+        }
+        catch {
+            installed = false;
+        }
+        ClientSession.piCliProbe = { at: now, installed };
+        return installed;
+    }
+    static invalidatePiCliProbe() {
+        ClientSession.piCliProbe = null;
+    }
+    /**
+     * Run a command async, collecting stdout+stderr; kills on timeout.
+     * Never throws / never crashes the server: spawn errors (ENOENT etc.)
+     * resolve with code -1 so callers can report them as notices.
+     */
+    runAsync(cmd, args, timeoutMs, cwd) {
+        return new Promise((resolve) => {
+            let p;
+            try {
+                p = spawn(cmd, args, {
+                    ...(cwd ? { cwd } : {}),
+                    stdio: ["ignore", "pipe", "pipe"],
+                    // Windows: npm and friends are .cmd shims — Node can only exec
+                    // them through the shell (otherwise spawn npm → ENOENT).
+                    shell: process.platform === "win32",
+                });
+            }
+            catch (err) {
+                resolve({ code: -1, out: String(err) });
+                return;
+            }
+            let out = "";
+            let settled = false;
+            const done = (code, text) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(t);
+                resolve({ code, out: text ?? out });
+            };
+            const t = setTimeout(() => p.kill(), timeoutMs);
+            p.stdout?.on("data", (d) => (out += d.toString()));
+            p.stderr?.on("data", (d) => (out += d.toString()));
+            p.on("error", (err) => done(-1, String(err)));
+            p.on("close", (code) => done(code));
+        });
+    }
+    /**
+     * Auto-install the pi agent: ensure the config dir exists and install the
+     * pi CLI globally (npm i -g). Auth is configured afterwards via the API key
+     * form or by running `pi` in a terminal.
+     */
+    /**
+     * Version of the RUNNING pi-web-ui package (read from its own package.json,
+     * resolved from this compiled module: <pkg>/dist/server → <pkg>).
+     */
+    static currentAppVersion() {
+        try {
+            const here = dirname(fileURLToPath(import.meta.url));
+            const pkgRoot = resolve(here, "..", "..");
+            const pkg = JSON.parse(readFileSync(join(pkgRoot, "package.json"), "utf8"));
+            return pkg.version ?? "0.0.0";
+        }
+        catch {
+            return "0.0.0";
+        }
+    }
+    /** Simple numeric semver compare: >0 means a newer than b. */
+    static compareVersions(a, b) {
+        const pa = a.split(".").map((n) => parseInt(n, 10) || 0);
+        const pb = b.split(".").map((n) => parseInt(n, 10) || 0);
+        for (let i = 0; i < 3; i++) {
+            const x = pa[i] ?? 0;
+            const y = pb[i] ?? 0;
+            if (x !== y)
+                return x - y;
+        }
+        return 0;
+    }
+    /** Set by index.ts: called when /pi-web-ui:quit is invoked. */
+    onQuit = undefined;
+    /** 本客户端成功切换工作区（set_cwd）后触发，参数为新绝对路径。
+     *  attach 时由 AgentService 接到全局 onClientCwdChanged —— 编辑器等
+     *  工作区跟随型插件借此把根目录切到用户当前项目。 */
+    onCwdChanged = undefined;
+    /** Ask the npm registry for the latest pi-web-ui version and report it. */
+    async checkUpdate() {
+        const current = ClientSession.currentAppVersion();
+        try {
+            // Fetch the full package doc (not /latest): it carries the per-version
+            // publish timestamps so the UI can hint when a version was JUST
+            // published and the registry/CDN caches may not have caught up yet.
+            const res = await fetch("https://registry.npmjs.org/pi-web-ui", {
+                signal: AbortSignal.timeout(8_000),
+            });
+            if (!res.ok)
+                throw new Error(`HTTP ${res.status}`);
+            const data = (await res.json());
+            const latest = data["dist-tags"]?.latest ?? null;
+            const latestPublishedAt = latest && data.time ? (data.time[latest] ?? null) : null;
+            const upToDate = latest === null || ClientSession.compareVersions(current, latest) >= 0;
+            this.emit({
+                type: "update_status",
+                current,
+                latest,
+                latestPublishedAt,
+                upToDate,
+            });
+        }
+        catch (err) {
+            this.emit({
+                type: "update_status",
+                current,
+                latest: null,
+                latestPublishedAt: null,
+                upToDate: false,
+                error: `检查更新失败：${err.message}`,
+            });
+        }
+    }
+    async installPiAgent() {
+        try {
+            mkdirSync(this.agentDir, { recursive: true });
+            this.emit({
+                type: "notice",
+                level: "info",
+                text: "正在安装 pi agent CLI（npm i -g @earendil-works/pi-coding-agent）…",
+            });
+            const { code, out } = await this.runAsync("npm", ["i", "-g", "@earendil-works/pi-coding-agent"], 180_000);
+            if (code === 0) {
+                this.emit({
+                    type: "notice",
+                    level: "info",
+                    text: "✅ pi agent CLI 安装完成。填入 API 密钥即可开始，或在终端运行 pi 完成登录。",
+                });
+                this.emit({ type: "install_result", ok: true, detail: "" });
+            }
+            else {
+                this.emit({
+                    type: "notice",
+                    level: "error",
+                    text: `pi agent 安装失败（${code ?? "timeout"}）：${out.slice(0, 400)}`,
+                });
+                this.emit({
+                    type: "install_result",
+                    ok: false,
+                    detail: out.slice(0, 600),
+                });
+            }
+        }
+        catch (err) {
+            this.emit({
+                type: "notice",
+                level: "error",
+                text: `pi agent 安装失败：${err.message}`,
+            });
+        }
+        // The CLI may just have landed on PATH (or the install may have failed) —
+        // drop the probe cache so the next snapshot re-checks.
+        ClientSession.invalidatePiCliProbe();
+        this.flushSnapshot();
+    }
+    /** Send a snapshot immediately (cancels any pending throttled one).
+     *  forceFull skips the incremental path — used by get_state so a (re)
+     *  connecting or desynced client always receives an authoritative full
+     *  state it can rebuild from. */
+    flushSnapshot(forceFull = false) {
+        if (this.snapshotTimer) {
+            clearTimeout(this.snapshotTimer);
+            this.snapshotTimer = null;
+        }
+        this.emitSnapshotNow(forceFull);
+    }
+    scheduleSnapshot() {
+        if (this.snapshotTimer || this.disposed)
+            return;
+        // During active streaming the deltas carry live rendering — full snapshots
+        // are just a periodic reconciliation checkpoint, so send them far less
+        // often (they serialize the whole session; big sessions made this path OOM).
+        const interval = Date.now() - this.lastDeltaAt < DELTA_ACTIVE_WINDOW_MS
+            ? STREAMING_SNAPSHOT_INTERVAL_MS
+            : SNAPSHOT_INTERVAL_MS;
+        this.snapshotTimer = setTimeout(() => {
+            this.snapshotTimer = null;
+            this.emitSnapshotNow();
+        }, interval);
+    }
+    /** Slash-command catalog + native command execution — 自包含模块，见
+     *  slash-commands.ts（内置命令拦截 + 扩展/模板/技能目录推送）。 */
+    slash = new SlashCommandsService({
+        emit: (msg) => this.emit(msg),
+        cwd: () => this.cwd,
+        getSession: () => this.session,
+        newChat: () => this.newChat(),
+        setModel: (id) => this.setModel(id),
+        setCwd: (path) => this.setCwd(path),
+        setThinking: (level) => this.setThinking(level),
+        refreshSessions: () => this.refreshSessions(),
+        afterReload: () => this.applyTerminalToolGating(this.session),
+        pluginCommands: () => this.pluginCommandsProvider?.() ?? [],
+        execPluginCommand: async (name, args) => {
+            const def = this.pluginCommandsProvider?.().find((c) => c.name === name);
+            if (!def)
+                return false;
+            try {
+                const result = await def.run(args, { clientId: this.clientId });
+                // 字符串返回值 → 通知条回显给发起人；富展示用 broadcast/sendTo。
+                if (typeof result === "string" && result.trim()) {
+                    this.emit({ type: "notice", level: "info", text: result });
+                }
+            }
+            catch (err) {
+                this.emit({
+                    type: "notice",
+                    level: "error",
+                    text: `插件命令 /${name} 执行失败：${err.message}`,
+                });
+            }
+            return true;
+        },
+        onQuit: () => this.onQuit?.() ?? false,
+    });
+    /** Catalog push — index.ts get_commands / attach / cwd 切换等都会调用。 */
+    pushSlashCommands() {
+        return this.slash.push();
+    }
+    /** 模型/服务商配置管理 —— 自包含模块，见 model-admin.ts。 */
+    modelAdmin;
+    /** Persist an api-key credential for a provider (auth.json). */
+    setProviderApiKey(provider, apiKey) {
+        return this.modelAdmin.setProviderApiKey(provider, apiKey);
+    }
+    clearProviderApiKey(provider) {
+        return this.modelAdmin.clearProviderApiKey(provider);
+    }
+    listProviders() {
+        return this.modelAdmin.listProviders();
+    }
+    listModelsConfig() {
+        return this.modelAdmin.listModelsConfig();
+    }
+    fetchModelsList(reqId, baseUrl, apiKey, authHeader, api) {
+        return this.modelAdmin.fetchModelsList(reqId, baseUrl, apiKey, authHeader, api);
+    }
+    refreshProviderModels(providerId, reqId) {
+        return this.modelAdmin.refreshProviderModels(providerId, reqId);
+    }
+    /** Copy a built-in provider into an editable custom-provider draft
+     *  (clone_provider_result) — lets the user run a second API key without
+     *  overwriting the built-in one. */
+    cloneProvider(providerId, reqId) {
+        return this.modelAdmin.cloneProvider(providerId, reqId);
+    }
+    saveModelConfig(providerId, config) {
+        return this.modelAdmin.saveModelConfig(providerId, config);
+    }
+    deleteModelConfig(providerId) {
+        return this.modelAdmin.deleteModelConfig(providerId);
+    }
+    // ---------------------------------------------------------------------------
+    // Settings (system prompt / skills / extensions / presets)
+    // ---------------------------------------------------------------------------
+    /** Push the full settings state (current settings + loaded skills/extensions
+     *  with enabled flags + saved presets). Pushed on attach and after every
+     *  settings change. */
+    pushSettings() {
+        this.settingsSvc.push();
+    }
+    /** Extensions/skills changed externally (e.g. `pi remove` finished in the
+     *  terminal): re-run session.reload() and re-push state. Streaming-safe —
+     *  deferred to agent_end, same as settings reloads. */
+    async reloadExtensions() {
+        return this.settingsSvc.applyRuntime();
+    }
+    /** Persist + apply a partial settings update (prompt text/mode, toggles). */
+    async setSettings(partial) {
+        await this.settingsSvc.set(partial);
+    }
+    /** Save the CURRENT settings as a named preset (overwrites if exists). */
+    async savePreset(name) {
+        return this.settingsSvc.savePreset(name);
+    }
+    /** Replace the current settings with the named preset and apply it. */
+    async applyPreset(name) {
+        return this.settingsSvc.applyPreset(name);
+    }
+    /** Remove a named preset. */
+    async deletePreset(name) {
+        return this.settingsSvc.deletePreset(name);
+    }
+    /** Make settings effective in the running runtime（流式中则延迟到 agent_end）。 */
+    async applyRuntimeSettings() {
+        return this.settingsSvc.applyRuntime();
+    }
+    /** 把终端工具开关应用到 session 的活跃工具集：关闭时从活跃集中剔除
+     *  terminal_*（工具仍留在注册表，重开时可直接加回）。session.reload() 与新
+     *  会话创建都会把 custom 工具加回活跃集，所以这两条路径之后都要重放本方法。 */
+    applyTerminalToolGating(session) {
+        try {
+            const enabled = this.settingsSvc.current.terminalToolsEnabled !== false;
+            const names = new Set(session.getActiveToolNames());
+            for (const n of TERMINAL_TOOL_NAMES) {
+                if (enabled)
+                    names.add(n);
+                else
+                    names.delete(n);
+            }
+            session.setActiveToolsByName([...names]);
+        }
+        catch {
+            // Session 未就绪——下次创建/reload 会再应用。
+        }
+    }
+    /** 把插件 AI 工具同步进一个已存在的会话（新增/更新/移除）。
+     *  实际 diff 逻辑在 plugins.ts 的 syncPluginToolsIntoSession（可单测）。 */
+    syncPluginTools(session) {
+        try {
+            const defs = (this.pluginToolsProvider?.() ?? []).map(pluginToolToDefinition);
+            const next = syncPluginToolsIntoSession(session, defs, this.appliedPluginToolNames);
+            if (next)
+                this.appliedPluginToolNames = new Set(next);
+        }
+        catch (err) {
+            console.error("[plugins] sync tools to session failed:", err);
+        }
+    }
+    /** index.ts 经 pluginMgr.onAgentToolsChanged 触发：把插件 AI 工具推入全部会话。 */
+    refreshPluginTools() {
+        for (const conv of this.convs.values())
+            this.syncPluginTools(conv.session);
+    }
+    async applySettingsReload() {
+        // 兼容旧入口：reload + 刷目录在宿主回调里完成
+        return this.settingsSvc.applyRuntime();
+    }
+    // ---------------------------------------------------------------------------
+    // Commands
+    // ---------------------------------------------------------------------------
+    /** True when the service is draining (quiesced): emits a rejection notice
+     *  and returns true. Guards every NEW-work entry point (prompt / new chat /
+     *  edit-resend / session resume / goal wizard) — existing runs keep going.
+     *  Called BEFORE any LLM/token work starts so quiesce is a hard admission
+     *  gate, not a best-effort hint. */
+    quiesceBlocked() {
+        if (!this.isQuiesced())
+            return false;
+        this.emit({
+            type: "notice",
+            level: "error",
+            text: "服务器正在排空存量工作（quiesce），已拒绝新的对话/消息/编辑。存量运行会继续跑完；用 pi-web-ui server unquiesce 可恢复。",
+        });
+        this.flushSnapshot();
+        return true;
+    }
+    /** Conversations with an in-flight run — active work for quiesce status. */
+    activeConversations() {
+        let n = 0;
+        for (const c of this.convs.values()) {
+            try {
+                if (c.session.isStreaming)
+                    n += 1;
+            }
+            catch {
+                // session being replaced — not running
+            }
+        }
+        return n;
+    }
+    /** Messages queued in the SDK (steer + follow-up) — pending work for
+     *  quiesce status. Quiesce refuses to add more, so this only drains. */
+    pendingMessages() {
+        let n = 0;
+        for (const c of this.convs.values())
+            n += c.queueFollowUp.length + c.queueSteering.length;
+        return n;
+    }
+    async prompt(text, attachments, 
+    /**
+     * true = followUp: while streaming, queue the prompt and deliver it only
+     * after the WHOLE run finishes (补充 button — "AI 生成结束才发送").
+     * false/undefined = steer: the pi CLI Enter semantic — injected right
+     * after the current turn settles, skipping remaining planned tool calls.
+     */
+    queue = false) {
+        try {
+            const s = this.session;
+            // Native slash commands (see NATIVE_COMMANDS) are executed here and
+            // never reach the SDK. Extension / skill / template commands fall
+            // through — AgentSession.prompt() handles those itself.
+            const slash = parseSlash(text);
+            if (slash && (await this.slash.exec(slash.name, slash.args))) {
+                this.flushSnapshot();
+                return;
+            }
+            // Native commands above are pure config tweaks (no tokens) — allow them
+            // even while quiesced. Everything that reaches the SDK is NEW work and
+            // is refused until admission reopens.
+            if (this.quiesceBlocked())
+                return;
+            // Attach files as independent nextTurn context messages (asides) so the
+            // user message stays clean; they render as separate attachment cards.
+            const asides = await buildAttachmentMessages({
+                cwd: this.cwd,
+                clientId: this.clientId,
+                emit: (msg) => this.emit(msg),
+                settings: this.settingsSvc.current,
+                session: this.session,
+            }, attachments);
+            for (const aside of asides) {
+                await s.sendCustomMessage(aside.message, { deliverAs: "nextTurn" });
+            }
+            if (s.isStreaming) {
+                // queue=true (补充 button) → followUp: the message is delivered only
+                // after the whole run finishes — the agent finishes what it started,
+                // then responds to the queued message. queue=false/undefined
+                // (plain Enter) → steer: interrupts the current run — the message
+                // is delivered right after the current assistant turn settles
+                // (remaining planned tool calls are skipped) and the agent
+                // immediately responds to it. This is the pi CLI
+                // Enter-during-streaming semantic (docs/usage: Enter queues a
+                // steering message); followUp would wait for the whole run
+                // to finish, which users perceive as ordinary queueing.
+                await s.prompt(text, {
+                    streamingBehavior: queue ? "followUp" : "steer",
+                });
+            }
+            else {
+                await s.prompt(text);
+            }
+        }
+        catch (err) {
+            this.emit({
+                type: "notice",
+                level: "error",
+                text: `提示发送失败：${err.message}`,
+            });
+        }
+        // Name the conversation after its first user prompt.
+        const conv = this.conv;
+        if (conv.title === DEFAULT_CONV_TITLE && text.trim()) {
+            const trimmed = text.trim().replace(/\s+/g, " ");
+            conv.title = trimmed.length > 30 ? `${trimmed.slice(0, 30)}…` : trimmed;
+            this.emitConversations();
+        }
+        // The active conversation has been continued since it was opened — it
+        // must not be dismissed when the user switches away. (Also bumps the
+        // per-project "most recently active" order used by set_cwd.)
+        conv.promptedSinceActive = true;
+        conv.lastActiveAt = Date.now();
+        // Fresh run — restart the stall watchdog window.
+        conv.lastSdkEventAt = Date.now();
+        conv.stallNoticed = false;
+        this.flushSnapshot();
+    }
+    /**
+     * Turn attached files into custom-message payloads.
+     *
+     * Text files are size-aware: small files are inlined into the message so the
+     * model sees them immediately; large files are passed as a <file path="...">
+     * reference and the model reads them on demand with its read tool (which has
+     * built-in truncation). Images are always passed as image content. Mode
+     * "lines" inlines only a 1-based inclusive line range of the file. Raw
+     * pasted/dropped/uploaded images (attachment.imageData) skip the workspace
+     * path entirely and go straight to the model as image content. Raw uploaded
+     * files (attachment.fileData) are persisted under <dataDir>/uploads/ and
+     * attached as absolute-path references (small text ones are inlined).
+     */
+    /**
+     * Hard-abort the running agent (Stop button / global 中断). Tries
+     * session.abort() first; if the run is not idle within
+     * HARD_ABORT_TIMEOUT_MS (model stream ignoring the abort signal), the
+     * conversation's runtime is force-disposed and recreated from the last
+     * persisted session so the chat ALWAYS comes back usable — never stuck
+     * overnight. The notice fires only on the forced-reset path.
+     */
+    async abort() {
+        // 只停止智能体运行本身；AI 在后台启动的服务由「后台任务」面板单独
+        // 管理（可逐个停止或全部关闭），不会在停止对话时被连带杀掉。
+        await this.interruptRun(this.conv, "已停止");
+        this.flushSnapshot();
+    }
+    /** Re-push the current list on request (panel opened); prunes dead entries first. */
+    async listBgServers() {
+        await this.bg.listAndPush();
+    }
+    /** 插件任务集合变化时由宿主调用：重推一次 bg_servers（含插件任务）。 */
+    refreshBgTasks() {
+        this.bg.push();
+    }
+    /** 插件设置保存结果等需要从 index.ts 发 notice 时用（emit 是私有的）。 */
+    emitNotice(level, text) {
+        this.emit({ type: "notice", level, text });
+    }
+    /** Kill ONE background server (by port); returns whether anything was killed. */
+    /** Kill ONE background server (by port) OR a plugin task (by taskId). */
+    async killBackgroundServer(port, taskId) {
+        if (taskId) {
+            // 插件任务：交给插件管理器 stop 回调（不杀进程树——任务在宿主进程内）。
+            const ok = this.pluginStopBgTask?.(taskId) ?? false;
+            if (!ok) {
+                this.emit({
+                    type: "notice",
+                    level: "info",
+                    text: `后台任务「${taskId}」不存在或已结束`,
+                });
+            }
+            this.bg.push();
+            this.flushSnapshot();
+            return ok;
+        }
+        if (typeof port !== "number")
+            return false;
+        return this.bg.killOne(port);
+    }
+    /** Kill every background server the agent started; returns the freed ports. */
+    async killAllBackgroundServers() {
+        return this.bg.killAll();
+    }
+    /** Kill only the running bash command(s) — the agent run itself continues
+     *  (the bash tool returns an aborted error and the model moves on). Uses
+     *  the per-client AbortController set registered by
+     *  makeKillableBashTool. */
+    async abortBash() {
+        if (this.bashKills.size === 0) {
+            this.emit({
+                type: "notice",
+                level: "info",
+                text: "当前没有正在运行的 bash 命令",
+            });
+            this.flushSnapshot();
+            return;
+        }
+        for (const ac of [...this.bashKills])
+            ac.abort();
+        this.emit({
+            type: "notice",
+            level: "info",
+            text: "已停止 bash 命令（对话继续）",
+        });
+        // 让 AI 明确知道是用户手动停止：sendUserMessage 触发下一轮，agent
+        // 会看到「命令被用户中止」而不是普通失败，并据此继续（不会困惑于
+        // 为什么命令失败了）。
+        try {
+            await this.conv.runtime.session.sendUserMessage("（系统：用户手动停止了刚才的 bash 命令——命令被中止，终止前已输出的内容在对应工具结果里。请据此继续，不要重跑被中止的命令，除非确实必要。）");
+        }
+        catch {
+            // best effort — 消息注入失败不影响命令已停止的事实
+        }
+        this.flushSnapshot();
+    }
+    /** Interrupt a run: abort, with a force-reset fallback on timeout. */
+    async interruptRun(conv, reason) {
+        // The run is only truly stopped when its agent_end event arrives:
+        // session.abort() can return without stopping anything when the run is
+        // stuck before the agent even started (e.g. a model stream that never
+        // begins), so we watch for agent_end and force-reset when it never
+        // comes — abort 卡住（超时）或空转（结算窗口）两条路都覆盖。
+        let ended = false;
+        let forced = false;
+        const off = conv.session.subscribe((e) => {
+            if (e.type === "agent_end") {
+                ended = true;
+            }
+        });
+        const force = () => {
+            if (forced)
+                return;
+            forced = true;
+            void this.forceResetConversation(conv, `${reason}：运行未终止，已强制重置当前对话`);
+        };
+        // 1) abort itself hangs (model stream ignores the signal) → hard kill.
+        const abortTimer = setTimeout(() => {
+            if (!ended)
+                force();
+        }, ClientSession.HARD_ABORT_TIMEOUT_MS);
+        abortTimer.unref?.();
+        // 2) abort itself (Stop semantics: kills the process tree, emits
+        //    agent_end with stopReason "aborted" on the normal path).
+        try {
+            await conv.runtime.session.abort();
+        }
+        catch (err) {
+            this.emit({
+                type: "notice",
+                level: "error",
+                text: `中止失败：${err.message}`,
+            });
+        }
+        // 3) abort returned but no agent_end within the settle window → the
+        //    run was stuck before it started; force-reset to recover.
+        if (!ended) {
+            await new Promise((r) => setTimeout(r, ClientSession.HARD_ABORT_SETTLE_MS));
+        }
+        clearTimeout(abortTimer);
+        off();
+        if (!ended)
+            force();
+    }
+    /** Force-reset a conversation: dispose the stuck runtime (kills the hung
+     *  model stream / child processes) and rebuild it from the most recent
+     *  persisted session. The conversation record itself is kept (same id,
+     *  same cwd, same serialization caches), so the UI stays attached. */
+    async forceResetConversation(conv, reason) {
+        try {
+            conv.unsubscribe?.();
+            conv.unsubscribe = undefined;
+            this.clearAllToolWatchdogs(conv);
+            conv.toolStartTimes.clear();
+            await conv.runtime.dispose();
+            const runtime = await createAgentSessionRuntime(this.makeRuntimeFactory(conv.terminals), {
+                cwd: conv.cwd,
+                agentDir: this.agentDir,
+                sessionManager: SessionManager.continueRecent(conv.cwd),
+            });
+            conv.runtime = runtime;
+            conv.session = runtime.session;
+            this.emit({ type: "notice", level: "warning", text: reason });
+            await this.bindSession();
+            this.emitConversations();
+            void this.pushSlashCommands();
+        }
+        catch (err) {
+            this.emit({
+                type: "notice",
+                level: "error",
+                text: `强制中断失败：${err.message}`,
+            });
+        }
+    }
+    async newChat() {
+        if (this.quiesceBlocked())
+            return;
+        // Reuse an already-open blank conversation instead of piling up new ones
+        // on every click: if the active chat has no messages it IS the new chat
+        // (focus already on it); otherwise switch to the first blank one (under
+        // the per-project running-list model displaced blanks are disposed, so
+        // this branch normally can't exist — kept as a safety net).
+        const isBlank = (c) => {
+            try {
+                return c.session.getSessionStats().totalMessages === 0 && c.terminals.list().length === 0;
+            }
+            catch {
+                // session being replaced — treat as used so we don't switch onto it
+                return false;
+            }
+        };
+        const active = this.conv;
+        if (active && isBlank(active)) {
+            this.flushSnapshot();
+            return;
+        }
+        for (const conv of this.convs.values()) {
+            if (conv.id === this.activeId)
+                continue;
+            if (isBlank(conv)) {
+                await this.switchConversation(conv.id);
+                this.flushSnapshot();
+                return;
+            }
+        }
+        // Cap is per project — conversations of other projects keep their own
+        // lists and don't consume this project's slots.
+        const openInProject = [...this.convs.values()].filter((c) => c.cwd === this.cwd).length;
+        if (openInProject >= MAX_OPEN_CONVERSATIONS) {
+            this.emit({
+                type: "notice",
+                level: "warning",
+                text: `当前项目运行的对话已达上限（${MAX_OPEN_CONVERSATIONS} 个），请先打开某个对话并离开（不继续对话）以移出列表`,
+            });
+            return;
+        }
+        // The outgoing conversation is left behind — apply the running-list
+        // lifecycle. Removal is deferred until the new chat exists so the active
+        // conversation stays valid during the (async) runtime creation.
+        const displaced = this.displaceActive();
+        // Carry the model chosen in the active chat over to the new chat so it
+        // doesn't silently revert to the ModelRuntime default model.
+        const prevModel = this.conv.session.agent.state.model ?? null;
+        try {
+            const conversationId = this.nextConversationId();
+            const terminals = this.makeTerminalManager(conversationId, this.cwd);
+            const runtime = await createAgentSessionRuntime(this.makeRuntimeFactory(terminals), {
+                cwd: this.cwd,
+                agentDir: this.agentDir,
+                sessionManager: SessionManager.create(this.cwd),
+            });
+            const conv = this.makeConversation(runtime, conversationId, terminals);
+            this.convs.set(conv.id, conv);
+            this.activeId = conv.id;
+            if (displaced)
+                this.removeConversation(displaced.id);
+            await this.bindSession();
+            // New session seeds with the ModelRuntime default model — restore the
+            // model the user had selected in the previous chat.
+            if (prevModel && this.sharedModelRuntime) {
+                try {
+                    await this.session.setModel(prevModel);
+                }
+                catch {
+                    // model no longer resolvable — keep the default
+                }
+            }
+            this.emitConversations();
+            this.goalSvc.emitGoalStatus();
+            this.pushTerminals();
+            // The new runtime re-discovered skills/templates — refresh the catalog
+            // so the picker stops showing the previous runtime's list.
+            void this.pushSlashCommands();
+        }
+        catch (err) {
+            this.emit({
+                type: "notice",
+                level: "error",
+                text: `新建对话失败：${err.message}`,
+            });
+        }
+        this.flushSnapshot();
+    }
+    /**
+     * The active conversation is being left (new_chat / switch_conversation /
+     * set_cwd). Runs the running-list lifecycle:
+     *
+     * - still streaming → it becomes a background run: ensure it is listed;
+     * - idle + listed + continued → keep it (the user did continue it);
+     * - any retained terminal state → keep it listed until the terminals are closed;
+     * - idle + listed + opened-but-not-continued, or never listed at all → the
+     *   caller must drop it (returns it so removal happens only after the
+     *   active conversation has been switched away).
+     */
+    displaceActive() {
+        const conv = this.conv;
+        // An isolated reviewer can keep working while the main session is idle;
+        // retain that conversation so its review is not disposed when the user
+        // switches away without sending another prompt.
+        if (conv.goal.reviewing || conv.wizardRunning) {
+            conv.listed = true;
+            return null;
+        }
+        if (conv.session.isStreaming) {
+            conv.listed = true;
+            return null;
+        }
+        // Terminal state is a reason to keep an otherwise idle conversation alive:
+        // switching chats must not kill a PTY the user or agent may still need.
+        if (conv.terminals.list().length > 0) {
+            conv.listed = true;
+            return null;
+        }
+        if (conv.listed && conv.promptedSinceActive)
+            return null;
+        return conv;
+    }
+    /** Remove a conversation from the running list and free its runtime. The
+     *  session stays persisted on disk, so it remains recoverable from the
+     *  history list. Never removes the active conversation. */
+    removeConversation(id) {
+        const conv = this.convs.get(id);
+        if (!conv || id === this.activeId)
+            return;
+        this.convs.delete(id);
+        this.clearAllToolWatchdogs(conv);
+        conv.terminals.killAll();
+        conv.unsubscribe?.();
+        conv.unsubscribe = undefined;
+        void conv.runtime.dispose().catch(() => { });
+    }
+    /** Switch the ACTIVE conversation without interrupting any other chat. */
+    async switchConversation(id) {
+        if (!this.convs.has(id) || id === this.activeId)
+            return;
+        const displaced = this.displaceActive();
+        this.activeId = id;
+        this.cwd = this.conv.cwd;
+        // All listed conversations share the current project's cwd, so this is
+        // normally a no-op — kept defensive for stale clients.
+        if (displaced)
+            this.removeConversation(displaced.id);
+        this.conv.promptedSinceActive = false;
+        this.conv.lastActiveAt = Date.now();
+        this.webUi.refresh();
+        this.emitConversations();
+        this.goalSvc.emitGoalStatus();
+        this.pushTerminals();
+        // The switched-to conversation has its own runtime (own resource cache).
+        void this.pushSlashCommands();
+        this.flushSnapshot();
+    }
+    /** Push the current project's running-conversation list to the client. */
+    emitConversations() {
+        const conversations = [];
+        for (const conv of this.convs.values()) {
+            // The running-conversation list is per project and only contains
+            // conversations that were displaced to the background while running.
+            if (conv.cwd !== this.cwd || !conv.listed)
+                continue;
+            let messageCount = 0;
+            let isStreaming = false;
+            try {
+                messageCount = conv.session.getSessionStats().totalMessages;
+                isStreaming = conv.session.isStreaming;
+            }
+            catch {
+                // session being replaced — report defaults
+            }
+            conversations.push({
+                id: conv.id,
+                title: conv.title,
+                cwd: conv.cwd,
+                messageCount,
+                isStreaming,
+            });
+        }
+        this.emit({
+            type: "conversations",
+            conversations,
+            activeId: this.activeId,
+        });
+    }
+    /** List persisted sessions for this client, newest first. */
+    /** The client asked for the session list at least once (lazy loading) —
+     *  background refreshes only re-push when this is true, so a mobile
+     *  client that never opened the panel never pays the disk scan. */
+    sessionsRequested = false;
+    /** Push the persisted session list to the client (client-requested). */
+    async refreshSessions() {
+        this.sessionsRequested = true;
+        await this.pushSessions();
+    }
+    async pushSessions() {
+        if (!this.sessionsRequested)
+            return;
+        if (!this.sessionsRequested)
+            return;
+        try {
+            // Sessions live in the SDK default per-project dir
+            // (<agentDir>/sessions/--<cwd>--/), the same files the pi CLI/TUI
+            // use — one listing covers every conversation of the current folder.
+            const infos = await SessionManager.list(this.cwd);
+            const sessions = new Map();
+            for (const s of infos) {
+                sessions.set(s.path, {
+                    path: s.path,
+                    name: s.name,
+                    firstMessage: s.firstMessage,
+                    messageCount: s.messageCount,
+                    modified: s.modified.getTime(),
+                    source: "web",
+                });
+            }
+            const sorted = [...sessions.values()]
+                .sort((a, b) => b.modified - a.modified)
+                .slice(0, 200); // newest first — the panel shows recent history
+            this.emit({ type: "sessions", sessions: sorted });
+        }
+        catch {
+            this.emit({ type: "sessions", sessions: [] });
+        }
+    }
+    /** Remove an entry from the client's recent-project list (UI state only). */
+    async removeProject(path) {
+        this.stateStore.removeProject(this.clientId, path);
+        await this.pushProjects();
+    }
+    /** Permanently delete a persisted session transcript file (history list ✕). */
+    async deleteSession(path) {
+        try {
+            const abs = resolve(path);
+            // Guardrail: only transcripts under the shared sessions root
+            // (<agentDir>/sessions/) may be deleted — never arbitrary files.
+            const sessionsRoot = resolve(this.agentDir, "sessions");
+            if (!abs.startsWith(sessionsRoot + sep)) {
+                this.emit({
+                    type: "notice",
+                    level: "error",
+                    text: "只能删除会话目录中的对话记录",
+                });
+                return;
+            }
+            // Refuse to pull the file out from under a live conversation.
+            for (const conv of this.convs.values()) {
+                if (conv.session.sessionFile === abs) {
+                    this.emit({
+                        type: "notice",
+                        level: "warning",
+                        text: "该对话正在使用中，请先切换到其他对话再删除",
+                    });
+                    return;
+                }
+            }
+            rmSync(abs, { force: true });
+            await this.refreshSessions();
+        }
+        catch (err) {
+            this.emit({
+                type: "notice",
+                level: "error",
+                text: `删除会话失败：${err.message}`,
+            });
+        }
+    }
+    /** Open a persisted session as the active conversation (from listSessions).
+     *
+     * A persisted-session click must follow the same ownership rule as
+     * new_chat/switch_conversation: every open conversation keeps its own
+     * runtime. AgentSessionRuntime.switchSession() tears down (and aborts) the
+     * current runtime, which would otherwise stop a response merely because the
+     * user opened history while it was streaming.
+     */
+    async switchSession(path) {
+        if (this.quiesceBlocked())
+            return;
+        let openedRuntime = null;
+        let openedTerminals = null;
+        try {
+            const targetPath = resolve(path);
+            // A session may already be open in the running-conversation map. Reuse it
+            // instead of creating a second writer for the same JSONL transcript.
+            for (const conv of this.convs.values()) {
+                const sessionFile = conv.session.sessionFile;
+                if (sessionFile && resolve(sessionFile) === targetPath) {
+                    await this.switchConversation(conv.id);
+                    return;
+                }
+            }
+            const sessionManager = SessionManager.open(targetPath);
+            const targetCwd = sessionManager.getCwd();
+            const conversationId = this.nextConversationId();
+            openedTerminals = this.makeTerminalManager(conversationId, targetCwd);
+            openedRuntime = await createAgentSessionRuntime(this.makeRuntimeFactory(openedTerminals), {
+                cwd: targetCwd,
+                agentDir: this.agentDir,
+                sessionManager,
+            });
+            // Only displace the old active conversation after the replacement runtime
+            // is known-good. This keeps a failed history open entirely non-destructive.
+            const oldListed = this.conv.listed;
+            const displaced = this.displaceActive();
+            const openInProject = [...this.convs.values()].filter((c) => c.cwd === targetCwd).length +
+                1 -
+                (displaced?.cwd === targetCwd ? 1 : 0);
+            if (openInProject > MAX_OPEN_CONVERSATIONS) {
+                // displaceActive() may have promoted a streaming conversation into the
+                // running list. Roll that presentation-only mutation back because no
+                // switch will take place.
+                this.conv.listed = oldListed;
+                openedTerminals.killAll();
+                await openedRuntime.dispose();
+                openedRuntime = null;
+                openedTerminals = null;
+                this.emit({
+                    type: "notice",
+                    level: "warning",
+                    text: `当前项目运行的对话已达上限（${MAX_OPEN_CONVERSATIONS} 个），请先打开某个对话并离开（不继续对话）以移出列表`,
+                });
+                return;
+            }
+            const conv = this.makeConversation(openedRuntime, conversationId, openedTerminals);
+            // Deliberately resumed — must not be dismissed when the user later
+            // switches away without sending a new message.
+            conv.promptedSinceActive = true;
+            this.convs.set(conv.id, conv);
+            this.activeId = conv.id;
+            openedRuntime = null;
+            openedTerminals = null;
+            if (displaced)
+                this.removeConversation(displaced.id);
+            await this.bindSession();
+            this.cwd = targetCwd;
+            this.conv.lastActiveAt = Date.now();
+            this.webUi.refresh();
+            this.emitConversations();
+            this.goalSvc.emitGoalStatus();
+            this.pushTerminals();
+            // The restored conversation has a fresh project-bound resource cache.
+            void this.pushSlashCommands();
+        }
+        catch (err) {
+            openedTerminals?.killAll();
+            if (openedRuntime)
+                await openedRuntime.dispose().catch(() => { });
+            this.emit({
+                type: "notice",
+                level: "error",
+                text: `切换会话失败：${err.message}`,
+            });
+        }
+        this.flushSnapshot();
+    }
+    /**
+     * Map a rendered user-message id (`u-<timestamp>-<seq>`, assigned in
+     * serialize.ts) back to its append-only session entry id. The seq handles
+     * two user messages sharing the same millisecond timestamp.
+     */
+    resolveUserMessageEntryId(messageId) {
+        const m = /^u-(\d+)(?:-(\d+))?$/.exec(messageId);
+        if (!m)
+            return null;
+        const ts = Number(m[1]);
+        const seq = m[2] ? Number(m[2]) : 1;
+        let count = 0;
+        // Resolve against the compaction-aware current leaf path — the same list
+        // the UI renders (state.messages). Scanning the whole file (getEntries)
+        // could match a summarized entry or one on a different branch.
+        for (const entry of this.session.sessionManager.buildContextEntries()) {
+            if (entry.type !== "message")
+                continue;
+            const msg = entry.message;
+            if (!msg || msg.role !== "user" || msg.timestamp !== ts)
+                continue;
+            count += 1;
+            if (count === seq)
+                return entry.id;
+        }
+        return null;
+    }
+    /**
+     * Edit a past user question and re-ask it: forks a NEW session file that
+     * keeps everything up to (but not including) that question, then sends the
+     * edited text there. The original thread is untouched and stays in the
+     * session list, so nothing is ever lost.
+     *
+     * Attachments (attachments) travel through the SAME pipeline as prompt()
+     * — the fork intentionally drops the original attachment asides because
+     * they live on the old branch past the fork point, so the browser re-sends
+     * the images it kept in the edit composer (original image blocks + any
+     * newly pasted/dropped ones). Text-only edits pass undefined.
+     */
+    async editMessage(messageId, text, attachments) {
+        if (this.quiesceBlocked())
+            return;
+        const trimmed = text.trim();
+        if (!trimmed) {
+            this.emit({
+                type: "notice",
+                level: "warning",
+                text: "编辑内容为空，已取消",
+            });
+            this.flushSnapshot();
+            return;
+        }
+        const entryId = this.resolveUserMessageEntryId(messageId);
+        if (!entryId) {
+            this.emit({
+                type: "notice",
+                level: "error",
+                text: "找不到要编辑的消息（可能已被压缩或不在当前分支）",
+            });
+            this.flushSnapshot();
+            return;
+        }
+        try {
+            // Preserve the model the user had selected — fork() seeds a new
+            // branch with the ModelRuntime default model otherwise.
+            const prevModel = this.session.agent.state.model ?? null;
+            const result = await this.runtime.fork(entryId);
+            if (result.cancelled) {
+                this.emit({
+                    type: "notice",
+                    level: "info",
+                    text: "已取消编辑重问",
+                });
+                this.flushSnapshot();
+                return;
+            }
+            await this.bindSession();
+            // Restore the previously-selected model on the forked branch.
+            if (prevModel && this.sharedModelRuntime) {
+                try {
+                    await this.session.setModel(prevModel);
+                }
+                catch {
+                    // model no longer resolvable — keep the default
+                }
+            }
+            await this.prompt(trimmed, attachments);
+            this.emit({
+                type: "notice",
+                level: "info",
+                text: "已从该问题重新提问（原对话保留在会话列表中）",
+            });
+        }
+        catch (err) {
+            this.emit({
+                type: "notice",
+                level: "error",
+                text: `编辑重问失败：${err.message}`,
+            });
+        }
+        this.flushSnapshot();
+    }
+    /**
+     * Push the recent-project list (persisted per client, merged with every cwd
+     * that has persisted sessions in this client's session store — so workspaces
+     * opened before the recent-list feature existed still show up).
+     */
+    async pushProjects() {
+        try {
+            const saved = this.stateStore.get(this.clientId);
+            const removedProjects = new Set(this.stateStore.getRemovedProjects(this.clientId));
+            const map = new Map();
+            for (const p of saved.projects)
+                map.set(p.path, p.lastUsed);
+            const all = await SessionManager.listAll();
+            for (const s of all) {
+                if (s.cwd) {
+                    const t = s.modified.getTime();
+                    const prev = map.get(s.cwd);
+                    if (prev === undefined || t > prev)
+                        map.set(s.cwd, t);
+                }
+            }
+            // Only keep directories that still exist — a deleted/unmounted workspace
+            // is useless in the picker. Tombstoned entries (explicitly removed by
+            // the user) stay hidden even though session files still mention them.
+            const projects = [...map.entries()]
+                .filter(([path]) => !removedProjects.has(path) && existsSync(path))
+                .map(([path, lastUsed]) => ({ path, lastUsed }))
+                .sort((a, b) => b.lastUsed - a.lastUsed)
+                .slice(0, 20);
+            this.emit({ type: "projects", projects });
+        }
+        catch {
+            this.emit({ type: "projects", projects: [] });
+        }
+    }
+    /** List a workspace directory (relative to the configured cwd). */
+    async listFiles(relPath) {
+        return this.files.listFiles(relPath);
+    }
+    /** 全局搜索：递归文件名匹配（结果经 search_files_result 回推，reqId 匹配）。 */
+    async searchFiles(query, reqId) {
+        return this.files.searchFiles(query, reqId);
+    }
+    /** SCM 只读查询（结构化 JSON，reqId 匹配）。 */
+    async scmQuery(kind, reqId, arg) {
+        return this.files.scmQuery(kind, reqId, arg);
+    }
+    /** Read a workspace file for the preview panel (size-capped, binary-safe). */
+    async readFile(relPath) {
+        return this.files.readFile(relPath);
+    }
+    /** Save text from the file preview panel within the active workspace. */
+    async writeFile(relPath, text) {
+        return this.files.writeFile(relPath, text);
+    }
+    async cycleModel() {
+        try {
+            await this.session.cycleModel();
+        }
+        catch (err) {
+            this.emit({
+                type: "notice",
+                level: "error",
+                text: `切换模型失败：${err.message}`,
+            });
+        }
+        this.flushSnapshot();
+    }
+    /**
+     * Path completion for the cwd input: expand ~/relative paths, list the parent
+     * directory, and return prefix matches (dirs first, capped).
+     */
+    async completePath(input) {
+        return this.files.completePath(input);
+    }
+    async setCwd(newCwd) {
+        try {
+            const { resolve } = await import("node:path");
+            this.files.unwatchGit(); // stale repo's watcher must not fire across projects
+            const fs = await import("node:fs/promises");
+            const abs = resolve(newCwd);
+            const st = await fs.stat(abs);
+            if (!st.isDirectory()) {
+                throw new Error("路径不是目录");
+            }
+            if (abs === this.cwd) {
+                this.emit({
+                    type: "notice",
+                    level: "info",
+                    text: `已在工作目录：${abs}`,
+                });
+                this.flushSnapshot();
+                return;
+            }
+            // The outgoing conversation is left behind — apply the running-list
+            // lifecycle (removal is deferred until the active conversation is
+            // safely switched away).
+            const displaced = this.displaceActive();
+            // Prefer the target project's own most recently active conversation;
+            // only create a fresh one (resuming its most recent session) when the
+            // project has none open yet.
+            let target;
+            for (const c of this.convs.values()) {
+                if (c.cwd === abs &&
+                    (!target || c.lastActiveAt > target.lastActiveAt)) {
+                    target = c;
+                }
+            }
+            if (target) {
+                this.activeId = target.id;
+                if (displaced)
+                    this.removeConversation(displaced.id);
+            }
+            else {
+                // First visit to this project: resume its most recent session.
+                const conversationId = this.nextConversationId();
+                const terminals = this.makeTerminalManager(conversationId, abs);
+                const newRuntime = await createAgentSessionRuntime(this.makeRuntimeFactory(terminals), {
+                    cwd: abs,
+                    agentDir: this.agentDir,
+                    sessionManager: SessionManager.continueRecent(abs),
+                });
+                const conv = this.makeConversation(newRuntime, conversationId, terminals);
+                this.convs.set(conv.id, conv);
+                this.activeId = conv.id;
+                if (displaced)
+                    this.removeConversation(displaced.id);
+                for (const d of newRuntime.diagnostics) {
+                    if (d.type !== "info") {
+                        this.emit({ type: "notice", level: d.type, text: d.message });
+                    }
+                }
+                await this.bindSession();
+            }
+            this.pushTerminals();
+            this.conv.promptedSinceActive = false;
+            this.conv.lastActiveAt = Date.now();
+            this.cwd = abs;
+            // 工作区跟随型插件（编辑器文件树等）同步切根。
+            try {
+                this.onCwdChanged?.(abs);
+            }
+            catch {
+                /* 钩子异常不影响主流程 */
+            }
+            // Remember the new workspace (restore target + recent-project entry).
+            this.stateStore.remember(this.clientId, abs);
+            void this.pushProjects();
+            this.webUi.refresh();
+            this.emitConversations();
+            this.goalSvc.emitGoalStatus();
+            // Skills / prompt templates are project-bound — refresh the catalog.
+            void this.pushSlashCommands();
+            this.emit({
+                type: "notice",
+                level: "info",
+                text: `已切换到工作目录：${abs}`,
+            });
+            void this.refreshSessions();
+            void this.listFiles(undefined);
+            // Commands are per-project (.pi/commands.json in the current cwd).
+            void this.listCommands();
+        }
+        catch (err) {
+            this.emit({
+                type: "notice",
+                level: "error",
+                text: `切换工作目录失败：${err.message}`,
+            });
+        }
+        this.flushSnapshot();
+    }
+    /** List models that have valid authentication configured. */
+    async listModels() {
+        try {
+            const mr = this.runtime.services.modelRuntime;
+            const available = await mr.getAvailable();
+            const models = available.map((m) => ({
+                id: `${m.provider}/${m.id}`,
+                name: m.name,
+                provider: m.provider,
+                reasoning: m.reasoning,
+                vision: m.input?.includes("image") ?? false,
+            }));
+            this.emit({ type: "models", models });
+        }
+        catch (err) {
+            this.emit({
+                type: "notice",
+                level: "error",
+                text: `获取模型列表失败：${err.message}`,
+            });
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Goal / review
+    // ---------------------------------------------------------------------------
+    /** Goal family delegates to GoalService (see goal-service.ts). */
+    async setGoal(goalText, opts) {
+        return this.goalSvc.setGoal(goalText, opts);
+    }
+    async startGoalWizard(text, opts) {
+        return this.goalSvc.startGoalWizard(text, opts);
+    }
+    async setGoalPrefs(opts) {
+        return this.goalSvc.setGoalPrefs(opts);
+    }
+    async clearGoal() {
+        return this.goalSvc.clearGoal();
+    }
+    /** Run a git diff (unstaged + staged) in a conversation's workspace, or
+     * "" when not a repo. */
+    async gitDiff(cwd) {
+        try {
+            const { code, out } = await this.runAsync("git", ["diff", "HEAD"], 10_000, cwd);
+            if (code !== 0)
+                return "";
+            return out.slice(0, 60_000);
+        }
+        catch {
+            return "";
+        }
+    }
+    /** Switch to a specific model by "provider/id" (e.g. "anthropic/claude-sonnet-5"). */
+    async setModel(modelId) {
+        try {
+            const mr = this.runtime.services.modelRuntime;
+            const slash = modelId.indexOf("/");
+            if (slash <= 0 || slash === modelId.length - 1) {
+                throw new Error(`无效的模型 ID：${modelId}`);
+            }
+            const provider = modelId.slice(0, slash);
+            const id = modelId.slice(slash + 1);
+            const model = mr.getModel(provider, id);
+            if (!model)
+                throw new Error(`模型不存在：${modelId}`);
+            await this.session.setModel(model);
+        }
+        catch (err) {
+            this.emit({
+                type: "notice",
+                level: "error",
+                text: `切换模型失败：${err.message}`,
+            });
+        }
+        this.flushSnapshot();
+    }
+    /** Set the thinking level for future turns. */
+    setThinking(level) {
+        try {
+            this.session.setThinkingLevel(level);
+        }
+        catch (err) {
+            this.emit({
+                type: "notice",
+                level: "error",
+                text: `切换思考强度失败：${err.message}`,
+            });
+        }
+        this.flushSnapshot();
+    }
+    cycleThinking() {
+        try {
+            this.session.cycleThinkingLevel();
+        }
+        catch (err) {
+            this.emit({
+                type: "notice",
+                level: "error",
+                text: `切换思考强度失败：${err.message}`,
+            });
+        }
+        this.flushSnapshot();
+    }
+    /** Push the user command list (.pi/commands.json) to the client. */
+    async listCommands() {
+        const { commands, path, warning } = await loadCommands(this.cwd);
+        if (warning) {
+            this.emit({ type: "notice", level: "warning", text: warning });
+        }
+        this.emit({ type: "commands", commands, path });
+    }
+    /** Persist the user command list (.pi/commands.json). */
+    async saveCommands(commands) {
+        const { path, error } = await saveCommandsFile(this.cwd, commands);
+        if (error) {
+            this.emit({ type: "notice", level: "error", text: error });
+            return;
+        }
+        this.emit({ type: "commands", commands, path });
+        this.emit({ type: "notice", level: "info", text: `命令已保存：${path}` });
+    }
+    async dispose() {
+        this.disposed = true;
+        for (const conv of this.convs.values())
+            conv.terminals.killAll();
+        if (this.snapshotTimer) {
+            clearTimeout(this.snapshotTimer);
+            this.snapshotTimer = null;
+        }
+        if (this.sessionsTimer) {
+            clearTimeout(this.sessionsTimer);
+            this.sessionsTimer = null;
+        }
+        if (this.widgetsTimer) {
+            clearInterval(this.widgetsTimer);
+            this.widgetsTimer = null;
+        }
+        if (this.stallTimer) {
+            clearInterval(this.stallTimer);
+            this.stallTimer = null;
+        }
+        this.files.unwatchDir();
+        this.files.unwatchGit();
+        this.webUi.dispose();
+        this.bg.stop();
+        for (const conv of this.convs.values()) {
+            this.clearAllToolWatchdogs(conv);
+            conv.unsubscribe?.();
+            try {
+                await conv.runtime.dispose();
+            }
+            catch {
+                // best effort
+            }
+        }
+    }
+}
+export class AgentService {
+    cwd;
+    /** index.ts 注入：SDK 工具执行事件的插件转发钩子，attach 时拷贝到每个新会话。 */
+    onToolEvent = undefined;
+    /** index.ts 注入：读取插件当前注册的 AI 工具（attach 时拷贝到每个新会话）。 */
+    pluginToolsProvider = undefined;
+    /** index.ts 注入：读取插件当前注册的斜杠命令（attach 时拷贝到每个新会话）。 */
+    pluginCommandsProvider = undefined;
+    /** index.ts 注入：读取插件注册的常驻后台任务（并入 bg_servers 面板）。 */
+    pluginBgTasksProvider = undefined;
+    /** index.ts 注入：停止插件任务（kill_background_server with taskId）。 */
+    pluginStopBgTask = undefined;
+    clients = new Map();
+    /** Quiesce (draining) state — the service refuses NEW work (prompts, forks,
+     *  session resumes, new clients) so a deploy/upgrade/backup can stop cleanly
+     *  once existing runs finish. Controlled via the local control socket:
+     *  `pi-web-ui server quiesce|unquiesce`. */
+    quiesced = false;
+    quiescedAt = 0;
+    /** Attached browser sockets (reported by index.ts on open/close) — the
+     *  control socket reports real sockets, not cached client-session objects. */
+    socketCount = 0;
+    pending = new Map();
+    stateStore;
+    /** Set by index.ts: called when /pi-web-ui:quit is invoked. */
+    onQuit = undefined;
+    /** 任意客户端成功切换工作区后触发（新绝对路径）。index.ts 接到
+     *  PluginManager.notifyCwd，让插件宿主的 host.cwd 实时跟随当前项目。 */
+    onClientCwdChanged = undefined;
+    constructor(cwd, stateFile) {
+        this.cwd = cwd;
+        this.stateStore = new ClientStateStore(stateFile);
+    }
+    /** Get or create the session for a client, racing attach calls safely. */
+    /** True while the service is draining — new work is refused. */
+    isQuiesced() {
+        return this.quiesced;
+    }
+    /** Enter quiesce: stop admitting new work. Existing runs keep going. */
+    quiesce() {
+        this.quiesced = true;
+        this.quiescedAt = Date.now();
+    }
+    /** Leave quiesce: admit new work again. */
+    unquiesce() {
+        this.quiesced = false;
+        this.quiescedAt = 0;
+    }
+    /** Snapshot for the control socket / status command. */
+    quiesceInfo() {
+        return this.quiesced
+            ? { quiesced: true, quiescedSince: this.quiescedAt }
+            : { quiesced: false };
+    }
+    /** Aggregate across every client session: conversations with in-flight runs. */
+    activeConversations() {
+        let n = 0;
+        for (const cs of this.clients.values())
+            n += cs.activeConversations();
+        return n;
+    }
+    /** Aggregate across every client session: messages queued in the SDK. */
+    pendingMessages() {
+        let n = 0;
+        for (const cs of this.clients.values())
+            n += cs.pendingMessages();
+        return n;
+    }
+    /** index.ts calls this when a browser socket opens/closes. */
+    noteSocketOpen() {
+        this.socketCount += 1;
+    }
+    noteSocketClose() {
+        this.socketCount = Math.max(0, this.socketCount - 1);
+    }
+    /** Full status for the control socket / `server status` command. */
+    serviceStatus() {
+        return {
+            pid: process.pid,
+            version: VERSION,
+            cwd: this.cwd,
+            ...this.quiesceInfo(),
+            connectedClients: this.socketCount,
+            activeConversations: this.activeConversations(),
+            pendingMessages: this.pendingMessages(),
+        };
+    }
+    /** Get or create the session for a client, racing attach calls safely. */
+    async attach(clientId, send) {
+        let cs = this.clients.get(clientId);
+        if (!cs) {
+            const inflight = this.pending.get(clientId);
+            if (inflight) {
+                cs = await inflight;
+            }
+            else {
+                // Restore this client's last-used workspace when it still exists;
+                // Admission gate: while quiesced, only clients with an EXISTING
+                // session may attach (they can watch their runs drain); brand-new
+                // clients are refused — index.ts closes their socket (4403) and the
+                // browser reconnect loop retries after admission reopens.
+                if (this.quiesced) {
+                    throw new QuiesceRejectedError("新连接被拒绝，请等服务器恢复后重试");
+                }
+                // otherwise fall back to the server's configured default cwd.
+                let cwd = this.cwd;
+                const saved = this.stateStore.get(clientId);
+                if (saved.lastCwd && saved.lastCwd !== this.cwd) {
+                    try {
+                        if (statSync(saved.lastCwd).isDirectory())
+                            cwd = saved.lastCwd;
+                    }
+                    catch {
+                        // gone (unmounted drive / deleted) — fall back to the default
+                    }
+                }
+                // Sessions use the SDK default per-project dir — no per-client dir.
+                const creating = ClientSession.create(clientId, cwd, this.stateStore).finally(() => {
+                    this.pending.delete(clientId);
+                });
+                this.pending.set(clientId, creating);
+                cs = await creating;
+                this.clients.set(clientId, cs);
+                // Make sure the restored/default workspace appears in the project list.
+                this.stateStore.remember(clientId, cwd);
+                if (cwd !== this.cwd) {
+                    send({
+                        type: "notice",
+                        level: "info",
+                        text: `已恢复上次的工作目录：${cwd}`,
+                    });
+                }
+            }
+        }
+        // First attach after a restart: report runs that were interrupted when
+        // the previous process shut down (consumed once, then cleared). Queue
+        // BEFORE attachSink so the notice rides the initial pending-notice flush.
+        cs.notifyInterrupted(this.stateStore.takeInterrupted(clientId));
+        cs.attachSink(send);
+        // Forward hooks (set once by index.ts) to every session.
+        cs.onQuit = this.onQuit;
+        cs.onToolEvent = this.onToolEvent;
+        cs.pluginToolsProvider = this.pluginToolsProvider;
+        cs.pluginCommandsProvider = this.pluginCommandsProvider;
+        cs.pluginBgTasksProvider = this.pluginBgTasksProvider;
+        cs.pluginStopBgTask = this.pluginStopBgTask;
+        cs.isQuiesced = () => this.quiesced;
+        // 插件宿主工作区跟随：初次接入也同步一次（恢复的 lastCwd 可能≠服务启动目录），
+        // notifyCwd 幂等去重；此后 set_cwd 成功时由 cs.onCwdChanged 继续驱动。
+        cs.onCwdChanged = (abs) => this.onClientCwdChanged?.(abs);
+        this.onClientCwdChanged?.(cs.cwd);
+        return cs;
+    }
+    /** 插件 AI 工具集合变化（注册/注销）时由 index.ts 触发：推送到所有客户端的全部会话。 */
+    applyPluginAgentTools() {
+        for (const cs of this.clients.values())
+            cs.refreshPluginTools();
+    }
+    /** 插件斜杠命令集合变化时由 index.ts 触发：重推各客户端的命令目录。 */
+    applyPluginCommandCatalog() {
+        for (const cs of this.clients.values())
+            void cs.pushSlashCommands();
+    }
+    /** 插件常驻后台任务变化时由 index.ts 触发：重推各客户端的 bg_servers。 */
+    refreshBackgroundServers() {
+        for (const cs of this.clients.values())
+            cs.refreshBgTasks();
+    }
+    /** Remove a socket from a client's broadcast set (called on socket close). */
+    detach(clientId, send) {
+        this.clients.get(clientId)?.detachSink(send);
+    }
+    get(clientId) {
+        return this.clients.get(clientId);
+    }
+    async disposeAll() {
+        // Record still-streaming conversations BEFORE tearing anything down, so
+        // the next attach can tell the user what was lost (SIGTERM / update).
+        for (const [clientId, cs] of [...this.clients]) {
+            try {
+                const running = cs.streamingSummaries();
+                if (running.length > 0) {
+                    this.stateStore.saveInterrupted(clientId, running.map((r) => ({ ...r, at: Date.now() })));
+                }
+            }
+            catch {
+                // best effort — never block shutdown on bookkeeping
+            }
+        }
+        const all = [...this.clients.values()];
+        this.clients.clear();
+        await Promise.all(all.map((cs) => cs.dispose()));
+    }
+}