@cicctencent/agent-core 0.1.30 → 0.1.33

package/dist/cjs/agent/engine.d.ts

@@ -10,6 +10,10 @@ export declare class AgentEngine {
     private abortMap;
     /** sessionId → steering messages（实时转向队列） */
     private steeringMap;
+    /** parentSessionId → Set<childSessionId>（父子会话关系跟踪，用于级联 abort） */
+    private childSessionMap;
+    /** childSessionId → parentSessionId（反向索引，用于快速查找父会话） */
+    private parentSessionMap;
     /** 子模块：历史管理器 */
     private historyManager;
     /** 子模块：LLM 调用器 */
@@ -26,6 +30,8 @@ export declare class AgentEngine {
     private outputTools;
     /** Guard 策略配置（阈值可注入，不硬编码业务逻辑） */
     private guardConfig;
+    /** 错误恢复策略配置 */
+    private errorRecovery;
     constructor(config: AgentConfig);
     /** 获取当前 Agent 的 ToolRegistry（供 read_tool_doc 等内置工具使用） */
     getToolRegistry(): ToolRegistry;
@@ -65,6 +71,29 @@ export declare class AgentEngine {
     forkHistory(sourceSessionId: string, targetSessionId: string, fromIndex?: number): number;
     /** 获取会话历史的消息数量 */
     getHistoryLength(sessionId: string): number;
+    /**
+     * 注册父子会话关系。
+     *
+     * 典型场景：主 Agent 通过 delegate_task 工具派生子任务时，
+     * 上层调用此方法将子会话与父会话关联。当父会话因异常终止时，
+     * 如果配置了 `cascadeAbortChildren`，所有子会话也会被自动 abort。
+     *
+     * @param parentSessionId 父会话 ID
+     * @param childSessionId 子会话 ID
+     */
+    linkChildSession(parentSessionId: string, childSessionId: string): void;
+    /**
+     * 解除父子会话关系（子会话完成后调用）。
+     */
+    unlinkChildSession(childSessionId: string): void;
+    /**
+     * 获取指定父会话的所有子会话 ID。
+     */
+    getChildSessions(parentSessionId: string): string[];
+    /**
+     * 获取指定子会话的父会话 ID（如有）。
+     */
+    getParentSession(childSessionId: string): string | undefined;
     /**
      * 执行 Agent 任务（流式推送事件）
      * 上层通过 for-await-of 消费事件流
@@ -105,6 +134,12 @@ export declare class AgentEngine {
     private refreshSummaryCache;
     /** 获取工具定义列表（含预过滤 + 渐进式发现） */
     private resolveToolDefs;
+    /**
+     * 将工具定义转为摘要形式（截断 description + 清空 parameters）。
+     * @param def 原始工具定义
+     * @param scope 摘要范围：'mcp'=仅MCP工具摘要, 'all'=所有传入工具摘要, null=保持原样
+     */
+    private summarizeToolDef;
     /** 构建 ToolContext */
     private buildToolContext;
     /** 汇总准备阶段，生成 LoopState */
@@ -161,10 +196,38 @@ export declare class AgentEngine {
     private emitDone;
     /** 中断指定会话的 Agent 执行 */
     abort(sessionId: string): void;
+    /**
+     * 中断指定会话及其所有子会话的 Agent 执行（级联 abort）。
+     *
+     * 递归遍历子会话树，从叶子节点到根节点依次 abort。
+     * 用于确保父会话异常终止时，所有 delegate_task 派生的子任务也被终止。
+     */
+    abortCascade(sessionId: string): void;
     /** 查询指定会话的 Agent 状态 */
     getStatus(sessionId: string): AgentStatus;
     /** 销毁引擎，释放所有会话资源 */
     destroy(): void;
+    /**
+     * 统一的致命错误处理入口。
+     *
+     * 由引擎内部（agentLoop、catch 块）在遇到不可恢复错误时调用。
+     * 按以下顺序执行：
+     * 1. 调用 config.errorRecovery.onFatalError 回调（允许上层记录/通知）
+     * 2. 如果 config.errorRecovery.autoAbortOnFatal，abort 当前会话
+     * 3. 如果 config.errorRecovery.cascadeAbortChildren，级联 abort 所有子会话
+     *
+     * @param error 致命错误信息（含 sessionId）
+     */
+    private handleFatalError;
+    /**
+     * 清理指定会话的父子关系记录。
+     *
+     * 在会话自然完成或 abort 后调用，防止内存泄漏。
+     * 处理两个方向：
+     * - 如果是父会话：移除所有子会话引用（但子会话若仍在运行则保留其关系）
+     * - 如果是子会话：从父会话的子集中移除自身
+     */
+    private cleanupSessionRelations;
     createEvent(sessionId: string, event: Record<string, unknown>): AgentEvent;
     private createNoopShell;
 }

package/dist/cjs/agent/engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../../src/agent/engine.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../../src/agent/engine.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,OAAO,EAAoE,MAAM,aAAa,CAAC;AAItI,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAoD,MAAM,YAAY,CAAC;AAE5G,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AA4H5E,qBAAa,WAAW;IACtB,OAAO,CAAC,MAAM,CAA4G;IAC1H,8BAA8B;IAC9B,OAAO,CAAC,SAAS,CAAkC;IACnD,6CAA6C;IAC7C,OAAO,CAAC,QAAQ,CAAsC;IACtD,4CAA4C;IAC5C,OAAO,CAAC,WAAW,CAA+B;IAClD,iEAAiE;IACjE,OAAO,CAAC,eAAe,CAAkC;IACzD,uDAAuD;IACvD,OAAO,CAAC,gBAAgB,CAA6B;IAErD,gBAAgB;IAChB,OAAO,CAAC,cAAc,CAAiB;IACvC,kBAAkB;IAClB,OAAO,CAAC,SAAS,CAAY;IAC7B,gBAAgB;IAChB,OAAO,CAAC,YAAY,CAAoB;IAExC,wEAAwE;IACxE,OAAO,CAAC,YAAY,CAAuE;IAC3F,aAAa;IACb,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,iBAAiB,CAAO;IAEhD,wBAAwB;IACxB,OAAO,CAAC,cAAc,CAAc;IACpC,iCAAiC;IACjC,OAAO,CAAC,WAAW,CAAc;IAEjC,iCAAiC;IACjC,OAAO,CAAC,WAAW,CAAwB;IAE3C,eAAe;IACf,OAAO,CAAC,aAAa,CAAgC;gBAEzC,MAAM,EAAE,WAAW;IAyE/B,yDAAyD;IACzD,eAAe,IAAI,YAAY;IAI/B,2CAA2C;IAC3C,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAInC,mEAAmE;IACnE,eAAe,IAAI,OAAO,qBAAqB,EAAE,YAAY,GAAG,SAAS;IAIzE;;;OAGG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,IAAI;IAIxD;;OAEG;IACH,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,EAAE;IAIhD;;;;OAIG;IACG,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAItD;;;;;OAKG;IACH,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM;IAI3D;;;;;;OAMG;IACH,WAAW,CAAC,eAAe,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM;IAIzF,kBAAkB;IAClB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM;IAM3C;;;;;;;;;OASG;IACH,gBAAgB,CAAC,eAAe,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,IAAI;IAWvE;;OAEG;IACH,kBAAkB,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI;IAUhD;;OAEG;IACH,gBAAgB,CAAC,eAAe,EAAE,MAAM,GAAG,MAAM,EAAE;IAInD;;OAEG;IACH,gBAAgB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAI5D;;;OAGG;IACI,GAAG,CAAC,OAAO,EAAE,UAAU,GAAG,cAAc,CAAC,UAAU,CAAC;IAiD3D,0CAA0C;YAC5B,YAAY;IAiB1B,wCAAwC;YAC1B,oBAAoB;IAiFlC;;;;;;;;;;;;;;;OAeG;YACW,oBAAoB;IAsGlC;;;OAGG;YACW,gBAAgB;IAqC9B;;;;;OAKG;YACW,mBAAmB;IAmBjC,6BAA6B;IAC7B,OAAO,CAAC,eAAe;IAgCvB;;;;OAIG;IACH,OAAO,CAAC,gBAAgB;IA2BxB,qBAAqB;IACrB,OAAO,CAAC,gBAAgB;IAmBxB,0BAA0B;YACZ,UAAU;IAyBxB,sCAAsC;YACvB,SAAS;IAoNxB;;;OAGG;IACH,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO;IASlD,yCAAyC;IACzC,OAAO,CAAC,aAAa;IAgBrB;;;;OAIG;IACH,OAAO,CAAC,mBAAmB;IAoB3B;;;;OAIG;IACH,OAAO,CAAC,oBAAoB;IA4C5B;;;;;;OAMG;IACH,OAAO,CAAC,kBAAkB;IAmC1B,wBAAwB;IACxB,OAAO,CAAC,oBAAoB;IAsC5B;;;;OAIG;IACH,OAAO,CAAC,uBAAuB;IAuB/B;;;;OAIG;IACH,OAAO,CAAC,sBAAsB;IA2B9B,uBAAuB;IACjB,QAAQ,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAkBzE,6BAA6B;YACf,kBAAkB;IAwBhC,yCAAyC;IACnC,sBAAsB,CAAC,KAAK,EAAE,cAAc,GAAG,aAAa,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAqB5G,OAAO,CAAC,QAAQ;IAgChB,uBAAuB;IACvB,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAS9B;;;;;OAKG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAarC,uBAAuB;IACvB,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,WAAW;IAIzC,oBAAoB;IACpB,OAAO,IAAI,IAAI;IAef;;;;;;;;;;OAUG;YACW,gBAAgB;IAyC9B;;;;;;;OAOG;IACH,OAAO,CAAC,uBAAuB;IAc/B,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,UAAU;IAI1E,OAAO,CAAC,eAAe;CAOxB"}

package/dist/cjs/agent/engine.js

@@ -11,8 +11,31 @@ const history_manager_ts_1 = require("./history-manager.js");
 const llm_caller_ts_1 = require("./llm-caller.js");
 const tool_executor_ts_1 = require("./tool-executor.js");
 const logger_ts_1 = require("../observability/logger.js");
+const rate_limit_manager_ts_1 = require("./rate-limit-manager.js");
 /** 默认系统提示词 */
 const DEFAULT_BASE_PROMPT = `You are a helpful AI assistant with access to tools. Use tools when needed to accomplish tasks. Always explain your actions clearly.`;
+/**
+ * 核心工具集（summary-all 模式下保持全量 schema 的工具）。
+ *
+ * 这些工具是 Agent 执行绝大多数任务的基础（文件读写、代码搜索、命令执行、
+ * 工具发现、委托派发），必须让 LLM 看到完整参数 schema 以保证调用可靠性。
+ * 非核心工具（通讯、日历、自动化、文档生成等）仅以摘要形式呈现，
+ * LLM 需通过 read_tool_doc 获取完整 schema 后再调用。
+ */
+const CORE_TOOL_NAMES = new Set([
+    'read_file',
+    'write_file',
+    'edit_file',
+    'append_file',
+    'search_code',
+    'execute_command',
+    'run_script',
+    'read_terminal',
+    'read_tool_doc',
+    'read_tool_result',
+    'read_offload',
+    'delegate_task',
+]);
 /** 进度叙述规则（追加到 system prompt，引导 LLM 在工具调用间输出可见文本）— 可通过 AgentConfig.progressNarrationRules 覆盖 */
 const DEFAULT_PROGRESS_NARRATION_RULES = `
 
@@ -85,6 +108,10 @@ class AgentEngine {
     abortMap = new Map();
     /** sessionId → steering messages（实时转向队列） */
     steeringMap = new Map();
+    /** parentSessionId → Set<childSessionId>（父子会话关系跟踪，用于级联 abort） */
+    childSessionMap = new Map();
+    /** childSessionId → parentSessionId（反向索引，用于快速查找父会话） */
+    parentSessionMap = new Map();
     /** 子模块：历史管理器 */
     historyManager;
     /** 子模块：LLM 调用器 */
@@ -101,6 +128,8 @@ class AgentEngine {
     outputTools;
     /** Guard 策略配置（阈值可注入，不硬编码业务逻辑） */
     guardConfig;
+    /** 错误恢复策略配置 */
+    errorRecovery;
     constructor(config) {
         this.config = {
             ...config,
@@ -159,6 +188,13 @@ class AgentEngine {
             delegateTargets: gc.delegateTargets ?? {},
             iterationGuardPrompt: gc.iterationGuardPrompt ?? '',
         };
+        // 初始化错误恢复策略
+        const er = config.errorRecovery ?? {};
+        this.errorRecovery = {
+            autoAbortOnFatal: er.autoAbortOnFatal ?? true,
+            cascadeAbortChildren: er.cascadeAbortChildren ?? false,
+            onFatalError: er.onFatalError ?? undefined,
+        };
     }
     /** 获取当前 Agent 的 ToolRegistry（供 read_tool_doc 等内置工具使用） */
     getToolRegistry() {
@@ -216,6 +252,51 @@ class AgentEngine {
     getHistoryLength(sessionId) {
         return this.historyManager.getHistoryLength(sessionId);
     }
+    // ---- 父子会话关系管理 ----
+    /**
+     * 注册父子会话关系。
+     *
+     * 典型场景：主 Agent 通过 delegate_task 工具派生子任务时，
+     * 上层调用此方法将子会话与父会话关联。当父会话因异常终止时，
+     * 如果配置了 `cascadeAbortChildren`，所有子会话也会被自动 abort。
+     *
+     * @param parentSessionId 父会话 ID
+     * @param childSessionId 子会话 ID
+     */
+    linkChildSession(parentSessionId, childSessionId) {
+        if (!this.childSessionMap.has(parentSessionId)) {
+            this.childSessionMap.set(parentSessionId, new Set());
+        }
+        this.childSessionMap.get(parentSessionId).add(childSessionId);
+        this.parentSessionMap.set(childSessionId, parentSessionId);
+        // 通知 RateLimitManager 建立父子映射（用于 429 终止主会话时定位父会话）
+        rate_limit_manager_ts_1.rateLimitManager.registerSubSession(childSessionId, parentSessionId);
+        (0, logger_ts_1.logEvent)({ event: 'engine.child_linked', sessionId: parentSessionId, data: { childSessionId } });
+    }
+    /**
+     * 解除父子会话关系（子会话完成后调用）。
+     */
+    unlinkChildSession(childSessionId) {
+        const parentId = this.parentSessionMap.get(childSessionId);
+        if (parentId) {
+            this.childSessionMap.get(parentId)?.delete(childSessionId);
+            this.parentSessionMap.delete(childSessionId);
+        }
+        // 通知 RateLimitManager 注销子会话，释放并发槽位
+        rate_limit_manager_ts_1.rateLimitManager.unregisterSubSession(childSessionId);
+    }
+    /**
+     * 获取指定父会话的所有子会话 ID。
+     */
+    getChildSessions(parentSessionId) {
+        return Array.from(this.childSessionMap.get(parentSessionId) ?? []);
+    }
+    /**
+     * 获取指定子会话的父会话 ID（如有）。
+     */
+    getParentSession(childSessionId) {
+        return this.parentSessionMap.get(childSessionId);
+    }
     /**
      * 执行 Agent 任务（流式推送事件）
      * 上层通过 for-await-of 消费事件流
@@ -225,6 +306,8 @@ class AgentEngine {
         // ① Abort 控制
         const internalAbort = new AbortController();
         this.abortMap.set(sessionId, internalAbort);
+        // 注册到 RateLimitManager，使其能在多轮冷却失败时终止主会话
+        rate_limit_manager_ts_1.rateLimitManager.registerMainSession(sessionId, internalAbort);
         const onExternalAbort = () => internalAbort.abort();
         if (abortSignal) {
             if (abortSignal.aborted)
@@ -246,6 +329,15 @@ class AgentEngine {
                 error: errorMsg,
                 recoverable: false,
             });
+            // 致命错误 → 自动 abort + 级联清理
+            await this.handleFatalError({
+                sessionId,
+                errorType: 'unexpected_exception',
+                error: errorMsg,
+                timestamp: Date.now(),
+                iteration: 0,
+                rawError: err,
+            });
             this.statusMap.set(sessionId, 'idle');
         }
         finally {
@@ -253,6 +345,8 @@ class AgentEngine {
                 abortSignal.removeEventListener('abort', onExternalAbort);
             this.abortMap.delete(sessionId);
             this.steeringMap.delete(sessionId);
+            // 注销主会话，清理限流状态和子会话映射
+            rate_limit_manager_ts_1.rateLimitManager.unregisterMainSession(sessionId);
         }
     }
     // ---- 准备阶段 ----
@@ -539,32 +633,51 @@ ${textHistory.join('\n')}`;
             const denied = new Set(this.config.deniedTools);
             defs = defs.filter(d => !denied.has(d.function.name));
         }
-        if (this.config.toolDiscovery === 'summary') {
+        const discovery = this.config.toolDiscovery;
+        // summary 模式：仅 MCP 工具摘要
+        if (discovery === 'summary') {
+            defs = defs.map(d => this.summarizeToolDef(d, 'mcp'));
+        }
+        // summary-all 模式：所有非核心工具摘要（MCP + 非核心内置工具）
+        if (discovery === 'summary-all') {
+            const coreOverride = this.config.coreToolNames
+                ? new Set(this.config.coreToolNames)
+                : CORE_TOOL_NAMES;
             defs = defs.map(d => {
-                const tool = this.config.toolRegistry.get(d.function.name);
-                if (tool?.category === 'mcp') {
-                    const maxDesc = this.config.toolSummaryMaxDesc ?? 100;
-                    const desc = d.function.description.length > maxDesc
-                        ? d.function.description.slice(0, maxDesc) + '...'
-                        : d.function.description;
-                    return {
-                        type: 'function',
-                        function: {
-                            name: d.function.name,
-                            description: desc + ` (use read_tool_doc to get full schema before calling; use read_tool_doc(tool_name="list") to see all available tools)`,
-                            parameters: {
-                                type: 'object',
-                                properties: {},
-                                required: [],
-                            },
-                        },
-                    };
-                }
-                return d;
+                const isCore = coreOverride.has(d.function.name);
+                return this.summarizeToolDef(d, isCore ? null : 'all');
             });
         }
         return defs;
     }
+    /**
+     * 将工具定义转为摘要形式（截断 description + 清空 parameters）。
+     * @param def 原始工具定义
+     * @param scope 摘要范围：'mcp'=仅MCP工具摘要, 'all'=所有传入工具摘要, null=保持原样
+     */
+    summarizeToolDef(def, scope) {
+        if (scope === null)
+            return def;
+        const tool = this.config.toolRegistry.get(def.function.name);
+        if (scope === 'mcp' && tool?.category !== 'mcp')
+            return def;
+        const maxDesc = this.config.toolSummaryMaxDesc ?? 100;
+        const desc = def.function.description.length > maxDesc
+            ? def.function.description.slice(0, maxDesc) + '...'
+            : def.function.description;
+        return {
+            type: 'function',
+            function: {
+                name: def.function.name,
+                description: desc + ` (use read_tool_doc to get full schema before calling; use read_tool_doc(tool_name="list") to see all available tools)`,
+                parameters: {
+                    type: 'object',
+                    properties: {},
+                    required: [],
+                },
+            },
+        };
+    }
     // ---- 准备阶段（续） ----
     /** 构建 ToolContext */
     buildToolContext(options, internalAbort) {
@@ -623,12 +736,21 @@ ${textHistory.join('\n')}`;
                 const budgetCheck = this.config.usageTracker.checkBudget(state.sessionId, this.config.tokenBudget);
                 if (budgetCheck.exceeded) {
                     if (this.config.tokenBudget.onExceed === 'abort') {
+                        const budgetErrMsg = `Token budget exceeded (${budgetCheck.currentTokens}/${budgetCheck.maxTokens} tokens). Task aborted to prevent cost overrun.`;
                         (0, logger_ts_1.logEvent)({ event: 'engine.token_budget_exceeded', sessionId: state.sessionId, level: 'warn', data: { current: budgetCheck.currentTokens, max: budgetCheck.maxTokens, action: 'abort' } });
                         yield this.createEvent(state.sessionId, {
                             type: 'error',
-                            error: `Token budget exceeded (${budgetCheck.currentTokens}/${budgetCheck.maxTokens} tokens). Task aborted to prevent cost overrun.`,
+                            error: budgetErrMsg,
                             recoverable: false,
                         });
+                        // 致命错误 → 自动 abort + 级联清理
+                        await this.handleFatalError({
+                            sessionId: state.sessionId,
+                            errorType: 'token_budget_exceeded',
+                            error: budgetErrMsg,
+                            timestamp: Date.now(),
+                            iteration: state.iteration,
+                        });
                         yield this.emitDone(state);
                         return;
                     }
@@ -674,8 +796,17 @@ ${textHistory.join('\n')}`;
                 // 所有 LLM provider 均已失败（callWithRetry 内部已重试+降级），
                 // 不再发 done 事件（callWithRetry 已发出带详细错误信息的 error 事件），
                 // 仅完成清理，避免 done 事件覆盖前端已展示的错误消息
+                const errorMsg = 'All LLM providers exhausted (all calls failed including retries and fallback)';
                 (0, logger_ts_1.logEvent)({ event: 'engine.llm_exhausted', sessionId: state.sessionId, level: 'warn', data: { iteration: state.iteration } });
                 this.statusMap.set(state.sessionId, 'idle');
+                // 致命错误 → 自动 abort + 级联清理（级联清理子 Agent 运行中的子任务）
+                await this.handleFatalError({
+                    sessionId: state.sessionId,
+                    errorType: 'llm_exhausted',
+                    error: errorMsg,
+                    timestamp: Date.now(),
+                    iteration: state.iteration,
+                });
                 // 记录 Token 用量到 UsageTracker
                 if (this.config.usageTracker && state.totalUsage) {
                     const modelInfo = this.config.llmProvider.getModel();
@@ -748,7 +879,16 @@ ${textHistory.join('\n')}`;
                 if (allFailed) {
                     state.consecutiveAllFailIterations++;
                     if (state.consecutiveAllFailIterations >= this.guardConfig.consecutiveAllFailThreshold) {
+                        const failMsg = `All tool calls failed for ${state.consecutiveAllFailIterations} consecutive iterations`;
                         (0, logger_ts_1.logEvent)({ event: 'engine.global_fail_breaker', sessionId: state.sessionId, level: 'warn', data: { consecutiveFails: state.consecutiveAllFailIterations, iteration: state.iteration } });
+                        // 致命错误 → 自动 abort + 级联清理
+                        await this.handleFatalError({
+                            sessionId: state.sessionId,
+                            errorType: 'all_tools_failed',
+                            error: failMsg,
+                            timestamp: Date.now(),
+                            iteration: state.iteration,
+                        });
                         yield this.emitDone(state);
                         return;
                     }
@@ -1059,6 +1199,8 @@ ${textHistory.join('\n')}`;
     // ---- 辅助 ----
     emitDone(state) {
         this.statusMap.set(state.sessionId, 'idle');
+        // 会话正常结束时清理父子关系（不级联 abort，子会话可自行运行完成）
+        this.cleanupSessionRelations(state.sessionId);
         // 记录 Token 用量到 UsageTracker
         if (this.config.usageTracker && state.totalUsage) {
             const modelInfo = this.config.llmProvider.getModel();
@@ -1089,7 +1231,24 @@ ${textHistory.join('\n')}`;
         if (controller) {
             controller.abort();
             this.statusMap.set(sessionId, 'aborting');
+            (0, logger_ts_1.logEvent)({ event: 'engine.abort', sessionId, data: { reason: 'abort() called' } });
+        }
+    }
+    /**
+     * 中断指定会话及其所有子会话的 Agent 执行（级联 abort）。
+     *
+     * 递归遍历子会话树，从叶子节点到根节点依次 abort。
+     * 用于确保父会话异常终止时，所有 delegate_task 派生的子任务也被终止。
+     */
+    abortCascade(sessionId) {
+        this.abort(sessionId);
+        // 遍历直接子会话，递归 abort
+        const children = this.getChildSessions(sessionId);
+        for (const childId of children) {
+            this.abortCascade(childId);
         }
+        // 清理父子关系
+        this.cleanupSessionRelations(sessionId);
     }
     /** 查询指定会话的 Agent 状态 */
     getStatus(sessionId) {
@@ -1103,9 +1262,81 @@ ${textHistory.join('\n')}`;
         this.abortMap.clear();
         this.statusMap.clear();
         this.steeringMap.clear();
+        this.childSessionMap.clear();
+        this.parentSessionMap.clear();
         this.summaryCache.clear();
         this.historyManager.clearAll();
     }
+    // ---- 致命错误处理 ----
+    /**
+     * 统一的致命错误处理入口。
+     *
+     * 由引擎内部（agentLoop、catch 块）在遇到不可恢复错误时调用。
+     * 按以下顺序执行：
+     * 1. 调用 config.errorRecovery.onFatalError 回调（允许上层记录/通知）
+     * 2. 如果 config.errorRecovery.autoAbortOnFatal，abort 当前会话
+     * 3. 如果 config.errorRecovery.cascadeAbortChildren，级联 abort 所有子会话
+     *
+     * @param error 致命错误信息（含 sessionId）
+     */
+    async handleFatalError(error) {
+        (0, logger_ts_1.logEvent)({
+            event: 'engine.fatal_error',
+            sessionId: error.sessionId,
+            level: 'error',
+            data: {
+                errorType: error.errorType,
+                error: error.error,
+                iteration: error.iteration,
+                autoAbort: this.errorRecovery.autoAbortOnFatal,
+                cascadeAbort: this.errorRecovery.cascadeAbortChildren,
+            },
+        });
+        // ① 外部回调通知（不阻塞后续清理流程）
+        if (this.errorRecovery.onFatalError) {
+            try {
+                await this.errorRecovery.onFatalError(error);
+            }
+            catch (e) {
+                // 回调异常不影响后续清理流程
+                (0, logger_ts_1.logEvent)({
+                    event: 'engine.fatal_error_callback_failed',
+                    sessionId: error.sessionId,
+                    level: 'warn',
+                    data: { error: e?.message || String(e) },
+                });
+            }
+        }
+        // ② 自动 abort 当前会话
+        if (this.errorRecovery.autoAbortOnFatal) {
+            if (this.errorRecovery.cascadeAbortChildren) {
+                // 级联 abort：终止当前会话及其所有子孙会话
+                this.abortCascade(error.sessionId);
+            }
+            else {
+                // 仅 abort 当前会话
+                this.abort(error.sessionId);
+            }
+        }
+    }
+    /**
+     * 清理指定会话的父子关系记录。
+     *
+     * 在会话自然完成或 abort 后调用，防止内存泄漏。
+     * 处理两个方向：
+     * - 如果是父会话：移除所有子会话引用（但子会话若仍在运行则保留其关系）
+     * - 如果是子会话：从父会话的子集中移除自身
+     */
+    cleanupSessionRelations(sessionId) {
+        // 从父会话的子集中移除自身
+        const parentId = this.parentSessionMap.get(sessionId);
+        if (parentId) {
+            this.childSessionMap.get(parentId)?.delete(sessionId);
+            this.parentSessionMap.delete(sessionId);
+        }
+        // 删除自身作为父会话的所有子关系记录（但保留子会话本身仍在运行）
+        this.childSessionMap.delete(sessionId);
+    }
     // ---- 内部辅助 ----
     createEvent(sessionId, event) {
         return { ...event, timestamp: Date.now(), sessionId };