oh-my-agent-web 0.7.0 → 1.0.2

package/dist/server/engine/codex-subagents.js

@@ -0,0 +1,349 @@
+/** 子代理 thread 的状态（`CollabAgentStatus`）→ 面板的三态 */
+function statusOfAgentState(status) {
+    switch (status) {
+        case "running":
+        case "pendingInit":
+            return "running";
+        case "completed":
+            return "completed";
+        case "interrupted":
+        case "shutdown":
+            return "aborted";
+        case "errored":
+            return "failed";
+        default:
+            return null;
+    }
+}
+/**
+ * 模板 id → codex 的 agent 类型名。
+ *
+ * codex 要求小写字母 / 数字 / 下划线（`spawn_agent` 的 `task_name` 是同一套规则），
+ * 我们的模板 id 里带连字符（`general-purpose`），所以映射一次。
+ */
+function agentTypeId(id) {
+    const cleaned = id
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "_")
+        .replace(/^_+|_+$/g, "");
+    return cleaned === "" ? "subagent" : cleaned;
+}
+/** `agentPath` 的最后一段就是模型给这次任务起的名字（`/root/directory_inventory`） */
+function taskNameOf(agentPath, fallback) {
+    const last = (agentPath ?? "")
+        .split("/")
+        .filter((part) => part !== "")
+        .pop();
+    if (!last)
+        return fallback;
+    const pretty = last.replace(/[_-]+/g, " ").trim();
+    return pretty === "" ? fallback : pretty.charAt(0).toUpperCase() + pretty.slice(1);
+}
+/**
+ * `subAgentActivity` → 增量。
+ *
+ * 文案全从引擎给的原话里取（`agentPath` / `model`），不自己编。
+ */
+function activityPatch(item, at) {
+    const threadId = typeof item.agentThreadId === "string" ? item.agentThreadId : "";
+    if (threadId === "")
+        return null;
+    const base = { threadId, label: taskNameOf(item.agentPath, threadId.slice(0, 8)) };
+    if (typeof item.model === "string" && item.model !== "")
+        base.model = item.model;
+    switch (item.kind) {
+        case "started":
+            return { ...base, status: "running" };
+        case "interrupted":
+            return { ...base, status: "aborted", endedAt: at };
+        case "completed":
+            return { ...base, status: "completed", endedAt: at };
+        case "interacted":
+            // 只是有消息往来：状态不变（running 的子代理继续保持 running）
+            return { ...base, status: "running" };
+        default:
+            return base;
+    }
+}
+/**
+ * `collabAgentToolCall` → 增量（可能一次带来多个子 thread 的状态）。
+ *
+ * 只认 `agentsStates`：那是引擎对「这个子代理现在怎么样」的**权威回答**。
+ * `wait` 之类的工具调用状态不等于子代理状态（wait 结束了不代表子代理跑完）。
+ */
+function collabStatesPatch(item) {
+    const states = item.agentsStates ?? {};
+    const patches = [];
+    for (const [threadId, state] of Object.entries(states)) {
+        const status = statusOfAgentState(state?.status);
+        if (!status)
+            continue;
+        const message = typeof state?.message === "string" && state.message !== "" ? state.message : undefined;
+        patches.push({
+            threadId,
+            status,
+            ...(status === "failed" && message ? { error: message } : {}),
+            ...(status === "running" ? {} : {}),
+        });
+    }
+    /**
+     * spawn 那一刻把 prompt 记下来（面板上「让它干什么」有原文可看）。
+     *
+     * 注意：spawn item 的 `agentsStates` **不一定**已经有这个新 thread（我们实测到的是空对象），
+     * 所以要按 `receiverThreadIds` 补一条 patch —— 否则卡片上只剩「由 Codex 自己发起的委派」。
+     */
+    if (item.tool === "spawnAgent" && typeof item.prompt === "string" && item.prompt !== "") {
+        for (const threadId of item.receiverThreadIds ?? []) {
+            const found = patches.find((patch) => patch.threadId === threadId);
+            if (found) {
+                found.task = item.prompt;
+                continue;
+            }
+            patches.push({ threadId, status: "running", task: item.prompt });
+        }
+    }
+    return patches;
+}
+/**
+ * 模板 + 开关 → `thread/start` 的 `config`（**按会话生效**，不写用户全局配置）。
+ *
+ * `agents.<id>.description`：codex 会用这个 description 告诉模型「有哪些子代理类型可挑」；
+ * 具体的模型 / 上下文由 `spawn_agent` 自己的参数决定（我们不硬塞，否则模板会骗人）。
+ */
+export function codexMultiAgentConfig(input) {
+    const version = input.version ?? "v1";
+    const agents = {
+        // 实测：这个数字是「同时几个子代理」；模型被告知的是 数字 + 1（含它自己）
+        max_concurrent_threads_per_session: Math.max(1, Math.min(16, Math.round(input.concurrency))),
+    };
+    // `agents.<id>` 的「类型」只有 v2 认（v1 里所有子代理能力相同、没有类型可挑）
+    if (input.enabled && version === "v2") {
+        for (const profile of input.profiles) {
+            agents[agentTypeId(profile.id)] = {
+                description: `${profile.label}：${profile.description}`.trim(),
+            };
+        }
+    }
+    return {
+        features: { multi_agent: input.enabled, multi_agent_v2: input.enabled && version === "v2" },
+        agents,
+    };
+}
+/**
+ * 注入到**父会话** developer instructions 的委派说明。
+ *
+ * 只写 codex 真有的动作（`spawn_agent` 等），不写 pi 的 `Agent` 工具；也不假装
+ * 「一定会主动委派」——codex 默认策略是 `explicitRequestOnly`（用户明确要求才派）。
+ */
+export function codexSubagentGuidance(input) {
+    const typed = (input.version ?? "v1") === "v2";
+    if (!input.enabled || input.profiles.length === 0)
+        return null;
+    const types = input.profiles
+        .map((profile) => typed
+        ? `- ${agentTypeId(profile.id)}: ${profile.label} — ${profile.description}`
+        : `- ${profile.label}: ${profile.description}`)
+        .join("\n");
+    return [
+        "## Delegating to subagents",
+        "You can delegate with the collaboration tools: `spawn_agent` (create a sub-agent thread),",
+        "`send_message` / `followup_task` (talk to it again), `wait_agent`, `interrupt_agent`, `list_agents`.",
+        "The user watches these runs in the workspace's Agents panel and can stop them, so:",
+        "- Delegate only when the user (or AGENTS.md / skill instructions) explicitly asks for",
+        "  delegation or parallel work; do not spawn sub-agents on your own initiative.",
+        "- Give every spawn a short `task_name` (it becomes the card title) and a self-contained",
+        "  first message: the sub-agent cannot see this conversation unless you pass a full-history fork.",
+        "- When several parts are independent, spawn them one after another and then `wait_agent` once",
+        "  with all ids — do not poll in a loop.",
+        typed
+            ? "- Available sub-agent types (pass the id as `agent_type`, and restate its rules in the message):"
+            : "- Available delegation briefs — pick one and restate its rules in the `message` you send:",
+        types,
+        "- Always pass the task as the spawn `message`; a spawn without a message starts an agent with nothing to do.",
+        "- Never claim you cannot delegate: if a collaboration call fails, report the error text.",
+    ].join("\n");
+}
+/** 内存里最多留几条运行记录（与 pi 侧同一个数） */
+const MAX_RUNS = 60;
+/**
+ * codex 版 `SubagentEnginePort`：**只观测 + 停止**，不起子会话（委派是模型自己发起的）。
+ *
+ * `start()` 因此会报一句可读错误：面板上并没有「手动起一个子代理」的入口，
+ * 这条路径只有 pi 的 `Agent` 工具会走（见 pi-subagent-tool.ts）。
+ */
+export function createCodexSubagents(options) {
+    const now = options.now ?? (() => Date.now());
+    const runs = new Map();
+    const order = [];
+    const listeners = new Set();
+    let limit = 4;
+    let enabled = true;
+    const emit = (run) => {
+        for (const listener of listeners) {
+            try {
+                listener({ ...run });
+            }
+            catch {
+                // 宿主侧抛错不能打断引擎的事件流
+            }
+        }
+    };
+    /** 只留最近 N 条（跑一天的会话不该把内存堆满；面板本来就只显示当前会话的） */
+    const trim = () => {
+        while (order.length > MAX_RUNS) {
+            const oldest = order.shift();
+            if (!oldest)
+                break;
+            const state = runs.get(oldest);
+            if (state && state.view.status === "running") {
+                order.push(oldest); // 还在跑的不能删
+                break;
+            }
+            runs.delete(oldest);
+        }
+    };
+    const apply = (conversationId, patch) => {
+        const id = `codex:${patch.threadId}`;
+        const existing = runs.get(id);
+        if (!existing) {
+            const view = {
+                id,
+                conversationId,
+                // codex 不在运行视图里报告用了哪个模板：如实写「引擎自己委派的」
+                profile: "codex",
+                label: patch.label ?? patch.threadId.slice(0, 8),
+                description: patch.task ? patch.task.slice(0, 120) : "由 Codex 自己发起的委派",
+                status: patch.status ?? "running",
+                task: patch.task ?? "",
+                startedAt: now(),
+                ...(patch.model ? { model: patch.model } : {}),
+                ...(patch.status && patch.status !== "running" ? { endedAt: patch.endedAt ?? now() } : {}),
+                ...(patch.error ? { error: patch.error } : {}),
+            };
+            runs.set(id, { view, settled: view.status !== "running" });
+            order.push(id);
+            trim();
+            emit(view);
+            // 结束得很快的任务：补一次结果（子 thread 的最后一条 agent 消息）
+            if (view.status !== "running")
+                void fillResult(patch.threadId, view);
+            return;
+        }
+        const state = existing;
+        if (state.settled && patch.status === "running")
+            return; // 迟到的事件不改已结算的记录
+        const next = {
+            ...state.view,
+            // agentPath / prompt 是稳定的，后到的事件带了就以它为准（先到的那条常常只有 thread id）
+            ...(patch.label ? { label: patch.label } : {}),
+            ...(patch.task && state.view.task === "" ? { task: patch.task, description: patch.task.slice(0, 120) } : {}),
+            ...(patch.model ? { model: patch.model } : {}),
+            ...(patch.status ? { status: patch.status } : {}),
+            ...(patch.error ? { error: patch.error } : {}),
+        };
+        if (patch.status && patch.status !== "running") {
+            next.endedAt = patch.endedAt ?? now();
+            state.settled = true;
+        }
+        state.view = next;
+        emit(next);
+        if (state.settled && next.result === undefined && next.status === "completed") {
+            void fillResult(patch.threadId, next);
+        }
+    };
+    /**
+     * 子代理的最终答复不在 collab item 里（那是「工具调用」的元数据）→ 结束前读一次子 thread 的
+     * 最后一条 agent 消息。读不到就算了：卡片上没有结果正文，比编一段强。
+     */
+    async function fillResult(threadId, view) {
+        try {
+            const listed = await options.request("thread/turns/list", { threadId, limit: 4, sortDirection: "desc" }, { timeoutMs: 15_000 });
+            const turns = listed?.data ?? [];
+            // 子代理自己的第一条 user 消息就是「你让它干什么」：派活时 codex 没把 prompt 放进 item，
+            // 只能从子 thread 里读回来（读不到就算了，卡片上没有任务原文，比编一段强）。
+            let task;
+            for (const turn of [...turns].reverse()) {
+                const first = (turn.items ?? []).find((item) => item.type === "userMessage");
+                const text = (first?.content ?? [])
+                    .map((part) => part.text ?? "")
+                    .join("")
+                    .trim();
+                if (text !== "") {
+                    task = text;
+                    break;
+                }
+            }
+            for (const turn of turns) {
+                const message = (turn.items ?? []).filter((item) => item.type === "agentMessage").pop();
+                if (message?.text) {
+                    const state = runs.get(view.id);
+                    if (state) {
+                        state.view = {
+                            ...state.view,
+                            result: message.text.slice(0, 4000),
+                            ...(task && state.view.task === "" ? { task, description: task.slice(0, 120) } : {}),
+                        };
+                        emit(state.view);
+                    }
+                    return;
+                }
+            }
+        }
+        catch (error) {
+            options.log?.(`codex：读子代理结果失败（${threadId.slice(0, 8)}）：${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    return {
+        concurrency: () => limit,
+        enabled: () => enabled,
+        setEnabled: (value) => {
+            enabled = value;
+        },
+        ingest(conversationId, item) {
+            if (item.type === "subAgentActivity") {
+                const patch = activityPatch(item, now());
+                if (patch)
+                    apply(conversationId, patch);
+                return;
+            }
+            for (const patch of collabStatesPatch(item))
+                apply(conversationId, patch);
+        },
+        async start(_request) {
+            throw new Error("codex 的委派由引擎自己发起：在对话里明确要求它委派子代理即可（面板只负责展示与停止）");
+        },
+        async interrupt(runId) {
+            const state = runs.get(runId);
+            if (!state)
+                return;
+            const threadId = runId.replace(/^codex:/, "");
+            try {
+                // 子代理是一个 thread：找到它正在跑的那一轮，再打断
+                const listed = await options.request("thread/turns/list", { threadId, limit: 1, sortDirection: "desc" }, { timeoutMs: 15_000 });
+                const turnId = listed?.data?.[0]?.id;
+                if (!turnId)
+                    return;
+                await options.request("turn/interrupt", { threadId, turnId });
+            }
+            catch (error) {
+                options.log?.(`codex：停止子代理失败：${error instanceof Error ? error.message : String(error)}`);
+            }
+        },
+        get(runId) {
+            return runs.get(runId)?.view ?? null;
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        setConcurrency(next) {
+            limit = Math.max(1, Math.min(16, Math.round(next)));
+        },
+        dispose() {
+            listeners.clear();
+            runs.clear();
+            order.length = 0;
+        },
+    };
+}

package/dist/server/engine/codex.js

@@ -1,17 +1,75 @@
 import { friendlyCodexError, itemsToTranscript, itemsToUiMessages, mapModels, thinkingLevelsOf, toolEndOf, toolStartOf, turnTs, } from "./codex-map.js";
 import { createCodexClient } from "./codex-transport.js";
+import { codexMultiAgentConfig, codexSubagentGuidance, createCodexSubagents } from "./codex-subagents.js";
 import { registerCodexApprovals } from "./codex-approvals.js";
 import { sanitizeHistoricalActions } from "../markers/actions.js";
+import { suggestionGuidance } from "./suggestion-guidance.js";
 import { ensureCodexProject } from "./codex-sessions.js";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+/**
+ * 探针提示词。
+ *
+ * 为什么不是「回一个字」：只出 1~3 个 token 时，生成窗口只有几十毫秒，
+ * 算出来的 tok/s 全是小数点后的噪声（实测 3 token / 42ms = 71 tok/s，毫无参考价值）。
+ * 让它出 20 个数字：输出约 20~40 token，生成窗口有几百毫秒，速度才有意义；
+ * 代价仍然只有几分钱量级。
+ */
+const PROBE_PROMPT = "Print the numbers 1 to 20 separated by spaces. Nothing else.";
+/** 探针墙钟上限：超了就中断并报「超时」，不能让按钮一直转 */
+const PROBE_TIMEOUT_MS = 60_000;
+/** 低于这个输出量不报 tok/s（样本太短，算出来只是噪声） */
+const MIN_TOKENS_FOR_TPS = 5;
+/**
+ * 生成窗口至少这么长才报「生成速度」。
+ *
+ * 踩过的坑：deepseek-flash 出 40 个 token 只用了 145ms（delta 是攒包过来的），
+ * 算出来 276 tok/s —— 谁都知道这不可能是真的。窗口太短就只给端到端均速。
+ */
+const MIN_GENERATION_MS_FOR_TPS = 500;
+/** 探针 thread 的 cwd：临时目录（`isScratchCwd` 判定 → 不会污染侧栏的项目列表），跑完连目录一起删 */
+const PROBE_CWD_PREFIX = "agent-web-probe-";
+/**
+ * 一次测速的收尾算术（纯函数）。
+ *
+ * 出字速度按「首字节之后到收尾」这段算：把排队 / 长思考之前的等待扣除，
+ * 才是模型真正的生成速度（TTFT 单独给你看）。
+ */
+function probeMetrics(probe, endedAt) {
+    const totalMs = Math.max(0, endedAt - probe.startedAt);
+    const ttftMs = probe.firstAt === null ? null : Math.max(0, probe.firstAt - probe.startedAt);
+    const generationMs = probe.firstAt === null ? totalMs : Math.max(1, endedAt - probe.firstAt);
+    const enoughTokens = probe.outputTokens >= MIN_TOKENS_FOR_TPS;
+    // 生成速度：只在那段窗口够长时才算（否则攒包会把数字抬成假的几百 tok/s）
+    const tps = enoughTokens && generationMs >= MIN_GENERATION_MS_FOR_TPS
+        ? Math.round((probe.outputTokens / generationMs) * 10_000) / 10
+        : null;
+    // 端到端均速：窗口短的时候靠它兜底（含首字延迟，不美化）
+    const averageTps = enoughTokens && totalMs > 0 ? Math.round((probe.outputTokens / totalMs) * 10_000) / 10 : null;
+    return { ok: true, ttftMs, totalMs, outputTokens: probe.outputTokens, tps, averageTps };
+}
 export function createCodexEngine(options = {}) {
     const client = options.client ?? createCodexClient({ bin: options.bin, home: options.home, log: options.log ?? (() => { }) });
     const bindings = new Map();
     const byThread = new Map();
     const active = new Map();
+    /** threadId → 探针：测速用的临时 thread 不映射到任何会话，事件走这条支线 */
+    const probes = new Map();
     let models = null;
     let approvalHandler = null;
     /** 最近一次可预期失败的原因（给界面用，见 EnginePort.lastError） */
     let lastError = null;
+    /**
+     * codex 的原生子代理：我们只**观测 + 停止**（委派由模型自己发起），
+     * 见 codex-subagents.ts 文件头（含实测依据）。
+     */
+    const subagents = createCodexSubagents({
+        request: (method, params, requestOptions) => client.request(method, params, requestOptions),
+        log: (text) => options.log?.(text),
+    });
+    /** 现读策略：面板改了模板 / 开关，**下一条**新建的会话立刻生效（老会话保持原样） */
+    const policy = () => options.subagentPolicy?.() ?? { enabled: false, concurrency: subagents.concurrency(), profiles: [] };
     const threadOf = (sessionId) => {
         const binding = bindings.get(sessionId);
         if (binding)
@@ -32,9 +90,72 @@ export function createCodexEngine(options = {}) {
         models = result?.data ?? [];
         return models;
     };
+    /**
+     * 把 codex 的**多代理 item** 喂给子代理观测器（面板的运行卡片就是它来的）。
+     *
+     * 只在这条 item 属于某个会话时喂：`senderThreadId` 反查宿主会话；
+     * 反查不到（比如历史 thread）就丢掉 —— 面板只显示当前会话的子代理。
+     */
+    const ingestSubagent = (conversationId, item) => {
+        const type = item.type;
+        if (type !== "collabAgentToolCall" && type !== "subAgentActivity")
+            return;
+        // item 自己带 senderThreadId；没有就用当前通知的 threadId 反查到的会话
+        const sender = item.senderThreadId;
+        const owner = conversationId ?? (sender ? byThread.get(sender) : undefined);
+        if (!owner)
+            return;
+        subagents.ingest(owner, item);
+    };
+    /**
+     * 测速支线：只做三件事 —— 记首字节时刻、记输出 token、等回合收尾。
+     * 报错一律转成一句人话（不抛，否则会把探针 Promise 挂死）。
+     */
+    const handleProbeNotification = (probe, notification) => {
+        const params = notification.params;
+        switch (notification.method) {
+            case "item/agentMessage/delta":
+            case "item/reasoning/textDelta":
+            case "item/reasoning/summaryTextDelta":
+                if (probe.firstAt === null)
+                    probe.firstAt = Date.now();
+                return;
+            case "thread/tokenUsage/updated": {
+                const last = params.tokenUsage?.last;
+                if (typeof last?.outputTokens === "number")
+                    probe.outputTokens = last.outputTokens;
+                return;
+            }
+            case "turn/completed": {
+                const status = params.turn?.status;
+                if (status === "failed") {
+                    probe.resolve({ ok: false, message: "codex 这一轮失败了（模型不可用或额度已尽）" });
+                    return;
+                }
+                probe.resolve(probeMetrics(probe, Date.now()));
+                return;
+            }
+            case "error": {
+                // willRetry=true 是 codex 内部的瞬时重试：不要当失败
+                if (params.willRetry === true)
+                    return;
+                const error = params.error;
+                probe.resolve({ ok: false, message: friendlyCodexError(new Error(error?.message ?? "codex 报错")) });
+                return;
+            }
+            default:
+                return;
+        }
+    };
     const handleNotification = (notification) => {
         const params = notification.params;
         const threadId = typeof params.threadId === "string" ? params.threadId : "";
+        // 测速的临时 thread 先认领：它不参与对话，事件只用来计时，绝不能串到任何会话里
+        const probe = threadId ? probes.get(threadId) : undefined;
+        if (probe) {
+            handleProbeNotification(probe, notification);
+            return;
+        }
         const conversationId = byThread.get(threadId);
         const turn = conversationId ? active.get(conversationId) : undefined;
         const emit = (event) => {
@@ -50,13 +171,17 @@ export function createCodexEngine(options = {}) {
                 emit({ type: "thinking_delta", text: typeof params.delta === "string" ? params.delta : "" });
                 return;
             case "item/started": {
-                const event = toolStartOf((params.item ?? {}));
+                const item = (params.item ?? {});
+                ingestSubagent(conversationId, item);
+                const event = toolStartOf(item);
                 if (event)
                     emit(event);
                 return;
             }
             case "item/completed": {
-                const event = toolEndOf((params.item ?? {}));
+                const item = (params.item ?? {});
+                ingestSubagent(conversationId, item);
+                const event = toolEndOf(item);
                 if (event)
                     emit(event);
                 return;
@@ -144,13 +269,42 @@ export function createCodexEngine(options = {}) {
     };
     return {
         client,
+        subagents,
         version: () => client.version(),
         async createSession(sessionOptions) {
             // 对齐原生：新会话落在 codex 的 project 里（没有就建一个，幂等键按目录）
             const projectId = await ensureCodexProject(client, sessionOptions.workspace);
+            /**
+             * 子代理（多代理）**按会话**开启：
+             *   - `config.agents.*` / `features.multi_agent*` 是 `thread/start` 的按 thread 覆盖，
+             *     所以模板与并发上限只对这条会话生效 —— 不写用户全局 config，Codex Desktop 不受影响；
+             *   - `developerInstructions` 里告诉模型「有哪些子代理类型、什么时候该派活」。
+             * 关掉时同样只影响这条会话：模型干脆没有 spawn 工具（而不是有个调不通的）。
+             */
+            const plan = policy();
             const response = await client.request("thread/start", {
                 cwd: sessionOptions.workspace,
                 ...(projectId ? { projectId } : {}),
+                config: codexMultiAgentConfig({
+                    enabled: plan.enabled,
+                    concurrency: plan.concurrency,
+                    profiles: plan.enabled
+                        ? plan.profiles.map((profile) => ({
+                            id: profile.id,
+                            label: profile.label,
+                            description: profile.description,
+                        }))
+                        : [],
+                }),
+                // 「下一步建议」的写法一直带（ADR-0022，否则 codex 永远出不了建议按钮）；
+                // 开了子代理就把委派说明接在后面。两者都是 **thread 级**覆盖，
+                // 只对这条新会话生效 —— 不写用户的 `~/.codex/config.toml`，Codex Desktop 不受影响。
+                developerInstructions: [
+                    suggestionGuidance(options.thinkCount?.() ?? null),
+                    codexSubagentGuidance({ enabled: plan.enabled, profiles: plan.profiles }),
+                ]
+                    .filter((part) => part !== null)
+                    .join("\n\n"),
             });
             const threadId = response?.thread?.id;
             if (!threadId)
@@ -244,6 +398,7 @@ export function createCodexEngine(options = {}) {
             byThread.clear();
             active.clear();
             models = null;
+            subagents.dispose?.();
             client.close();
         },
         setApprovalHandler(handler) {
@@ -259,6 +414,64 @@ export function createCodexEngine(options = {}) {
         async listModels() {
             return mapModels(await loadModels());
         },
+        /**
+         * 测速 = 在临时目录里开一个一次性 thread，发一句 `ping`，量首字节与出字速度。
+         *
+         * 为什么不拿 `~/.codex/auth.json` 去发 HTTP：那是偷凭证（见 port.ts 里的注释），
+         * 而且 ChatGPT 订阅额度的请求路径跟 API key 不是一回事，版本一变就坏。
+         * 这里用的全是本工具已在用的方法（thread/start → settings/update → turn/start → delete），
+         * 所以 codex 升级也不会多一个新依赖。
+         */
+        async probeModel(modelId) {
+            let threadId = null;
+            let cwd = null;
+            let timer = null;
+            try {
+                await client.ensureStarted();
+                // 模型名先对一下表：不对就直接报可读错误，不去烧一次真实回合
+                const catalog = await loadModels().catch(() => []);
+                if (catalog.length > 0 && !catalog.some((model) => (model.model || model.id) === modelId)) {
+                    return { ok: false, message: `codex 里没有这个模型：${modelId}` };
+                }
+                cwd = await mkdtemp(join(tmpdir(), PROBE_CWD_PREFIX));
+                const created = await client.request("thread/start", { cwd });
+                threadId = created?.thread?.id ?? null;
+                if (!threadId)
+                    return { ok: false, message: "codex 没有返回 thread id" };
+                // 用我们已经在用的那条路改模型（比猜 thread/start 的参数稳）
+                await client.request("thread/settings/update", { threadId, model: modelId });
+                const probeThreadId = threadId;
+                const measured = new Promise((resolve) => {
+                    probes.set(probeThreadId, { startedAt: Date.now(), firstAt: null, outputTokens: 0, resolve });
+                });
+                const timedOut = new Promise((resolve) => {
+                    timer = setTimeout(() => resolve({ ok: false, message: `测速超时（${Math.round(PROBE_TIMEOUT_MS / 1000)}s 没跑完）` }), PROBE_TIMEOUT_MS);
+                });
+                const turn = await client.request("turn/start", { threadId, input: [{ type: "text", text: PROBE_PROMPT, text_elements: [] }] }, { timeoutMs: 30_000 });
+                const result = await Promise.race([measured, timedOut]);
+                if (!result.ok) {
+                    // 超时 / 抛错：把回合收掉，别让 codex 在后台继续烧 token
+                    const turnId = turn?.turn?.id;
+                    if (turnId)
+                        await client.request("turn/interrupt", { threadId, turnId }).catch(() => undefined);
+                }
+                return result;
+            }
+            catch (error) {
+                return { ok: false, message: friendlyCodexError(error) };
+            }
+            finally {
+                if (timer)
+                    clearTimeout(timer);
+                if (threadId) {
+                    probes.delete(threadId);
+                    // 探针 thread 不该留在 codex 的历史里（侧栏与 Codex Desktop 都会看到它）
+                    await client.request("thread/delete", { threadId }).catch(() => undefined);
+                }
+                if (cwd)
+                    await rm(cwd, { recursive: true, force: true }).catch(() => undefined);
+            }
+        },
         currentModel: currentModelOf,
         sessionModel: currentModelOf,
         async switchModel(sessionId, modelId) {

package/dist/server/engine/dsh-history.js

@@ -1,5 +1,5 @@
 /**
- * DSH 会话日志 → 工作台的对话区消息 / 转录 / 统计（纯函数，单测直接覆盖）。
+ * DSH 会话日志 → 工作台的对话区消息 / 转录 / 统计（纯函数）。
  *
  * 与 `dsh-log.ts` 分工：那边只管**怎么把文件读出来**（多帧 zstd、定位、标题素材），
  * 这里只管**怎么映射成我们的形状**（消息块 / 工具状态 / 四桶用量）。