@cicctencent/agent-core 0.1.1 → 0.1.3

package/dist/cjs/agent/engine.js

@@ -0,0 +1,766 @@
+"use strict";
+// ============================================================
+// AgentEngine — Agent Loop 执行引擎（编排层）
+// ============================================================
+// 职责：编排 HistoryManager、LLMCaller、ToolExecutor 完成 ReAct 循环
+// 历史管理、LLM 调用、工具执行已分别抽离到独立模块
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentEngine = void 0;
+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 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 在工具调用间输出可见文本） */
+const PROGRESS_NARRATION_RULES = `
+
+## Progress Narration Rules
+
+When using tools, you MUST provide brief visible narration for the user:
+- **Before** each tool call: write ONE short sentence (in the user's language) describing what you are about to do. Example: "Let me query the latest sales data..."
+- **After** each tool result: write ONE short sentence summarizing the key finding or outcome. Example: "Found 3 quarters of data, revenue grew 15% YoY."
+- Keep narration **brief and informative** — no filler words.
+- For multi-step tasks, use a numbered list or checklist at the start.
+- When the task is complete, always end with a clear summary of what was accomplished.
+- DO NOT output tool calls without accompanying text narration.
+`;
+/**
+ * 构建 Skill 目录（当 SkillRouter 未命中时注入到 system prompt）
+ * 让 Agent 通过 load_skill 工具按需加载 skill 全量内容
+ *
+ * 权限隔离：skillManager 是当前 Agent 专属实例（在 agent.service.ts 中构建），
+ * 仅包含该 Agent 有权访问的 Skill，确保不会泄露其他 Agent 的私有 Skill。
+ */
+function buildSkillCatalog(skillManager) {
+    const manifests = skillManager.getAllManifests();
+    if (manifests.length === 0)
+        return null;
+    const lines = manifests.map(m => `- \`${m.id}\`: ${m.name} — ${m.description || '(no description)'}`);
+    return `## Available Skills\n\nYou have access to the following skills. Use \`load_skill(skill_id="<id>")\` to load full instructions when a task matches a skill's purpose.\n\n${lines.join('\n')}`;
+}
+class AgentEngine {
+    config;
+    /** sessionId → AgentStatus */
+    statusMap = new Map();
+    /** sessionId → AbortController (internal) */
+    abortMap = new Map();
+    /** sessionId → steering messages（实时转向队列） */
+    steeringMap = new Map();
+    /** 子模块：历史管理器 */
+    historyManager;
+    /** 子模块：LLM 调用器 */
+    llmCaller;
+    /** 子模块：工具执行器 */
+    toolExecutor;
+    /** 数据获取类工具集合（用于循环检测） */
+    dataFetchTools;
+    /** 产出型工具集合（有这些调用时不触发数据获取循环检测） */
+    outputTools;
+    constructor(config) {
+        this.config = {
+            ...config,
+            maxIterations: config.maxIterations ?? 15,
+            maxMessages: config.maxMessages ?? 50,
+            toolTimeout: config.toolTimeout ?? 30000,
+            llmTimeout: config.llmTimeout ?? 120000,
+            basePrompt: config.basePrompt ?? DEFAULT_BASE_PROMPT,
+        };
+        // 初始化子模块
+        this.historyManager = new history_manager_ts_1.HistoryManager({
+            maxMessages: this.config.maxMessages,
+            contextBudget: this.config.contextBudget,
+            toolResultStore: this.config.toolResultStore,
+        });
+        this.llmCaller = new llm_caller_ts_1.LLMCaller({
+            llmProvider: this.config.llmProvider,
+            fallbackProvider: this.config.fallbackProvider,
+            retryPolicy: this.config.retryPolicy,
+            llmTimeout: this.config.llmTimeout,
+            runHooks: this.runHooks.bind(this),
+            createEvent: this.createEvent.bind(this),
+            historyManager: this.historyManager,
+        });
+        this.toolExecutor = new tool_executor_ts_1.AgentToolExecutor({
+            toolRegistry: this.config.toolRegistry,
+            securityGuard: this.config.securityGuard,
+            toolTimeout: this.config.toolTimeout,
+            runHooks: this.runHooks.bind(this),
+            runMiddlewareToolPhase: this.runMiddlewareToolPhase.bind(this),
+            createEvent: this.createEvent.bind(this),
+            historyManager: this.historyManager,
+            getMiddleware: () => this.config.middleware,
+        });
+        // 初始化工具分类集合（可通过 config 覆盖默认值）
+        this.dataFetchTools = new Set(config.dataFetchTools ?? [
+            'web_fetch', 'execute_command', 'write_file', 'append_file',
+            'run_script', 'read_file', 'read_tool_doc',
+        ]);
+        this.outputTools = new Set(config.outputTools ?? [
+            'delegate_task', 'create_presentation', 'create_document',
+            'create_pdf', 'show_widget', 'save_artifact',
+        ]);
+    }
+    /** 获取当前 Agent 的 ToolRegistry（供 read_tool_doc 等内置工具使用） */
+    getToolRegistry() {
+        return this.config.toolRegistry;
+    }
+    /** 动态调整最大迭代上限（用于子 Agent 场景，避免子任务消耗过多迭代） */
+    setMaxIterations(max) {
+        this.config.maxIterations = max;
+    }
+    /** 获取当前 Agent 的 SkillManager（供 load_skill 等内置工具使用，确保 scope 内操作） */
+    getSkillManager() {
+        return this.config.skillManager;
+    }
+    /**
+     * 注入会话历史（从外部恢复，如持久化存储）
+     * 用于跨引擎实例保持对话上下文
+     */
+    setHistory(sessionId, messages) {
+        this.historyManager.setHistory(sessionId, messages);
+    }
+    /**
+     * 获取会话历史副本（用于持久化保存）
+     */
+    getHistorySnapshot(sessionId) {
+        return this.historyManager.getHistorySnapshot(sessionId);
+    }
+    /**
+     * 执行 Agent 任务（流式推送事件）
+     * 上层通过 for-await-of 消费事件流
+     */
+    async *run(options) {
+        const { sessionId, abortSignal } = options;
+        // ① Abort 控制
+        const internalAbort = new AbortController();
+        this.abortMap.set(sessionId, internalAbort);
+        const onExternalAbort = () => internalAbort.abort();
+        if (abortSignal) {
+            if (abortSignal.aborted)
+                internalAbort.abort();
+            else
+                abortSignal.addEventListener('abort', onExternalAbort, { once: true });
+        }
+        try {
+            // ② 准备阶段：Skill 路由 → 上下文 → 工具 → LoopState
+            const state = await this.prepareRun(options, internalAbort);
+            // ③ Agent Loop
+            yield* this.agentLoop(state);
+        }
+        catch (err) {
+            const errorMsg = `Agent execution failed: ${err.message || err}`;
+            await this.runHooks('on_error', { sessionId, iteration: 0, error: errorMsg, recoverable: false });
+            yield this.createEvent(sessionId, {
+                type: 'error',
+                error: errorMsg,
+                recoverable: false,
+            });
+            this.statusMap.set(sessionId, 'idle');
+        }
+        finally {
+            if (abortSignal)
+                abortSignal.removeEventListener('abort', onExternalAbort);
+            this.abortMap.delete(sessionId);
+            this.steeringMap.delete(sessionId);
+        }
+    }
+    // ---- 准备阶段 ----
+    /** 解析 Skill 路由，返回 Skill 内容、实际消息和路由命中状态 */
+    async resolveSkill(options, sessionId) {
+        if (options.skillId && this.config.skillManager) {
+            const skill = this.config.skillManager.get(options.skillId);
+            return { skillContent: skill?.content, actualMessage: options.message, skillMatched: !!skill };
+        }
+        if (this.config.skillRouter) {
+            this.statusMap.set(sessionId, 'thinking');
+            const routeResult = await this.config.skillRouter.route(options.message);
+            if (routeResult.skill) {
+                return { skillContent: routeResult.skill.content, actualMessage: routeResult.message, skillMatched: true };
+            }
+        }
+        return { actualMessage: options.message, skillMatched: false };
+    }
+    /** 构建初始消息列表（system + history + user） */
+    buildInitialMessages(options, skillContent, actualMessage, skillMatched) {
+        const { sessionId } = options;
+        let systemPrompt = this.config.basePrompt || '';
+        if (options.systemPromptOverride) {
+            systemPrompt += `\n\n${options.systemPromptOverride}`;
+        }
+        // 注入当前运行时环境
+        const now = new Date();
+        systemPrompt += `\n\n## Current Runtime\n\n- Date: ${now.toLocaleDateString('en-CA')} (${['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'][now.getDay()]})\n- Time: ${now.toLocaleTimeString('en-GB')}\n- Timezone: ${Intl.DateTimeFormat().resolvedOptions().timeZone} (UTC${now.getTimezoneOffset() <= 0 ? '+' : '-'}${String(Math.abs(Math.floor(now.getTimezoneOffset() / 60))).padStart(2, '0')}:${String(Math.abs(now.getTimezoneOffset() % 60)).padStart(2, '0')})`;
+        if (options.context?.env) {
+            systemPrompt += `\n- OS: ${options.context.env.os}\n- Shell: ${options.context.env.shell}`;
+            if (options.context.env.platform)
+                systemPrompt += `\n- Platform: ${options.context.env.platform}`;
+            if (options.context.env.hostname)
+                systemPrompt += `\n- Hostname: ${options.context.env.hostname}`;
+            if (options.context.env.user)
+                systemPrompt += `\n- User: ${options.context.env.user}`;
+            if (options.context.env.custom) {
+                for (const [key, value] of Object.entries(options.context.env.custom)) {
+                    systemPrompt += `\n- ${key}: ${value}`;
+                }
+            }
+        }
+        if (skillContent) {
+            systemPrompt += `\n\n## Current Skill Instructions\n\n${skillContent}`;
+        }
+        else if (!skillMatched && this.config.skillManager) {
+            // 未命中 skill → 注入 catalog 供 agent 自主调用 load_skill
+            const catalog = buildSkillCatalog(this.config.skillManager);
+            if (catalog) {
+                systemPrompt += `\n\n${catalog}`;
+            }
+        }
+        if (options.context?.terminalOutput) {
+            systemPrompt += `\n\n## Recent Terminal Output\n\n\`\`\`\n${options.context.terminalOutput}\n\`\`\``;
+        }
+        // 注入进度叙述规则（仅在有工具可用时）
+        if (this.config.toolRegistry) {
+            const toolCount = this.config.toolRegistry.getDefinitions().length;
+            if (toolCount > 0) {
+                systemPrompt += PROGRESS_NARRATION_RULES;
+            }
+        }
+        return this.config.contextManager.buildMessages({
+            systemPrompt,
+            history: this.historyManager.getHistory(sessionId),
+            userMessage: actualMessage,
+        });
+    }
+    // ---- 工具定义 ----
+    /** 获取工具定义列表（含预过滤 + 渐进式发现） */
+    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));
+        }
+        if (this.config.toolDiscovery === 'summary') {
+            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;
+            });
+        }
+        return defs;
+    }
+    // ---- 准备阶段（续） ----
+    /** 构建 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,
+                toolRegistry: custom?.toolRegistry ?? this.config.toolRegistry,
+                skillManager: custom?.skillManager ?? this.config.skillManager,
+            },
+            emitSubEvent: custom?.emitSubEvent,
+            emitWidget: custom?.emitWidget,
+            emitArtifact: custom?.emitArtifact,
+        };
+    }
+    /** 汇总准备阶段，生成 LoopState */
+    async prepareRun(options, internalAbort) {
+        const { skillContent, actualMessage, skillMatched } = await this.resolveSkill(options, options.sessionId);
+        const toolDefs = this.resolveToolDefs(options);
+        console.log(`[Engine] session=${options.sessionId} tools(${toolDefs.length}): ${toolDefs.map(t => t.function.name).join(', ') || '(none)'}`);
+        return {
+            sessionId: options.sessionId,
+            messages: this.buildInitialMessages(options, skillContent, actualMessage, skillMatched),
+            toolDefs,
+            toolContext: this.buildToolContext(options, internalAbort),
+            internalAbort,
+            iteration: 0,
+            lastContent: '',
+            toolCallRecords: [],
+            consecutiveToolFailures: new Map(),
+            iterationGuardInjected: false,
+            consecutiveSilentIterations: 0,
+            lastIterationHadToolCalls: false,
+            continuationNudges: 0,
+            dataFetchGuardInjected: false,
+            consecutiveAllFailIterations: 0,
+        };
+    }
+    // ---- Agent Loop ----
+    /** 主循环：迭代调用 LLM → 执行工具 → 直到完成或达到上限 */
+    async *agentLoop(state) {
+        while (state.iteration < this.config.maxIterations) {
+            state.iteration++;
+            state.lastIterationHadToolCalls = false; // 每轮迭代重置，工具执行后才置 true
+            // 中断检查
+            if (state.internalAbort.signal.aborted) {
+                yield this.emitDone(state);
+                return;
+            }
+            // Middleware.before + Hook: on_iteration_start
+            await this.runMiddlewarePhase('before', state);
+            await this.runHooks('on_iteration_start', {
+                sessionId: state.sessionId,
+                iteration: state.iteration,
+            });
+            // Live Steering
+            const steeringResult = this.drainSteering(state);
+            if (steeringResult) {
+                yield this.createEvent(state.sessionId, {
+                    type: 'steering',
+                    messages: steeringResult.messages,
+                    count: steeringResult.count,
+                });
+            }
+            // 迭代预算提醒：接近上限时注入提醒，防止 agent 耗尽迭代仍在收集数据
+            this.injectIterationGuard(state);
+            // 数据获取循环检测：连续多轮只调用数据获取工具时注入强制提示
+            // 首次触发：注入 guard 消息让 LLM 下轮产出总结；不立即终止，给 LLM 一次产出机会
+            // 若 LLM 继续失败，全局连续失败熔断器（consecutiveAllFailIterations >= 3）会兜底
+            this.checkDataFetchLoop(state);
+            // 调用 LLM（流式，含重试与降级）
+            this.statusMap.set(state.sessionId, 'thinking');
+            const assistant = yield* this.llmCaller.callWithRetry(state.sessionId, state.messages, state.toolDefs, state.internalAbort.signal);
+            // 从 LLMCaller 流中提取 usage（通过 last event 的 usage）
+            // 注意：usage 在 chunk 级别，这里通过 callWithRetry 的返回无法直接获取
+            // 保持原有逻辑：usage 累加在 LLMCaller 内部暂不可见，后续可优化
+            if (!assistant) {
+                // LLM 返回 null（上下文过长/错误）后，如果上一轮有工具调用，注入提示重试
+                if (state.lastIterationHadToolCalls && state.continuationNudges < 2) {
+                    state.continuationNudges++;
+                    console.log(`[Engine] LLM returned null after tool calls, injecting continuation nudge #${state.continuationNudges} at iteration ${state.iteration}`);
+                    this.injectContinuationNudge(state);
+                }
+                continue;
+            }
+            // Hook: after_ll_call
+            await this.runHooks('after_ll_call', {
+                sessionId: state.sessionId,
+                iteration: state.iteration,
+                response: assistant,
+            });
+            // 处理 LLM 响应
+            state.messages.push(assistant);
+            // 保存原始 tool_call arguments 长度（addHistory 可能触发压缩，原地替换 arguments 为占位符）
+            // tool-executor 使用此信息判断截断（而非占位符的长度）
+            if (assistant.tool_calls?.length) {
+                for (const tc of assistant.tool_calls) {
+                    tc._rawArgLength = tc.function.arguments?.length ?? 0;
+                }
+            }
+            this.historyManager.addHistory(state.sessionId, assistant);
+            if (assistant.content) {
+                state.lastContent = assistant.content;
+                state.consecutiveSilentIterations = 0;
+            }
+            // 无 tool_calls → 检查是否提前停止（上一轮有工具调用，说明任务可能未完成）
+            if (!assistant.tool_calls?.length) {
+                if (state.lastIterationHadToolCalls && state.continuationNudges < 2) {
+                    state.continuationNudges++;
+                    console.log(`[Engine] LLM stopped after tool calls without new tool_calls, injecting continuation nudge #${state.continuationNudges} at iteration ${state.iteration}`);
+                    this.injectContinuationNudge(state);
+                    // 不退出，继续下一轮迭代让 LLM 继续执行任务
+                    continue;
+                }
+                yield this.emitDone(state);
+                return;
+            }
+            // 重置继续提示计数（LLM 仍在生成工具调用，说明任务在推进）
+            state.continuationNudges = 0;
+            // 检测连续静默迭代（有 tool_calls 但无 content），超过阈值自动注入提醒
+            if (!assistant.content) {
+                state.consecutiveSilentIterations++;
+                if (state.consecutiveSilentIterations >= 2) {
+                    this.injectProgressNudge(state);
+                    state.consecutiveSilentIterations = 0;
+                }
+            }
+            // 执行工具
+            const prevRecordCount = state.toolCallRecords.length;
+            yield* this.toolExecutor.executeToolCalls(state, assistant.tool_calls);
+            // ---- 全局连续失败熔断 ----
+            const newRecords = state.toolCallRecords.slice(prevRecordCount);
+            if (newRecords.length > 0) {
+                const allFailed = newRecords.every(r => r.isError);
+                if (allFailed) {
+                    state.consecutiveAllFailIterations++;
+                    if (state.consecutiveAllFailIterations >= 3) {
+                        console.warn(`[Engine] Global early stop: ${state.consecutiveAllFailIterations} consecutive all-fail iterations at iteration ${state.iteration}`);
+                        yield this.emitDone(state);
+                        return;
+                    }
+                }
+                else {
+                    state.consecutiveAllFailIterations = 0;
+                }
+            }
+            // 渐进式结果交付：并行分发多个 delegate_task 后，提示 LLM 逐步呈现结果
+            this.injectProgressiveNudge(state, assistant.tool_calls);
+            // 标记本轮有工具调用（用于下一轮检测 LLM 是否提前停止）
+            state.lastIterationHadToolCalls = true;
+            // Middleware.after
+            await this.runMiddlewarePhase('after', state);
+        }
+        // 达到最大迭代
+        yield this.emitDone(state);
+    }
+    // ---- Live Steering（实时转向）----
+    /**
+     * 向运行中的 Agent 注入 steering 消息
+     * 消息将在下次 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;
+    }
+    /** 消费当前会话的 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 };
+    }
+    /**
+     * 进度叙述提醒
+     * 当 LLM 连续 2 次迭代仅发出 tool_calls 而无 content 时，注入 user 消息提醒输出进度说明。
+     * 确保用户在对话中有可见的文字输出，而不是所有内容都收在执行步骤中。
+     */
+    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);
+        console.log(`[Engine] Progress nudge injected at iteration ${state.iteration}`);
+    }
+    /**
+     * 迭代预算提醒
+     * 当剩余迭代不足 30% 时，注入 user 消息提醒 LLM 停止数据收集、转向完成任务。
+     * 解决 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 >= 0.35 && remaining > 0) {
+            state.iterationGuardInjected = true;
+            const toolCallCount = state.toolCallRecords.length;
+            const msg = {
+                role: 'user',
+                content: [
+                    `[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.**',
+                    '3. **NOW delegate remaining work:**',
+                    '   - For reports/dashboards: call `delegate_task` with agent "报表创作助手".',
+                    '   - For documents: call `delegate_task` with agent "文档创作助手".',
+                    '   - For PPT: call `delegate_task` with agent "文档创作助手".',
+                    '   - For direct output: call `create_presentation`/`create_document`/`show_widget` directly.',
+                    '4. If you cannot delegate, produce the final output NOW with the data you have.',
+                    '',
+                    'Do NOT write any more scripts or fetch any more data. Your data collection phase is OVER.',
+                ].join('\n'),
+            };
+            state.messages.push(msg);
+            this.historyManager.addHistory(state.sessionId, msg);
+            console.log(`[Engine] Iteration guard injected at ${cur}/${max}`);
+        }
+    }
+    /**
+     * 数据获取循环检测 + 连续失败熔断
+     *
+     * 两类触发条件：
+     * 1. 数据获取循环：最近 3+ 条工具调用全部是数据获取类且无产出型工具
+     * 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：数据获取循环（最近 3+ 条全是数据获取类） ---
+        if (recent.length >= 3) {
+            const last3 = recent.slice(-3);
+            const allDataFetch = last3.every(r => DATA_FETCH_TOOLS.has(r.tool));
+            if (allDataFetch) {
+                this.injectDataFetchGuard(state, recent, 'loop');
+                return;
+            }
+        }
+        // --- 条件 2：连续失败熔断（最近 5+ 条中 4+ 条失败） ---
+        if (recent.length >= 5) {
+            const errorCount = recent.filter(r => r.isError).length;
+            if (errorCount >= 4) {
+                this.injectDataFetchGuard(state, recent, 'failures');
+                return;
+            }
+        }
+    }
+    /** 注入数据获取循环/连续失败熔断提示 */
+    injectDataFetchGuard(state, recent, reason) {
+        state.dataFetchGuardInjected = true;
+        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:**',
+                '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);
+        console.log(`[Engine] Data-fetch guard (${reason}) injected at iteration ${state.iteration}, recent: ${toolSummary}`);
+    }
+    /**
+     * 任务继续提示
+     * 当 LLM 在工具调用后提前停止（无新工具调用也无明确总结）时，注入提示让其继续完成剩余任务。
+     * 典型场景：多步委托任务中，第一步数据采集完成后 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**.',
+                '- Use `delegate_task` to delegate remaining work to appropriate specialists.',
+                '- If document/PPT/report generation is needed, call the relevant tools immediately.',
+                '- 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);
+        console.log(`[Engine] Continuation nudge injected at iteration ${state.iteration} (nudge #${state.continuationNudges})`);
+    }
+    /**
+     * 渐进式结果交付
+     * 当主 Agent 并行分发了多个 delegate_task 后，注入提示让 LLM 逐步呈现每个子任务的结果，
+     * 而不是等所有结果全部返回后才开始输出。减少用户感知等待时间。
+     */
+    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);
+        console.log(`[Engine] Progressive delivery nudge injected at iteration ${state.iteration} (${delegateCalls.length} parallel delegates)`);
+    }
+    // ---- Hooks ----
+    /** 执行指定事件类型的所有 Hook */
+    async runHooks(event, ctx) {
+        const hooks = this.config.hooks?.filter(h => h.event === event) || [];
+        if (hooks.length === 0)
+            return [];
+        const results = [];
+        for (const hook of hooks) {
+            try {
+                const result = await hook.handler(ctx);
+                if (result)
+                    results.push(result);
+            }
+            catch (e) {
+                console.warn(`[Hook] ${hook.name} (${event}) failed:`, e?.message || e);
+            }
+        }
+        return results;
+    }
+    // ---- Middleware ----
+    /** 执行中间件的 before/after 阶段 */
+    async runMiddlewarePhase(phase, state) {
+        const middlewares = this.config.middleware;
+        if (!middlewares || middlewares.length === 0)
+            return;
+        const ctx = {
+            sessionId: state.sessionId,
+            iteration: state.iteration,
+            messages: state.messages,
+            toolCount: state.toolDefs.length,
+        };
+        for (const mw of middlewares) {
+            try {
+                if (phase === 'before' && mw.before) {
+                    await mw.before(ctx);
+                }
+                else if (phase === 'after' && mw.after) {
+                    await mw.after(ctx);
+                }
+            }
+            catch (e) {
+                console.warn(`[Middleware] ${mw.name} (${phase}) failed:`, e?.message || e);
+            }
+        }
+    }
+    /** 执行中间件的 onToolBefore/onToolAfter 阶段 */
+    async runMiddlewareToolPhase(phase, ctx) {
+        const middlewares = this.config.middleware;
+        if (!middlewares || middlewares.length === 0)
+            return [];
+        const results = [];
+        for (const mw of middlewares) {
+            try {
+                const handler = mw[phase];
+                if (handler) {
+                    const result = await handler.call(mw, ctx);
+                    if (result)
+                        results.push(result);
+                }
+            }
+            catch (e) {
+                console.warn(`[Middleware] ${mw.name} (${phase}) failed:`, e?.message || e);
+            }
+        }
+        return results;
+    }
+    // ---- 辅助 ----
+    emitDone(state) {
+        this.statusMap.set(state.sessionId, 'idle');
+        this.runHooks('on_complete', {
+            sessionId: state.sessionId,
+            iteration: state.iteration,
+            totalIterations: state.iteration,
+            usage: state.totalUsage,
+        }).catch(() => { });
+        return this.createEvent(state.sessionId, {
+            type: 'done',
+            content: state.lastContent || 'Max iterations reached',
+            iterations: state.iteration,
+            usage: state.totalUsage,
+        });
+    }
+    /** 中断指定会话的 Agent 执行 */
+    abort(sessionId) {
+        const controller = this.abortMap.get(sessionId);
+        if (controller) {
+            controller.abort();
+            this.statusMap.set(sessionId, 'aborting');
+        }
+    }
+    /** 查询指定会话的 Agent 状态 */
+    getStatus(sessionId) {
+        return this.statusMap.get(sessionId) || 'idle';
+    }
+    /** 销毁引擎，释放所有会话资源 */
+    destroy() {
+        for (const controller of Array.from(this.abortMap.values())) {
+            controller.abort();
+        }
+        this.abortMap.clear();
+        this.statusMap.clear();
+        this.steeringMap.clear();
+        this.historyManager.clearAll();
+    }
+    // ---- 内部辅助 ----
+    createEvent(sessionId, event) {
+        return { ...event, timestamp: Date.now(), sessionId };
+    }
+    createNoopShell() {
+        return {
+            exec: async () => 'Error: Shell executor not configured',
+            write: () => { },
+            read: () => '',
+        };
+    }
+}
+exports.AgentEngine = AgentEngine;
+//# sourceMappingURL=engine.js.map