@cicctencent/agent-core 0.1.28 → 0.1.31

package/dist/cjs/a2a/rest-runner.d.ts

@@ -1,5 +1,13 @@
 import type { SubAgentRunner } from '../tool/delegate.js';
 import type { RestA2AClient } from './rest-client.js';
+/** 远程 Capability 的 input_schema 片段（供 runner 拆解 JSON 打包的 task） */
+export interface RestInputSchema {
+    type?: string;
+    /** input_schema.required 字段名列表 */
+    required?: string[];
+    /** input_schema.properties，值为各字段的 schema 定义（含 type/description/enum 等） */
+    properties?: Record<string, unknown>;
+}
 /** createRestA2ARemoteRunner 配置项 */
 export interface RestA2ARemoteRunnerConfig {
     /** 远程 Agent 的 base URL（如 http://localhost:8000） */
@@ -16,6 +24,14 @@ export interface RestA2ARemoteRunnerConfig {
     staticFields?: Record<string, string>;
     /** 任务字符串映射到的字段名（默认 'analysis_focus'） */
     taskField?: string;
+    /**
+     * 允许 LLM 动态填写的字段名列表（来自 input_schema 的 properties 键）。
+     * - 缺省时仅 taskField 为动态，其余走 staticFields（与旧行为一致）。
+     * - 配置后，当 LLM 把 task 打包成 JSON 对象时，这些键会被合并进最终 input。
+     */
+    dynamicFields?: string[];
+    /** 远程 Capability 的 input_schema 片段，用于校验/白名单动态字段及生成 LLM 引导文案 */
+    inputSchema?: RestInputSchema;
     /** 是否启用流式（默认 true） */
     streaming?: boolean;
     /** 流式失败时是否自动回退到同步模式，默认 true */

package/dist/cjs/a2a/rest-runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rest-runner.d.ts","sourceRoot":"","sources":["../../../src/a2a/rest-runner.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D,OAAO,KAAK,EAAE,aAAa,EAAsC,MAAM,kBAAkB,CAAC;AAE1F,oCAAoC;AACpC,MAAM,WAAW,yBAAyB;IACxC,mDAAmD;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,4CAA4C;IAC5C,YAAY,EAAE,MAAM,CAAC;IACrB,sBAAsB;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,4BAA4B;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,qBAAqB;IACrB,MAAM,EAAE,aAAa,CAAC;IACtB,0EAA0E;IAC1E,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,wCAAwC;IACxC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sBAAsB;IACtB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,+BAA+B;IAC/B,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,yBAAyB,GAAG,cAAc,CA8F3F"}
+{"version":3,"file":"rest-runner.d.ts","sourceRoot":"","sources":["../../../src/a2a/rest-runner.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D,OAAO,KAAK,EAAE,aAAa,EAAsC,MAAM,kBAAkB,CAAC;AAE1F,iEAAiE;AACjE,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kCAAkC;IAClC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,0EAA0E;IAC1E,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED,oCAAoC;AACpC,MAAM,WAAW,yBAAyB;IACxC,mDAAmD;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,4CAA4C;IAC5C,YAAY,EAAE,MAAM,CAAC;IACrB,sBAAsB;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,4BAA4B;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,qBAAqB;IACrB,MAAM,EAAE,aAAa,CAAC;IACtB,0EAA0E;IAC1E,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,wCAAwC;IACxC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,+DAA+D;IAC/D,WAAW,CAAC,EAAE,eAAe,CAAC;IAC9B,sBAAsB;IACtB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,+BAA+B;IAC/B,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,yBAAyB,GAAG,cAAc,CAsK3F"}

package/dist/cjs/a2a/rest-runner.js

@@ -22,11 +22,61 @@ exports.createRestA2ARemoteRunner = createRestA2ARemoteRunner;
  *   - error → error
  */
 function createRestA2ARemoteRunner(config) {
-    const { baseUrl, capabilityId, name: runnerName, description: runnerDesc, client, staticFields = {}, taskField = 'analysis_focus', streaming = true, fallbackToSync = true, } = config;
-    /** 将 task 字符串构建为请求输入 */
+    const { baseUrl, capabilityId, name: runnerName, description: runnerDesc, client, staticFields = {}, taskField = 'analysis_focus', dynamicFields, inputSchema, streaming = true, fallbackToSync = true, } = config;
+    /**
+     * 允许 LLM 动态填写的字段白名单。
+     * - 优先用 dynamicFields；
+     * - 缺省时退化为 inputSchema 的所有 properties 键；
+     * - 都没有则只保留 taskField。
+     * taskField 永远视为动态字段。
+     */
+    const allowedDynamicFields = Array.from(new Set([
+        taskField,
+        ...(dynamicFields && dynamicFields.length
+            ? dynamicFields
+            : (inputSchema?.properties ? Object.keys(inputSchema.properties) : [])),
+    ]));
+    /**
+     * 将 task 字符串构建为请求输入。
+     *
+     * 支持两种形态：
+     * 1. task 为普通字符串 → 映射到 taskField（旧行为，向后兼容）。
+     * 2. task 为 JSON 对象字符串（如 '{"analysis_focus":"...","competitors":"..."}'）
+     *    → 解析后把属于 allowedDynamicFields 的键合并进 input（覆盖静态默认值），
+     *      其余键忽略，避免污染请求体。
+     *
+     * 静态字段始终作为基础值先行铺底，动态字段在后覆盖。
+     */
     function buildInput(task) {
-        const input = { ...staticFields, [taskField]: task };
-        console.log(`[REST-A2A] '${runnerName}' buildInput:\n  baseUrl: ${baseUrl}\n  capabilityId: ${capabilityId}\n  taskField: ${taskField}\n  task (value): ${JSON.stringify(task)}\n  staticFields: ${JSON.stringify(staticFields)}\n  => final input: ${JSON.stringify(input, null, 2)}`);
+        const input = { ...staticFields };
+        const trimmed = (task ?? '').trim();
+        const looksLikeJson = trimmed.startsWith('{') && trimmed.endsWith('}');
+        let parsedTask = null;
+        if (looksLikeJson) {
+            try {
+                const parsed = JSON.parse(trimmed);
+                if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                    parsedTask = parsed;
+                }
+            }
+            catch { /* 非法 JSON，按纯文本处理 */ }
+        }
+        if (parsedTask) {
+            for (const key of allowedDynamicFields) {
+                if (parsedTask[key] !== undefined && parsedTask[key] !== null) {
+                    input[key] = parsedTask[key];
+                }
+            }
+            // 若解析出的对象未命中任何动态字段，则把整段原文回填到 taskField，避免丢内容
+            const hitAny = allowedDynamicFields.some(k => parsedTask[k] !== undefined && parsedTask[k] !== null);
+            if (!hitAny) {
+                input[taskField] = task;
+            }
+        }
+        else {
+            input[taskField] = task;
+        }
+        console.log(`[REST-A2A] '${runnerName}' buildInput:\n  baseUrl: ${baseUrl}\n  capabilityId: ${capabilityId}\n  taskField: ${taskField}\n  dynamicFields: [${allowedDynamicFields.join(', ')}]\n  task (value): ${JSON.stringify(task)}\n  staticFields: ${JSON.stringify(staticFields)}\n  => final input: ${JSON.stringify(input, null, 2)}`);
         return input;
     }
     /** 从 RestCapabilityResult 中提取最终文本 */
@@ -85,9 +135,26 @@ function createRestA2ARemoteRunner(config) {
             return `[REST A2A '${runnerName}'] Error: ${errMsg}`;
         }
     };
+    // 暴露给 delegate_task 用于生成 LLM 引导文案的动态字段元数据。
+    // 仅当存在多个动态字段（>1，即不止 taskField）时才填充，避免单字段场景产生噪音。
+    const inputFields = allowedDynamicFields.length > 1
+        ? allowedDynamicFields.map(name => {
+            const prop = inputSchema?.properties?.[name];
+            const propDef = (prop && typeof prop === 'object' ? prop : {});
+            const rawType = propDef.type;
+            const type = Array.isArray(rawType) ? rawType.filter(Boolean).join('|') : (typeof rawType === 'string' ? rawType : 'string');
+            return {
+                name,
+                required: inputSchema?.required?.includes(name) ?? false,
+                description: typeof propDef.description === 'string' ? propDef.description : '',
+                type,
+            };
+        })
+        : undefined;
     return {
         name: runnerName,
         description: runnerDesc,
+        inputFields,
         run: async (task, ctx, _options) => {
             return streaming && ctx?.emitSubEvent
                 ? runStreaming(task, ctx)

package/dist/cjs/a2a/rest-runner.js.map

@@ -1 +1 @@
-{"version":3,"file":"rest-runner.js","sourceRoot":"","sources":["../../../src/a2a/rest-runner.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"rest-runner.js","sourceRoot":"","sources":["../../../src/a2a/rest-runner.ts"],"names":[],"mappings":"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"}

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 消费事件流
@@ -161,10 +190,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":"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"}

package/dist/cjs/agent/engine.js

@@ -11,6 +11,7 @@ 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.`;
 /** 进度叙述规则（追加到 system prompt，引导 LLM 在工具调用间输出可见文本）— 可通过 AgentConfig.progressNarrationRules 覆盖 */
@@ -85,6 +86,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 +106,8 @@ class AgentEngine {
     outputTools;
     /** Guard 策略配置（阈值可注入，不硬编码业务逻辑） */
     guardConfig;
+    /** 错误恢复策略配置 */
+    errorRecovery;
     constructor(config) {
         this.config = {
             ...config,
@@ -159,6 +166,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 +230,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 +284,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 +307,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 +323,8 @@ class AgentEngine {
                 abortSignal.removeEventListener('abort', onExternalAbort);
             this.abortMap.delete(sessionId);
             this.steeringMap.delete(sessionId);
+            // 注销主会话，清理限流状态和子会话映射
+            rate_limit_manager_ts_1.rateLimitManager.unregisterMainSession(sessionId);
         }
     }
     // ---- 准备阶段 ----
@@ -623,12 +695,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 +755,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 +838,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 +1158,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,8 +1190,25 @@ ${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) {
         return this.statusMap.get(sessionId) || 'idle';
@@ -1103,9 +1221,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 };