oh-my-agent-web 0.6.0 → 0.7.0

package/dist/server/engine/builtin.js

@@ -18,6 +18,7 @@ export function createBuiltinEngineRegistry(options) {
                     options.onLog?.(text);
                     options.onNotice(text, level);
                 },
+                ...(options.skillPaths ? { skillPaths: options.skillPaths } : {}),
             }),
         },
         ...(options.codex
@@ -29,7 +30,15 @@ export function createBuiltinEngineRegistry(options) {
                     // 能力如实写：审批是命令/文件级的（比 pi 粗一档），没有 provider 面板
                     description: options.codex.description ?? "codex 官方 agent：独立 loop 与沙箱，会话与 Codex Desktop / CLI 共用",
                     providerConfig: false,
-                    capabilities: { approvals: true, tools: true, modelSwitch: true, thinkingLevel: true, resume: true },
+                    // steer: false —— 底层（JSON-RPC / ACP）没有「插进正在跑的这一轮」的语义，宿主会降级成排队
+                    capabilities: {
+                        approvals: true,
+                        tools: true,
+                        modelSwitch: true,
+                        thinkingLevel: true,
+                        resume: true,
+                        steer: false,
+                    },
                     create: () => createCodexEngine({ client: options.codex?.client, log: options.onLog }),
                 },
             ]
@@ -43,7 +52,15 @@ export function createBuiltinEngineRegistry(options) {
                     description: options.dsh.description ??
                         "DeepSeek 官方 agent（ACP）：模型与思考档可切、权限逐次确认，会话与 dsh web/tui 共用",
                     providerConfig: false,
-                    capabilities: { approvals: true, tools: true, modelSwitch: true, thinkingLevel: true, resume: true },
+                    // steer: false —— 底层（JSON-RPC / ACP）没有「插进正在跑的这一轮」的语义，宿主会降级成排队
+                    capabilities: {
+                        approvals: true,
+                        tools: true,
+                        modelSwitch: true,
+                        thinkingLevel: true,
+                        resume: true,
+                        steer: false,
+                    },
                     create: () => createDshEngine({ client: options.dsh?.client, model: options.dsh?.model, log: options.onLog }),
                 },
             ]
@@ -59,7 +76,15 @@ export function createBuiltinEngineRegistry(options) {
                         "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 },
+                    // steer: false —— 底层（JSON-RPC / ACP）没有「插进正在跑的这一轮」的语义，宿主会降级成排队
+                    capabilities: {
+                        approvals: true,
+                        tools: true,
+                        modelSwitch: true,
+                        thinkingLevel: true,
+                        resume: true,
+                        steer: false,
+                    },
                     create: () => createOpencodeEngine({
                         client: options.opencode?.client,
                         bin: options.opencode?.bin,

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

@@ -13,7 +13,7 @@
  * 这条兜底很重要：本机实测 codex 的 threads.project_id 大量为 NULL（Desktop 只在某些路径下写入），
  * 只按 projectId 归类会让侧栏空掉。
  */
-import { basename } from "node:path";
+import { basename, sep } from "node:path";
 import { isScratchCwd } from "./scratch.js";
 /**
  * 拉会话时必须显式声明这两项，否则会「看不见大部分历史」（实测 0.162/0.163）：
@@ -126,12 +126,12 @@ export async function ensureCodexProject(client, workspace) {
         const list = await client.request("project/list", {});
         const match = (list?.data ?? [])
             .flatMap((project) => (project.roots ?? []).map((root) => ({ id: project.id, path: root.path ?? "" })))
-            .filter((root) => root.path !== "" && (workspace === root.path || workspace.startsWith(`${root.path}/`)))
+            .filter((root) => root.path !== "" && (workspace === root.path || workspace.startsWith(`${root.path}${sep}`)))
             .sort((left, right) => right.path.length - left.path.length)[0];
         if (match)
             return match.id;
         const created = await client.request("project/create", {
-            name: workspace.split("/").filter(Boolean).pop() ?? workspace,
+            name: basename(workspace) || workspace,
             roots: [{ path: workspace }],
             idempotencyKey: `agent-web:${workspace}`,
         });

package/dist/server/engine/dsh.js

@@ -119,7 +119,9 @@ export function createDshEngine(options = {}) {
     };
     const handlePermission = async (id, params) => {
         const facts = params.toolCall?.toolCallId ? toolFacts.get(params.toolCall.toolCallId) : undefined;
-        const request = permissionApprovalRequest(params, facts);
+        // 带上会话归属：宿主收尾时只收这个会话的审批（不然会误伤并行会话，见 approval-bridge）
+        const owner = params.sessionId ? bySession.get(params.sessionId) : undefined;
+        const request = { ...permissionApprovalRequest(params, facts), ...(owner ? { conversationId: owner } : {}) };
         let decision = "deny";
         if (approvalHandler) {
             try {

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

@@ -20,6 +20,7 @@
  *   服务端请求 → `{"id":9,"method":"…","params":{…}}`（有 id + method，**必须回包**否则对端一直等）
  */
 import { spawn } from "node:child_process";
+import { killTree, resolveCli } from "../util/spawn-cli.js";
 export function createJsonRpcStdioClient(options) {
     const baseTimeout = options.timeoutMs ?? 30_000;
     const prefix = options.name;
@@ -43,6 +44,10 @@ export function createJsonRpcStdioClient(options) {
     const send = (payload) => {
         if (!child)
             throw new Error(`${prefix} 未连接`);
+        // 子进程刚死、或已经被 close() 掉的时候这里还在写 → 会抛 EPIPE。
+        // 先自己拦一道，给调用方一个能看懂的错，而不是趟进 EPIPE 的未捕获异常（见 wire 里的 stdin 监听）
+        if (child.stdin.destroyed || !child.stdin.writable)
+            throw new Error(`${prefix} 管道已关闭`);
         child.stdin.write(`${JSON.stringify(options.jsonrpc ? { jsonrpc: "2.0", ...payload } : payload)}\n`);
     };
     const respond = (id, result) => {
@@ -103,6 +108,10 @@ export function createJsonRpcStdioClient(options) {
     const wire = (process) => {
         process.stdout.setEncoding("utf8");
         process.stdout.on("data", (chunk) => {
+            // close() 之后旧进程可能还会吐完缓冲区里的字节：不许它写进“新进程”的 buffer，
+            // 否则重启后第一帧会被旧半行拼坏 → JSON.parse 失败 → initialize 超时（看着就是「切回来连不上」）
+            if (child !== process)
+                return;
             buffer += chunk;
             let index;
             while ((index = buffer.indexOf("\n")) >= 0) {
@@ -133,6 +142,15 @@ export function createJsonRpcStdioClient(options) {
         };
         process.on("exit", (code) => onGone(`${prefix} 已退出（code ${code ?? "?"}）`));
         process.on("error", (error) => onGone(`${prefix} 启动失败：${error.message}`));
+        /**
+         * stdin 的 error **必须**接住。
+         *
+         * 子进程已经没了但我们还在 write（审批回包、turn/interrupt、通知都可能撞上），
+         * Node 会把 EPIPE 以 'error' 事件形式丢到 Writable 上；没监听就是**未捕获异常**，
+         * 而本仓只注册了 unhandledRejection（index.ts），于是整个工作台跟着退出。
+         * 处理方式与进程退出一致：拒掉在飞请求、通知 onExit（上层会标记引擎不可用）。
+         */
+        process.stdin.on("error", (error) => onGone(`${prefix} 写入失败：${error.message}`));
     };
     const requestRaw = (method, params, timeoutMs = baseTimeout) => {
         const id = ++seq;
@@ -166,7 +184,14 @@ export function createJsonRpcStdioClient(options) {
                     else
                         env[key] = value;
                 }
-                const next = spawn(options.bin, options.args, { env, cwd: options.cwd, stdio: ["pipe", "pipe", "pipe"] });
+                // Windows 上 codex/dsh 是 .cmd shim：resolveCli 负责改成 cmd.exe /c
+                const command = resolveCli(options.bin, options.args, env);
+                const next = spawn(command.file, command.args, {
+                    ...command.options,
+                    env,
+                    cwd: options.cwd,
+                    stdio: ["pipe", "pipe", "pipe"],
+                });
                 child = next;
                 wire(next);
             }
@@ -182,7 +207,8 @@ export function createJsonRpcStdioClient(options) {
             child = null;
             initialized = false;
             version = null;
-            process?.kill("SIGTERM");
+            if (process)
+                killTree(process);
             throw error instanceof Error ? error : new Error(String(error));
         }
         finally {
@@ -234,8 +260,12 @@ export function createJsonRpcStdioClient(options) {
             child = null;
             initialized = false;
             version = null;
+            // 必须清：onGone 里那句 `if (child !== process) return` 在 close 之后会提前返回，
+            // 所以这条路径上没人会帮我们清 buffer（旧半行会污染下次 spawn 的第一帧）
+            buffer = "";
             rejectAll(new Error(`${prefix} 已关闭`));
-            process?.kill("SIGTERM");
+            if (process)
+                killTree(process);
         },
     };
 }

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

@@ -19,6 +19,7 @@
  */
 import { spawn } from "node:child_process";
 import { basename } from "node:path";
+import { killTree, resolveCli } from "../util/spawn-cli.js";
 import { isScratchCwd } from "./scratch.js";
 /** 单个项目的 `session/list` 超时：侧栏刷新不该被一个卡住的项目拖死 */
 const PROJECT_LIST_TIMEOUT_MS = 10_000;
@@ -146,11 +147,16 @@ export function createOpencodeSessionsProvider(options) {
  */
 function runOpencode(bin, args, options = {}) {
     return new Promise((resolve, reject) => {
-        const child = spawn(bin, args, { cwd: options.cwd, stdio: ["ignore", "pipe", "pipe"] });
+        const command = resolveCli(bin, args, process.env);
+        const child = spawn(command.file, command.args, {
+            ...command.options,
+            cwd: options.cwd,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
         let stdout = "";
         let stderr = "";
         const timer = setTimeout(() => {
-            child.kill("SIGTERM");
+            killTree(child);
             reject(new Error(`opencode ${args[0]} 超时`));
         }, options.timeoutMs ?? 30_000);
         child.stdout?.setEncoding("utf8");

package/dist/server/engine/opencode.js

@@ -159,7 +159,9 @@ export function createOpencodeEngine(options = {}) {
     };
     const handlePermission = async (id, params) => {
         const facts = params.toolCall?.toolCallId ? toolFacts.get(params.toolCall.toolCallId) : undefined;
-        const request = permissionApprovalRequest(params, facts);
+        // 带上会话归属：宿主收尾时只收这个会话的审批（不然会误伤并行会话，见 approval-bridge）
+        const owner = params.sessionId ? byEngineSession.get(params.sessionId) : undefined;
+        const request = { ...permissionApprovalRequest(params, facts), ...(owner ? { conversationId: owner } : {}) };
         let decision = "deny";
         if (approvalHandler) {
             try {

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

@@ -7,6 +7,7 @@
  * 与 SDK 的对接方式（M3 侦察结论）：
  */
 import { DefaultResourceLoader, SessionManager, createAgentSession, getAgentDir, } from "@earendil-works/pi-coding-agent";
+import { getBuiltinModels } from "@earendil-works/pi-ai/providers/all";
 import { classifyScope } from "../approval/scope.js";
 import { mapSessionEvent } from "./pi-events.js";
 import { createPiSubagents } from "./pi-subagents.js";
@@ -17,6 +18,29 @@ import { entriesToUiMessages } from "./pi-transcript.js";
 function asRecord(value) {
     return typeof value === "object" && value !== null ? value : {};
 }
+/**
+ * pi 的「已经在跑了」那句拒绝（`Agent is already processing. Specify streamingBehavior…`）。
+ * 宿主拿它判断「这条其实该插队」—— 见 sendMessage 里的兜底。
+ */
+function isAlreadyProcessing(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return message.includes("Agent is already processing");
+}
+/**
+ * 插队那条要等「这一轮真的 settle」才算收尾；这个上限只是兜底，
+ * 免得 pi 万一不吐 agent_settled（abort 失败之类）时回合永远不收尾（宿主看门狗本来也会 interrupt）。
+ */
+const STEER_SETTLE_FALLBACK_MS = 20 * 60 * 1000;
+/**
+ * 普通（非插队）回合的「等 settle」宽限。
+ *
+ * `prompt()` 返回时收尾事件（agent_settled / 最后的 message_end）可能还在路上：
+ * 本来只给 50ms，一步慢机器上就会错过 —— 后果不是报错而是**静默错报**：
+ * `interrupted` 只在 agent_settled 里置位，错过它的话「用户点停的回合」会被报成 `turn_end: done`，
+ * 而且 finally 里的 unsubscribe 会把尾帧（含 usage）一起丢掉（token/费用少记）。
+ * 800ms 是个只影响「settle 干脆不来」那种病态情况的兵底，正常回合 settles 一到就返回。
+ */
+const SETTLE_GRACE_MS = 800;
 /**
  * provider 的显示名：只覆盖 SDK 名字太长/不直观的两个（和 pi-web 的选择一致），
  * 其余直接用引擎给的 OAuth 名称（`Anthropic (Claude Pro/Max)`、`xAI (Grok/X subscription)` 等）。
@@ -25,6 +49,18 @@ const OAUTH_LABELS = {
     "openai-codex": "ChatGPT Plus/Pro",
     "github-copilot": "GitHub Copilot",
 };
+/**
+ * 「只填 key 还不够」的 provider：还得有端点 / 云凭证。
+ * 写死名单而不是去猜 provider 定义：这些的 baseUrl 要么挂在模型上、要么要 account id，
+ * 而 pi 的 provider 对象没有「需不需要额外配置」这个字段。
+ */
+const NEEDS_EXTRA_CONFIG = new Set([
+    "amazon-bedrock",
+    "google-vertex",
+    "azure",
+    "cloudflare-ai-gateway",
+    "cloudflare-workers-ai",
+]);
 /** SDK 的 AuthPrompt → 端口的 ProviderAuthPrompt */
 function toAuthPrompt(prompt) {
     const record = asRecord(prompt);
@@ -94,8 +130,13 @@ export function createPiSdkEngine(options = {}) {
         // 子代理沿用父会话的模型运行时 / 当前模型（不然扩展提供的 provider 在子会话里不存在）
         getParentSession: (conversationId) => sessions.get(conversationId)?.session ?? null,
     });
-    /** 审批用的 inline 扩展：拦在工具真正执行之前（SDK 的公开拦截点） */
-    function makeApprovalExtension(workspace) {
+    /**
+     * 审批用的 inline 扩展：拦在工具真正执行之前（SDK 的公开拦截点）。
+     *
+     * 这个扩展是**按会话**建的（见 startSession），所以能把会话 id 一起带上 ——
+     * 回合收尾时宿主据此只收掉本会话悬着的审批，不会误伤并行跑着的其它会话。
+     */
+    function makeApprovalExtension(workspace, conversationId) {
         return {
             name: "agent-web-approval",
             hidden: true,
@@ -111,6 +152,7 @@ export function createPiSdkEngine(options = {}) {
                         return undefined; // 只读工具不问
                     const decision = approvalHandler
                         ? await approvalHandler({
+                            conversationId,
                             toolName: scope.toolName,
                             argsSummary: scope.argsSummary,
                             scopeKey: scope.scopeKey,
@@ -131,11 +173,9 @@ export function createPiSdkEngine(options = {}) {
         const agentDir = options.agentDir ?? getAgentDir();
         // 子会话要按父会话归档：会话文件名在 createAgentSession 之后才确定，所以用一个懒引用
         const parentSessionPath = () => sessionManager.getSessionFile() ?? sessionPath;
-        const extensionFactories = [makeApprovalExtension(workspace)];
+        const extensionFactories = [makeApprovalExtension(workspace, sessionId)];
         // 子代理开着、且有可用模板时，才把「什么时候派活」这段拼进系统提示
-        const subagentReady = sessionId !== PREWARM_ID
-            && readSubagentSettings(agentDir).enabled
-            && enabledSubagentSpecs(agentDir).length > 0;
+        const subagentReady = sessionId !== PREWARM_ID && readSubagentSettings(agentDir).enabled && enabledSubagentSpecs(agentDir).length > 0;
         // 预热会话不暴露 Agent 工具：它不下发提示词，给它一个委派入口只会误伤
         if (sessionId !== PREWARM_ID) {
             extensionFactories.push(makeSubagentToolExtension({
@@ -149,14 +189,13 @@ export function createPiSdkEngine(options = {}) {
         const resourceLoader = new DefaultResourceLoader({
             cwd: workspace,
             agentDir,
+            // 本工作台的技能目录（默认 `~/.agents/skills`）：pi 自己不扫那里，
+            // 不显式加上的话 `/skill:xxx` 不会被展开成技能正文（见 PiSdkEngineOptions.skillPaths）
+            ...(options.skillPaths && options.skillPaths.length > 0 ? { additionalSkillPaths: options.skillPaths } : {}),
             extensionFactories,
             // 教模型「下一步建议」的写法（ADR-0022）：纯文本标记，不需要调用任何工具
             // 「动手前先说话」：过程默认折叠，不写正文用户就不知道它在干什么
-            appendSystemPrompt: [
-                SUGGESTION_GUIDANCE,
-                NARRATE_GUIDANCE,
-                ...(subagentReady ? [SUBAGENT_GUIDANCE] : []),
-            ],
+            appendSystemPrompt: [SUGGESTION_GUIDANCE, NARRATE_GUIDANCE, ...(subagentReady ? [SUBAGENT_GUIDANCE] : [])],
         });
         await resourceLoader.reload();
         const { session } = await createAgentSession({
@@ -237,6 +276,66 @@ export function createPiSdkEngine(options = {}) {
         }))
             .sort((left, right) => left.id.localeCompare(right.id));
     }
+    /**
+     * 引擎目录里的全部 provider（ADR-0004 快照 / 「官方内置服务商」分组）。
+     *
+     * 与 `listModels()` 的区别：那个只回**已鉴权**的，这里连「没配 key 的」也列 ——
+     * 界面才有一个地方让用户粘 key。两个标记决定能不能归到「填 key 就能用」：
+     *   - `oauthOnly`：pi 只给了订阅登录（openai-codex），填 key 没用；
+     *   - `needsExtraConfig`：除了 key 还要端点 / 云凭证（bedrock、vertex、azure、cloudflare）。
+     * 名单按 id 写死：pi 的 provider 定义没有「需不需要额外配置」这个字段，而靠猜更不可靠。
+     */
+    async function listProviderCatalog() {
+        const runtime = await authRuntime();
+        if (!runtime)
+            return [];
+        return runtime
+            .getProviders()
+            .map((provider) => {
+            const apiKey = Boolean(provider.auth.apiKey);
+            const oauth = Boolean(provider.auth.oauth);
+            const models = runtime.getModels(provider.id);
+            // SDK 的 Provider 类型里没写 baseUrl（运行时是有的，pi-ai 的 createProvider 会给）：
+            // 这里只读一个可选的显示信息，不值得为它去引 pi-ai 的内部类型。
+            const declaredBaseUrl = provider.baseUrl;
+            /**
+             * 端点 / 协议可能**挂在模型上**而不是 provider 上（opencode / opencode-go 就是这种，
+             * 而且同一家还混着 anthropic / openai / gemini 三种协议）。
+             * 运行时拿到的模型对象不一定带这些字段，所以再拿 pi 的静态目录按 id 补一份。
+             */
+            const builtin = getBuiltinModels(provider.id);
+            const specById = new Map();
+            for (const model of builtin) {
+                specById.set(model.id, {
+                    ...(typeof model.api === "string" && model.api !== "" ? { api: model.api } : {}),
+                    ...(typeof model.baseUrl === "string" && model.baseUrl !== "" ? { baseUrl: model.baseUrl } : {}),
+                });
+            }
+            const modelSpecs = models.map((model) => ({
+                id: model.id,
+                ...((model.api ?? specById.get(model.id)?.api) ? { api: model.api ?? specById.get(model.id)?.api } : {}),
+                ...((model.baseUrl ?? specById.get(model.id)?.baseUrl)
+                    ? { baseUrl: model.baseUrl ?? specById.get(model.id)?.baseUrl }
+                    : {}),
+            }));
+            const baseUrl = declaredBaseUrl ??
+                modelSpecs.find((model) => model.baseUrl !== undefined)?.baseUrl ??
+                models.find((model) => typeof model.baseUrl === "string" && model.baseUrl !== "")?.baseUrl;
+            const api = modelSpecs.find((model) => model.api !== undefined)?.api ??
+                models.find((model) => typeof model.api === "string" && model.api !== "")?.api;
+            return {
+                provider: provider.id,
+                name: provider.name,
+                ...(baseUrl ? { baseUrl } : {}),
+                ...(api ? { api } : {}),
+                ...(modelSpecs.length > 0 ? { models: modelSpecs } : {}),
+                modelCount: models.length,
+                ...(apiKey ? {} : oauth ? { oauthOnly: true } : { needsExtraConfig: true }),
+                ...(NEEDS_EXTRA_CONFIG.has(provider.id) ? { needsExtraConfig: true } : {}),
+            };
+        })
+            .sort((left, right) => left.provider.localeCompare(right.provider));
+    }
     return {
         /** 预热：pi 的 modelRuntime 挂在会话上，没会话就列不出模型（内存会话，不落盘） */
         async prewarm() {
@@ -335,6 +434,8 @@ export function createPiSdkEngine(options = {}) {
                 }
             });
             handle.subscriptions.add(off);
+            /** 这条消息是被「插进正在跑的那一轮」的：它的输出要等那一轮结束，不能 50ms 就收尾 */
+            let steered = false;
             try {
                 // 图片走 SDK 的 images 参数（视觉注入）；没有图片时不传，避免空数组影响提示词缓存
                 const images = messageOptions?.images?.map((image) => ({
@@ -348,9 +449,31 @@ export function createPiSdkEngine(options = {}) {
                     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))]);
+                const session = handle.session;
+                try {
+                    await session.prompt(text, promptOptions);
+                }
+                catch (error) {
+                    /**
+                     * pi 说「已经在跑了」= 宿主的忙碌判断和 pi 的 `isStreaming` 错开了一步（排队排空恰好撞上
+                     * 上一轮还没真正 settle、看门狗强制收尾、插队与 settle 抢跑……）。
+                     * 这**不是**「回合失败」而是「该插队」：补一次 steer 交给 pi 排队（与 turn-queue 的
+                     * flushSteer 同一语义），别把用户那条消息变成界面上的一条红条、然后人也没了。
+                     * 已经就是 steer 还报这句 = 真异常，照旧报错。
+                     */
+                    if (promptOptions.streamingBehavior === "steer" || !isAlreadyProcessing(error))
+                        throw error;
+                    await session.prompt(text, { ...promptOptions, streamingBehavior: "steer" });
+                    steered = true;
+                }
+                // 等 settle：prompt() 返回后仍可能有收尾事件（插队那条更要等整轮真结束，否则会提前收尾）
+                if (steered)
+                    await Promise.race([
+                        settled,
+                        new Promise((done) => setTimeout(done, STEER_SETTLE_FALLBACK_MS).unref?.()),
+                    ]);
+                else
+                    await Promise.race([settled, new Promise((resolve) => setTimeout(resolve, SETTLE_GRACE_MS).unref?.())]);
             }
             catch (error) {
                 failed = {
@@ -367,7 +490,10 @@ export function createPiSdkEngine(options = {}) {
                 onEvent({ type: "turn_end", reason: "error" });
                 return;
             }
-            onEvent({ type: "turn_end", reason: interrupted ? "interrupted" : providerError ? "error" : "done" });
+            // `handle.aborting` 是兵底：中断时它已经被 interrupt() 置 true，
+            // 即使 agent_settled 没来得及到，也不要把「点停」报成「完成」
+            const aborted = interrupted || handle.aborting;
+            onEvent({ type: "turn_end", reason: aborted ? "interrupted" : providerError ? "error" : "done" });
         },
         async interrupt(sessionId) {
             const handle = sessions.get(sessionId);
@@ -405,6 +531,7 @@ export function createPiSdkEngine(options = {}) {
         setApprovalHandler(handler) {
             approvalHandler = handler;
         },
+        listProviderCatalog,
         async listModels(sessionId) {
             // 模型注册表挂在会话的 modelRuntime 上：没有会话时给不出（界面在打开会话后才显示列表）
             const handle = sessionId ? sessions.get(sessionId) : [...sessions.values()].at(-1);
@@ -484,6 +611,21 @@ export function createPiSdkEngine(options = {}) {
          * `sessions.get(undefined)` 什么也没关，每切一次引擎就漏一批 SDK 会话与资源加载器。
          */
         async dispose(sessionId) {
+            /**
+             * 引擎级 dispose（切引擎/退出）**必须连子代理一起收掉**。
+             *
+             * 子代理会话是 `pi-subagents` 自己 `createAgentSession` 起的，**不在下面这个 sessions map 里** ——
+             * 只关 sessions 就会漏掉它们：切走引擎后旧子代理还在跑（还在调工具、还在烧 token），
+             * 而且再也没人能把它们停下（宿主已经换了引擎，`interrupt_subagent` 会发给新引擎）。
+             */
+            if (!sessionId && subagents.dispose) {
+                try {
+                    await subagents.dispose();
+                }
+                catch {
+                    // 收不掉也不阻断切换（旧引擎的子代理最多多跑一会儿，但不会再阻塞切引擎）
+                }
+            }
             const ids = sessionId ? [sessionId] : [...sessions.keys()];
             for (const id of ids) {
                 const handle = sessions.get(id);

package/dist/server/engine/pi-subagent-tool.js

@@ -40,28 +40,52 @@ function resultText(run) {
         return `${head}（已停止）${body ? `\n\n${body}` : ""}`;
     return `${head}：${run.error ?? "未知错误"}${body ? `\n\n${body}` : ""}`;
 }
-/** 等这个运行进入终态；返回最后一次看到的记录 */
-function waitForRun(port, id, timeoutMs) {
+/**
+ * 等这个运行进入终态；返回最后一次看到的记录。
+ *
+ * 导出是为了单测（`tests/unit/subagent-wait.test.ts`）：这里有一个「先查再订阅」的竞态，
+ * 只有把函数单独拿出来才能构造出那个窗口。
+ */
+export function waitForRun(port, id, timeoutMs) {
     // 极快的任务可能在 start() 返回前就结束了：先看一眼，再订阅
     const current = port.get(id);
     if (current && TERMINAL.has(current.status))
         return Promise.resolve(current);
     return new Promise((resolve) => {
-        let last = null;
-        const timer = setTimeout(() => {
+        let last = current;
+        let settled = false;
+        let timer = null;
+        let off = () => { };
+        const finish = (run) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer)
+                clearTimeout(timer);
             off();
-            resolve(last);
-        }, timeoutMs);
-        const off = port.subscribe((run) => {
+            resolve(run);
+        };
+        timer = setTimeout(() => finish(last), timeoutMs);
+        off = port.subscribe((run) => {
             if (run.id !== id)
                 return;
             last = run;
             if (!TERMINAL.has(run.status))
                 return;
-            clearTimeout(timer);
-            off();
-            resolve(run);
+            finish(run);
         });
+        /**
+         * 订阅之后再补查一次。
+         *
+         * `port.subscribe` **只推后续事件、不回放当前状态**，所以上面那次 `get()` 与订阅之间
+         * 如果刚好跃迁到终态，那一推就永远收不到 —— 工具会一直等到 timeoutMs（默认 40 分钟）
+         * 才返回「一直没有结束」，父回合也就一直挂在「进行中」。补这一次查询把窗口关掉。
+         */
+        const after = port.get(id);
+        if (after)
+            last = after;
+        if (after && TERMINAL.has(after.status))
+            finish(after);
     });
 }
 export function makeSubagentToolExtension(options) {
@@ -152,9 +176,7 @@ export function makeSubagentToolExtension(options) {
                     }
                     catch (error) {
                         return {
-                            content: [
-                                { type: "text", text: error instanceof Error ? error.message : String(error) },
-                            ],
+                            content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }],
                             details: undefined,
                             isError: true,
                         };

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

@@ -21,6 +21,15 @@ const RESULT_CHARS = 4000;
 const MAX_RUNS = 60;
 /** 状态推进的节流：正文增量很频繁，面板只需要「大概每秒一次」的刷新 */
 const EMIT_INTERVAL_MS = 300;
+/**
+ * 单个子代理的**墙钟**上限。
+ *
+ * `session.prompt()` 没有任何超时参数，模板里的 `maxTurns` 也只在 `message_end` 时才检查 ——
+ * 一个卡在长工具调用 / provider 静默断流（不报错也不结束）的子会话可以永远挂着：
+ * 它占着一个并发槽（超了上限就再也不会起新的）、持续烧 token，
+ * 而且宿主侧只能靠用户手动点「停止」。
+ */
+const DEFAULT_TIMEOUT_MS = 20 * 60 * 1000;
 /**
  * 子会话不加载扩展（noExtensions）：由扩展注册的 provider（api 是扩展自己的实现）
  * 在子会话里就找不到 —— SDK 只会甩一句英文「No API provider registered for api: xxx」。
@@ -223,7 +232,35 @@ export function createPiSubagents(options) {
                 settled();
         });
         try {
-            await session.prompt(request.task);
+            /**
+             * 墙钟超时：`prompt()` 没有超时参数，卡住的子会话会一直占并发槽 + 烧 token。
+             * 到点先 abort（尽量让它正常收尾），并且**不再等 prompt 的 Promise** ——
+             * 真正卡死的会话那个 Promise 是永远不会 resolve 的。
+             */
+            const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+            const minutes = Math.max(1, Math.round(timeoutMs / 60_000));
+            let timer = null;
+            const deadline = new Promise((resolve) => {
+                timer = setTimeout(() => {
+                    errorText = errorText ?? `子代理超时（超过 ${minutes} 分钟没有结束）`;
+                    void session.abort().catch(() => undefined);
+                    resolve();
+                }, timeoutMs);
+                timer.unref?.();
+            });
+            let promptError = null;
+            const prompt = session.prompt(request.task).catch((error) => {
+                promptError = error;
+            });
+            try {
+                await Promise.race([prompt, deadline]);
+            }
+            finally {
+                if (timer)
+                    clearTimeout(timer);
+            }
+            if (promptError !== null)
+                throw promptError instanceof Error ? promptError : new Error(String(promptError));
             // prompt() 返回后仍可能有收尾事件：给它 50ms（与宿主侧同一套做法）
             await Promise.race([done, new Promise((resolve) => setTimeout(resolve, 50))]);
         }

package/dist/server/engine/registry.js

@@ -44,4 +44,5 @@ export const FAKE_CAPABILITIES = {
     thinkingLevel: false,
     resume: true,
 };
-export const PI_CAPABILITIES = { ...ALL_ON, subagents: true };
+/** pi：能力全开，而且**只有它真能插队**（`streamingBehavior: "steer"`，见 ADR-0043） */
+export const PI_CAPABILITIES = { ...ALL_ON, subagents: true, steer: true };

package/dist/server/engine/wiring.js

@@ -119,6 +119,7 @@ export function createEngineWiring(options) {
     };
     const registry = createBuiltinEngineRegistry({
         onNotice: options.onNotice,
+        ...(options.skillPaths ? { skillPaths: options.skillPaths } : {}),
         onLog: (text) => options.onLog(text),
         codex: { client: codexClient },
         dsh: { client: dshClient, model: defaultModel },