aws-runtime-bridge 1.9.33 → 1.9.40

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

@@ -0,0 +1,535 @@
+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;
+        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）
+        const childConfig = {
+            ...opts.parentConfig,
+            sessionId: subId,
+            workingDirectory: opts.workingDirectory,
+            agentId: `${opts.parentAgentId}__sub__${subId}`,
+            // sub-agent 不继承 initialPrompt（用 submit 触发）
+            initialPrompt: 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,
+            contextSnapshot: {
+                tokenUsage: { input: 0, output: 0 },
+                messageCount: 0,
+                updatedAt: new Date().toISOString(),
+            },
+        };
+        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
+        });
+    }
+    /**
+     * 阻塞等待指定 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;
+            }
+            // 如果还在 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,
+                });
+            }
+        });
+        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();
+            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 });
+        }
+        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 });
+        }
+        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" });
+    }
+    /** 获取内存中的 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");
+    }
+    /** 订阅 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();
+    }
+    // ---------- 内部方法 ----------
+    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":
+                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 });
+                }
+                else if (event.data?.action === "tool_result") {
+                    this.emitEvent(subId, "tool_end", { tool: snapshot.currentTool });
+                    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 {
+                    /* 忽略 */
+                }
+            }
+        }
+    }
+    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,
+        };
+    }
+    /** 获取当前上下文快照（供 HTTP 路由调用） */
+    getContextSnapshot(subId) {
+        return this.subAgents.get(subId)?.contextSnapshot;
+    }
+}

package/package/acode/dist/sub-agent-store.d.ts

@@ -0,0 +1,33 @@
+import type { SubAgentDocument, SubAgentRecord } from "./sub-agent-types.js";
+/**
+ * Sub Agent JSON 文件存储，按 agentId 隔离。
+ * 文件路径：{homedir}/.acode/sub-agents/{agentId}.json
+ *
+ * 设计与 TodoStore 完全同构：
+ *   - 不依赖 agent 工作目录，避免 workspacePath 错误时读取失败
+ *   - sub-agent 跟随 agent（agentId），不跟随项目工作区
+ *   - 写操作通过 Promise 链串行化，tmp + rename 原子替换
+ *
+ * 历史保留策略：全部 sub-agent 记录都持久化（含 completed/failed/cancelled），
+ *   按 startedAt 倒序排列。dashboard 按需分页读取。
+ */
+export declare class SubAgentStore {
+    private readonly dir;
+    private writeChain;
+    constructor();
+    /** 文件路径（按 agentId 隔离，防路径穿越） */
+    private filePath;
+    /** 读取该 agentId 的完整文档。文件不存在或损坏时返回空文档。 */
+    read(agentId: string): Promise<SubAgentDocument>;
+    /** 读取单个 sub-agent 记录 */
+    get(agentId: string, subId: string): Promise<SubAgentRecord | null>;
+    /** 全量替换该 agentId 的文档。串行化以避免并发覆盖。 */
+    write(agentId: string, subAgents: SubAgentRecord[]): Promise<void>;
+    /** 插入或更新单条记录（保留其他记录） */
+    upsert(agentId: string, record: SubAgentRecord): Promise<void>;
+    /** 部分更新单条记录 */
+    updateStatus(agentId: string, subId: string, patch: Partial<SubAgentRecord>): Promise<void>;
+    /** 列出该 agent 的全部 sub-agent（已按 startedAt 倒序） */
+    list(agentId: string): Promise<SubAgentRecord[]>;
+}
+//# sourceMappingURL=sub-agent-store.d.ts.map

package/package/acode/dist/sub-agent-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sub-agent-store.d.ts","sourceRoot":"","sources":["../src/sub-agent-store.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE7E;;;;;;;;;;;GAWG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,UAAU,CAAoC;;IAMtD,+BAA+B;IAC/B,OAAO,CAAC,QAAQ;IAKhB,wCAAwC;IAClC,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAoBtD,wBAAwB;IAClB,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAKzE,oCAAoC;IAC9B,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAiBxE,wBAAwB;IAClB,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAWpE,eAAe;IACT,YAAY,CAChB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,OAAO,CAAC,cAAc,CAAC,GAC7B,OAAO,CAAC,IAAI,CAAC;IAQhB,+CAA+C;IACzC,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;CAGvD"}

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

@@ -0,0 +1,109 @@
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+/**
+ * Sub Agent JSON 文件存储，按 agentId 隔离。
+ * 文件路径：{homedir}/.acode/sub-agents/{agentId}.json
+ *
+ * 设计与 TodoStore 完全同构：
+ *   - 不依赖 agent 工作目录，避免 workspacePath 错误时读取失败
+ *   - sub-agent 跟随 agent（agentId），不跟随项目工作区
+ *   - 写操作通过 Promise 链串行化，tmp + rename 原子替换
+ *
+ * 历史保留策略：全部 sub-agent 记录都持久化（含 completed/failed/cancelled），
+ *   按 startedAt 倒序排列。dashboard 按需分页读取。
+ */
+export class SubAgentStore {
+    constructor() {
+        this.writeChain = Promise.resolve();
+        this.dir = path.join(os.homedir(), ".acode", "sub-agents");
+    }
+    /** 文件路径（按 agentId 隔离，防路径穿越） */
+    filePath(agentId) {
+        const safe = String(agentId).replace(/[^a-zA-Z0-9_-]/g, "_");
+        return path.join(this.dir, `${safe}.json`);
+    }
+    /** 读取该 agentId 的完整文档。文件不存在或损坏时返回空文档。 */
+    async read(agentId) {
+        const empty = { agentId, updatedAt: "", subAgents: [] };
+        try {
+            const raw = await fs.readFile(this.filePath(agentId), "utf-8");
+            const doc = JSON.parse(raw);
+            return {
+                agentId,
+                updatedAt: typeof doc.updatedAt === "string" ? doc.updatedAt : "",
+                subAgents: Array.isArray(doc.subAgents)
+                    ? doc.subAgents.filter(isValidRecord)
+                        .sort((a, b) => b.startedAt - a.startedAt)
+                    : [],
+            };
+        }
+        catch (err) {
+            if (err && err.code === "ENOENT")
+                return empty;
+            if (err instanceof SyntaxError)
+                return empty;
+            throw err;
+        }
+    }
+    /** 读取单个 sub-agent 记录 */
+    async get(agentId, subId) {
+        const doc = await this.read(agentId);
+        return doc.subAgents.find((r) => r.subId === subId) ?? null;
+    }
+    /** 全量替换该 agentId 的文档。串行化以避免并发覆盖。 */
+    async write(agentId, subAgents) {
+        const target = this.filePath(agentId);
+        const run = this.writeChain.then(async () => {
+            await fs.mkdir(this.dir, { recursive: true });
+            const doc = {
+                agentId,
+                updatedAt: new Date().toISOString(),
+                subAgents: subAgents.sort((a, b) => b.startedAt - a.startedAt),
+            };
+            const tmp = `${target}.tmp`;
+            await fs.writeFile(tmp, JSON.stringify(doc, null, 2), "utf-8");
+            await fs.rename(tmp, target);
+        });
+        this.writeChain = run.catch(() => { });
+        await run;
+    }
+    /** 插入或更新单条记录（保留其他记录） */
+    async upsert(agentId, record) {
+        const doc = await this.read(agentId);
+        const idx = doc.subAgents.findIndex((r) => r.subId === record.subId);
+        if (idx >= 0) {
+            doc.subAgents[idx] = record;
+        }
+        else {
+            doc.subAgents.unshift(record);
+        }
+        await this.write(agentId, doc.subAgents);
+    }
+    /** 部分更新单条记录 */
+    async updateStatus(agentId, subId, patch) {
+        const doc = await this.read(agentId);
+        const idx = doc.subAgents.findIndex((r) => r.subId === subId);
+        if (idx < 0)
+            return;
+        doc.subAgents[idx] = { ...doc.subAgents[idx], ...patch };
+        await this.write(agentId, doc.subAgents);
+    }
+    /** 列出该 agent 的全部 sub-agent（已按 startedAt 倒序） */
+    async list(agentId) {
+        return (await this.read(agentId)).subAgents;
+    }
+}
+/** 运行时校验记录结构（防损坏文件污染内存） */
+function isValidRecord(r) {
+    return (r !== null &&
+        typeof r === "object" &&
+        typeof r.subId === "string" &&
+        typeof r.parentAgentId === "string" &&
+        typeof r.parentSessionId === "string" &&
+        typeof r.subagentType === "string" &&
+        typeof r.description === "string" &&
+        typeof r.prompt === "string" &&
+        typeof r.status === "string" &&
+        typeof r.startedAt === "number");
+}