pi-web-ui 0.68.0 → 0.68.2

package/dist/server/agent-service.js

@@ -14,7 +14,7 @@ import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { createRequire } from "node:module";
 import { existsSync, readFileSync, rmSync, statSync, mkdirSync, watch } from "node:fs";
-import { basename, dirname, join, resolve, sep } from "node:path";
+import { basename, delimiter, dirname, join, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { createAgentSessionFromServices, createAgentSessionRuntime, createAgentSessionServices, createBashTool, createLocalBashOperations, getAgentDir, SessionManager, VERSION, } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
@@ -27,7 +27,7 @@ import { GoalService } from "./goal-service.js";
 import { MarkerService } from "./marker-service.js";
 import { SlashCommandsService, parseSlash } from "./slash-commands.js";
 import { ModelAdminService } from "./model-admin.js";
-import { FilesService, workspacePath } from "./files-service.js";
+import { FilesService, MACHINE_ROOT, workspacePath } from "./files-service.js";
 import { isExtensionDisabled, isExtensionEnabled, ClientStateStore } from "./client-state.js";
 import { SubagentTemplatesStore } from "./subagent-templates.js";
 import { applyHeadTail, makePersistentTerminalTools, makeTerminalBashTool, stripAnsi, TERMINAL_TOOLS_GUIDANCE, TERMINAL_TOOL_NAMES, } from "./terminals.js";
@@ -35,8 +35,8 @@ import { WebUIContext, mockThemeProxy } from "./webui-context.js";
 import { makeEditSoftTool, SOFT_EDIT_TOOL_NAME } from "./edit-soft-tool.js";
 import { makeSubagentTools, subagentTitle, } from "./subagents.js";
 import { buildAttachmentMessages } from "./attachments.js";
-import { BUILTIN_SOUL, DEFAULT_PROMPT_TEMPLATE, renderPromptTemplate, resolveSectionTexts, } from "./prompt-composer.js";
-import { serializeMessage, serializeStreamingMessage } from "./serialize.js";
+import { BUILTIN_SOUL, DEFAULT_PROMPT_TEMPLATE, buildToolsSchemaText, renderPromptTemplate, resolveSectionTexts, } from "./prompt-composer.js";
+import { serializeMessage, serializeStreamingMessage, stripTransientRetryErrors, } from "./serialize.js";
 import { loadCommands, saveCommandsFile, TerminalManager } from "./terminals.js";
 const SNAPSHOT_INTERVAL_MS = 60;
 /** While assistant deltas are flowing, live rendering is carried by
@@ -215,6 +215,67 @@ function makeMarkersListTool(getActiveId, markerSvc) {
         },
     };
 }
+/**
+ * 标准 pi 引擎的 ask_user_question 工具：模型调用时把问题桥到浏览器（复用 DSH
+ * 引擎的 question_pending/question_answer 协议，前端 DshQuestionDialog 富渲染），
+ * 阻塞 agent 循环直到用户在浏览器回答或取消。
+ *
+ * 标准 SDK 没有内建 ask_user_question，故由 pi-web-ui 以 customTool 注册（与
+ * bash/edit 同机制）。DSH 引擎走 goal-rpc 的 userQuestions provider，两者互不
+ * 冲突（各引擎各走各的）。
+ *
+ * askUser 签名带 {aborted} 快照而非完整 AbortSignal：customTool 的 execute 信号
+ * 服务于整个 agent 生命周期，这里按「已中止即拒绝」的最小语义处理，避免与其它
+ * 工具的取消逻辑纠缠。
+ */
+export function makeAskUserQuestionTool(clientSession) {
+    const QuestionOptionSchema = Type.Object({
+        label: Type.String({ description: "Display label for the option" }),
+        description: Type.Optional(Type.String({ description: "Optional description shown below label" })),
+        preview: Type.Optional(Type.String({
+            description: "Optional preview rendered below when this option is selected (markdown or HTML — use for mockups/code/config).",
+        })),
+    });
+    const QuestionSchema = Type.Object({
+        id: Type.String({ description: "Unique identifier for this question" }),
+        question: Type.String({ description: "The full question text to display (markdown/HTML ok)" }),
+        detail: Type.Optional(Type.String({ description: "Optional detail/context shown under the question" })),
+        header: Type.Optional(Type.String({ description: "Optional short header for this question" })),
+        options: Type.Optional(Type.Array(QuestionOptionSchema, { description: "Available options to choose from" })),
+        multiSelect: Type.Optional(Type.Boolean({ description: "Allow selecting multiple options (default: false)" })),
+    });
+    return {
+        name: "ask_user_question",
+        label: "Ask the user",
+        description: "Ask the user focused questions to pin down ambiguous requirements. Use for clarifying the task, confirming decisions, or getting preferences. Each question renders a browser dialog with markdown/HTML rich text; options may carry a `preview`. Submit or cancel to resume.",
+        parameters: Type.Object({
+            questions: Type.Array(QuestionSchema, { description: "Questions to ask the user" }),
+        }),
+        execute: async (_id, params, signal) => {
+            const qs = params.questions;
+            if (!Array.isArray(qs) || qs.length === 0) {
+                throw new Error("ask_user_question requires at least one question");
+            }
+            const answers = await clientSession.askUser(qs, {
+                aborted: signal?.aborted,
+            });
+            if (answers === null) {
+                throw new Error("用户取消了提问");
+            }
+            // 工具结果：把每道题的回答拼成简洁文本给模型，同时留 details 供 UI 展示。
+            const lines = answers.map((a) => {
+                const q = qs.find((q) => q.id === a.id);
+                const label = a.selected.join(", ");
+                const custom = a.custom?.trim() ? ` (wrote: ${a.custom.trim()})` : "";
+                return `${q?.header ?? q?.id ?? a.id}: ${label || "(no selection)"}${custom}`;
+            });
+            return {
+                content: [{ type: "text", text: lines.join("\n") }],
+                details: { answers },
+            };
+        },
+    };
+}
 /**
  * 插件结构化工具 → SDK ToolDefinition。
  * execute 返回值宽容处理：{content,details} 原样收编；字符串/对象包成文本块。
@@ -296,6 +357,37 @@ function extractAssistantTextFromContent(content) {
         .join("\n");
 }
 export { workspacePath };
+/** 轨迹事件 payload 封顶（可直接广播/持久化，不撑爆 storage.json）。 */
+const RUN_TASK_CAP = 500;
+const RUN_ARGS_CAP = 4000;
+const RUN_RESULT_CAP = 4000;
+function truncRun(s, cap) {
+    return s.length <= cap ? s : `${s.slice(0, cap)}\n… [truncated]`;
+}
+/** 从 SDK tool result 里抠可读文本预览（text 块拼接，图片/二进制占位，封顶）。 */
+function previewToolResult(result) {
+    try {
+        const content = result?.content;
+        if (Array.isArray(content)) {
+            const parts = [];
+            for (const c of content) {
+                if (c && typeof c === "object" && c.type === "text") {
+                    parts.push(String(c.text ?? ""));
+                }
+                else {
+                    parts.push("[…]");
+                }
+            }
+            return truncRun(parts.join("\n"), RUN_RESULT_CAP);
+        }
+        if (typeof result === "string")
+            return truncRun(result, RUN_RESULT_CAP);
+        return truncRun(JSON.stringify(result ?? null), RUN_RESULT_CAP);
+    }
+    catch {
+        return "[unserializable result]";
+    }
+}
 /** 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
@@ -494,6 +586,12 @@ export class ClientSession {
     /** index.ts 注入（经 AgentService 拷贝到每个新会话）：把 SDK 工具执行事件转发给
      *  插件（PluginManager.emitToolEvent）。未设置时不做任何事。 */
     onToolEvent = undefined;
+    /** index.ts 注入：把运行轨迹事件转发给插件（PluginManager.emitRunEvent，
+     *  轨迹视图插件靠它聚合时间线）。未设置时不做任何事。 */
+    onRunEvent = undefined;
+    /** index.ts 注入：当前打开对话变了（切历史会话/切 running 对话/新对话）时
+     *  通知插件（PluginManager.emitConversationChanged）——轨迹视图靠它重拉。 */
+    onConversationChanged = undefined;
     /** index.ts 注入：读取插件当前注册的 AI 工具（attach 时拷贝到每个新会话）。 */
     pluginToolsProvider = undefined;
     /** index.ts 注入：读取插件当前注册的斜杠命令（目录展示 + prompt 拦截执行）。 */
@@ -726,6 +824,10 @@ export class ClientSession {
     /** 子代理最近一次运行的结局：最后一条 assistant 消息的 errorMessage / stopReason。
      *  报错 > 中止 > 正常，三者互斥；无 assistant 消息时返回空。 */
     subagentRunOutcome(conv) {
+        // 自动重试等待期结局未定：瞬时 error 不算失败，避免向主对话误报
+        // 「子代理运行失败」（耗尽后 auto_retry_end 清旗，真正失败照常通知）。
+        if (conv.retryState)
+            return {};
         try {
             const msgs = conv.session.agent.state.messages;
             for (let i = msgs.length - 1; i >= 0; i--) {
@@ -827,6 +929,7 @@ export class ClientSession {
             const active = sess.getActiveToolNames();
             const snippets = {};
             const guidelines = [];
+            const schemaEntries = [];
             for (const name of active) {
                 const def = sess.getToolDefinition(name);
                 if (!def)
@@ -835,6 +938,11 @@ export class ClientSession {
                     snippets[name] = def.promptSnippet;
                 if (def.promptGuidelines)
                     guidelines.push(...def.promptGuidelines);
+                schemaEntries.push({
+                    name,
+                    description: def.description,
+                    parameters: def.parameters,
+                });
             }
             const loader = sess.resourceLoader;
             const texts = resolveSectionTexts(this.composeInputs({
@@ -854,7 +962,7 @@ export class ClientSession {
             const ovs = this.settingsSvc.current.promptOverrides ?? {};
             const hasOverride = Object.values(ovs).some((v) => typeof v === "string" && v.trim());
             const rendered = !tpl && !hasOverride ? undefined : renderPromptTemplate(tpl || DEFAULT_PROMPT_TEMPLATE, texts, ovs);
-            return { texts, full: rendered ?? sess.systemPrompt };
+            return { texts, full: rendered ?? sess.systemPrompt, toolsSchema: buildToolsSchemaText(schemaEntries) };
         }
         catch {
             // Session not ready yet.
@@ -864,7 +972,7 @@ export class ClientSession {
     /** 设置面板预览用的 host 回调（见 SettingsHost.promptSnapshot）：完整生效提示词
      *  + 各来源默认（自动）内容。会话未就绪时给空值，面板保持可编辑但不预览。 */
     promptSnapshot() {
-        return this.sessionPromptSnapshot() ?? { full: "", texts: {} };
+        return this.sessionPromptSnapshot() ?? { full: "", texts: {}, toolsSchema: "" };
     }
     /** Web-facing extension UI context (widgets, notifications). */
     webUi = new WebUIContext((msg) => this.emit(msg));
@@ -959,6 +1067,14 @@ export class ClientSession {
     subagentTemplates;
     /** 内置标记服务（todo/notify/svc/rename 等，可全局/分组开关）。 */
     markerSvc;
+    // -----------------------------------------------------------------------
+    // 用户提问桥（标准 pi 引擎的 ask_user_question customTool）：与 DSH 引擎的
+    // question_pending/question_answer 同协议。模型调 ask_user_question 工具 →
+    // 本桥发 question_pending 给浏览器 → 等 question_answer → resolve/reject
+    // 工具结果（agent 循环阻塞）。一次只展示一个提问（agent 阻塞在工具执行）。
+    // -----------------------------------------------------------------------
+    questionSeq = 0;
+    pendingQuestions = new Map();
     constructor(clientId, cwd, agentDir, stateStore) {
         this.clientId = clientId;
         this.cwd = cwd;
@@ -1235,6 +1351,10 @@ export class ClientSession {
                     ...makeSubagentTools(this.subagentHost),
                     // 内置标记只读查询工具（todo/svc 状态查询，写操作走内联标记）。
                     makeMarkersListTool(() => this.activeId, this.markerSvc),
+                    // 标准引擎的 ask_user_question：模型调用 → 浏览器富渲染问卷（复用 DSH
+                    // 的 question_pending/question_answer 协议，前端 DshQuestionDialog）。
+                    // DSH 引擎不经此（它走 goal-rpc 的 userQuestions provider）。
+                    makeAskUserQuestionTool(this),
                 ],
             });
             // 终端工具开关从创建起就生效（工具始终注册进注册表，只调活跃集）。
@@ -1456,6 +1576,76 @@ export class ClientSession {
             clearTimeout(t);
         conv.toolWatchdogs.clear();
     }
+    /** 发一条运行轨迹事件给插件（host.onRunEvent 订阅者，如轨迹视图插件）。
+     *  异常隔离——序列化/插件坏了只记日志，绝不影响主流程。 */
+    emitRun(conv, ev) {
+        if (!this.onRunEvent)
+            return;
+        try {
+            this.onRunEvent({ ...ev, conversationId: conv.id, at: Date.now() });
+        }
+        catch (err) {
+            console.error("[agent-service] onRunEvent failed:", err);
+        }
+    }
+    /** 当前打开对话变了 → 通知插件重拉（切历史会话/切 running 对话/新对话）。
+     *  异常隔离——插件坏了只记日志，绝不影响切换流程。 */
+    notifyConversationChanged() {
+        if (!this.onConversationChanged)
+            return;
+        try {
+            this.onConversationChanged();
+        }
+        catch (err) {
+            console.error("[agent-service] onConversationChanged failed:", err);
+        }
+    }
+    /** 插件用：本客户端最近活跃对话的快照（轨迹视图直接显示打开对话的时间线）。
+     *  messages/streamingMessage 为引用稳定的只读缓存对象——调用方只读、不得修改。 */
+    readConversationForPlugins() {
+        try {
+            let target = null;
+            for (const c of this.convs.values()) {
+                if (!target || c.lastActiveAt > target.lastActiveAt)
+                    target = c;
+            }
+            if (!target)
+                return null;
+            const state = target.session.agent.state;
+            let stats = {
+                totalMessages: 0,
+                tokens: { input: 0, output: 0, total: 0 },
+                cost: 0,
+            };
+            try {
+                const s = target.session.getSessionStats();
+                stats = { totalMessages: s.totalMessages, tokens: s.tokens, cost: s.cost };
+            }
+            catch {
+                /* stats 尽力而为 */
+            }
+            let streamingMessage = null;
+            try {
+                streamingMessage = state.streamingMessage ? serializeStreamingMessage(state.streamingMessage) : null;
+            }
+            catch {
+                /* 尽力而为 */
+            }
+            return {
+                conversationId: target.id,
+                title: target.title,
+                at: target.lastActiveAt,
+                isStreaming: target.session.isStreaming,
+                messages: this.messagesOf(target),
+                streamingMessage,
+                stats,
+            };
+        }
+        catch (err) {
+            console.error("[agent-service] readConversationForPlugins failed:", err);
+            return null;
+        }
+    }
     onEvent(conv, event) {
         // Any SDK event proves the run is alive — feeds the stall watchdog below.
         conv.lastSdkEventAt = Date.now();
@@ -1485,7 +1675,26 @@ export class ClientSession {
                 }
                 this.armToolWatchdog(conv, event.toolCallId);
                 // 插件扩展点：工具开始执行（异常由 emitToolEvent 隔离）。
-                this.onToolEvent?.({ phase: "start", toolName: event.toolName, conversationId: conv.id });
+                this.onToolEvent?.({
+                    phase: "start",
+                    toolName: event.toolName,
+                    conversationId: conv.id,
+                    toolCallId: event.toolCallId,
+                });
+                // 轨迹事件：带参数预览（JSON 封顶；超大参数只记截断）。
+                let argsText = "null";
+                try {
+                    argsText = truncRun(JSON.stringify(event.args ?? null), RUN_ARGS_CAP);
+                }
+                catch {
+                    argsText = "[unserializable args]";
+                }
+                this.emitRun(conv, {
+                    type: "tool_start",
+                    toolCallId: event.toolCallId,
+                    toolName: event.toolName,
+                    argsText,
+                });
                 break;
             }
             case "tool_execution_end": {
@@ -1502,6 +1711,16 @@ export class ClientSession {
                     phase: "end",
                     toolName: event.toolName,
                     conversationId: conv.id,
+                    toolCallId: event.toolCallId,
+                    ...(durationMs !== undefined ? { durationMs } : {}),
+                    isError: event.isError,
+                });
+                // 轨迹事件：带结果预览（封顶）+ 耗时/错误标志。
+                this.emitRun(conv, {
+                    type: "tool_end",
+                    toolCallId: event.toolCallId,
+                    toolName: event.toolName,
+                    resultText: previewToolResult(event.result),
                     ...(durationMs !== undefined ? { durationMs } : {}),
                     isError: event.isError,
                 });
@@ -1597,9 +1816,58 @@ export class ClientSession {
                 }
                 break;
             }
+            case "auto_retry_start": {
+                // 大模型 API 瞬时报错，SDK 退避重试：填实重试信息。末尾 error
+                // 消息已被（或即将被）SDK 从 state 摘掉，currentMessages() 凭此旗
+                // 过滤，快照只显示温和的重试条。落盘由底部检查点立即 flush。
+                conv.retryState = {
+                    attempt: event.attempt,
+                    maxAttempts: event.maxAttempts,
+                    delayMs: event.delayMs,
+                    errorMessage: event.errorMessage,
+                };
+                break;
+            }
+            case "auto_retry_end": {
+                // 重试结束：成功 → 新内容照常显示；耗尽 → error 消息留驻，
+                // 快照永久标红。落盘由底部检查点立即 flush。
+                conv.retryState = null;
+                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": {
+                // 可重试错误：SDK 随后发 auto_retry_start 并把末尾 error 消息从
+                // state 摘掉。这里先立占位，让本次立即 flush 的快照就不含瞬时红错
+                // ——否则快照先画红、摘掉后又消失，即「红色报错一闪而过」。
+                if (event.willRetry) {
+                    let errorMessage = "";
+                    for (let i = event.messages.length - 1; i >= 0; i--) {
+                        const m = event.messages[i];
+                        if (m.role === "assistant" && typeof m.errorMessage === "string") {
+                            errorMessage = m.errorMessage;
+                            break;
+                        }
+                    }
+                    conv.retryState = { attempt: 0, maxAttempts: 0, delayMs: 0, errorMessage };
+                }
+                else {
+                    // 本轮结束且无后续重试：任何残留占位都是过期的（会话替换、
+                    // 结束信号丢失等），清掉，否则横幅会卡住不消失。
+                    conv.retryState = null;
+                }
+                // 轨迹事件：本轮结束（放最前——aborted 中断路径也会 break，
+                // 轨迹里必须留下「已停止」而不是凭空消失）。
+                try {
+                    const lastAssistant = [...event.messages].reverse().find((m) => {
+                        const a = m;
+                        return a.role === "assistant" && typeof a.stopReason === "string";
+                    });
+                    this.emitRun(conv, lastAssistant?.stopReason ? { type: "run_end", stopReason: lastAssistant.stopReason } : { type: "run_end" });
+                }
+                catch {
+                    /* 轨迹尽力而为 */
+                }
                 this.scheduleSessionsRefresh();
                 this.refreshConversationTitle(conv);
                 // 内联标记不在此兜底扫最后一条 assistant：每条气泡结束已走 message_end
@@ -1659,16 +1927,47 @@ export class ClientSession {
                 break;
             }
             case "message_end": {
+                // 轨迹事件：一条消息定稿（user/assistant 都收；custom display:false
+                // 的 serializeMessage 返回 null 时跳过）。
+                try {
+                    const ui = serializeMessage(event.message, 0);
+                    if (ui)
+                        this.emitRun(conv, { type: "message", message: ui });
+                }
+                catch {
+                    /* 轨迹尽力而为 */
+                }
+                // 每条 assistant 气泡流式结束 → 立即解析其中的内联标记：每个气泡各自
                 // 每条 assistant 气泡流式结束 → 立即解析其中的内联标记：每个气泡各自
                 // 生效（不再等整轮 agent_end），同一轮里先前消息的标记也不再丢。
                 const mm = event.message;
                 if (mm?.role !== "assistant")
                     break;
+                // 非 error 的 assistant 定稿 = 重试周期结束（与 SDK 重置
+                // _retryAttempt 的条件一致）：即使 auto_retry_end 丢失，横幅也不会卡住。
+                if (mm.stopReason !== "error")
+                    conv.retryState = null;
                 const text = extractAssistantTextFromContent(mm.content);
                 if (text && text.includes("[["))
                     void this.markerSvc.handleAssistantText(conv.id, text);
                 break;
             }
+            case "agent_start": {
+                // 轨迹事件：新一轮开始（任务文本由 prompt() 暂存；steer/内部续跑
+                // 无暂存时省略，插件回退为「继续执行」）。
+                const task = conv.pendingTask;
+                conv.pendingTask = undefined;
+                this.emitRun(conv, task ? { type: "run_start", task } : { type: "run_start" });
+                break;
+            }
+            case "turn_start": {
+                this.emitRun(conv, { type: "turn_start" });
+                break;
+            }
+            case "turn_end": {
+                this.emitRun(conv, { type: "turn_end" });
+                break;
+            }
             case "message_update": {
                 // Live assistant-message increment, deliberately OUTSIDE the snapshot
                 // channel: send() drops snapshots under backpressure (big sessions),
@@ -1714,7 +2013,11 @@ export class ClientSession {
         // Snapshot checkpoint policy: deltas carry live rendering during streaming;
         // full snapshots are reconciliation checkpoints taken immediately at
         // run/tool boundaries and on a slow timer otherwise.
-        if (event.type === "agent_end" || event.type === "tool_execution_end" || event.type === "compaction_end") {
+        if (event.type === "agent_end" ||
+            event.type === "tool_execution_end" ||
+            event.type === "compaction_end" ||
+            event.type === "auto_retry_start" ||
+            event.type === "auto_retry_end") {
             this.flushSnapshot();
         }
         else {
@@ -1751,7 +2054,10 @@ export class ClientSession {
     }
     /** Serialize a persisted message with a STABLE id + cached object reference. */
     serializeCached(m) {
-        const conv = this.conv;
+        return this.serializeCachedFor(this.conv, m);
+    }
+    /** serializeCached 的按对话版本（插件快照读非活跃对话用；缓存仍按对话隔离）。 */
+    serializeCachedFor(conv, m) {
         // 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
@@ -1801,10 +2107,17 @@ export class ClientSession {
      *  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))
+        return this.messagesOf(this.conv);
+    }
+    /** currentMessages 的按对话版本（插件快照读非活跃对话用）。 */
+    messagesOf(conv) {
+        let rawMessages = conv.session.agent.state.messages
+            .map((m) => this.serializeCachedFor(conv, m))
             .filter((m) => m !== null);
+        // 自动重试等待期：SDK 暂留在 state 末尾的 error 气泡只是中间态（随后被
+        // 摘掉重跑），不进快照——成功则用户永远看不到，耗尽才标红。否则 agent_end
+        // 的立即 flush 会先画红、摘掉后又消失（红色一闪而过）。
+        rawMessages = stripTransientRetryErrors(rawMessages, !!conv.retryState);
         // 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.
@@ -1843,6 +2156,13 @@ export class ClientSession {
         catch {
             // stats are best-effort
         }
+        // 流式 error 同样是中间态（定稿走 message_end/agent_end）：先藏起
+        // errorMessage，避免红色在 streaming 气泡里闪一下。最终失败会经由
+        // messages 永久标红，不影响告警。
+        let streamingMessage = state.streamingMessage ? serializeStreamingMessage(state.streamingMessage) : null;
+        if (streamingMessage?.stopReason === "error") {
+            streamingMessage = { ...streamingMessage, errorMessage: undefined };
+        }
         return {
             clientId: this.clientId,
             cwd: this.cwd,
@@ -1850,11 +2170,7 @@ export class ClientSession {
             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,
+            streamingMessage,
             isStreaming: this.session.isStreaming,
             model: model
                 ? {
@@ -1870,6 +2186,7 @@ export class ClientSession {
             availableThinkingLevels: this.session.getAvailableThinkingLevels(),
             queue: { steering: conv.queueSteering, followUp: conv.queueFollowUp },
             errorMessage: state.errorMessage,
+            retry: conv.retryState ?? null,
             tools: state.tools.map((t) => t.name),
             version: ++this.version,
             piConfigured: this.isPiConfigured(),
@@ -1930,6 +2247,55 @@ export class ClientSession {
     resolveDialog(id, value) {
         this.webUi.resolveDialog(id, value);
     }
+    // -----------------------------------------------------------------------
+    // 用户提问桥（标准 pi 引擎 ask_user_question customTool）
+    // -----------------------------------------------------------------------
+    /** 标准引擎模型调 ask_user_question：发 question_pending 给浏览器并阻塞等待
+     *  question_answer。sig 为工具执行信号的当前状态（aborted → 立即 reject）。
+     *  返回 answers（用户选中/自定义），或 null（用户取消）。 */
+    askUser(questions, sig) {
+        return new Promise((resolve, reject) => {
+            if (sig?.aborted || this.disposed) {
+                reject(new Error("ask_user_question 已中止"));
+                return;
+            }
+            // 问卷开关（默认开）：关 → 不弹对话框，立即报错让模型得知已禁用。
+            if (this.settingsSvc.current.questionnaireEnabled === false) {
+                reject(new Error("问卷功能已关闭，可在设置中重新开启"));
+                return;
+            }
+            const id = `q-${++this.questionSeq}`;
+            this.pendingQuestions.set(id, resolve);
+            this.emit({
+                type: "question_pending",
+                id,
+                questions,
+            });
+        });
+    }
+    /** 前端回答模型提问（question_answer → 恢复 askUser 的 Promise）。id 需匹配
+     *  pendingQuestions 中键；cancelled 或未匹配（例如用户早已切走）时按「取消」处理
+     *  —— 把挂起的提问全部 reject，让模型知道用户离开了。 */
+    resolveQuestion(id, answers, cancelled) {
+        const resolve = this.pendingQuestions.get(id);
+        if (resolve) {
+            this.pendingQuestions.delete(id);
+            resolve(cancelled ? null : answers);
+        }
+    }
+    /** 标准引擎的 question_answer 路由入口（index.ts 经 cs.answerQuestion?. 转发）。
+     *  DSH 引擎的 AgentService 也实现了同名方法，此处为 ClientSession 的转发。 */
+    answerQuestion(id, answers, cancelled) {
+        this.resolveQuestion(id, answers, cancelled);
+        return Promise.resolve();
+    }
+    /** 关闭所有挂起提问（切对话 / dispose 时清理）：以「取消」解析，避免模型挂死。 */
+    cancelPendingQuestions() {
+        for (const [, resolve] of this.pendingQuestions) {
+            resolve(null);
+        }
+        this.pendingQuestions.clear();
+    }
     /**
      * Whether the pi agent has at least one usable model. ModelRuntime's
      * available snapshot already accounts for models.json, auth.json, env-var
@@ -1950,65 +2316,32 @@ export class ClientSession {
      * probe). Cached machine-wide (same binary for every client) for 10s —
      * the check is only rerun after install or when the cache expires.
      *
-     * The probe runs ASYNCHRONOUSLY in the background: this getter serves the
-     * last known value and never blocks the event loop. It previously used
-     * spawnSync here, which could deadlock the whole server on Android/Termux:
-     * fork() inside a multi-threaded process (websocket handlers + snapshot
-     * serialization are active) occasionally left the forked child stuck
-     * between fork and exec (futex_wait) while the blocked main thread sat in
-     * spawnSync's pipe_read — the server kept running but stopped accepting
-     * connections. Observed reproducibly on Android/Termux (Node 26).
+     * The probe is FORK-FREE: it scans PATH for the pi executable instead of
+     * spawning `pi --version`. Do not reintroduce a spawn here — ANY fork on
+     * the main thread of this multi-threaded server can deadlock the whole
+     * process on Android/Termux (issue #78): libuv's uv_spawn blocks its
+     * caller reading the child's error pipe, and that pipe never closes when
+     * the forked child deadlocks between fork and exec. This applies to
+     * asynchronous spawns too — the previous async probe reproduced the hang.
      */
     static piCliProbe = null;
-    static piCliProbePending = false;
     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;
-        ClientSession.refreshPiCliProbe();
-        return cached?.installed ?? false;
+        const installed = ClientSession.piCliOnPath();
+        ClientSession.piCliProbe = { at: now, installed };
+        return installed;
     }
-    static refreshPiCliProbe() {
-        if (ClientSession.piCliProbePending)
-            return;
-        ClientSession.piCliProbePending = true;
-        let proc;
-        try {
-            proc = spawn("pi", ["--version"], {
-                stdio: "ignore",
-                // Windows: `pi` resolves to a pi.cmd shim — spawn can only
-                // exec those through a shell (else ENOENT).
-                shell: process.platform === "win32",
-            });
+    static piCliOnPath() {
+        const dirs = (process.env.PATH ?? "").split(delimiter);
+        for (const dir of dirs) {
+            if (dir && existsSync(join(dir, "pi")))
+                return true;
         }
-        catch {
-            ClientSession.piCliProbe = { at: Date.now(), installed: false };
-            ClientSession.piCliProbePending = false;
-            return;
-        }
-        const finish = (installed) => {
-            ClientSession.piCliProbe = { at: Date.now(), installed };
-            ClientSession.piCliProbePending = false;
-        };
-        const timer = setTimeout(() => {
-            try {
-                proc.kill();
-            }
-            catch {
-                /* already exited */
-            }
-            finish(false);
-        }, 5000);
-        proc.on("error", () => {
-            clearTimeout(timer);
-            finish(false);
-        });
-        proc.on("close", (code) => {
-            clearTimeout(timer);
-            finish(code === 0);
-        });
+        return false;
     }
     static invalidatePiCliProbe() {
         ClientSession.piCliProbe = null;
@@ -2607,6 +2940,9 @@ export class ClientSession {
             // is refused until admission reopens.
             if (this.quiesceBlocked())
                 return;
+            // 轨迹用：暂存本轮任务文本，下一轮 agent_start 消费（steer/内部续跑
+            // 不经此处，届时 task 缺省，插件回退为「继续执行」）。
+            conv.pendingTask = text.trim() ? truncRun(text.trim(), RUN_TASK_CAP) : undefined;
             // Name the conversation from its FIRST prompt immediately, before any
             // await: the typed text IS the name. The `conv` reference was captured
             // before the try block, so a concurrent switch/new_chat while prompt()
@@ -3000,6 +3336,8 @@ export class ClientSession {
             // The new runtime re-discovered skills/templates — refresh the catalog
             // so the picker stops showing the previous runtime's list.
             void this.pushSlashCommands();
+            // 新对话即当前打开 → 插件重拉（轨迹视图跟随）。
+            this.notifyConversationChanged();
         }
         catch (err) {
             this.emit({
@@ -3115,6 +3453,8 @@ export class ClientSession {
             void this.listFiles(undefined);
             void this.listCommands();
         }
+        // 当前打开对话变了 → 插件重拉（轨迹视图切会话后即刷新，不等轮询）。
+        this.notifyConversationChanged();
         this.flushSnapshot();
     }
     /** Push every running conversation across ALL projects to the client. The
@@ -3565,6 +3905,8 @@ export class ClientSession {
             this.pushTerminals();
             // The restored conversation has a fresh project-bound resource cache.
             void this.pushSlashCommands();
+            // 切历史会话成功 → 插件重拉（轨迹视图立即显示该会话时间线）。
+            this.notifyConversationChanged();
         }
         catch (err) {
             openedTerminals?.killAll();
@@ -3812,10 +4154,25 @@ export class ClientSession {
     }
     async setCwd(newCwd) {
         try {
-            const { resolve } = await import("node:path");
+            const { resolve, sep } = 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 trimmed = newCwd.trim();
+            if (trimmed === MACHINE_ROOT) {
+                // 机器根是虚拟层（盘符列表），不能作工作目录——指引用户选具体目录。
+                this.emit({
+                    type: "notice",
+                    level: "warning",
+                    text: "请选择一个具体目录作为工作目录（此电脑本身不是目录）",
+                    textEn: "Pick a concrete directory as the workspace (This PC itself is not a directory)",
+                });
+                return;
+            }
+            // Windows 裸盘符（"C:"）：resolve 会按该盘当前目录解析，必须显式指到盘根；
+            // 仅 win32 生效——posix 下 "C:" 仍是普通相对路径，避免误伤同名目录。
+            const abs = process.platform === "win32" && /^[A-Za-z]:$/.test(trimmed)
+                ? `${trimmed.toUpperCase()}${sep}`
+                : resolve(trimmed);
             const st = await fs.stat(abs);
             if (!st.isDirectory()) {
                 throw new Error("路径不是目录");
@@ -3900,6 +4257,8 @@ export class ClientSession {
             void this.listFiles(undefined);
             // Commands are per-project (.pi/commands.json in the current cwd).
             void this.listCommands();
+            // 切项目即换了当前打开对话 → 插件重拉。
+            this.notifyConversationChanged();
         }
         catch (err) {
             this.emit({
@@ -4063,6 +4422,8 @@ export class ClientSession {
         this.files.unwatchDir();
         this.files.unwatchGit();
         this.webUi.dispose();
+        // 关闭所有挂起的用户提问（dispose 时以「取消」解析，避免模型挂死）。
+        this.cancelPendingQuestions();
         this.bg.stop();
         for (const conv of this.convs.values()) {
             this.clearAllToolWatchdogs(conv);
@@ -4080,6 +4441,10 @@ export class AgentService {
     cwd;
     /** index.ts 注入：SDK 工具执行事件的插件转发钩子，attach 时拷贝到每个新会话。 */
     onToolEvent = undefined;
+    /** index.ts 注入：运行轨迹事件的插件转发钩子，attach 时拷贝到每个新会话。 */
+    onRunEvent = undefined;
+    /** index.ts 注入：对话切换通知钩子，attach 时拷贝到每个新会话。 */
+    onConversationChanged = undefined;
     /** index.ts 注入：读取插件当前注册的 AI 工具（attach 时拷贝到每个新会话）。 */
     pluginToolsProvider = undefined;
     /** index.ts 注入：读取插件当前注册的斜杠命令（attach 时拷贝到每个新会话）。 */
@@ -4142,6 +4507,21 @@ export class AgentService {
             n += cs.pendingMessages();
         return n;
     }
+    /** 插件用：全客户端最近活跃对话的快照（at 最大者即“当前打开的对话”）。 */
+    readConversationForPlugins() {
+        let best = null;
+        for (const cs of this.clients.values()) {
+            try {
+                const s = cs.readConversationForPlugins();
+                if (s && (!best || s.at > best.at))
+                    best = s;
+            }
+            catch {
+                /* 单客户端坏了不影响其他 */
+            }
+        }
+        return best;
+    }
     /** index.ts calls this when a browser socket opens/closes. */
     noteSocketOpen() {
         this.socketCount += 1;
@@ -4217,6 +4597,8 @@ export class AgentService {
         // Forward hooks (set once by index.ts) to every session.
         cs.onQuit = this.onQuit;
         cs.onToolEvent = this.onToolEvent;
+        cs.onRunEvent = this.onRunEvent;
+        cs.onConversationChanged = () => this.onConversationChanged?.();
         cs.pluginToolsProvider = this.pluginToolsProvider;
         cs.pluginCommandsProvider = this.pluginCommandsProvider;
         cs.pluginBgTasksProvider = this.pluginBgTasksProvider;