oh-my-agent-web 0.2.0 → 0.4.0

package/dist/server/engine/pi-sdk.js

@@ -0,0 +1,343 @@
+/**
+ * 真实引擎：用 pi SDK 实现「引擎端口」（ADR-0003）。
+ *
+ * ⚠️ 这是**唯一**允许 import `@earendil-works/*` 的地方（守卫 `check-engine-imports.mjs` 强制）。
+ * 业务代码只见 `port.ts` 里的类型。
+ *
+ * 与 SDK 的对接方式（M3 侦察结论）：
+ */
+import { DefaultResourceLoader, SessionManager, createAgentSession, getAgentDir, } from "@earendil-works/pi-coding-agent";
+import { classifyScope } from "../approval/scope.js";
+import { mapSessionEvent } from "./pi-events.js";
+import { readSessionModel } from "./pi-session-model.js";
+import { entriesToUiMessages } from "./pi-transcript.js";
+function asRecord(value) {
+    return typeof value === "object" && value !== null ? value : {};
+}
+/** 教模型怎么写「下一步建议」（ADR-0022）：刻意写得短（每次请求都付 token） */
+import { reloadModelRegistry } from "./model-registry-reload.js";
+import { SUGGESTION_GUIDANCE } from "./suggestion-guidance.js";
+export { SUGGESTION_GUIDANCE };
+import { createPiThinking } from "./pi-thinking.js";
+import { piSdkVersion } from "./pi-version.js";
+import { renameSessionIn } from "./pi-rename.js";
+export function createPiSdkEngine(options = {}) {
+    const sessions = new Map();
+    const thinking = createPiThinking(sessions);
+    let approvalHandler = null;
+    const notice = (text, level = "warn") => options.onNotice?.(text, level);
+    /** 审批用的 inline 扩展：拦在工具真正执行之前（SDK 的公开拦截点） */
+    function makeApprovalExtension(workspace) {
+        return {
+            name: "agent-web-approval",
+            hidden: true,
+            factory: (pi) => {
+                pi.on("tool_call", async (event) => {
+                    const record = asRecord(event);
+                    const scope = classifyScope({
+                        toolName: String(record.toolName ?? ""),
+                        args: record.input,
+                        workspace,
+                    });
+                    if (!scope.dangerous)
+                        return undefined; // 只读工具不问
+                    const decision = approvalHandler
+                        ? await approvalHandler({
+                            toolName: scope.toolName,
+                            argsSummary: scope.argsSummary,
+                            scopeKey: scope.scopeKey,
+                            scopeHint: scope.scopeHint,
+                            riskNote: scope.riskNote,
+                        })
+                        : "deny";
+                    if (decision === "deny") {
+                        return { block: true, reason: "用户拒绝了这次操作（不要在未获批准时重试同一操作）" };
+                    }
+                    return undefined;
+                });
+            },
+        };
+    }
+    /** 建 resourceLoader 并拉起一个 AgentSession（createSession 与 openSession 共用） */
+    async function startSession(sessionId, workspace, sessionManager, sessionPath = null) {
+        const agentDir = options.agentDir ?? getAgentDir();
+        const resourceLoader = new DefaultResourceLoader({
+            cwd: workspace,
+            agentDir,
+            extensionFactories: [makeApprovalExtension(workspace)],
+            // 教模型「下一步建议」的写法（ADR-0022）：纯文本标记，不需要调用任何工具
+            appendSystemPrompt: [SUGGESTION_GUIDANCE],
+        });
+        await resourceLoader.reload();
+        const { session } = await createAgentSession({
+            cwd: workspace,
+            agentDir,
+            resourceLoader,
+            // ADR-0021 §2：转录的事实源就是 SDK 自己的会话文件（新建或打开的那个）
+            sessionManager,
+        });
+        const subscriptions = new Set();
+        const handle = {
+            session: session,
+            workspace,
+            unsubscribe: () => {
+                for (const off of subscriptions)
+                    off();
+                subscriptions.clear();
+            },
+            subscriptions,
+            aborting: false,
+            sessionManager: sessionManager,
+            sessionPath: sessionPath ?? sessionManager.getSessionFile() ?? null,
+        };
+        sessions.set(sessionId, handle);
+        return handle;
+    }
+    const PREWARM_ID = "__prewarm__";
+    async function warmUp() {
+        if (sessions.has(PREWARM_ID))
+            return;
+        try {
+            await startSession(PREWARM_ID, process.cwd(), SessionManager.inMemory());
+        }
+        catch (error) {
+            options.onNotice?.(`模型表预热失败：${error instanceof Error ? error.message : String(error)}`, "warn");
+        }
+    }
+    return {
+        /** 预热：pi 的 modelRuntime 挂在会话上，没会话就列不出模型（内存会话，不落盘） */
+        async prewarm() {
+            if (sessions.has(PREWARM_ID))
+                return;
+            try {
+                await startSession(PREWARM_ID, process.cwd(), SessionManager.inMemory());
+            }
+            catch (error) {
+                options.onNotice?.(`模型表预热失败：${error instanceof Error ? error.message : String(error)}`, "warn");
+            }
+        },
+        version: piSdkVersion,
+        reloadModels: () => reloadModelRegistry(sessions, PREWARM_ID, warmUp, options.agentDir ?? getAgentDir()),
+        async createSession(sessionOptions) {
+            // ADR-0021 §2：新建会话就落在 **pi 的会话存储**里（不再用 inMemory + 自建 jsonl），
+            // 用我们的 sessionId 当 SDK 的会话 id → 两边 id 空间完全一致。
+            const sessionManager = SessionManager.create(sessionOptions.workspace, options.sessionDir, {
+                id: sessionOptions.sessionId,
+            });
+            const handle = await startSession(sessionOptions.sessionId, sessionOptions.workspace, sessionManager);
+            return { sessionPath: handle.sessionPath };
+        },
+        async openSession(openOptions) {
+            const sessionPath = openOptions.sessionPath ?? openOptions.engineSessionId;
+            if (!sessionPath)
+                throw new Error("pi 打开会话需要 sessionPath（文件路径）");
+            const sessionManager = SessionManager.open(sessionPath, options.sessionDir); // header 里的 cwd + 同一个文件续写
+            const workspace = sessionManager.getCwd() || process.cwd();
+            await startSession(openOptions.sessionId, workspace, sessionManager, sessionPath);
+        },
+        renameSession: (sessionPath, name) => renameSessionIn(sessions, sessionPath, name, options.sessionDir),
+        async readUiMessages(sessionId) {
+            const handle = sessions.get(sessionId);
+            if (!handle)
+                return [];
+            return entriesToUiMessages(handle.sessionManager.getEntries());
+        },
+        async sendMessage(sessionId, text, onEvent, messageOptions) {
+            const handle = sessions.get(sessionId);
+            if (!handle) {
+                onEvent({ type: "error", code: "engine.no_session", message: `引擎里没有这个会话：${sessionId}` });
+                onEvent({ type: "turn_end", reason: "error" });
+                return;
+            }
+            handle.aborting = false;
+            let interrupted = false;
+            let providerError = false;
+            let failed = null;
+            let settled = null;
+            let markSettled = null;
+            settled = new Promise((resolve) => {
+                markSettled = resolve;
+            });
+            // 订阅**按次**持有：steer 会并发再进一次 sendMessage，两轮各自摘自己的监听器
+            const off = handle.session.subscribe((event) => {
+                const mapped = mapSessionEvent(event);
+                if (mapped) {
+                    // provider 报错也要算「这一轮失败」：不能最后还发 turn_end: done
+                    if (mapped.type === "error")
+                        providerError = true;
+                    onEvent(mapped);
+                    return;
+                }
+                const record = asRecord(event);
+                if (record.type === "agent_settled") {
+                    interrupted = record.aborted === true || handle.aborting;
+                    markSettled?.();
+                }
+            });
+            handle.subscriptions.add(off);
+            try {
+                // 图片走 SDK 的 images 参数（视觉注入）；没有图片时不传，避免空数组影响提示词缓存
+                const images = messageOptions?.images?.map((image) => ({
+                    type: "image",
+                    data: image.data,
+                    mimeType: image.mimeType,
+                }));
+                // streamingBehavior 交给 pi 自己排队：steer = 打断当前轮插入，followUp = 等这轮结束
+                const promptOptions = {};
+                if (images && images.length > 0)
+                    promptOptions.images = images;
+                if (messageOptions?.streamingBehavior)
+                    promptOptions.streamingBehavior = messageOptions.streamingBehavior;
+                await handle.session.prompt(text, promptOptions);
+                // 等 settle：prompt() 返回后仍可能有收尾事件
+                await Promise.race([settled, new Promise((resolve) => setTimeout(resolve, 50))]);
+            }
+            catch (error) {
+                failed = {
+                    code: "engine.prompt_failed",
+                    message: error instanceof Error ? error.message : String(error),
+                };
+            }
+            finally {
+                off();
+                handle.subscriptions.delete(off);
+            }
+            if (failed) {
+                onEvent({ type: "error", code: failed.code, message: failed.message });
+                onEvent({ type: "turn_end", reason: "error" });
+                return;
+            }
+            onEvent({ type: "turn_end", reason: interrupted ? "interrupted" : providerError ? "error" : "done" });
+        },
+        async interrupt(sessionId) {
+            const handle = sessions.get(sessionId);
+            if (!handle)
+                return;
+            handle.aborting = true;
+            try {
+                await handle.session.abort();
+            }
+            catch (error) {
+                notice(`中断失败：${error instanceof Error ? error.message : String(error)}`);
+            }
+        },
+        async readTranscript(sessionId) {
+            const handle = sessions.get(sessionId);
+            if (!handle)
+                return [];
+            return handle.session.messages.map((message) => {
+                const record = asRecord(message);
+                const content = asRecord(record.content);
+                const text = typeof record.content === "string"
+                    ? record.content
+                    : Array.isArray(content)
+                        ? content
+                            .map((part) => {
+                            const item = asRecord(part);
+                            return typeof item.text === "string" ? item.text : "";
+                        })
+                            .join("")
+                        : "";
+                const role = record.role === "assistant" ? "assistant" : "user";
+                return { role, text, ts: typeof record.timestamp === "number" ? record.timestamp : Date.now() };
+            });
+        },
+        setApprovalHandler(handler) {
+            approvalHandler = handler;
+        },
+        async listModels(sessionId) {
+            // 模型注册表挂在会话的 modelRuntime 上：没有会话时给不出（界面在打开会话后才显示列表）
+            const handle = sessionId ? sessions.get(sessionId) : [...sessions.values()].at(-1);
+            const runtime = handle?.session
+                ?.modelRuntime;
+            if (!runtime?.getAvailable)
+                return [];
+            try {
+                const models = (await runtime.getAvailable());
+                const current = await this.currentModel?.(sessionId ?? "");
+                return models
+                    .map((model) => {
+                    const id = `${String(model.provider ?? "?")}/${String(model.id ?? "?")}`;
+                    return {
+                        id,
+                        label: String(model.name ?? model.id ?? id),
+                        ...(typeof model.baseUrl === "string" ? { baseUrl: model.baseUrl } : {}),
+                        ...(typeof model.api === "string" ? { api: model.api } : {}),
+                        current: current ? id === `${current.provider}/${current.model}` : false,
+                    };
+                })
+                    .sort((a, b) => Number(b.current) - Number(a.current) || a.id.localeCompare(b.id));
+            }
+            catch {
+                return [];
+            }
+        },
+        listThinkingLevels: thinking.listThinkingLevels,
+        getThinkingLevel: thinking.getThinkingLevel,
+        setThinkingLevel: thinking.setThinkingLevel,
+        async switchModel(sessionId, modelId) {
+            // ModelRuntime 上没有 find（那是 ModelRegistry 的方法）→ 从可用列表里自己匹配
+            const handle = sessions.get(sessionId);
+            const runtime = handle?.session
+                ?.modelRuntime;
+            if (!handle || !runtime?.getAvailable)
+                return false;
+            const [provider, ...rest] = modelId.split("/");
+            const wanted = rest.join("/");
+            const available = (await runtime.getAvailable());
+            const model = available.find((item) => String(item.provider) === provider && String(item.id) === wanted);
+            if (!model)
+                return false;
+            try {
+                await handle.session.setModel(model);
+                return true;
+            }
+            catch (error) {
+                options.onNotice?.(`切换模型失败：${error instanceof Error ? error.message : String(error)}`, "error");
+                return false;
+            }
+        },
+        async currentModel(sessionId) {
+            const handle = sessions.get(sessionId);
+            const model = handle?.session?.model;
+            if (!model)
+                return null;
+            return { provider: String(model.provider ?? "?"), model: String(model.id ?? "?") };
+        },
+        sessionModel: async (sessionId) => readSessionModel(sessions.get(sessionId)),
+        async closeSession(sessionId) {
+            const handle = sessions.get(sessionId);
+            if (!handle)
+                return;
+            handle.unsubscribe();
+            try {
+                handle.session.dispose();
+            }
+            catch {
+                // 已经关掉了
+            }
+            sessions.delete(sessionId);
+        },
+        /**
+         * 关会话：给了 id 就关那一个；**不给就是引擎级 dispose（切引擎时宿主就是这么调的）**，
+         * 把所有会话一起关掉。以前这个签名必填 sessionId，宿主 `dispose?.()` 传空 →
+         * `sessions.get(undefined)` 什么也没关，每切一次引擎就漏一批 SDK 会话与资源加载器。
+         */
+        async dispose(sessionId) {
+            const ids = sessionId ? [sessionId] : [...sessions.keys()];
+            for (const id of ids) {
+                const handle = sessions.get(id);
+                if (!handle)
+                    continue;
+                handle.unsubscribe();
+                try {
+                    handle.session.dispose();
+                }
+                catch {
+                    // 已经关掉了
+                }
+                sessions.delete(id);
+            }
+        },
+    };
+}

package/dist/server/engine/pi-session-model.js

@@ -0,0 +1,23 @@
+/**
+ * 「这个会话持久化的是哪个模型」——读会话条目里**最后一条** `model_change`。
+ *
+ * 为什么不用 SDK 的 `session.model`：续聊历史会话时它常常还是进程默认模型，
+ * 界面就会显示成「别的模型」，看起来像「选了模型没生效」（真实踩过）。
+ * 为什么会话文件里是这个：用户在模型选择器上切换时 SDK 就写一条 `model_change`，
+ * 所以它既是「当前模型」也是「下次续聊用的模型」。
+ */
+export function readSessionModel(handle) {
+    const entries = handle?.sessionManager?.getEntries?.() ?? [];
+    // 倒着找：追加式文件，最后一条就是当前生效的
+    for (let index = entries.length - 1; index >= 0; index -= 1) {
+        const entry = entries[index];
+        if (entry?.type !== "model_change")
+            continue;
+        const modelId = typeof entry.modelId === "string" ? entry.modelId : "";
+        if (modelId === "")
+            continue;
+        const provider = typeof entry.provider === "string" ? entry.provider : "?";
+        return { provider, model: modelId };
+    }
+    return null;
+}

package/dist/server/engine/pi-thinking.js

@@ -0,0 +1,34 @@
+/**
+ * 思考强度（P4）——从 pi-sdk.ts 抽出来（400 行护栏）。
+ *
+ * 档位与 pi-ai 的 ThinkingLevelSchema 对齐；这个常量没对外导出，所以写死并在此注明。
+ * 模型不支持推理（model.reasoning !== true）时不提供档位 → 界面隐藏控件。
+ */
+const THINKING_LEVELS = ["minimal", "low", "medium", "high", "xhigh", "max"];
+export function createPiThinking(sessions) {
+    const pick = (sessionId) => (sessionId ? sessions.get(sessionId) : [...sessions.values()].at(-1))?.session;
+    return {
+        async listThinkingLevels(sessionId) {
+            const session = pick(sessionId);
+            if (!session?.model?.reasoning)
+                return [];
+            return [...THINKING_LEVELS];
+        },
+        async getThinkingLevel(sessionId) {
+            const level = pick(sessionId)?.thinkingLevel;
+            return typeof level === "string" ? level : null;
+        },
+        async setThinkingLevel(sessionId, level) {
+            const session = pick(sessionId);
+            if (!session?.setThinkingLevel)
+                return false;
+            try {
+                session.setThinkingLevel(level);
+                return session.thinkingLevel === level;
+            }
+            catch {
+                return false;
+            }
+        },
+    };
+}

package/dist/server/engine/pi-transcript.js

@@ -0,0 +1,225 @@
+/**
+ * 把 pi 会话的条目映射成界面消息（ADR-0021 §2：事实源换成 pi 的会话存储之后，
+ * 「显示」这件事就落在这个纯函数上）。
+ *
+ * 输入是 SDK 的 `SessionEntry[]`（我们只认识其中两种：
+ *   `{type:"message", id, timestamp, message}` 与其它状态条目——后者忽略）。
+ * 输出是我们的 `UiMessage[]`（text / tool / error 三类块）。
+ *
+ * 刻意**不 import SDK 类型**：只用最小结构描述（TS 里用 unknown + 收窄），
+ * 这样单测可以用合成条目直接覆盖，不需要拉起 SDK。
+ */
+import { TOOL_EXCERPT_CHARS } from "../protocol.js";
+import { fullArgs, summarizeArgs } from "./pi-events.js";
+import { sanitizeHistoricalActions } from "../markers/actions.js";
+import { parseUsage } from "../util/usage.js";
+import { scheduledCost } from "../util/pricing-index.js";
+function asRecord(value) {
+    return typeof value === "object" && value !== null ? value : {};
+}
+function textOfContent(content) {
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    return content
+        .map((part) => {
+        const record = asRecord(part);
+        return typeof record.text === "string" ? record.text : "";
+    })
+        .join("");
+}
+/** 工具结果里的退出码（不同工具的 details 形状不同，取不到就不给） */
+function exitCodeOf(details) {
+    const record = asRecord(details);
+    const value = record.exitCode ?? asRecord(record.structuredContent).exitCode;
+    return typeof value === "number" ? value : undefined;
+}
+function truncate(text) {
+    if (text.length <= TOOL_EXCERPT_CHARS)
+        return { outputExcerpt: text, truncated: false };
+    return { outputExcerpt: text.slice(0, TOOL_EXCERPT_CHARS), truncated: true };
+}
+/**
+ * 把一条 SDK message 转成「消息 + 其中的工具块」。
+ *
+ * 助手消息只是**一次模型调用**：一轮里有几次工具轮次就有几条。调用方会把同一轮里的
+ * 助手消息**合并成一条界面消息**（见 entriesToUiMessagesRaw）—— 界面上一次提问只该有一个
+ * 回复气泡，费用与 token 也要按整轮累加。
+ */
+function mapMessage(entryId, message, order) {
+    const record = asRecord(message);
+    const role = record.role;
+    const ts = typeof record.timestamp === "number" ? record.timestamp : Date.now();
+    if (role === "user") {
+        const text = textOfContent(record.content);
+        if (text.trim() === "")
+            return null;
+        return { id: entryId, role: "user", ts, blocks: [{ kind: "text", text }] };
+    }
+    if (role === "assistant") {
+        const usage = parseUsage(record.usage);
+        // 这条消息自己用的模型（历史按当时的模型显示，不跟当前选择变）
+        const provider = typeof record.provider === "string" ? record.provider : "";
+        const modelId = typeof record.model === "string" ? record.model : "";
+        const model = modelId ? (provider ? `${provider}/${modelId}` : modelId) : undefined;
+        const blocks = [];
+        const content = Array.isArray(record.content) ? record.content : [];
+        for (const part of content) {
+            const item = asRecord(part);
+            if (item.type === "text" && typeof item.text === "string" && item.text.trim() !== "") {
+                blocks.push({ kind: "text", text: item.text });
+                continue;
+            }
+            // 思考过程也回放出来（「过程」里要按发生顺序摆，历史里没有它就对不上）
+            if (item.type === "thinking" &&
+                typeof (item.thinking ?? item.text ?? item.reasoning) === "string" &&
+                String(item.thinking ?? item.text ?? item.reasoning).trim() !== "") {
+                blocks.push({ kind: "thinking", text: String(item.thinking ?? item.text ?? item.reasoning) });
+                continue;
+            }
+            if (item.type === "toolCall" || item.type === "tool_use") {
+                blocks.push({
+                    kind: "tool",
+                    toolCallId: String(item.id ?? `tool-${order}-${blocks.length}`),
+                    name: String(item.name ?? "unknown"),
+                    argsSummary: summarizeArgs(item.arguments),
+                    // 摘要被截断时带一份完整的：历史里展开也要看得见整条命令
+                    argsFull: fullArgs(item.arguments),
+                    // 结果在后面的条目里回填；此刻只表明「调用过」
+                    status: "ok",
+                    outputExcerpt: "",
+                    truncated: false,
+                    startedAt: ts,
+                });
+            }
+            // 其它部件（images 等）不进界面
+        }
+        if (blocks.length === 0)
+            return null;
+        // 分时价格（ADR-0026 D 期）：配了时段表就按这条消息的时间算钱，
+        // 不沿用会话里 pi 当时按全天价算出来的 cost（否则历史一会儿是旧价、一会儿是新价）
+        const priced = usage && model ? scheduledCost(model, usage, ts) : undefined;
+        const finalUsage = usage && priced !== undefined ? { ...usage, cost: priced } : usage;
+        return {
+            id: entryId,
+            role: "assistant",
+            ts,
+            blocks,
+            ...(finalUsage ? { usage: finalUsage } : {}),
+            ...(model ? { model } : {}),
+        };
+    }
+    return null; // system / toolResult 单独处理
+}
+/** 两段用量相加（一轮里多次模型调用 → 合计；cost 拿不到就不给，别编 0） */
+function addUsage(base, extra) {
+    const cost = (base?.cost ?? 0) + (extra.cost ?? 0);
+    return {
+        input: (base?.input ?? 0) + extra.input,
+        output: (base?.output ?? 0) + extra.output,
+        cacheRead: (base?.cacheRead ?? 0) + extra.cacheRead,
+        cacheWrite: (base?.cacheWrite ?? 0) + extra.cacheWrite,
+        ...(base?.cost === undefined && extra.cost === undefined ? {} : { cost }),
+    };
+}
+/**
+ * 纯函数：条目 → 界面消息。
+ * 工具结果按 `toolCallId` 回填到最近的对应工具块（找不到就补一条工具块，保证结果不丢）。
+ */
+export function entriesToUiMessages(entries) {
+    return sanitizeHistoricalActions(entriesToUiMessagesRaw(entries));
+}
+function entriesToUiMessagesRaw(entries) {
+    const messages = [];
+    /** toolCallId → 已经放进消息里的那个块（用于回填结果） */
+    const toolBlocks = new Map();
+    for (const [order, entry] of entries.entries()) {
+        const record = asRecord(entry);
+        if (record.type !== "message")
+            continue; // 状态类条目（model_change / thinking_level_change …）不进界面
+        const entryId = typeof record.id === "string" ? record.id : `entry-${order}`;
+        const message = asRecord(record.message);
+        if (message.role === "toolResult") {
+            const toolCallId = String(message.toolCallId ?? "");
+            const block = toolBlocks.get(toolCallId);
+            const { outputExcerpt, truncated } = truncate(textOfContent(message.content));
+            const failed = message.isError === true;
+            if (block) {
+                const exitCode = exitCodeOf(message.details);
+                block.status = failed ? "failed" : "ok";
+                block.outputExcerpt = outputExcerpt;
+                block.truncated = truncated;
+                block.endedAt = typeof message.timestamp === "number" ? message.timestamp : block.startedAt;
+                if (exitCode !== undefined)
+                    block.exitCode = exitCode;
+            }
+            else {
+                // 找不到对应调用（老会话里可能有）：补一条工具块，保证结果不丢
+                const exitCode = exitCodeOf(message.details);
+                const ts2 = typeof message.timestamp === "number" ? message.timestamp : Date.now();
+                messages.push({
+                    id: entryId,
+                    role: "assistant",
+                    ts: ts2,
+                    blocks: [
+                        {
+                            kind: "tool",
+                            toolCallId,
+                            name: String(message.toolName ?? "unknown"),
+                            argsSummary: "",
+                            status: failed ? "failed" : "ok",
+                            outputExcerpt,
+                            truncated,
+                            startedAt: ts2,
+                            endedAt: ts2,
+                            ...(exitCode === undefined ? {} : { exitCode }),
+                        },
+                    ],
+                });
+            }
+            continue;
+        }
+        const mapped = mapMessage(entryId, message, order);
+        if (!mapped)
+            continue;
+        // 同一轮里的助手消息合并成一条（工具轮次会有很多条）：界面上一次提问只有一个回复气泡，
+        // token / 费用也跟着累加 —— 否则历史里看到的是「每次模型调用各一条」，总数还得自己加。
+        const previous = messages.at(-1);
+        if (previous && previous.role === "assistant") {
+            previous.blocks = [...previous.blocks, ...mapped.blocks];
+            if (mapped.usage)
+                previous.usage = addUsage(previous.usage, mapped.usage);
+            if (mapped.model)
+                previous.model = mapped.model;
+            // 完成时间 = 这一轮最后一次模型调用的时间
+            previous.endedAt = mapped.ts;
+            for (const block of mapped.blocks) {
+                if (block.kind === "tool")
+                    toolBlocks.set(block.toolCallId, block);
+            }
+            continue;
+        }
+        messages.push(mapped);
+        for (const block of mapped.blocks) {
+            if (block.kind === "tool")
+                toolBlocks.set(block.toolCallId, block);
+        }
+    }
+    return messages;
+}
+/** 从条目里取「首条用户消息」当标题（侧栏用；扫描器也有一份同口径实现） */
+export function firstUserText(entries) {
+    for (const entry of entries) {
+        const record = asRecord(entry);
+        if (record.type !== "message")
+            continue;
+        const message = asRecord(record.message);
+        if (message.role !== "user")
+            continue;
+        const text = textOfContent(message.content).replace(/\s+/g, " ").trim();
+        if (text !== "")
+            return text;
+    }
+    return "";
+}

package/dist/server/engine/pi-version.js

@@ -0,0 +1,11 @@
+/**
+ * pi SDK 的版本号（界面抬头显示 `pi v1.3.0`）。
+ *
+ * 用 SDK 自己导出的 `VERSION`，不去读它的 package.json：那个包只导出 `import`/`.`，
+ * `require.resolve("…/package.json")` 会报 ERR_PACKAGE_PATH_NOT_EXPORTED。
+ * 单独一个文件是为了守住 ADR-0003（只有 server/engine 能碰 SDK）与 400 行护栏。
+ */
+import { VERSION } from "@earendil-works/pi-coding-agent";
+export function piSdkVersion() {
+    return typeof VERSION === "string" && VERSION.trim() !== "" ? VERSION.trim() : null;
+}

package/dist/server/engine/port.js

@@ -0,0 +1 @@
+export {};