@cicctencent/agent-core 1.0.34 → 1.0.37

package/dist/cjs/agent/engine.js

@@ -13,30 +13,11 @@ 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 compaction_ts_1 = require("./compaction.js");
+const tool_section_builder_ts_1 = require("./tool-section-builder.js");
+const guard_controller_ts_1 = require("./guard-controller.js");
+const session_state_manager_ts_1 = require("./session-state-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 = `
 
@@ -102,10 +83,14 @@ class AgentEngine {
     abortMap = new Map();
     /** sessionId → steering messages（实时转向队列） */
     steeringMap = new Map();
+    /** sessionId -> pause state (user pause: agent loop suspends at turn boundary until resume) */
+    pauseMap = new Map();
     /** parentSessionId → Set<childSessionId>（父子会话关系跟踪，用于级联 abort） */
     childSessionMap = new Map();
     /** childSessionId → parentSessionId（反向索引，用于快速查找父会话） */
     parentSessionMap = new Map();
+    /** 被摘要化的工具名集合（progressive loading：这些工具的 prompt 不注入 system prompt） */
+    summarizedToolNames = new Set();
     /** 子模块：历史管理器 */
     historyManager;
     /** 子模块：LLM 调用器 */
@@ -126,6 +111,33 @@ class AgentEngine {
     guardConfig;
     /** 错误恢复策略配置 */
     errorRecovery;
+    /** 为 ToolSectionBuilder 提供依赖 */
+    get toolSectionDeps() {
+        return { config: this.config, summarizedToolNames: this.summarizedToolNames };
+    }
+    /** 为 GuardController 提供依赖 */
+    get guardControllerDeps() {
+        return {
+            historyManager: this.historyManager,
+            dataFetchTools: this.dataFetchTools,
+            outputTools: this.outputTools,
+            guardConfig: this.guardConfig,
+            maxIterations: this.config.maxIterations,
+            hasTool: (name) => this.hasTool(name),
+            runHooks: (event, ctx) => this.runHooks(event, ctx),
+        };
+    }
+    /** 为 SessionStateManager 提供依赖 */
+    get sessionStateDeps() {
+        return {
+            abortMap: this.abortMap,
+            steeringMap: this.steeringMap,
+            statusMap: this.statusMap,
+            childSessionMap: this.childSessionMap,
+            parentSessionMap: this.parentSessionMap,
+            historyManager: this.historyManager,
+        };
+    }
     constructor(config) {
         this.config = {
             ...config,
@@ -163,6 +175,9 @@ class AgentEngine {
             createEvent: this.createEvent.bind(this),
             historyManager: this.historyManager,
             getMiddleware: () => this.config.middleware,
+            // 流式工具早分发：存在 before_tool hook / onToolBefore middleware 时禁用（防 block/modify 语义被绕过）
+            hasBeforeToolInterceptors: () => (this.config.hooks ?? []).some((h) => h.event === 'before_tool') ||
+                (this.config.middleware ?? []).some((m) => m.onToolBefore !== undefined),
         });
         // 初始化工具分类集合（可通过 config 覆盖默认值）
         this.dataFetchTools = new Set(config.dataFetchTools ?? [
@@ -176,8 +191,7 @@ class AgentEngine {
         // 模型在收尾阶段无法再用它读取 data/ 下的结果文件。
         // 若某 agent 仍需将其纳入数据获取循环检测，可在 AgentConfig.dataFetchTools 中显式加回。
         this.outputTools = new Set(config.outputTools ?? [
-            'delegate_task', 'create_presentation', 'create_document',
-            'create_pdf', 'create_report', 'show_widget', 'save_artifact',
+            'delegate_task', 'create_document', 'show_widget', 'save_artifact',
         ]);
         // 外部数据源获取工具（用于数据出处水印判定，仅含真正访问外部/实时数据源的工具，
         // 不含 read_file 等本地读取——本地读取不构成「实时数据核验」但也不代表数据源失败）
@@ -371,6 +385,8 @@ class AgentEngine {
                 abortSignal.removeEventListener('abort', onExternalAbort);
             this.abortMap.delete(sessionId);
             this.steeringMap.delete(sessionId);
+            // 清理暂停状态（run 结束后不再保留标志）
+            this.pauseMap.delete(sessionId);
             // 注销主会话，清理限流状态和子会话映射
             rate_limit_manager_ts_1.rateLimitManager.unregisterMainSession(sessionId);
         }
@@ -694,67 +710,19 @@ ${textHistory.join('\n')}`;
     // ---- 工具定义 ----
     /** 获取工具定义列表（含预过滤 + 渐进式发现） */
     resolveToolDefs(options) {
-        const toolNames = [...(this.config.defaultTools || []), ...(options.extraTools || [])];
-        let defs = toolNames.length > 0
-            ? this.config.toolRegistry.getDefinitions({ names: toolNames })
-            : this.config.toolRegistry.getDefinitions();
-        if (this.config.deniedTools?.length) {
-            const denied = new Set(this.config.deniedTools);
-            defs = defs.filter(d => !denied.has(d.function.name));
-        }
-        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 isCore = coreOverride.has(d.function.name);
-                return this.summarizeToolDef(d, isCore ? null : 'all');
-            });
-        }
-        return defs;
+        return (0, tool_section_builder_ts_1.resolveToolDefs)(this.toolSectionDeps, options);
     }
     /**
      * 将工具定义转为摘要形式（截断 description + 清空 parameters）。
-     * 实现抽离至 ./compaction.ts，保持单一来源。
+     * 实现抽离至 ./tool-section-builder.ts -> compaction.ts，保持单一来源。
      */
     summarizeToolDef(def, scope) {
-        return (0, compaction_ts_1.summarizeToolDef)(def, {
-            scope,
-            maxDesc: this.config.toolSummaryMaxDesc ?? 100,
-            getCategory: (name) => this.config.toolRegistry.get(name)?.category,
-        });
+        return (0, tool_section_builder_ts_1.summarizeToolDefImpl)(this.toolSectionDeps, def, scope);
     }
     // ---- 准备阶段（续） ----
     /** 构建 ToolContext */
     buildToolContext(options, internalAbort) {
-        const custom = options.context?.custom;
-        return {
-            sessionId: options.sessionId,
-            shell: custom?.shell || this.createNoopShell(),
-            fs: custom?.fs,
-            env: options.context?.env,
-            abortSignal: internalAbort.signal,
-            custom: {
-                ...custom,
-                // Fix A：始终使用引擎授权注册表（已按 selectedTools/disabledTools 过滤），
-                // 不接受 custom.toolRegistry 覆盖——防止 read_tool_doc/diagnose 泄漏被禁工具 schema。
-                toolRegistry: this.config.toolRegistry,
-                skillManager: custom?.skillManager ?? this.config.skillManager,
-            },
-            emitSubEvent: custom?.emitSubEvent,
-            emitWidget: custom?.emitWidget,
-            emitArtifact: custom?.emitArtifact,
-            emitToolLog: custom?.emitToolLog,
-            emitToolHeartbeat: custom?.emitToolHeartbeat,
-            toolTimeout: this.config.toolTimeout,
-            maxScriptTimeoutMs: this.config.maxScriptTimeoutMs,
-        };
+        return (0, tool_section_builder_ts_1.buildToolContext)(this.toolSectionDeps, options, internalAbort);
     }
     /** 汇总准备阶段，生成 LoopState */
     async prepareRun(options, internalAbort) {
@@ -788,33 +756,14 @@ ${textHistory.join('\n')}`;
             hadFatalError: false,
             fatalErrorMsg: undefined,
             stableSystemPrompt,
+            // 请求级覆盖 Profile 级（AgentConfig.responseFormat）
+            responseFormat: options.responseFormat ?? this.config.responseFormat,
         };
     }
     /** 动态构建工具区 prompt（Available Tools + Tool Usage Guidelines）。
      * 从 state.toolDefs 现场拼装，确保与可执行工具集一致，消除静态穿透。 */
     buildDynamicToolSection(toolDefs) {
-        if (this.config.buildToolSection) {
-            return this.config.buildToolSection(toolDefs, this.config.toolRegistry);
-        }
-        if (toolDefs.length === 0)
-            return '';
-        // 可用工具名集合：用于占位符 {{TOOL:name}} 渲染时判定引用是否真实可用
-        const available = new Set(toolDefs.map(d => d.function.name));
-        const lines = toolDefs.map(d => `- \`${d.function.name}\`: ${this.renderToolRefs(d.function.description || '', available)}`);
-        let section = `\n\n## Available Tools\n${lines.join('\n')}`;
-        // 收集工具自带的使用引导（tool.prompt），并对其中对其他工具的引用做可用裁剪。
-        // tool.relatedTools 是声明式的「本工具引用的其它工具」清单，
-        // 用于：若某占位符 {{TOOL:x}} 未注册，则整段引用被剔除（见 renderToolRefs）。
-        const prompts = [];
-        for (const def of toolDefs) {
-            const tool = this.config.toolRegistry.get(def.function.name);
-            if (tool?.prompt)
-                prompts.push(this.renderToolRefs(tool.prompt, available, tool.relatedTools));
-        }
-        if (prompts.length > 0) {
-            section += `\n\n## Tool Usage Guidelines\n\n${prompts.join('\n\n')}`;
-        }
-        return section;
+        return (0, tool_section_builder_ts_1.buildDynamicToolSection)(this.toolSectionDeps, toolDefs);
     }
     /**
      * 渲染工具提示中对其它工具的引用，避免「提示穿透」：
@@ -829,51 +778,29 @@ ${textHistory.join('\n')}`;
      *   显式声明在 relatedTools 中的工具名也可被识别为「已知引用」参与裁剪。
      */
     renderToolRefs(text, available, relatedTools) {
-        // relatedTools 声明本工具引用的「其他工具」。占位符 {{TOOL:name}} 只有在
-        // - name 确实注册（available）时才渲染为 `name`；
-        // - 否则用哨兵标记，后续做子句级清除，避免留下 "do NOT call  after" 这类残缺。
-        // 不在 relatedTools 且未注册的占位符视为误写，保留原文。
-        const knownRefs = relatedTools && relatedTools.length > 0 ? new Set(relatedTools) : null;
-        const SENTINEL = '\x00'; // 哨兵：标记被剔除的占位符位置
-        // 1) 替换：可用 -> name；不可用且为已知引用 -> 哨兵；其余保留原文
-        let out = text.replace(/\{\{TOOL:([a-zA-Z0-9_-]+)\}\}/g, (m, name) => {
-            if (available.has(name))
-                return `\`${name}\``;
-            if (knownRefs && !knownRefs.has(name))
-                return m;
-            return SENTINEL;
-        });
-        // 2) 子句级清除：以 " - " 或 ", " 分隔的子句中含哨兵，则移除整个子句
-        out = out
-            .split(/(?<=\S)\s+-\s+|(?<=\S),\s+/)
-            .filter(clause => !clause.includes(SENTINEL))
-            .join(', ');
-        // 3) 行级清除：多行 prompt 中，整行仅剩哨兵/标点/空白的予以移除
-        out = out
-            .split('\n')
-            .filter(line => {
-            const trimmed = line.trim();
-            if (trimmed === '')
-                return true;
-            const meaningful = trimmed.replace(/[`.,;:()\-]+/g, '').replace(/\s+/g, '');
-            return meaningful.length > 0 && !trimmed.includes(SENTINEL);
-        })
-            .join('\n');
-        // 4) 清理残留哨兵 + 收缩多余空格
-        out = out.replace(/\x00/g, '').replace(/ {2,}/g, ' ').replace(/\s+\n/g, '\n').trim();
-        return out;
+        return (0, tool_section_builder_ts_1.renderToolRefs)(text, available, relatedTools);
     }
     /** 刷新 system prompt 中的工具区，确保与 state.toolDefs 一致 */
     refreshToolSection(state) {
-        if (state.messages[0] && state.stableSystemPrompt != null) {
-            state.messages[0].content = state.stableSystemPrompt + this.buildDynamicToolSection(state.toolDefs);
-        }
+        (0, tool_section_builder_ts_1.refreshToolSection)(this.toolSectionDeps, state);
     }
     // ---- Agent Loop ----
     /** 主循环：迭代调用 LLM → 执行工具 → 直到完成或达到上限 */
     async *agentLoop(state) {
         while (state.iteration < this.config.maxIterations) {
             state.iteration++;
+            // Pause checkpoint: when user pauses, the current tool/LLM call has finished;
+            // the agent loop exits gracefully before the next LLM call (stream ends normally).
+            // Resume is implemented by starting a NEW SSE stream that rebuilds context from
+            // persisted message history - no in-memory suspension (survives process restart).
+            if (this.pauseMap.get(state.sessionId)?.paused === true) {
+                // 清理暂停标志（恢复由新建流完成，不再唤醒本循环）
+                this.pauseMap.delete(state.sessionId);
+                yield this.createEvent(state.sessionId, { type: 'paused' });
+                // 正常结束 SSE 流（run 状态 ok，与 abort 的 error 收尾区分）
+                yield this.emitDone(state);
+                return;
+            }
             // 中断检查
             if (state.internalAbort.signal.aborted) {
                 // 外部中断（客户端断开 / 用户主动 abort / 看门狗超时）：标记致命错误，
@@ -970,8 +897,38 @@ ${textHistory.join('\n')}`;
             });
             // 调用 LLM（流式，含重试与降级）
             this.statusMap.set(state.sessionId, 'thinking');
+            // 流式工具早分发：本轮 LLM 调用的预执行缓存（重试/降级时由 onToolCallReset 重置）
+            state.earlyToolResults = new Map();
+            state.earlyExecutions = [];
             const llmStart = Date.now();
-            const { assistant, usage, observability } = yield* this.llmCaller.callWithRetry(state.sessionId, state.messages, state.toolDefs, state.internalAbort.signal);
+            // 透传 LLMCaller 事件流，同时捕获 error 事件的原始报文（服务商返回的 429/5xx 等），
+            // 用于 llm_exhausted 分支向用户透传服务商原始异常信息。
+            // 采用 next() 循环：转发所有 yield 事件，并在 done 时拿到 callWithRetry 的 return 值（assistant/usage/observability）。
+            let lastLlmErrorMsg;
+            const llmGen = this.llmCaller.callWithRetry(state.sessionId, state.messages, state.toolDefs, state.internalAbort.signal, {
+                // 工具调用参数聚合完成即预执行（纯优化：执行结果缓存后由 executeToolCalls 命中复用）
+                onToolCallReady: (tc) => this.toolExecutor.startEarlyExecution(state, tc),
+                onToolCallReset: () => {
+                    state.earlyToolResults = new Map();
+                    state.earlyExecutions = [];
+                },
+            }, state.responseFormat);
+            let llmResult = { assistant: null, usage: undefined, observability: undefined };
+            while (true) {
+                const { value: ev, done } = await llmGen.next();
+                if (done) {
+                    if (ev)
+                        llmResult = ev;
+                    break;
+                }
+                if (ev && ev.type === 'error' && ev.error) {
+                    lastLlmErrorMsg = ev.error;
+                }
+                yield ev;
+            }
+            const { assistant, usage, observability } = llmResult;
+            // 等待流中启动的预执行收尾（abort 场景同样先收尾再继续，保证资源不泄漏）
+            await this.toolExecutor.awaitEarlyExecutions(state);
             const llmDuration = Date.now() - llmStart;
             // 累加 Token 用量
             if (usage) {
@@ -981,6 +938,9 @@ ${textHistory.join('\n')}`;
                 state.totalUsage.promptTokens += usage.promptTokens || 0;
                 state.totalUsage.completionTokens += usage.completionTokens || 0;
                 state.totalUsage.totalTokens += usage.totalTokens || 0;
+                state.totalUsage.cacheReadTokens = (state.totalUsage.cacheReadTokens || 0) + (usage.cacheReadTokens || 0);
+                state.totalUsage.cacheWriteTokens = (state.totalUsage.cacheWriteTokens || 0) + (usage.cacheWriteTokens || 0);
+                state.totalUsage.reasoningTokens = (state.totalUsage.reasoningTokens || 0) + (usage.reasoningTokens || 0);
             }
             if (!assistant) {
                 // 所有 LLM provider 均已失败（callWithRetry 内部已重试+降级）。
@@ -989,7 +949,9 @@ ${textHistory.join('\n')}`;
                 // 前端 onDone 回调不触发（无法更新 UI 状态）。
                 // error 和 done 是不同的 SSE 事件类型，前端分别用 onError 和 onDone 处理，
                 // done 事件携带 lastContent（之前成功迭代的输出）或兜底总结，不会覆盖 error 消息。
-                const errorMsg = 'All LLM providers exhausted (all calls failed including retries and fallback)';
+                // 优先透传服务商原始异常报文（LLMCaller 经 error 事件发出的 429/5xx 原文，含 code 与重置时间等），
+                // 缺失时回退到固定概括文案，向后兼容。
+                const errorMsg = lastLlmErrorMsg || '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 运行中的子任务）
@@ -1187,6 +1149,9 @@ ${textHistory.join('\n')}`;
                 state.totalUsage.promptTokens += finalUsage.promptTokens || 0;
                 state.totalUsage.completionTokens += finalUsage.completionTokens || 0;
                 state.totalUsage.totalTokens += finalUsage.totalTokens || 0;
+                state.totalUsage.cacheReadTokens = (state.totalUsage.cacheReadTokens || 0) + (finalUsage.cacheReadTokens || 0);
+                state.totalUsage.cacheWriteTokens = (state.totalUsage.cacheWriteTokens || 0) + (finalUsage.cacheWriteTokens || 0);
+                state.totalUsage.reasoningTokens = (state.totalUsage.reasoningTokens || 0) + (finalUsage.reasoningTokens || 0);
             }
             if (finalAssistant) {
                 state.messages.push(finalAssistant);
@@ -1278,27 +1243,11 @@ ${textHistory.join('\n')}`;
      * 消息将在下次 LLM 调用前注入对话上下文
      */
     steer(sessionId, message) {
-        if (!this.abortMap.has(sessionId))
-            return false;
-        if (!this.steeringMap.has(sessionId)) {
-            this.steeringMap.set(sessionId, []);
-        }
-        this.steeringMap.get(sessionId).push(message);
-        return true;
+        return (0, session_state_manager_ts_1.steer)(this.sessionStateDeps, sessionId, message);
     }
     /** 消费当前会话的 steering 消息，注入到 messages 中 */
     drainSteering(state) {
-        const msgs = this.steeringMap.get(state.sessionId);
-        if (!msgs || msgs.length === 0)
-            return null;
-        const drained = [...msgs];
-        msgs.length = 0;
-        for (const msg of drained) {
-            const userMsg = { role: 'user', content: msg };
-            state.messages.push(userMsg);
-            this.historyManager.addHistory(state.sessionId, userMsg);
-        }
-        return { messages: drained, count: drained.length };
+        return (0, session_state_manager_ts_1.drainSteering)(this.sessionStateDeps, state);
     }
     /**
      * 进度叙述提醒
@@ -1306,23 +1255,7 @@ ${textHistory.join('\n')}`;
      * 确保用户在对话中有可见的文字输出，而不是所有内容都收在执行步骤中。
      */
     injectProgressNudge(state) {
-        const msg = {
-            role: 'user',
-            content: [
-                '[SYSTEM: PROGRESS NARRATION]',
-                '',
-                'You have been calling tools without providing visible text to the user.',
-                'Please provide a brief progress update in the user\'s language:',
-                '- What have you accomplished so far?',
-                '- What are you working on next?',
-                '- If you found important data, summarize the key findings.',
-                '',
-                'Keep it to 1-3 sentences. This text is displayed directly to the user.',
-            ].join('\n'),
-        };
-        state.messages.push(msg);
-        this.historyManager.addHistory(state.sessionId, msg);
-        (0, logger_ts_1.logEvent)({ event: 'engine.progress_nudge', sessionId: state.sessionId, data: { iteration: state.iteration } });
+        (0, guard_controller_ts_1.injectProgressNudge)(this.guardControllerDeps, state);
     }
     /**
      * 迭代预算提醒
@@ -1330,49 +1263,7 @@ ${textHistory.join('\n')}`;
      * 解决 agent 在数据查询循环中耗尽迭代、永远无法进入文档生成/委托阶段的问题。
      */
     injectIterationGuard(state) {
-        if (state.iterationGuardInjected)
-            return;
-        const max = this.config.maxIterations;
-        const cur = state.iteration;
-        const remaining = max - cur;
-        const ratio = cur / max;
-        if (ratio >= this.guardConfig.iterationGuardThreshold && remaining > 0) {
-            state.iterationGuardInjected = true;
-            const toolCallCount = state.toolCallRecords.length;
-            const targets = this.guardConfig.delegateTargets;
-            const reportAgent = targets.report ? `"${targets.report}"` : 'the appropriate report agent';
-            const docAgent = targets.document ? `"${targets.document}"` : 'the appropriate document agent';
-            const pptAgent = targets.presentation ? `"${targets.presentation}"` : docAgent;
-            // P1 #6: 使用可配置的提示文本，默认为通用英文提示（不绑定业务 Agent 名称）
-            // 仅引用当前 registry 实际注册的工具，避免引导 LLM 调用未绑定工具
-            const hasDelegate = this.hasTool('delegate_task');
-            const delegateLines = [];
-            if (hasDelegate) {
-                delegateLines.push(`   - For reports/dashboards: call \`delegate_task\` with agent ${reportAgent}.`);
-                delegateLines.push(`   - For documents: call \`delegate_task\` with agent ${docAgent}.`);
-                delegateLines.push(`   - For PPT: call \`delegate_task\` with agent ${pptAgent}.`);
-            }
-            const promptText = this.guardConfig.iterationGuardPrompt || [
-                `[SYSTEM ITERATION BUDGET: iteration ${cur}/${max}, ${remaining} remaining]`,
-                '',
-                `⚠️ You have used ${cur} of ${max} iterations (${toolCallCount} tool calls). Budget is running low.`,
-                '',
-                '**MANDATORY rules for remaining iterations — violating these will result in task failure:**',
-                '1. **STOP all data gathering immediately.** You already have enough data from previous tool calls.',
-                '2. **DO NOT call web_fetch, execute_command, write_file, or run_script again.**',
-                ...(hasDelegate ? [`3. **NOW delegate remaining work (only if the user explicitly requested file/document generation):**`, ...delegateLines] : []),
-                '4. If you cannot delegate, produce the final output NOW with the data you have.',
-                '5. **Do NOT proactively generate files (PPT/PDF/HTML/Word) unless the user explicitly asked for them.** If the user only asked for analysis or information, present your findings directly in the conversation as text/markdown.',
-                '',
-                'Do NOT write any more scripts or fetch any more data. Your data collection phase is OVER.',
-            ].join('\n');
-            const msg = { role: 'user', content: promptText };
-            state.messages.push(msg);
-            this.historyManager.addHistory(state.sessionId, msg);
-            (0, logger_ts_1.logEvent)({ event: 'engine.iteration_guard', sessionId: state.sessionId, data: { iteration: cur, max } });
-            // 硬性禁用数据获取工具，防止 LLM 无视文字提示继续调用
-            this.disableDataFetchTools(state);
-        }
+        (0, guard_controller_ts_1.injectIterationGuard)(this.guardControllerDeps, state);
     }
     /**
      * 从可用工具列表中移除数据获取类工具，强制 LLM 转向产出。
@@ -1380,20 +1271,7 @@ ${textHistory.join('\n')}`;
      * 仅移除尚未执行的 toolDefs，不影响正在执行的工具。
      */
     disableDataFetchTools(state) {
-        const before = state.toolDefs.length;
-        state.toolDefs = state.toolDefs.filter(t => !this.dataFetchTools.has(t.function.name));
-        const removed = before - state.toolDefs.length;
-        // 同步将禁用的工具名加入 blockedTools 集合，供 tool executor 在执行层拦截
-        // LLM 基于对话历史的幻觉调用（toolDefs 仅控制 LLM 可见的工具列表，
-        // 但 tool executor 检查的是 toolRegistry，不会拦截已注册但被禁用的工具）
-        if (!state.blockedTools)
-            state.blockedTools = new Set();
-        for (const name of this.dataFetchTools) {
-            state.blockedTools.add(name);
-        }
-        if (removed > 0) {
-            (0, logger_ts_1.logEvent)({ event: 'engine.tools_disabled', sessionId: state.sessionId, data: { removed, remaining: state.toolDefs.length, blocked: state.blockedTools.size } });
-        }
+        (0, guard_controller_ts_1.disableDataFetchTools)(this.guardControllerDeps, state);
     }
     /**
      * 数据获取循环检测 + 连续失败熔断
@@ -1403,90 +1281,11 @@ ${textHistory.join('\n')}`;
      * 2. 连续失败熔断：最近 5+ 条工具调用中 4+ 条失败，强制停止试错、转向产出
      */
     checkDataFetchLoop(state) {
-        if (state.dataFetchGuardInjected)
-            return;
-        // 数据获取类工具（非产出型）— 使用实例配置
-        const DATA_FETCH_TOOLS = this.dataFetchTools;
-        // 产出型工具（有这些就不算数据获取循环）— 使用实例配置
-        const OUTPUT_TOOLS = this.outputTools;
-        const hasOutput = state.toolCallRecords.some(r => OUTPUT_TOOLS.has(r.tool));
-        if (hasOutput)
-            return; // 已调用过产出型工具，不再干预
-        const recent = state.toolCallRecords.slice(-6);
-        // --- 条件 1：数据获取循环（最近 N+ 条全是数据获取类） ---
-        const loopMin = this.guardConfig.dataFetchLoopMinCount;
-        if (recent.length >= loopMin) {
-            const lastN = recent.slice(-loopMin);
-            const allDataFetch = lastN.every(r => DATA_FETCH_TOOLS.has(r.tool));
-            if (allDataFetch) {
-                this.injectDataFetchGuard(state, recent, 'loop');
-                return;
-            }
-        }
-        // --- 条件 2：连续失败熔断（最近 N+ 条中 M+ 条失败） ---
-        const failMin = this.guardConfig.consecutiveFailMinCount;
-        if (recent.length >= failMin) {
-            const errorCount = recent.filter(r => r.isError).length;
-            if (errorCount >= this.guardConfig.consecutiveFailErrorThreshold) {
-                this.injectDataFetchGuard(state, recent, 'failures');
-                return;
-            }
-        }
-        // --- 条件 3：跨迭代累计失败（总调用 >=8 且失败率 >=70%） ---
-        // 解决 LLM 在不同迭代中切换工具类型（web_fetch -> http_request -> browser_navigate）
-        // 导致每种工具的连续失败计数都不够触发条件 2 的问题。
-        const totalCalls = state.toolCallRecords.length;
-        if (totalCalls >= 8) {
-            const totalErrors = state.toolCallRecords.filter(r => r.isError).length;
-            if (totalErrors >= Math.floor(totalCalls * 0.7)) {
-                this.injectDataFetchGuard(state, state.toolCallRecords.slice(-6), 'cumulative_failures');
-                return;
-            }
-        }
+        (0, guard_controller_ts_1.checkDataFetchLoop)(this.guardControllerDeps, state);
     }
     /** 注入数据获取循环/连续失败熔断提示 */
     injectDataFetchGuard(state, recent, reason) {
-        state.dataFetchGuardInjected = true;
-        // 触发 guardrail 可观测事件（fire-and-forget，不阻塞主流程）
-        void this.runHooks('on_data_fetch_loop', {
-            sessionId: state.sessionId,
-            iteration: state.iteration,
-            traceId: state.toolContext?.custom?.traceId,
-        });
-        const toolSummary = recent.map(r => `${r.tool}(${r.isError ? 'err' : 'ok'})`).join(', ');
-        const errorCount = recent.filter(r => r.isError).length;
-        const reasonText = reason === 'loop'
-            ? `Your last ${recent.length} tool calls are all data-fetching without any output: ${toolSummary}`
-            : `${errorCount} of your last ${recent.length} tool calls FAILED: ${toolSummary}`;
-        const msg = {
-            role: 'user',
-            content: [
-                `[SYSTEM: ${reason === 'loop' ? 'DATA GATHERING LOOP' : 'CONSECUTIVE FAILURES'} DETECTED]`,
-                '',
-                reasonText,
-                '',
-                '⛔ **You MUST stop trying to fetch more data NOW.**',
-                '',
-                '**Required action — do ONE of the following immediately:**',
-                ...(this.hasTool('delegate_task')
-                    ? ['1. Call `delegate_task` with whatever data/context you have to let a specialist generate the output.']
-                    : []),
-                '2. If delegation is not suitable, produce the final output NOW with available data.',
-                '3. At minimum, provide a clear text summary to the user explaining what you found and what failed.',
-                '',
-                '**Do NOT:**',
-                '- Write another script to fetch data',
-                '- Try another API, URL, or npm package',
-                '- Debug the current failure — accept it and move on',
-                '',
-                'The user is waiting for OUTPUT, not more failed attempts.',
-            ].join('\n'),
-        };
-        state.messages.push(msg);
-        this.historyManager.addHistory(state.sessionId, msg);
-        (0, logger_ts_1.logEvent)({ event: 'engine.data_fetch_guard', sessionId: state.sessionId, data: { reason, iteration: state.iteration, recent: toolSummary } });
-        // 硬性禁用数据获取工具，防止 LLM 无视文字提示继续调用
-        this.disableDataFetchTools(state);
+        (0, guard_controller_ts_1.injectDataFetchGuard)(this.guardControllerDeps, state, recent, reason);
     }
     /**
      * 任务继续提示
@@ -1494,28 +1293,7 @@ ${textHistory.join('\n')}`;
      * 典型场景：多步委托任务中，第一步数据采集完成后 LLM 未生成后续步骤的 delegate_task。
      */
     injectContinuationNudge(state) {
-        const toolCallCount = state.toolCallRecords.length;
-        const msg = {
-            role: 'user',
-            content: [
-                '[SYSTEM: TASK CONTINUATION]',
-                '',
-                `You have completed ${toolCallCount} tool call(s) so far, but the original user request has NOT been fully fulfilled.`,
-                '',
-                'Please review the original request and continue with the remaining steps:',
-                '- If you planned multi-step tasks (e.g., data gathering → PPT/report generation), **NOW execute the remaining steps**.',
-                ...(this.hasTool('delegate_task')
-                    ? ['- Use `delegate_task` to delegate remaining work to appropriate specialists.']
-                    : []),
-                '- Only if the user **explicitly requested** document/PPT/report generation, call the relevant tools now. Do NOT proactively generate files the user did not ask for.',
-                '- Do NOT re-gather data you already have. Use the results from previous tool calls.',
-                '',
-                'Continue your work now.',
-            ].join('\n'),
-        };
-        state.messages.push(msg);
-        this.historyManager.addHistory(state.sessionId, msg);
-        (0, logger_ts_1.logEvent)({ event: 'engine.continuation_nudge_injected', sessionId: state.sessionId, data: { iteration: state.iteration, nudge: state.continuationNudges } });
+        (0, guard_controller_ts_1.injectContinuationNudge)(this.guardControllerDeps, state);
     }
     /**
      * 渐进式结果交付
@@ -1523,28 +1301,7 @@ ${textHistory.join('\n')}`;
      * 而不是等所有结果全部返回后才开始输出。减少用户感知等待时间。
      */
     injectProgressiveNudge(state, toolCalls) {
-        const delegateCalls = toolCalls.filter(tc => tc.function.name === 'delegate_task');
-        if (delegateCalls.length < 2)
-            return;
-        const msg = {
-            role: 'user',
-            content: [
-                '[SYSTEM: PROGRESSIVE DELIVERY]',
-                '',
-                `You dispatched ${delegateCalls.length} sub-tasks in parallel. Some may succeed while others fail or take longer.`,
-                '',
-                'When presenting results to the user:',
-                '1. **Present each completed result as it becomes available** — do NOT wait for all tasks to finish.',
-                '2. If a sub-agent reports network/sandbox restrictions or fails, **acknowledge it briefly and move on** with available data.',
-                '3. **Do NOT re-dispatch** a failed task to the same or different agent — use what you already have.',
-                '4. Start your final analysis/report with whatever data is available, noting which parts are missing.',
-                '',
-                'The user values SPEED over COMPLETENESS. A partial result delivered in 2 minutes is better than a perfect result delivered in 15 minutes.',
-            ].join('\n'),
-        };
-        state.messages.push(msg);
-        this.historyManager.addHistory(state.sessionId, msg);
-        (0, logger_ts_1.logEvent)({ event: 'engine.progressive_nudge', sessionId: state.sessionId, data: { iteration: state.iteration, delegates: delegateCalls.length } });
+        (0, guard_controller_ts_1.injectProgressiveNudge)(this.guardControllerDeps, state, toolCalls);
     }
     // ---- Hooks ----
     /** 执行指定事件类型的所有 Hook */
@@ -1664,13 +1421,34 @@ ${textHistory.join('\n')}`;
     }
     /** 中断指定会话的 Agent 执行 */
     abort(sessionId) {
-        const controller = this.abortMap.get(sessionId);
-        if (controller) {
-            controller.abort();
-            this.statusMap.set(sessionId, 'aborting');
-            (0, logger_ts_1.logEvent)({ event: 'engine.abort', sessionId, data: { reason: 'abort() called' } });
+        (0, session_state_manager_ts_1.abortSession)(this.sessionStateDeps, sessionId);
+    }
+    /**
+     * 暂停指定会话的 Agent 执行：当前工具/LLM 调用继续完成，
+     * agent loop 在下一轮 turn 边界优雅退出（发送 paused 事件后正常结束流）。
+     * 恢复由新建 SSE 流重建上下文实现（不唤醒本循环）。
+     * 对不存在的会话调用是幂等 no-op。
+     */
+    pause(sessionId) {
+        const entry = this.pauseMap.get(sessionId);
+        if (entry) {
+            entry.paused = true;
+        }
+        else {
+            this.pauseMap.set(sessionId, { paused: true, waiters: [] });
         }
     }
+    /**
+     * 清理指定会话的暂停标志（恢复由新建 SSE 流完成，不再唤醒挂起循环）。
+     * 对未暂停的会话调用是幂等 no-op。
+     */
+    resume(sessionId) {
+        this.pauseMap.delete(sessionId);
+    }
+    /** 查询指定会话是否处于暂停状态 */
+    isPaused(sessionId) {
+        return this.pauseMap.get(sessionId)?.paused === true;
+    }
     /**
      * 中断指定会话及其所有子会话的 Agent 执行（级联 abort）。
      *
@@ -1678,14 +1456,7 @@ ${textHistory.join('\n')}`;
      * 用于确保父会话异常终止时，所有 delegate_task 派生的子任务也被终止。
      */
     abortCascade(sessionId) {
-        this.abort(sessionId);
-        // 遍历直接子会话，递归 abort
-        const children = this.getChildSessions(sessionId);
-        for (const childId of children) {
-            this.abortCascade(childId);
-        }
-        // 清理父子关系
-        this.cleanupSessionRelations(sessionId);
+        (0, session_state_manager_ts_1.abortCascade)(this.sessionStateDeps, sessionId);
     }
     /** 查询指定会话的 Agent 状态 */
     getStatus(sessionId) {
@@ -1765,25 +1536,14 @@ ${textHistory.join('\n')}`;
      * - 如果是子会话：从父会话的子集中移除自身
      */
     cleanupSessionRelations(sessionId) {
-        // 从父会话的子集中移除自身
-        const parentId = this.parentSessionMap.get(sessionId);
-        if (parentId) {
-            this.childSessionMap.get(parentId)?.delete(sessionId);
-            this.parentSessionMap.delete(sessionId);
-        }
-        // 删除自身作为父会话的所有子关系记录（但保留子会话本身仍在运行）
-        this.childSessionMap.delete(sessionId);
+        (0, session_state_manager_ts_1.cleanupSessionRelations)(this.sessionStateDeps, sessionId);
     }
     // ---- 内部辅助 ----
     createEvent(sessionId, event) {
         return { ...event, timestamp: Date.now(), sessionId };
     }
     createNoopShell() {
-        return {
-            exec: async () => 'Error: Shell executor not configured',
-            write: () => { },
-            read: () => '',
-        };
+        return (0, tool_section_builder_ts_1.createNoopShell)();
     }
 }
 exports.AgentEngine = AgentEngine;