oh-my-agent-web 0.4.0 → 0.5.0

package/README.md

@@ -79,7 +79,7 @@ oh-my-agent-web/
 │  ├─ index.ts          进程入口：路由、WS、静态产物、优雅退出
 │  ├─ cli.ts            agent-web / omaw 命令（start / stop / restart / status / upgrade）
 │  ├─ protocol.ts       WS 协议单源（前端通过 web/src/types.ts 复用类型）
-│  ├─ engine/           引擎适配层：pi（原生 SDK）/ codex / dsh / fake（测试）
+│  ├─ engine/           引擎适配层：pi（原生 SDK）/ codex / dsh / opencode（ACP）/ fake（测试）
 │  ├─ session/          会话运行时：切换、改名、删除、模型控制、审批桥
 │  ├─ sessions/         会话文件扫描（标题 / 模型 / 缓存）
 │  ├─ files/            文件树、预览、搜索、上传、git 分支
@@ -87,7 +87,8 @@ oh-my-agent-web/
 │  ├─ approval/         审批规则与作用域判断
 │  ├─ providers/        自定义 provider / 模型清单
 │  ├─ push/             Web Push
-│  └─ skills/           技能发现与启停
+│  ├─ skills/           技能发现与启停
+│  └─ subagents/        子代理模板（落 ~/.pi/agent/agents/*.md，与 pi 共用同一套）
 ├─ web/                 前端（React 19 + Vite）
 │  └─ src/
 │     ├─ components/    侧栏、消息流、输入框、文件树、终端、各类面板
@@ -103,10 +104,36 @@ oh-my-agent-web/
 | **pi**（默认） | 完整的插件 / 技能生态、工具延迟加载、审批门禁、目标模式与子代理；模型与 provider 由本工作台管理 |
 | **Codex** | codex 官方 agent，独立 loop 与沙箱，会话与 Codex Desktop / CLI 共用；审批是命令 / 文件级的 |
 | **DeepSeek Harness** | DeepSeek 官方 agent（ACP），模型与思考档可切，权限逐次确认 |
+| **opencode** | opencode 官方 agent（ACP），自带工具 / MCP / 插件生态，模型与思考档可切，会话与 opencode CLI / TUI 共用；**审批取决于 opencode 自身的 `permission` 配置**（配成全局 allow 时不会询问） |
 | **fake** | 零 token 的脚本化引擎，只用来验证协议 / 工具 / 审批流程（`AGENT_WEB_ENGINE=fake`，默认不进切换面板） |
 
 装没装的引擎不影响启动：只有切到它时才会报「没找到」。
 
+opencode 相关的环境变量（都有默认值，通常不用配）：
+
+| 变量 | 作用 |
+| --- | --- |
+| `AGENT_WEB_OPENCODE_BIN` | opencode 可执行文件路径（默认 PATH 里的 `opencode`） |
+| `AGENT_WEB_OPENCODE_ARGS` | 传给 `opencode acp` 的额外参数，空格分隔（例如 `--pure` 跳过外部插件） |
+| `AGENT_WEB_OPENCODE_MODEL` | 新会话优先用的模型（`provider/model`）；不设就沿用 opencode 自己的默认 |
+
+## 子代理（多开 + 可管理）
+
+pi 引擎带一套自己的子代理实现（**不依赖 pi-subagents 插件**）：
+
+- **怎么开**：主 Agent 拿到 `Agent` 工具（`subagent_type` / `prompt` / `description` / `run_in_background`），
+  一次可以并行开好几个；每次委派都是**一个真实的 pi 会话**（自己的上下文、会话文件、工具白名单）。
+- **在哪看**：运行卡片**就在对话下方**（输入区上方那条「子代理」卡片条）：状态、耗时、工具次数、token 与花费，点「查看结果」原地展开结果原文与会话文件路径，随时**停掉某一个**；
+  卡片条可折叠，切会话自动换成本会话的那批。顶栏「子代理」徽标保留一眼概览（几个在跑 / 合计花销），点开是小浮层。
+- **怎么管**：同一个面板只剩**模板**（内置 explore / general-purpose / plan，可停用；可新建 / 编辑 / 删除），运行记录不在面板里。
+  模板落 `~/.pi/agent/agents/*.md`，frontmatter 写 `name / description / tools / model / thinking / max_turns`，
+  正文就是子代理的系统指令 —— 与 pi / pi-web 的 agent 文件同一套格式，直接可读可改可进 git。
+- **并发**：面板右上角设上限（1–12，默认 4），超出的排队；总开关关掉后模型不再看到 `Agent` 工具。
+- **隔离**：子代理默认不加载技能 / 插件 / 主题 / 上下文文件（快、可预期）；模型不跟随父会话时会沿用父会话的模型。
+  有的模型由扩展注册 provider，这类模型在子代理里会失败并提示「在模板里指定模型」。
+
+子代理的会话文件紧挨着父会话归档（`<父会话目录>/<父会话名>/subagents/`），不进侧栏的项目清单。
+
 ## 安全模型
 
 - 默认只监听 `127.0.0.1`，并校验 `Origin` / `Host`；要远程访问必须显式给 `-H` + `-P` + `--allow-host`。

package/dist/server/engine/builtin.js

@@ -1,6 +1,7 @@
 import { createCodexEngine } from "./codex.js";
 import { createDshEngine } from "./dsh.js";
 import { createFakeEngine } from "./fake.js";
+import { createOpencodeEngine } from "./opencode.js";
 import { createPiSdkEngine } from "./pi-sdk.js";
 import { createEngineRegistry, FAKE_CAPABILITIES, PI_CAPABILITIES } from "./registry.js";
 export function createBuiltinEngineRegistry(options) {
@@ -47,6 +48,28 @@ export function createBuiltinEngineRegistry(options) {
                 },
             ]
             : []),
+        ...(options.opencode
+            ? [
+                {
+                    name: "opencode",
+                    label: "opencode",
+                    badge: "OC",
+                    // 如实写：审批能不能真的拦住，取决于 opencode 自己的权限配置（见 engine/opencode.ts 头注释）
+                    description: options.opencode.description ??
+                        "opencode 官方 agent（ACP）：自带工具与 MCP/插件生态，模型与思考档可切，会话与 opencode CLI / TUI 共用；审批取决于 opencode 自身 permission 配置",
+                    providerConfig: false,
+                    // 没有子代理面板（ACP 不暴露 task 子代理的运行视图）→ subagents 不写，界面就不出现那块
+                    capabilities: { approvals: true, tools: true, modelSwitch: true, thinkingLevel: true, resume: true },
+                    create: () => createOpencodeEngine({
+                        client: options.opencode?.client,
+                        bin: options.opencode?.bin,
+                        args: options.opencode?.args,
+                        model: options.opencode?.model,
+                        log: options.onLog,
+                    }),
+                },
+            ]
+            : []),
         {
             name: "fake",
             label: "假引擎",

package/dist/server/engine/jsonrpc-stdio.js

@@ -166,7 +166,7 @@ export function createJsonRpcStdioClient(options) {
                     else
                         env[key] = value;
                 }
-                const next = spawn(options.bin, options.args, { env, stdio: ["pipe", "pipe", "pipe"] });
+                const next = spawn(options.bin, options.args, { env, cwd: options.cwd, stdio: ["pipe", "pipe", "pipe"] });
                 child = next;
                 wire(next);
             }

package/dist/server/engine/narrate-guidance.js

@@ -0,0 +1,22 @@
+/**
+ * 教模型「动手之前先说人话」。
+ *
+ * 为什么必须有：对话区里的「过程」容器默认是**折叠**的 —— 用户一眼只看到
+ * 「1 段思考 1 次工具 过程 2 步」。模型要是连着调五个工具、一句正文都不写，
+ * 用户全程不知道它在查什么、改什么、碰到什么问题，只能干等。
+ *
+ * 所以：每一步动作前先给一两句「我发现了什么 / 我准备做什么」，
+ * 工具结果推翻计划时也说一句。界面侧同时有「正在运行 bash…」那行实时状态（见 LiveActivity），
+ * 两者合起来才是「看得懂在跑什么」。
+ *
+ * 同样写得短：这段会在**每一次**请求里重复计费。
+ */
+export const NARRATE_GUIDANCE = [
+    "## Narrate before acting",
+    "The user watches this conversation live, and tool cards are collapsed by default — they only see",
+    '"1 thinking segment, 1 tool call" unless you write prose. So:',
+    "- Before the first tool call of a task, write 1-2 sentences: what you found and what you are about to do.",
+    "- Before modifying, writing or deleting files, say which files and why (1-2 sentences), then call the tools.",
+    "- When a tool result changes your plan (failure, unexpected output, a discovery), say what it means before the next call.",
+    "- Keep it short and in the user's language; never paste tool arguments back as prose.",
+].join("\n");

package/dist/server/engine/opencode-map.js

@@ -0,0 +1,499 @@
+/**
+ * opencode ACP 的**纯映射**（不碰网络/子进程，单测直接覆盖）。
+ *
+ * 三件事：
+ *   1. `configOptions`（模型 / 思考档）→ 我们的模型下拉与档位；
+ *   2. `session/update` 通知 → 我们的 EngineEvent；
+ *   3. `session/request_permission` → 我们的审批请求 + 回包选项。
+ *
+ * 实测依据（opencode 1.19.0，`opencode acp`）：
+ *   - `session/new` 的 `configOptions` 有 2~3 项：
+ *       `{id:"model", category:"model"}`、
+ *       `{id:"effort", category:"thought_level"}`（**只有部分模型有**）、
+ *       `{id:"mode", category:"mode"}`（build / plan）。
+ *     所以「思考档」必须按 `category` 找，不能写死 id（dsh 那边叫 `reasoning_effort`）；
+ *     换成不支持推理的模型（如 deepseek-office/deepseek-flash）时该项会**整个消失**。
+ *   - 模型 value 是 `provider/model`，而 provider 自己也可能带斜杠
+ *     （`cloudflare-ai-gateway/anthropic/claude-opus-4.5`）→ 解析只切**第一个**斜杠。
+ *   - 工具是两段式：先来一条 `tool_call`（`title` 就是工具名 `bash`、`rawInput` 只有 `{cwd}`），
+ *     真正的命令在随后 `tool_call_update` 的 `title`/`rawInput` 里；`status` 走
+ *     pending → in_progress（可能多次）→ completed/failed。**所以 tool_start 要延迟到「有真参数」那一条**，
+ *     否则界面上卡片会先写着 `bash {"cwd":"…"}`，很误导。
+ *   - `completed` 的 update 带 `content[]` 与 `rawOutput{output, metadata{exit, truncated}}`（有时只有 status）。
+ *   - `session/prompt` 返回 `{stopReason, usage:{inputTokens, outputTokens, cachedReadTokens, thoughtTokens, totalTokens}}`
+ *     —— 有 input/output 分桶（比 dsh 只给 used/size 强）；`usage_update` 通知则**不稳定**
+ *     （同一个 opencode 版本，deepseek-office 的模型一次都没发），不能拿它算账。
+ *   - 权限请求带完整 `toolCall`（含 `rawInput`）+ 三个选项：
+ *     `{optionId:"once", kind:"allow_once"}` / `{optionId:"always", kind:"allow_always"}` / `{optionId:"reject", kind:"reject_once"}`。
+ */
+import { TOOL_EXCERPT_CHARS } from "../protocol.js";
+/** 把 configOptions 里可能分组的选项摊平（保留 group 名，便于显示） */
+export function flattenChoices(option) {
+    if (!option?.options)
+        return [];
+    const out = [];
+    for (const entry of option.options) {
+        if ("options" in entry && Array.isArray(entry.options)) {
+            for (const choice of entry.options)
+                out.push({ ...choice, group: choice.group ?? entry.group ?? entry.name });
+        }
+        else {
+            out.push(entry);
+        }
+    }
+    return out;
+}
+/** `provider/model` → { provider, model }；provider 本身可能带斜杠，所以只切第一刀 */
+export function parseModelValue(value) {
+    if (!value)
+        return null;
+    const index = value.indexOf("/");
+    if (index <= 0 || index === value.length - 1)
+        return null;
+    return { provider: value.slice(0, index), model: value.slice(index + 1) };
+}
+const modelOptionOf = (config) => (config ?? []).find((entry) => entry.category === "model" || entry.id === "model");
+export function modelOptions(config) {
+    const option = modelOptionOf(config);
+    const current = option?.currentValue;
+    const seen = new Set();
+    const models = [];
+    for (const choice of flattenChoices(option)) {
+        const id = choice.value;
+        if (!id || seen.has(id))
+            continue;
+        seen.add(id);
+        models.push({
+            id,
+            label: choice.name ?? id,
+            ...(id === current ? { current: true } : {}),
+        });
+    }
+    return models;
+}
+export function currentModelId(config) {
+    return modelOptionOf(config)?.currentValue ?? null;
+}
+/** 模型 id（就是 value 原文）→ ACP 需要的 value；不在列表里返回 null */
+export function modelValueFor(config, modelId) {
+    const option = modelOptionOf(config);
+    if (!option)
+        return null;
+    for (const choice of flattenChoices(option)) {
+        // label 也可能被当成 id 传进来（界面上显示的是 label），两种都认
+        if (choice.value === modelId || choice.name === modelId)
+            return choice.value;
+    }
+    return null;
+}
+/**
+ * 思考档那一项：按 `category: "thought_level"` 找（dsh 叫 reasoning_effort，opencode 叫 effort）。
+ * 不支持推理的模型没有这一项 → 返回 undefined，界面自动隐藏控件。
+ */
+export function thinkingOptionOf(config) {
+    return (config ?? []).find((entry) => entry.category === "thought_level" || entry.id === "effort" || entry.id === "reasoning_effort");
+}
+export function thinkingLevels(config) {
+    return flattenChoices(thinkingOptionOf(config))
+        .map((choice) => choice.value)
+        .filter((value) => typeof value === "string" && value !== "");
+}
+export function currentThinkingLevel(config) {
+    return thinkingOptionOf(config)?.currentValue ?? null;
+}
+/** 思考档位的 configId（切档位时用，随模型而变） */
+export function thinkingConfigId(config) {
+    return thinkingOptionOf(config)?.id ?? "effort";
+}
+/** 取 content 里的纯文本（两种形状都认：单块对象 / 内容数组） */
+export function textOfContent(content) {
+    if (content === undefined || content === null)
+        return "";
+    if (Array.isArray(content)) {
+        return content
+            .map((item) => {
+            const entry = item;
+            if (entry?.content?.type === "text")
+                return entry.content.text ?? "";
+            if (entry?.type === "text")
+                return entry.text ?? "";
+            return "";
+        })
+            .join("");
+    }
+    const single = content;
+    return single?.type === "text" ? (single.text ?? "") : "";
+}
+/** 正文 / 思考增量 → 事件；其余类型返回 null（工具与配置由引擎自己处理） */
+export function textEventOf(update) {
+    if (update.sessionUpdate === "agent_message_chunk") {
+        const text = textOfContent(update.content);
+        return text === "" ? null : { type: "text_delta", text };
+    }
+    if (update.sessionUpdate === "agent_thought_chunk") {
+        const text = textOfContent(update.content);
+        return text === "" ? null : { type: "thinking_delta", text };
+    }
+    return null;
+}
+/** opencode 的内置工具名：`title` 等于这些值时说明**还没**带上真参数，别急着开卡片 */
+const GENERIC_TITLES = new Set([
+    "bash",
+    "edit",
+    "write",
+    "read",
+    "multi-edit",
+    "multiedit",
+    "patch",
+    "grep",
+    "glob",
+    "list",
+    "ls",
+    "webfetch",
+    "task",
+    "todowrite",
+    "todoread",
+    "skill",
+]);
+/**
+ * 这条 update 是否已经「够格」开一张工具卡片。
+ *
+ * 判据：参数里有 `cwd` 之外的东西（bash 的真实命令 / edit 的路径），
+ * 或者 title 已经不是工具名本身（opencode 把 bash 的 title 设成命令原文）。
+ */
+export function hasUsableToolFacts(facts) {
+    const input = facts.rawInput;
+    if (input !== null && typeof input === "object") {
+        if (Object.keys(input).some((key) => key !== "cwd"))
+            return true;
+    }
+    const title = (facts.title ?? "").trim();
+    if (title === "")
+        return false;
+    return !GENERIC_TITLES.has(title.toLowerCase());
+}
+export function toolStartEvent(facts) {
+    const raw = facts.rawInput === undefined ? "" : safeJson(facts.rawInput);
+    return {
+        type: "tool_start",
+        toolCallId: facts.toolCallId,
+        name: (facts.title ?? "").trim() || facts.kind || "tool",
+        argsSummary: raw.length > 300 ? `${raw.slice(0, 300)}…` : raw,
+        argsFull: raw,
+    };
+}
+/** 工具收口：只有 completed / failed 才发（in_progress 是过程态） */
+export function isFinalToolStatus(status) {
+    return status === "completed" || status === "failed" || status === "error" || status === "cancelled";
+}
+export function toolEndEvent(update) {
+    const raw = update.rawOutput?.output;
+    const output = typeof raw === "string" ? raw : textOfContent(update.content);
+    const exit = update.rawOutput?.metadata?.exit;
+    return {
+        type: "tool_end",
+        toolCallId: update.toolCallId ?? "opencode-tool",
+        status: update.status === "completed" ? "ok" : "failed",
+        output,
+        ...(typeof exit === "number" ? { exitCode: exit } : {}),
+    };
+}
+function safeJson(value) {
+    try {
+        return JSON.stringify(value) ?? "";
+    }
+    catch {
+        return String(value);
+    }
+}
+/** ACP stopReason → 我们的回合结束原因（与 dsh 同口径） */
+export function stopReasonToTurnEnd(reason) {
+    if (reason === "cancelled")
+        return "interrupted";
+    if (reason === "refusal")
+        return "error";
+    return "done"; // end_turn / max_tokens / max_turn_requests：这轮确实结束了
+}
+/**
+ * prompt 结果里的 usage → 我们的用量事件。
+ *
+ * `final: true`：这是**这一次模型调用**的最终值，宿主按轮累加（一轮里可能多次调用）。
+ * `cacheWrite` opencode 不单独给（写缓存并进 input 计费），留 0 而不是瞎猜。
+ */
+export function usageEventOf(result) {
+    const usage = result?.usage;
+    if (!usage)
+        return null;
+    const input = Number(usage.inputTokens ?? 0);
+    const output = Number(usage.outputTokens ?? 0);
+    const cacheRead = Number(usage.cachedReadTokens ?? 0);
+    if (input === 0 && output === 0 && cacheRead === 0)
+        return null;
+    return { type: "usage", input, output, cacheRead, cacheWrite: 0, final: true };
+}
+// ---------------------------------------------------------------------------
+// 权限请求
+// ---------------------------------------------------------------------------
+/**
+ * 权限请求 → 我们的审批请求。
+ *
+ * opencode 的请求体自带 `toolCall.rawInput`（命令原文），所以不像 dsh 那样要靠
+ * `rememberToolCall` 补全；`toolFacts` 只用于兜底。
+ */
+export function permissionApprovalRequest(request, tool) {
+    const title = request.toolCall?.title ?? tool?.title ?? "opencode 工具调用";
+    const args = request.toolCall?.rawInput ?? tool?.rawInput;
+    const summary = args === undefined ? "" : safeJson(args);
+    const clipped = summary.length > 300 ? `${summary.slice(0, 300)}…` : summary;
+    const kind = request.toolCall?.kind ?? tool?.kind ?? "";
+    return {
+        toolName: title,
+        argsSummary: clipped,
+        scopeKey: `opencode|${title}`,
+        scopeHint: title,
+        riskNote: kind === "execute"
+            ? "opencode 请求执行这条命令；是否放行由你决定"
+            : "opencode 请求执行这个操作；是否放行由你决定",
+    };
+}
+/** 我们的三态 → 权限选项 id（优先按 kind 匹配，其次按 optionId 猜） */
+export function permissionOptionId(options, decision) {
+    const list = options ?? [];
+    const byKind = (kinds) => {
+        for (const kind of kinds) {
+            const hit = list.find((option) => option.kind === kind);
+            if (hit)
+                return hit.optionId;
+        }
+        return null;
+    };
+    const picked = decision === "deny"
+        ? (byKind(["reject_once", "reject_always"]) ??
+            list.find((option) => /reject|deny|cancel/i.test(option.optionId))?.optionId)
+        : (byKind(decision === "always" ? ["allow_always", "allow_once"] : ["allow_once", "allow_always"]) ??
+            list.find((option) => /allow|accept|approve/i.test(option.optionId))?.optionId);
+    return picked ?? list[0]?.optionId ?? (decision === "deny" ? "reject" : "once");
+}
+const textPartsOf = (message, type) => (message.parts ?? [])
+    .filter((part) => part.type === type && typeof part.text === "string")
+    .map((part) => part.text ?? "")
+    .join("");
+/** 工具输出可能放在 `state.output`（字符串）或数组里 */
+function outputTextOf(value) {
+    if (typeof value === "string")
+        return value;
+    if (Array.isArray(value))
+        return textOfContent(value);
+    if (value && typeof value === "object") {
+        const record = value;
+        if (typeof record.output === "string")
+            return record.output;
+        const inner = textOfContent(record.content);
+        if (inner !== "")
+            return inner;
+        if (typeof record.text === "string")
+            return record.text;
+    }
+    return "";
+}
+/**
+ * export JSON → 对话区消息（历史回放）。
+ *
+ * 工具块状态直接取 `state.status`（completed → ok，error → failed），
+ * 还在跑的（导出时被中断）标 failed，不能留在 running 上骗人。
+ */
+export function exportToUiMessages(exported) {
+    const messages = [];
+    for (const message of exported?.messages ?? []) {
+        const info = message.info ?? {};
+        const createdAt = info.time?.created;
+        const ts = typeof createdAt === "number" ? createdAt : 0;
+        const id = info.id ?? `m-${messages.length}`;
+        if (info.role === "user") {
+            const text = textPartsOf(message, "text");
+            if (text.trim() === "")
+                continue;
+            messages.push({ id: `u-${id}`, role: "user", ts, blocks: [{ kind: "text", text }] });
+            continue;
+        }
+        if (info.role !== "assistant")
+            continue;
+        const blocks = [];
+        for (const part of message.parts ?? []) {
+            if (part.type === "reasoning" && typeof part.text === "string" && part.text !== "") {
+                blocks.push({ kind: "thinking", text: part.text });
+                continue;
+            }
+            if (part.type === "text" && typeof part.text === "string" && part.text !== "") {
+                blocks.push({ kind: "text", text: part.text });
+                continue;
+            }
+            if (part.type === "tool") {
+                const state = part.state ?? {};
+                const rawInput = state.input === undefined ? "" : safeJson(state.input);
+                const output = outputTextOf(state.output);
+                const clipped = output.length > TOOL_EXCERPT_CHARS ? `${output.slice(0, TOOL_EXCERPT_CHARS)}…` : output;
+                const exit = state.metadata?.exit;
+                const status = state.status === "completed"
+                    ? "ok"
+                    : state.status === "error" || state.status === "failed"
+                        ? "failed"
+                        : "failed";
+                blocks.push({
+                    kind: "tool",
+                    toolCallId: part.callID ?? `tool-${id}-${blocks.length}`,
+                    name: (state.title ?? part.tool ?? "tool").trim() || part.tool || "tool",
+                    argsSummary: rawInput.length > 300 ? `${rawInput.slice(0, 300)}…` : rawInput,
+                    argsFull: rawInput,
+                    status,
+                    outputExcerpt: clipped,
+                    truncated: output.length > TOOL_EXCERPT_CHARS,
+                    startedAt: typeof state.time?.start === "number" ? state.time.start : ts,
+                    endedAt: typeof state.time?.end === "number" ? state.time.end : ts,
+                    ...(typeof exit === "number" ? { exitCode: exit } : {}),
+                });
+            }
+        }
+        if (blocks.length === 0)
+            continue;
+        const tokens = info.tokens;
+        const endedAt = info.time?.completed;
+        messages.push({
+            id: `a-${id}`,
+            role: "assistant",
+            ts,
+            endedAt: typeof endedAt === "number" ? endedAt : ts,
+            blocks,
+            ...(info.providerID && info.modelID ? { model: `${info.providerID}/${info.modelID}` } : {}),
+            ...(tokens
+                ? {
+                    usage: {
+                        input: tokens.input ?? 0,
+                        output: tokens.output ?? 0,
+                        cacheRead: tokens.cache?.read ?? 0,
+                        cacheWrite: tokens.cache?.write ?? 0,
+                        ...(typeof info.cost === "number" ? { cost: info.cost } : {}),
+                    },
+                }
+                : {}),
+        });
+    }
+    return messages;
+}
+/** export JSON → 引擎转录（只留正文） */
+export function exportToTranscript(exported) {
+    const out = [];
+    for (const message of exported?.messages ?? []) {
+        const role = message.info?.role;
+        if (role !== "user" && role !== "assistant")
+            continue;
+        const text = textPartsOf(message, "text");
+        if (text.trim() === "")
+            continue;
+        const created = message.info?.time?.created;
+        out.push({ role, text, ts: typeof created === "number" ? created : 0 });
+    }
+    return out;
+}
+/**
+ * 这份导出里最后一条 assistant 是不是「还没记账」？
+ *
+ * 用在哪里：回合刚结束那一瞬间 `opencode export` 可能已经看得到消息、却**还没有 tokens**
+ * （实测会出现 `tokens:{}` 的行）—— 拿它算账会得到「消息数新、token 是上一轮的」这种半截数字。
+ * 所以统计遇到 pending 就再等一帧重读，而不是把这个中间态写进面板。
+ */
+export function hasPendingUsage(exported) {
+    const assistants = (exported?.messages ?? []).filter((message) => message.info?.role === "assistant");
+    const last = assistants.at(-1);
+    if (!last)
+        return true; // 连 assistant 都没有：这一轮肯定还没落完
+    const tokens = last.info?.tokens;
+    if (!tokens)
+        return true;
+    const sum = (tokens.total ?? 0) +
+        (tokens.input ?? 0) +
+        (tokens.output ?? 0) +
+        (tokens.cache?.read ?? 0) +
+        (tokens.cache?.write ?? 0);
+    return sum === 0;
+}
+/**
+ * export JSON → 会话统计。
+ *
+ * 四桶用量来自每条 assistant 的 `info.tokens`（opencode 自己按次记账），
+ * 上下文占用取「最后一条 assistant 的 input + cache.read」（近似"当前上下文多大"）。
+ */
+export function exportStats(exported) {
+    const stats = {
+        userMessages: 0,
+        assistantMessages: 0,
+        toolCalls: 0,
+        toolResults: 0,
+        totalMessages: 0,
+        inputTokens: 0,
+        outputTokens: 0,
+        cacheRead: 0,
+        cacheWrite: 0,
+        totalTokens: 0,
+        contextTokens: 0,
+    };
+    for (const message of exported?.messages ?? []) {
+        const role = message.info?.role;
+        if (role === "user") {
+            stats.userMessages += 1;
+            stats.totalMessages += 1;
+            continue;
+        }
+        if (role !== "assistant")
+            continue;
+        stats.assistantMessages += 1;
+        stats.totalMessages += 1;
+        for (const part of message.parts ?? []) {
+            if (part.type !== "tool")
+                continue;
+            stats.toolCalls += 1;
+            const status = part.state?.status;
+            if (status === "completed" || status === "error" || status === "failed")
+                stats.toolResults += 1;
+        }
+        const tokens = message.info?.tokens;
+        if (!tokens)
+            continue;
+        const input = tokens.input ?? 0;
+        const cacheRead = tokens.cache?.read ?? 0;
+        const cacheWrite = tokens.cache?.write ?? 0;
+        const output = tokens.output ?? 0;
+        stats.inputTokens += input;
+        stats.outputTokens += output;
+        stats.cacheRead += cacheRead;
+        stats.cacheWrite += cacheWrite;
+        stats.totalTokens += tokens.total ?? input + output + cacheRead + cacheWrite;
+        // 最后一条 assistant 的输入侧 = 当前上下文占用
+        stats.contextTokens = input + cacheRead;
+    }
+    return stats;
+}
+// ---------------------------------------------------------------------------
+// 错误 → 人话
+// ---------------------------------------------------------------------------
+export function friendlyOpencodeError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (/ENOENT|spawn .* ENOENT|command not found/i.test(message)) {
+        return "没有找到 opencode 可执行文件：先安装它（`npm i -g opencode-ai`），或设 AGENT_WEB_OPENCODE_BIN 指向它";
+    }
+    // 顺序有讲究：opencode 的拒绝理由常是「Invalid params: <东西> not found」，「<东西>」
+    // 到底是思考档 / 模型 / 会话，决定了该给人哪一句 —— 所以先认具体的关键字。
+    if (/effort|thought_level|thoughtLevel|config option/i.test(message)) {
+        return "这个模型不支持该思考档位：换一个模型，或换回默认档";
+    }
+    if (/model not found|unknown model|model.*invalid|provider.*not found/i.test(message)) {
+        return "opencode 里没有这个模型路由：换一个模型（列表来自 opencode 自己的 provider 配置）";
+    }
+    if (/api key|credential|unauthorized|401|403|no provider|permission denied to use model/i.test(message)) {
+        return "这条模型没有凭据或额度：换一个模型，或在终端里跑 `opencode auth login`（本机 opencode 的凭据要单独登录）";
+    }
+    if (/unknown session|no such session|session not found|not found: ses_/i.test(message)) {
+        return "opencode 里找不到这条会话（可能已在 CLI / TUI 里删除）";
+    }
+    return message;
+}