aws-runtime-bridge 1.9.33 → 1.9.41

package/package/acode/dist/sub-agent-manager.js

@@ -0,0 +1,825 @@
+import { randomUUID } from "node:crypto";
+import { ACodeRuntime } from "./runtime.js";
+/** 已完成 entry 在内存中的保留时长（30 分钟），超时后清理释放内存 */
+const COMPLETED_ENTRY_TTL_MS = 30 * 60 * 1000;
+/**
+ * SubAgentManager：管理独立 ACodeRuntime 实例池。
+ *
+ * 核心职责：
+ *   1. spawn 创建独立 ACodeRuntime 实例（避免父 agent 的 submitQueue 死锁）
+ *   2. start 异步启动子 agent（不阻塞），awaitCompletion 显式等待完成
+ *   3. abort 取消运行中的 sub-agent
+ *   4. 维护父子关系映射（parentAgentId -> subIds）
+ *   5. SSE 事件订阅（subscribe/unsubscribe）
+ *   6. 状态持久化到 SubAgentStore
+ *
+ * 线程模型：单进程 Node.js，所有 ACodeRuntime 实例共享事件循环。
+ *   非阻塞模式：spawn 后调 start 立即返回，主 agent 可继续工作；
+ *   主 agent 通过 awaitCompletion 显式阻塞等待指定 sub-agent 数组完成。
+ *
+ * 重要：ACodeRuntime.submit() 返回 Promise<void>，assistant 文本通过
+ *   "event" 上的 "assistant_delta" 事件传递，turn 结束时发出 "turn_complete"。
+ *   因此 start 内部注册事件监听器累积输出文本，awaitCompletion 通过 Promise 等待。
+ *
+ * Entry 生命周期：
+ *   - pending: spawn 后未 start
+ *   - running: start 后运行中
+ *   - completed/failed/cancelled: 终态，entry 保留在内存中 TTL=30min，
+ *     供 list/get_status 查询；超时后从内存清理（store 仍持久化）
+ */
+export class SubAgentManager {
+    constructor(opts) {
+        this.subAgents = new Map();
+        this.parentToSubs = new Map();
+        this.subscribers = new Map(); // subId 或 "*" -> subs
+        /** 已完成 entry 的清理定时器 */
+        this.cleanupTimer = null;
+        /**
+         * 终态通知队列：子 agent 到达终态时入队，takeCompletedSubAgents 消费。
+         * 供 poll_message 在 ACode 运行时层检测子 agent 完成事件。
+         */
+        this.completionQueue = [];
+        /**
+         * waitForAnyCompletion 的 resolve 回调，终态事件到达时调用。
+         * null 表示当前没有等待者。
+         */
+        this.completionWaiterResolve = null;
+        this.store = opts.store;
+        this.maxConcurrent = opts.maxConcurrent ?? 5;
+        // 启动定期清理已完成 entry 的定时器（每 5 分钟扫一次）
+        this.cleanupTimer = setInterval(() => this.cleanupCompletedEntries(), 5 * 60 * 1000);
+        // 不阻止进程退出
+        if (this.cleanupTimer.unref)
+            this.cleanupTimer.unref();
+    }
+    /** 创建 sub-agent（不立即运行；调 start 才执行） */
+    async spawn(opts) {
+        // 并发上限检查（pending + running 都算占用配额）
+        const activeCount = this.countByStatus(opts.parentAgentId, "running", "pending");
+        if (activeCount >= this.maxConcurrent) {
+            throw new Error(`concurrent sub-agent limit reached (${this.maxConcurrent}) for agent ${opts.parentAgentId}`);
+        }
+        const subId = `sub-${randomUUID()}`;
+        const startedAt = Date.now();
+        const abortController = new AbortController();
+        // 构造子 agent 的 config（继承父 agent 的 model/prompt，但独立 sessionId）
+        // 若父 agent 配置了 subAgentModel/subAgentEffort，则覆盖子 agent 的 model/effort
+        const childConfig = {
+            ...opts.parentConfig,
+            sessionId: subId,
+            workingDirectory: opts.workingDirectory,
+            agentId: `${opts.parentAgentId}__sub__${subId}`,
+            // sub-agent 不继承 initialPrompt（用 submit 触发）
+            initialPrompt: undefined,
+            // sub-agent 不允许再 spawn 自己的子 agent（禁止递归嵌套）
+            subAgentManager: undefined,
+            // Sub Agent 模型/强度覆盖：有值则覆盖继承的 model/effort
+            ...(opts.parentConfig.subAgentModel
+                ? { model: opts.parentConfig.subAgentModel }
+                : {}),
+            ...(opts.parentConfig.subAgentEffort
+                ? { effort: opts.parentConfig.subAgentEffort }
+                : {}),
+            // 子 agent 不再继承 subAgent 专用覆盖字段（防止孙 agent 二次覆盖）
+            subAgentModel: undefined,
+            subAgentEffort: undefined,
+        };
+        const runtime = new ACodeRuntime(childConfig);
+        const entry = {
+            subId,
+            parentAgentId: opts.parentAgentId,
+            parentSessionId: opts.parentSessionId,
+            subagentType: opts.subagentType,
+            description: opts.description,
+            prompt: opts.prompt,
+            status: "pending",
+            startedAt,
+            runtime,
+            abortController,
+            silent: opts.silent,
+            contextSnapshot: {
+                tokenUsage: { input: 0, output: 0 },
+                messageCount: 0,
+                updatedAt: new Date().toISOString(),
+            },
+            availableTools: [],
+        };
+        this.subAgents.set(subId, entry);
+        this.addToParentMap(opts.parentAgentId, subId);
+        // 持久化初始记录
+        const record = this.toRecord(entry);
+        await this.store.upsert(opts.parentAgentId, record);
+        // 监听 runtime 事件以更新 contextSnapshot
+        runtime.on("event", (event) => {
+            this.handleRuntimeEvent(subId, event);
+        });
+        this.emitEvent(subId, "spawned", {});
+        return subId;
+    }
+    /**
+     * 异步启动 sub-agent（不阻塞，立即返回）。
+     *
+     * 内部创建 completionPromise 供后续 awaitCompletion 等待。
+     * 启动后立即返回，主 agent 可继续做其他事。
+     *
+     * 同一 sub-agent 只能 start 一次；重复 start 抛错。
+     */
+    async start(subId) {
+        const entry = this.subAgents.get(subId);
+        if (!entry) {
+            throw new Error(`sub-agent not found: ${subId}`);
+        }
+        if (entry.status !== "pending") {
+            throw new Error(`sub-agent ${subId} cannot start from status: ${entry.status}`);
+        }
+        // 创建 completionPromise（在 finally 中 settle）
+        entry.completionPromise = new Promise((resolve, reject) => {
+            entry.completionResolve = resolve;
+            entry.completionReject = reject;
+        });
+        // 异步启动，不阻塞调用方
+        void this.runEntryToCompletion(entry).catch(() => {
+            // runEntryToCompletion 内部已处理异常并更新状态；
+            // 这里捕获防止 unhandled rejection
+        });
+    }
+    /**
+     * 带 recheck 循环的异步启动（不阻塞，立即返回）。
+     *
+     * 与 start 的区别：每轮 submit 完成后调用 recheck 回调查询服务端真实状态。
+     * 若 recheck 返回 { done: false, continueMessage }，将 continueMessage 作为
+     * 下一轮 submit 注入同一 sub-agent（保持上下文连续性），最多重试 maxRetries 次。
+     *
+     * 适用场景：memory 过期整理 / 文件变更更新 / 容量整理等需要系统级硬保证
+     * "确实完成"的场景，不依赖 LLM 自报结果。
+     */
+    async startWithRecheck(subId, recheck, maxRetries = 3) {
+        const entry = this.subAgents.get(subId);
+        if (!entry) {
+            throw new Error(`sub-agent not found: ${subId}`);
+        }
+        if (entry.status !== "pending") {
+            throw new Error(`sub-agent ${subId} cannot start from status: ${entry.status}`);
+        }
+        // 创建 completionPromise（在 finally 中 settle）
+        entry.completionPromise = new Promise((resolve, reject) => {
+            entry.completionResolve = resolve;
+            entry.completionReject = reject;
+        });
+        // 异步启动，不阻塞调用方
+        void this.runEntryToCompletionWithRecheck(entry, recheck, maxRetries).catch(() => {
+            // 内部已处理异常并更新状态；这里捕获防止 unhandled rejection
+        });
+    }
+    /**
+     * 阻塞等待指定 sub-agent 数组全部完成（completed/failed/cancelled）。
+     *
+     * - 已完成的立即 resolve
+     * - 未 start 的会先 start（自动启动）
+     * - 返回每个 sub-agent 的最终结果
+     *
+     * 注意：本方法不取消 sub-agent，仅等待。如需取消用 abort。
+     */
+    async awaitCompletion(subIds, timeoutMs = 0) {
+        if (subIds.length === 0)
+            return [];
+        const results = [];
+        // 对每个 subId 准备等待 Promise
+        const waitPromises = subIds.map(async (subId) => {
+            const entry = this.subAgents.get(subId);
+            if (!entry) {
+                // entry 已从内存清理，从 store 查
+                const record = await this.findRecordInStore(subId);
+                if (record) {
+                    results.push({
+                        subId,
+                        output: record.result ?? "",
+                        error: record.errorMessage,
+                        status: record.status,
+                    });
+                }
+                else {
+                    results.push({
+                        subId,
+                        output: "",
+                        error: `sub-agent not found: ${subId}`,
+                        status: "failed",
+                    });
+                }
+                return;
+            }
+            // 标记为 awaited：防止 enqueueCompletion 将终态通知推入 completionQueue
+            // （避免后续 poll_message 重复返回已被 await 消费的结果）
+            entry.awaited = true;
+            // 如果还在 pending，自动 start
+            if (entry.status === "pending") {
+                await this.start(subId);
+            }
+            // 等待 completionPromise（可能已被 start 创建）
+            const promise = entry.completionPromise ?? Promise.resolve({ output: "", error: "not started" });
+            try {
+                const result = await promise;
+                results.push({
+                    subId,
+                    output: result.output,
+                    error: result.error,
+                    status: entry.status,
+                });
+            }
+            catch (err) {
+                results.push({
+                    subId,
+                    output: "",
+                    error: err instanceof Error ? err.message : String(err),
+                    status: entry.status,
+                });
+            }
+        });
+        // 等待全部完成后，清理 completionQueue 中可能已存在的这些 subId 的通知
+        // （处理子 agent 在 awaited 标记设置前已完成入队的情况）
+        const subIdSet = new Set(subIds);
+        for (let i = this.completionQueue.length - 1; i >= 0; i--) {
+            if (subIdSet.has(this.completionQueue[i].subId)) {
+                this.completionQueue.splice(i, 1);
+            }
+        }
+        if (timeoutMs > 0) {
+            await Promise.race([
+                Promise.allSettled(waitPromises),
+                new Promise((resolve) => setTimeout(() => resolve(), timeoutMs)),
+            ]);
+        }
+        else {
+            await Promise.allSettled(waitPromises);
+        }
+        return results;
+    }
+    /**
+     * 内部方法：执行 entry 直到完成。
+     *
+     * 实际 ACodeRuntime.submit() 返回 Promise<void>，assistant 文本通过
+     * assistant_delta 事件传递。本方法注册临时监听器累积输出文本，
+     * 同时检测 turn_complete 事件中的 failed 标志以处理运行时内部错误。
+     *
+     * 完成后：
+     *   - 更新 entry 状态（completed/failed）
+     *   - 持久化到 store
+     *   - settle completionPromise
+     *   - 清理 runtime 实例（释放内存）
+     *   - **不删除 entry**（保留在内存供 list/get_status 查询，30min 后由定时器清理）
+     */
+    async runEntryToCompletion(entry) {
+        // 收集 assistant_delta 文本 + 检测 turn 失败标志
+        const chunks = [];
+        let turnFailed = false;
+        let turnErrorMessage;
+        const onEvent = (event) => {
+            if (!event)
+                return;
+            switch (event.type) {
+                case "assistant_delta":
+                    if (typeof event.data?.text === "string") {
+                        chunks.push(event.data.text);
+                    }
+                    break;
+                case "turn_complete":
+                    if (event.data?.failed) {
+                        turnFailed = true;
+                    }
+                    break;
+                case "error":
+                    if (typeof event.data?.message === "string") {
+                        turnErrorMessage = event.data.message;
+                    }
+                    break;
+            }
+        };
+        entry.runtime.on("event", onEvent);
+        // 状态 -> running
+        entry.status = "running";
+        await this.store.updateStatus(entry.parentAgentId, entry.subId, { status: "running" });
+        this.emitEvent(entry.subId, "running", {});
+        try {
+            await entry.runtime.start();
+            // 记录启动后的可用工具列表
+            entry.availableTools = entry.runtime.getAvailableTools();
+            await entry.runtime.submit(entry.prompt);
+            // 实际 API 中 submit 解析后所有事件已同步触发完毕（EventEmitter.emit 是同步的）
+            // 若 turn_complete 标记 failed，抛错走 catch
+            if (turnFailed) {
+                throw new Error(turnErrorMessage ?? "sub-agent turn failed");
+            }
+            const output = chunks.join("");
+            entry.status = "completed";
+            entry.result = output;
+            entry.endedAt = Date.now();
+            entry.durationMs = entry.endedAt - entry.startedAt;
+            await this.store.updateStatus(entry.parentAgentId, entry.subId, {
+                status: "completed",
+                result: output,
+                endedAt: entry.endedAt,
+                durationMs: entry.durationMs,
+                contextSnapshot: undefined, // 完成后清空快照
+            });
+            this.emitEvent(entry.subId, "completed", { result: output });
+            entry.completionResolve?.({ output });
+            this.enqueueCompletion(entry, output, undefined);
+        }
+        catch (err) {
+            const errorMessage = err instanceof Error ? err.message : String(err);
+            entry.status = "failed";
+            entry.errorMessage = errorMessage;
+            entry.endedAt = Date.now();
+            entry.durationMs = entry.endedAt - entry.startedAt;
+            await this.store.updateStatus(entry.parentAgentId, entry.subId, {
+                status: "failed",
+                errorMessage,
+                endedAt: entry.endedAt,
+                durationMs: entry.durationMs,
+                contextSnapshot: undefined,
+            });
+            this.emitEvent(entry.subId, "failed", { error: errorMessage });
+            entry.completionResolve?.({ output: "", error: errorMessage });
+            this.enqueueCompletion(entry, "", errorMessage);
+        }
+        finally {
+            // 移除临时监听器
+            try {
+                entry.runtime.removeListener?.("event", onEvent);
+            }
+            catch {
+                /* 忽略移除失败 */
+            }
+            // 完成后清理 runtime 实例（释放内存），但保留 entry 供查询
+            try {
+                await entry.runtime.stop();
+            }
+            catch {
+                /* 忽略 stop 失败 */
+            }
+        }
+    }
+    /**
+     * 带 recheck 循环的 entry 执行（多轮 submit）。
+     *
+     * 与 runEntryToCompletion 的区别：
+     *   1. 第一轮 submit(entry.prompt) 完成后，调用 recheck 回调查询服务端真实状态
+     *   2. 若 recheck 返回 { done: false, continueMessage }，将 continueMessage 注入下一轮 submit
+     *   3. 最多重试 maxRetries 次；超过后视为完成（不再继续）
+     *   4. onEvent 监听器跨所有轮次累积 assistant_delta，最终 output 包含全部轮次的文本
+     *
+     * turnFailed 标志在每轮 submit 前重置，确保上一轮的失败状态不影响下一轮判断。
+     * recheck 自身抛错时视为 done（不阻塞 sub-agent 结束），仅记录日志。
+     */
+    async runEntryToCompletionWithRecheck(entry, recheck, maxRetries) {
+        const chunks = [];
+        let turnFailed = false;
+        let turnErrorMessage;
+        const onEvent = (event) => {
+            if (!event)
+                return;
+            switch (event.type) {
+                case "assistant_delta":
+                    if (typeof event.data?.text === "string") {
+                        chunks.push(event.data.text);
+                    }
+                    break;
+                case "turn_complete":
+                    if (event.data?.failed) {
+                        turnFailed = true;
+                    }
+                    break;
+                case "error":
+                    if (typeof event.data?.message === "string") {
+                        turnErrorMessage = event.data.message;
+                    }
+                    break;
+            }
+        };
+        entry.runtime.on("event", onEvent);
+        // 状态 -> running
+        entry.status = "running";
+        await this.store.updateStatus(entry.parentAgentId, entry.subId, { status: "running" });
+        this.emitEvent(entry.subId, "running", {});
+        try {
+            await entry.runtime.start();
+            entry.availableTools = entry.runtime.getAvailableTools();
+            // 第一轮：使用初始 prompt
+            await entry.runtime.submit(entry.prompt);
+            if (turnFailed) {
+                throw new Error(turnErrorMessage ?? "sub-agent turn failed");
+            }
+            let turn = 1;
+            // recheck 循环：最多 maxRetries 次
+            while (turn <= maxRetries) {
+                let recheckResult;
+                try {
+                    recheckResult = await recheck(chunks.join(""), turn);
+                }
+                catch (recheckErr) {
+                    // recheck 自身出错：不阻塞 sub-agent 结束，视为完成
+                    console.error(`[SubAgentManager] recheck threw error for subId=${entry.subId} turn=${turn}, treating as done:`, recheckErr instanceof Error ? recheckErr.message : String(recheckErr));
+                    break;
+                }
+                if (recheckResult.done) {
+                    break;
+                }
+                // 未完成：注入 continueMessage 进行下一轮
+                const continueMessage = recheckResult.continueMessage ?? "经检查，未完成处理，请继续。";
+                // 重置 turn 失败标记，确保本轮失败状态不影响下一轮判断
+                turnFailed = false;
+                turnErrorMessage = undefined;
+                console.error(`[SubAgentManager] recheck not done for subId=${entry.subId} turn=${turn}/${maxRetries}, ` +
+                    `injecting continue message (${continueMessage.length} chars)`);
+                await entry.runtime.submit(continueMessage);
+                if (turnFailed) {
+                    throw new Error(turnErrorMessage ?? `sub-agent turn ${turn + 1} failed during recheck continuation`);
+                }
+                turn++;
+            }
+            if (turn > maxRetries) {
+                console.error(`[SubAgentManager] recheck reached maxRetries=${maxRetries} for subId=${entry.subId}, ` +
+                    `completing with potentially unfinished work`);
+            }
+            const output = chunks.join("");
+            entry.status = "completed";
+            entry.result = output;
+            entry.endedAt = Date.now();
+            entry.durationMs = entry.endedAt - entry.startedAt;
+            await this.store.updateStatus(entry.parentAgentId, entry.subId, {
+                status: "completed",
+                result: output,
+                endedAt: entry.endedAt,
+                durationMs: entry.durationMs,
+                contextSnapshot: undefined,
+            });
+            this.emitEvent(entry.subId, "completed", { result: output });
+            entry.completionResolve?.({ output });
+            this.enqueueCompletion(entry, output, undefined);
+        }
+        catch (err) {
+            const errorMessage = err instanceof Error ? err.message : String(err);
+            entry.status = "failed";
+            entry.errorMessage = errorMessage;
+            entry.endedAt = Date.now();
+            entry.durationMs = entry.endedAt - entry.startedAt;
+            await this.store.updateStatus(entry.parentAgentId, entry.subId, {
+                status: "failed",
+                errorMessage,
+                endedAt: entry.endedAt,
+                durationMs: entry.durationMs,
+                contextSnapshot: undefined,
+            });
+            this.emitEvent(entry.subId, "failed", { error: errorMessage });
+            entry.completionResolve?.({ output: "", error: errorMessage });
+            this.enqueueCompletion(entry, "", errorMessage);
+        }
+        finally {
+            // 移除临时监听器
+            try {
+                entry.runtime.removeListener?.("event", onEvent);
+            }
+            catch {
+                /* 忽略移除失败 */
+            }
+            // 完成后清理 runtime 实例（释放内存），但保留 entry 供查询
+            try {
+                await entry.runtime.stop();
+            }
+            catch {
+                /* 忽略 stop 失败 */
+            }
+        }
+    }
+    /**
+     * @deprecated 兼容旧接口：spawn + 阻塞等待完成。
+     * 新代码应使用 spawn + start + awaitCompletion。
+     */
+    async runToCompletion(subId) {
+        const entry = this.subAgents.get(subId);
+        if (!entry) {
+            throw new Error(`sub-agent not found: ${subId}`);
+        }
+        if (entry.status === "running") {
+            throw new Error(`sub-agent already running: ${subId}`);
+        }
+        // 重置 status 以便 runEntryToCompletion 能进入 running
+        if (entry.status !== "pending") {
+            entry.status = "pending";
+        }
+        await this.start(subId);
+        return (await entry.completionPromise) ?? { output: "", error: "not started" };
+    }
+    /** 取消运行中的 sub-agent */
+    async abort(subId) {
+        const entry = this.subAgents.get(subId);
+        if (!entry)
+            return;
+        if (entry.status === "completed" || entry.status === "failed" || entry.status === "cancelled") {
+            return;
+        }
+        entry.abortController.abort();
+        try {
+            await entry.runtime.abort();
+        }
+        catch {
+            /* 忽略 */
+        }
+        entry.status = "cancelled";
+        entry.endedAt = Date.now();
+        entry.durationMs = entry.endedAt - entry.startedAt;
+        await this.store.updateStatus(entry.parentAgentId, subId, {
+            status: "cancelled",
+            endedAt: entry.endedAt,
+            durationMs: entry.durationMs,
+            contextSnapshot: undefined,
+        });
+        this.emitEvent(subId, "cancelled", {});
+        // settle completionPromise（cancelled 视为 error）
+        entry.completionResolve?.({ output: "", error: "aborted" });
+        this.enqueueCompletion(entry, "", "aborted");
+    }
+    /** 获取内存中的 entry */
+    getSubAgent(subId) {
+        return this.subAgents.get(subId);
+    }
+    /** 列出某 agent 的全部内存中 sub-agent（含运行中和已完成未清理） */
+    listByParent(parentAgentId) {
+        const subIds = this.parentToSubs.get(parentAgentId);
+        if (!subIds)
+            return [];
+        return Array.from(subIds)
+            .map((id) => this.subAgents.get(id))
+            .filter((e) => e !== undefined);
+    }
+    /**
+     * 列出某父 agent 下处于活跃状态（pending / running）的 sub-agent。
+     *
+     * 已完成/失败/取消的 entry 在内存中仍保留 TTL=30min 供查询，但不应计入
+     * "进行中" 列表。前端 "进行中" tab 与 SSE snapshot 都应使用此方法。
+     */
+    listActiveByParent(parentAgentId) {
+        return this.listByParent(parentAgentId).filter((e) => e.status === "pending" || e.status === "running");
+    }
+    /**
+     * 取走并清空终态通知队列。
+     *
+     * 主流程：返回 completionQueue 中的所有通知并清空队列。
+     * 供 ACode 运行时在 poll_message 调用前后检查子 agent 是否已完成。
+     * 每次 poll_message 调用前先调此方法，若有已完成子 agent 则直接返回，无需等待 MCP。
+     */
+    takeCompletedSubAgents() {
+        if (this.completionQueue.length === 0)
+            return [];
+        const drained = this.completionQueue.splice(0);
+        return drained;
+    }
+    /**
+     * 等待任意子 agent 到达终态（completed/failed/cancelled）。
+     *
+     * 主流程：如果 completionQueue 中已有通知，立即 resolve；
+     * 否则注册一个 resolve 回调，在下次子 agent 终态事件到达时触发。
+     * 供 ACode 运行时在 poll_message 期间 race 子 agent 完成事件。
+     *
+     * 返回 { promise, cancel }：
+     * - promise: 子 agent 终态时 resolve
+     * - cancel: 取消等待（poll_message 先返回时调用，清理 resolve 回调）
+     */
+    waitForAnyCompletion() {
+        // 如果队列中已有通知，立即返回
+        if (this.completionQueue.length > 0) {
+            const notif = this.completionQueue.shift();
+            return {
+                promise: Promise.resolve(notif),
+                cancel: () => { },
+            };
+        }
+        let cancelled = false;
+        const promise = new Promise((resolve) => {
+            this.completionWaiterResolve = (notif) => {
+                if (!cancelled)
+                    resolve(notif);
+            };
+        });
+        const cancel = () => {
+            cancelled = true;
+            this.completionWaiterResolve = null;
+        };
+        return { promise, cancel };
+    }
+    /** 订阅 sub-agent 事件（subId 或 "*" 全局） */
+    subscribe(subId, cb) {
+        let set = this.subscribers.get(subId);
+        if (!set) {
+            set = new Set();
+            this.subscribers.set(subId, set);
+        }
+        set.add(cb);
+        return () => {
+            set?.delete(cb);
+            if (set && set.size === 0)
+                this.subscribers.delete(subId);
+        };
+    }
+    /** 清理所有运行中的 sub-agent（bridge 关闭时调用） */
+    async dispose() {
+        if (this.cleanupTimer) {
+            clearInterval(this.cleanupTimer);
+            this.cleanupTimer = null;
+        }
+        const entries = Array.from(this.subAgents.values());
+        await Promise.allSettled(entries.map((e) => this.abort(e.subId)));
+        this.subAgents.clear();
+        this.parentToSubs.clear();
+        this.subscribers.clear();
+    }
+    // ---------- 内部方法 ----------
+    /**
+     * 将子 agent 终态事件入队并通知等待者。
+     * 主流程：构建通知对象 -> 入队 completionQueue -> 若有 waitForAnyCompletion 等待者则立即 resolve。
+     */
+    enqueueCompletion(entry, output, error) {
+        // 静默完成或已被 awaitCompletion 消费的子 agent 不进入 completionQueue
+        if (entry.silent || entry.awaited) {
+            return;
+        }
+        const notif = {
+            subId: entry.subId,
+            subagentType: entry.subagentType,
+            description: entry.description,
+            status: entry.status,
+            output,
+            error,
+            durationMs: entry.durationMs,
+        };
+        this.completionQueue.push(notif);
+        // 如果有 poll_message 正在等待子 agent 完成事件，立即通知
+        if (this.completionWaiterResolve) {
+            const resolve = this.completionWaiterResolve;
+            this.completionWaiterResolve = null;
+            // 从队列中取出刚入队的通知（即此条）
+            const queued = this.completionQueue.pop();
+            resolve(queued ?? notif);
+        }
+    }
+    countByStatus(parentAgentId, ...statuses) {
+        return this.listByParent(parentAgentId).filter((e) => statuses.includes(e.status)).length;
+    }
+    addToParentMap(parentAgentId, subId) {
+        let set = this.parentToSubs.get(parentAgentId);
+        if (!set) {
+            set = new Set();
+            this.parentToSubs.set(parentAgentId, set);
+        }
+        set.add(subId);
+    }
+    removeFromParentMap(parentAgentId, subId) {
+        const set = this.parentToSubs.get(parentAgentId);
+        if (set) {
+            set.delete(subId);
+            if (set.size === 0)
+                this.parentToSubs.delete(parentAgentId);
+        }
+    }
+    /**
+     * 清理已超过 TTL 的终态 entry（completed/failed/cancelled）。
+     * 释放内存，store 仍保留历史记录供查询。
+     */
+    cleanupCompletedEntries() {
+        const now = Date.now();
+        for (const [subId, entry] of this.subAgents) {
+            if ((entry.status === "completed" || entry.status === "failed" || entry.status === "cancelled") &&
+                entry.endedAt &&
+                now - entry.endedAt > COMPLETED_ENTRY_TTL_MS) {
+                this.subAgents.delete(subId);
+                this.removeFromParentMap(entry.parentAgentId, subId);
+            }
+        }
+    }
+    /** 从 store 中查找记录（entry 已从内存清理时使用） */
+    async findRecordInStore(subId) {
+        // store 按父 agent 组织，无法直接按 subId 查；遍历所有 parent
+        // 注意：此方法仅在 awaitCompletion 时调用，频率低
+        for (const parentAgentId of this.parentToSubs.keys()) {
+            const doc = await this.store.read(parentAgentId);
+            const record = doc.subAgents.find((r) => r.subId === subId);
+            if (record)
+                return record;
+        }
+        return undefined;
+    }
+    handleRuntimeEvent(subId, event) {
+        const entry = this.subAgents.get(subId);
+        if (!entry)
+            return;
+        // 更新 contextSnapshot
+        const snapshot = entry.contextSnapshot;
+        snapshot.updatedAt = new Date().toISOString();
+        switch (event?.type) {
+            case "ai_request":
+                // estimatedContextTokens 是请求前的上下文估算，可作为 input 近似值
+                if (event.data?.estimatedContextTokens != null) {
+                    snapshot.tokenUsage.input = (event.data.estimatedContextTokens ?? snapshot.tokenUsage.input);
+                }
+                break;
+            case "turn_complete":
+                // turn_complete 携带实际的 token 用量，覆盖 ai_request 的估算值
+                if (event.data?.usage) {
+                    snapshot.tokenUsage.input = (event.data.usage.inputTokens ?? snapshot.tokenUsage.input);
+                    snapshot.tokenUsage.output = (event.data.usage.outputTokens ?? snapshot.tokenUsage.output);
+                }
+                else if (event.data?.failed || event.data?.aborted) {
+                    // 失败/中止路径不携带 usage，重置 output 避免残留上一轮值
+                    snapshot.tokenUsage.output = 0;
+                }
+                break;
+            case "assistant_delta":
+                // 累积文本，截断到最近 500 字符
+                snapshot.lastAssistantText = ((snapshot.lastAssistantText ?? "") + (event.data?.text ?? "")).slice(-500);
+                snapshot.messageCount += 1;
+                this.emitEvent(subId, "delta", { text: event.data?.text });
+                break;
+            case "mcp_status":
+                // runtime 发射的 mcp_status 使用 action 字段（而非 phase）
+                if (event.data?.action === "call_tool") {
+                    snapshot.currentTool = event.data?.tool;
+                    this.emitEvent(subId, "tool_start", { tool: snapshot.currentTool, snapshot: { ...snapshot } });
+                }
+                else if (event.data?.action === "tool_result") {
+                    this.emitEvent(subId, "tool_end", { tool: snapshot.currentTool, snapshot: { ...snapshot } });
+                    snapshot.currentTool = undefined;
+                }
+                break;
+            case "session_complete":
+                snapshot.messageCount += 1;
+                break;
+        }
+    }
+    emitEvent(subId, type, data) {
+        const event = {
+            type,
+            subId,
+            timestamp: new Date().toISOString(),
+            data,
+        };
+        // 通知该 subId 的订阅者
+        const subs = this.subscribers.get(subId);
+        if (subs) {
+            for (const cb of subs) {
+                try {
+                    cb(event);
+                }
+                catch {
+                    /* 忽略订阅者错误 */
+                }
+            }
+        }
+        // 通知全局订阅者
+        const globalSubs = this.subscribers.get("*");
+        if (globalSubs) {
+            for (const cb of globalSubs) {
+                try {
+                    cb(event);
+                }
+                catch {
+                    /* 忽略 */
+                }
+            }
+        }
+        // tool_start / tool_end 异步落盘（fire-and-forget，不阻塞事件发射）
+        if (type === "tool_start" || type === "tool_end") {
+            const entry = this.subAgents.get(subId);
+            if (entry) {
+                console.error(`[SubAgentManager] appendEvent: subId=${subId} type=${type} tool=${data.tool ?? "?"} parentAgentId=${entry.parentAgentId}`);
+                void this.store.appendEvent(entry.parentAgentId, subId, event).catch((err) => {
+                    console.error(`[SubAgentManager] appendEvent FAILED: subId=${subId} error=${err instanceof Error ? err.message : String(err)}`);
+                });
+            }
+            else {
+                console.error(`[SubAgentManager] appendEvent SKIPPED (entry not found): subId=${subId} type=${type}`);
+            }
+        }
+    }
+    toRecord(entry) {
+        return {
+            subId: entry.subId,
+            parentAgentId: entry.parentAgentId,
+            parentSessionId: entry.parentSessionId,
+            subagentType: entry.subagentType,
+            description: entry.description,
+            prompt: entry.prompt,
+            status: entry.status,
+            result: entry.result,
+            errorMessage: entry.errorMessage,
+            startedAt: entry.startedAt,
+            endedAt: entry.endedAt,
+            durationMs: entry.durationMs,
+            contextSnapshot: entry.status === "running" ? entry.contextSnapshot : undefined,
+            availableTools: entry.availableTools,
+        };
+    }
+    /** 获取当前上下文快照（供 HTTP 路由调用） */
+    getContextSnapshot(subId) {
+        return this.subAgents.get(subId)?.contextSnapshot;
+    }
+}