@ai-setting/roy-agent-cli 1.3.15 → 1.3.16

package/dist/core/src/env/agent/agent-component.js

@@ -0,0 +1,1481 @@
+/**
+ * @fileoverview AgentComponent - Agent执行核心组件
+ *
+ * 基于 roy-agent docs/agent-component-design.md
+ * 参考 agent-core Agent.run 实现
+ *
+ * 核心功能：
+ * - ReAct 循环编排
+ * - Hook 机制和 Plugin 扩展
+ * - 多 Agent 管理
+ * - 工具调用
+ *
+ * 依赖：
+ * - ../llm - LLMComponent 用于 LLM 调用
+ * - ../log-trace/logger - createLogger 用于日志
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+import { BaseComponent } from "../component.js";
+import { createLogger } from "../log-trace/logger.js";
+import { z } from "zod";
+import { envKeyToConfigKey } from "../../config/env-key.js";
+import { AGENT_CONFIG_REGISTRATION, AGENT_DEFAULTS } from "./agent-config-registration.js";
+import { TracedAs } from "../log-trace/decorator.js";
+// Session Message 转换器
+import { SessionMessageConverter } from "../session/session-message-converter.js";
+// AskUserError - 用于工作流暂停的特定错误
+import { AskUserError } from "../workflow/types/workflow-hil.js";
+// ============================================================================
+// Logger
+// ============================================================================
+const logger = createLogger("agent:component");
+// ============================================================================
+// Type Conversion Utilities
+// ============================================================================
+/**
+ * 将 ModelMessage 转换为 LLMMessage
+ *
+ * ModelMessage 来自 ai SDK，LLMMessage 是内部格式
+ */
+function toLLMMessage(msg) {
+    // 处理 content 字段
+    let content;
+    let toolCallId;
+    let toolName;
+    // 使用 any 类型避免 ai SDK 和内部 ToolCall 类型不兼容
+    let toolCalls;
+    if (typeof msg.content === "string") {
+        content = msg.content;
+        // 对于 tool 消息，提取 toolCallId 和 toolName
+        if (msg.role === "tool") {
+            toolCallId = msg.toolCallId;
+            toolName = msg.toolName;
+        }
+        // assistant 消息可能包含 toolCalls（ai SDK v6 格式）
+        if (msg.role === "assistant" && msg.toolCalls) {
+            toolCalls = msg.toolCalls;
+        }
+    }
+    else if (Array.isArray(msg.content)) {
+        // 处理 tool 消息（AI SDK v6 格式）
+        if (msg.role === "tool") {
+            // 提取 tool-result 的 output
+            const toolResult = msg.content.find((part) => part.type === "tool-result");
+            // output 可能是 { type: 'text', value: '...' } 或纯字符串
+            const output = toolResult?.output;
+            if (typeof output === "string") {
+                content = output;
+            }
+            else if (output && typeof output === "object" && "value" in output) {
+                content = output.value?.toString() || "";
+            }
+            else {
+                content = JSON.stringify(output) || "";
+            }
+            toolCallId = toolResult?.toolCallId;
+            toolName = toolResult?.toolName;
+        }
+        else {
+            // 处理多模态内容，提取文本和 toolCalls
+            const textParts = msg.content.filter((part) => part.type === "text");
+            const toolCallParts = msg.content.filter((part) => part.type === "tool-call");
+            // 提取文本内容
+            content = textParts.map((part) => part.text || "").join("");
+            // 对于 assistant 消息，从 tool-call part 中提取 toolCalls
+            // 注意：toModelMessage 生成的格式是扁平的 { toolCallId, toolName, input }
+            // 不是嵌套的 { toolCall: { name, arguments } }
+            if (msg.role === "assistant" && toolCallParts.length > 0) {
+                toolCalls = toolCallParts.map((part) => {
+                    // input 是已解析的参数对象，需要转回字符串给 convertToSDKMessages
+                    const argsString = typeof part.input === "string"
+                        ? part.input
+                        : JSON.stringify(part.input || {});
+                    const toolName = part.toolName || "unknown";
+                    return {
+                        id: part.toolCallId,
+                        name: toolName,
+                        arguments: argsString,
+                        function: {
+                            name: toolName,
+                            arguments: argsString,
+                        },
+                    };
+                });
+            }
+        }
+    }
+    else {
+        content = "";
+    }
+    return {
+        role: msg.role,
+        content,
+        ...(toolCallId ? { toolCallId } : {}),
+        ...(toolName ? { name: toolName } : {}),
+        ...(toolCalls && toolCalls.length > 0 ? { toolCalls } : {}),
+    };
+}
+// ============================================================================
+// Config Schema
+// ============================================================================
+/**
+ * AgentComponent 默认配置
+ */
+const DEFAULT_AGENT_CONFIG = {
+    type: "primary",
+    maxIterations: 200,
+    maxErrorRetries: 3,
+    doomLoopThreshold: 5,
+    toolTimeout: 60000,
+    toolRetries: 3,
+    /** 是否过滤 history 中的 tool 消息（默认不过滤，保留完整上下文） */
+    filterHistory: false,
+};
+/**
+ * Agent 实例配置 Schema
+ */
+const AgentInstanceSchema = z.object({
+    type: z.enum(["primary", "sub"]).default("primary"),
+    systemPrompt: z.string().optional(),
+    behaviorSpecId: z.string().optional(),
+    model: z.string().optional(),
+    maxIterations: z.number().default(200),
+    maxErrorRetries: z.number().default(3),
+    doomLoopThreshold: z.number().default(5),
+    allowedTools: z.array(z.string()).optional(),
+    deniedTools: z.array(z.string()).optional(),
+    toolTimeout: z.number().default(60000),
+    toolRetries: z.number().default(3),
+    /** 是否过滤 history 中的 tool 消息（默认不过滤，保留完整上下文） */
+    filterHistory: z.boolean().default(false),
+});
+/**
+ * AgentComponent 配置 Schema
+ */
+export const AgentComponentConfigSchema = z.object({
+    defaultAgent: AgentInstanceSchema,
+});
+// ============================================================================
+// AgentComponent
+// ============================================================================
+/**
+ * AgentComponent
+ *
+ * 提供 Agent 执行能力和 Hook 扩展机制
+ */
+export class AgentComponent extends BaseComponent {
+    name = "agent";
+    version = "1.0.0";
+    agents = new Map();
+    config;
+    llmComponent = null;
+    toolComponent = null;
+    aborted = new Map();
+    abortControllers = new Map(); // Agent Run 的 AbortController，使用 runId 作为 key
+    defaultTools = [];
+    // Doom loop detection cache (per-agent for isolation)
+    doomLoopCaches = new Map();
+    /** ConfigComponent 用于配置管理 */
+    configComponent;
+    /** 配置变更 watcher 清理函数 */
+    configWatcher;
+    /** Session 消息转换器 */
+    messageConverter = new SessionMessageConverter();
+    /** 构造函数传入的配置（最高优先级） */
+    _constructorConfig;
+    /** Run ID 计数器（用于生成唯一的 runId） */
+    runCounter = 0;
+    constructor(options = {}) {
+        super();
+        // 保存构造函数传入的配置（最高优先级）
+        this._constructorConfig = options.config;
+        this.config = {
+            defaultAgent: {
+                ...DEFAULT_AGENT_CONFIG,
+                ...options.config?.defaultAgent,
+            },
+        };
+    }
+    /**
+     * 初始化组件
+     *
+     * 配置加载优先级（从高到低）：
+     * 1. Object - 直接传入的 config 对象
+     * 2. Env - 环境变量（通过 envPrefix 配置前缀）
+     * 3. File - 配置文件（通过 configPath 指定）
+     */
+    async init(config) {
+        // 调用基类 init，注入 env
+        await super.init(config);
+        // 从 options 获取 ConfigComponent
+        const options = config.options;
+        if (!options?.configComponent) {
+            throw new Error("ConfigComponent is required for AgentComponent initialization");
+        }
+        this.configComponent = options.configComponent;
+        await this.registerConfig(options);
+        this.setStatus("running");
+    }
+    /**
+     * 注册配置到 ConfigComponent
+     *
+     * 配置加载顺序（优先级从低到高）：
+     * 1. Defaults - 默认值（最低）
+     * 2. FileSource - 从配置文件加载
+     * 3. EnvSource - 从环境变量加载
+     * 4. config 对象 - 直接传入的配置（最高）
+     */
+    async registerConfig(options) {
+        const configComponent = options.configComponent;
+        if (!configComponent)
+            return;
+        const { configPath, envPrefix, config } = options;
+        const prefix = envPrefix ?? "AGENT";
+        // 1. 使用 registerComponent 注册配置结构（keys 和 sources，不含 defaults）
+        configComponent.registerComponent(AGENT_CONFIG_REGISTRATION);
+        // 2. 注册 FileSource（如果提供了 configPath）
+        if (configPath) {
+            configComponent.registerSource({
+                type: "file",
+                relativePath: configPath,
+                optional: true,
+                watch: false
+            });
+        }
+        // 3. 注册 EnvSource
+        configComponent.registerSource({
+            type: "env",
+            envPrefix: prefix,
+            priority: 20,
+            watch: false
+        });
+        // 4. 从 sources 加载配置（FileSource 和 EnvSource）
+        await configComponent.load("agent");
+        // 5. 后备方案：直接读取环境变量（确保所有环境变量都被处理）
+        for (const envKey of Object.keys(process.env)) {
+            const configKey = envKeyToConfigKey(envKey, prefix, "agent");
+            if (!configKey)
+                continue;
+            const value = process.env[envKey];
+            if (value !== undefined) {
+                await configComponent.set(configKey, value);
+            }
+        }
+        // 6. 设置默认值（只有当配置不存在时）
+        for (const [key, value] of Object.entries(AGENT_DEFAULTS)) {
+            if (configComponent.get(key) === undefined) {
+                await configComponent.set(key, value);
+            }
+        }
+        // 7. 直接配置对象（最高优先级）
+        if (config) {
+            const flatConfig = this.flattenConfig(config);
+            for (const [key, value] of Object.entries(flatConfig)) {
+                await configComponent.set(key, value);
+            }
+        }
+        // 8. 从 ConfigComponent 同步配置到 this.config
+        // 重要：配置文件/环境变量的值必须同步回实例配置，供 registerAgent() 使用
+        // 注意：构造函数传入的配置优先级最高
+        const constructorDefaultAgent = this._constructorConfig?.defaultAgent;
+        // 从 ConfigComponent 读取值，并设置默认值
+        // 构造函数传入的值优先级最高，会覆盖从 ConfigComponent 读取的值
+        this.config.defaultAgent = {
+            maxIterations: constructorDefaultAgent?.maxIterations
+                ?? configComponent.get("agent.defaultAgent.maxIterations")
+                ?? 200,
+            maxErrorRetries: constructorDefaultAgent?.maxErrorRetries
+                ?? configComponent.get("agent.defaultAgent.maxErrorRetries")
+                ?? 3,
+            doomLoopThreshold: constructorDefaultAgent?.doomLoopThreshold
+                ?? configComponent.get("agent.defaultAgent.doomLoopThreshold")
+                ?? 5,
+            toolTimeout: constructorDefaultAgent?.toolTimeout
+                ?? configComponent.get("agent.defaultAgent.toolTimeout")
+                ?? 60000,
+            toolRetries: constructorDefaultAgent?.toolRetries
+                ?? configComponent.get("agent.defaultAgent.toolRetries")
+                ?? 3,
+            filterHistory: constructorDefaultAgent?.filterHistory
+                ?? configComponent.get("agent.defaultAgent.filterHistory")
+                ?? false,
+            type: constructorDefaultAgent?.type
+                ?? configComponent.get("agent.defaultAgent.type")
+                ?? "primary",
+            systemPrompt: constructorDefaultAgent?.systemPrompt
+                ?? configComponent.get("agent.defaultAgent.systemPrompt"),
+            model: constructorDefaultAgent?.model
+                ?? configComponent.get("agent.defaultAgent.model"),
+            behaviorSpecId: constructorDefaultAgent?.behaviorSpecId
+                ?? configComponent.get("agent.defaultAgent.behaviorSpecId"),
+        };
+        logger.info(`[registerConfig] Synced config from ConfigComponent: maxIterations=${this.config.defaultAgent.maxIterations}`);
+        // 9. 注册配置热更新监听
+        this.registerConfigWatcher(configComponent);
+    }
+    /**
+     * 将配置对象展平为点号路径
+     */
+    flattenConfig(obj, prefix = "agent") {
+        const result = {};
+        for (const [key, value] of Object.entries(obj)) {
+            const fullKey = `${prefix}.${key}`;
+            if (value && typeof value === "object" && !Array.isArray(value)) {
+                Object.assign(result, this.flattenConfig(value, fullKey));
+            }
+            else {
+                result[fullKey] = value;
+            }
+        }
+        return result;
+    }
+    /**
+     * 注册配置热更新监听
+     */
+    registerConfigWatcher(configComponent) {
+        if (typeof configComponent.watch !== "function") {
+            return;
+        }
+        this.configWatcher = configComponent.watch("agent.*", (event) => {
+            this.onConfigChange(event);
+        });
+    }
+    /**
+     * 处理配置变更
+     */
+    onConfigChange(event) {
+        logger.info(`Agent config changed: ${event.key}`, {
+            oldValue: event.oldValue,
+            newValue: event.newValue
+        });
+    }
+    /**
+     * 组件停止时的清理逻辑
+     *
+     * 清理内容：
+     * 1. 终止所有正在运行的 Agent（调用 abort() 以中断 LLM 调用）
+     * 2. 清空 AbortController 注册表
+     * 3. 清空 Doom Loop 缓存
+     * 4. 取消配置变更监听
+     * 5. 清空 Agent 注册表
+     */
+    async onStop() {
+        logger.info("[AgentComponent] Stopping and cleaning up resources...");
+        // 1. 终止所有正在运行的 Agent（调用 abort() 以中断 LLM 调用）
+        for (const [name, agent] of this.agents) {
+            if (agent.status === "running" || agent.status === "idle") {
+                // 调用 abort() 方法会触发 AbortController.abort()，从而中断正在进行的 LLM 调用
+                this.abort(name);
+                logger.debug(`[AgentComponent] Aborted agent: ${name}`);
+            }
+        }
+        // 2. 清空 AbortController 注册表
+        this.abortControllers.clear();
+        // 3. 清空 Doom Loop 缓存
+        this.doomLoopCaches.clear();
+        // 4. 取消配置变更监听
+        if (this.configWatcher) {
+            this.configWatcher();
+            this.configWatcher = undefined;
+        }
+        // 5. 清空 Agent 注册表
+        this.agents.clear();
+        this.setStatus("stopped");
+        logger.info("[AgentComponent] Cleanup completed");
+    }
+    /**
+     * 刷新依赖组件引用
+     *
+     * 当组件被添加到 Environment 后调用，以确保获取到最新的组件引用
+     */
+    refreshDependencies() {
+        if (this.env) {
+            const llm = this.env.getComponent("llm");
+            const tool = this.env.getComponent("tool");
+            this.llmComponent = llm ? llm : null;
+            this.toolComponent = tool ? tool : null;
+            logger.debug("[refreshDependencies] AgentComponent refreshed", {
+                hasLLM: !!this.llmComponent,
+                hasTool: !!this.toolComponent,
+            });
+        }
+    }
+    /**
+     * 获取 Agent 实例
+     */
+    getAgent(agentName) {
+        return this.agents.get(agentName);
+    }
+    /**
+     * 获取所有 Agent 实例
+     */
+    listAgents() {
+        return Array.from(this.agents.values());
+    }
+    /**
+     * Add placeholder tool results for remaining unprocessed tool calls
+     *
+     * This ensures that the message history maintains a 1:1 correspondence
+     * between tool-calls and tool-results, which is required by AI SDK v6.
+     *
+     * @param ctx - Hook context containing messages
+     * @param allToolCalls - All tool calls from the LLM response
+     * @param processedCount - Number of tool calls that have been processed
+     * @param reason - Reason for the abort/interruption
+     */
+    addRemainingToolResults(ctx, allToolCalls, processedCount, reason) {
+        const remainingToolCalls = allToolCalls.slice(processedCount);
+        for (const tc of remainingToolCalls) {
+            const tcName = tc.function?.name || tc.name || "unknown";
+            this.pushMessage(ctx, {
+                role: "tool",
+                content: [{
+                        type: "tool-result",
+                        toolCallId: tc.id,
+                        toolName: tcName,
+                        output: JSON.stringify({ error: reason }),
+                    }],
+            });
+        }
+    }
+    /**
+     * 注册 Agent
+     *
+     * 配置优先级（从高到低）：
+     * 1. registerAgent 传入的 config（来自 PromptComponent）
+     * 2. defaultAgent 配置（来自 ConfigComponent，作为 fallback）
+     */
+    registerAgent(name, config) {
+        // 合并配置：defaultAgent 填充默认值，传入的 config 覆盖
+        // 注意：需要显式设置每个字段，避免 spread 操作导致默认值被覆盖的问题
+        const mergedConfig = {
+            // 基础字段
+            type: config.type ?? this.config.defaultAgent.type,
+            name,
+            // 数值类型字段（显式设置以避免被覆盖）
+            maxIterations: config.maxIterations ?? this.config.defaultAgent.maxIterations,
+            maxErrorRetries: config.maxErrorRetries ?? this.config.defaultAgent.maxErrorRetries,
+            doomLoopThreshold: config.doomLoopThreshold ?? this.config.defaultAgent.doomLoopThreshold,
+            toolTimeout: config.toolTimeout ?? this.config.defaultAgent.toolTimeout,
+            toolRetries: config.toolRetries ?? this.config.defaultAgent.toolRetries,
+            // 字符串类型字段
+            systemPrompt: config.systemPrompt ?? this.config.defaultAgent.systemPrompt,
+            model: config.model ?? this.config.defaultAgent.model,
+            behaviorSpecId: config.behaviorSpecId ?? this.config.defaultAgent.behaviorSpecId,
+            // 工具过滤字段
+            allowedTools: config.allowedTools ?? this.config.defaultAgent.allowedTools,
+            deniedTools: config.deniedTools ?? this.config.defaultAgent.deniedTools,
+            // History 过滤字段
+            filterHistory: config.filterHistory ?? this.config.defaultAgent.filterHistory,
+        };
+        const instance = {
+            name,
+            config: mergedConfig,
+            status: "idle",
+            plugins: new Map(),
+        };
+        this.agents.set(name, instance);
+        logger.info(`Agent registered: ${name}`, { type: instance.config.type });
+        return instance;
+    }
+    /**
+     * 注销 Agent
+     */
+    unregisterAgent(name) {
+        const deleted = this.agents.delete(name);
+        if (deleted) {
+            logger.info(`Agent unregistered: ${name}`);
+        }
+        return deleted;
+    }
+    /**
+     * 注册 Plugin 到指定 Agent
+     */
+    registerPlugin(agentName, plugin) {
+        const agent = this.agents.get(agentName);
+        if (!agent) {
+            throw new Error(`Agent not found: ${agentName}`);
+        }
+        agent.plugins.set(plugin.name, plugin);
+        logger.info(`Plugin registered: ${plugin.name} to ${agentName}`, {
+            hooks: plugin.hooks.map(h => h.point),
+        });
+    }
+    /**
+     * 注销 Plugin
+     */
+    unregisterPlugin(agentName, pluginName) {
+        const agent = this.agents.get(agentName);
+        if (!agent) {
+            return false;
+        }
+        const deleted = agent.plugins.delete(pluginName);
+        if (deleted) {
+            logger.info(`Plugin unregistered: ${pluginName} from ${agentName}`);
+        }
+        return deleted;
+    }
+    /**
+     * 设置默认工具列表
+     */
+    setDefaultTools(tools) {
+        this.defaultTools = tools;
+    }
+    /**
+     * 获取可用工具
+     */
+    getAvailableTools(agent, context) {
+        // 首先添加 defaultTools（来自 setDefaultTools 的 Memory Agent tools）
+        let tools = [...this.defaultTools];
+        logger.debug(`[getAvailableTools] After defaultTools: ${tools.length} tools`, {
+            toolNames: tools.map(t => t.name)
+        });
+        // 如果有 ToolComponent，从组件获取
+        if (this.toolComponent?.listTools) {
+            // 类型转换：ToolComponent 的 Tool 与 AgentComponent 的 Tool 兼容
+            const componentTools = this.toolComponent.listTools();
+            tools = [...tools, ...componentTools];
+            logger.debug(`[getAvailableTools] After adding componentTools: ${tools.length} tools`, {
+                componentToolNames: componentTools.map(t => t.name)
+            });
+        }
+        // 获取工具过滤配置（context 优先于 agent 配置）
+        const allowedTools = context?.allowedTools ?? agent.config.allowedTools;
+        const deniedTools = context?.deniedTools ?? agent.config.deniedTools;
+        logger.debug(`[getAvailableTools] Filtering: allowed=${allowedTools}, denied=${deniedTools}`);
+        // 应用 allowedTools 过滤
+        if (allowedTools?.length) {
+            tools = tools.filter(t => allowedTools.includes(t.name));
+            logger.debug(`[getAvailableTools] After allowedTools filter: ${tools.length} tools`, {
+                toolNames: tools.map(t => t.name)
+            });
+        }
+        // 应用 deniedTools 过滤
+        if (deniedTools?.length) {
+            tools = tools.filter(t => !deniedTools.includes(t.name));
+            logger.debug(`[getAvailableTools] After deniedTools filter: ${tools.length} tools`, {
+                toolNames: tools.map(t => t.name)
+            });
+        }
+        logger.debug(`[getAvailableTools] Final tools: ${tools.length}`, {
+            toolNames: tools.map(t => t.name)
+        });
+        return tools;
+    }
+    /**
+     * 执行 Agent
+     *
+     * @param agentName Agent 名称
+     * @param query 用户查询
+     * @param context 执行上下文
+     * @returns Agent 执行结果
+     */
+    async run(agentName, query, context) {
+        return this._run(agentName, query, context);
+    }
+    pushMessage(hookCtx, message) {
+        hookCtx.messages.push(message);
+        this.notifyMessageAdded(message);
+    }
+    /**
+     * 执行 Agent（核心方法，内部实现）
+     */
+    async _run(agentName, query, context) {
+        // 刷新依赖组件引用（确保获取到最新的组件）
+        this.refreshDependencies();
+        const agent = this.getAgent(agentName);
+        if (!agent) {
+            throw new Error(`Agent not found: ${agentName}`);
+        }
+        // 生成唯一的 runId（支持并发调用同一个 agent）
+        const runId = `${agentName}:${++this.runCounter}`;
+        logger.info(`Starting agent run: ${agentName} (runId=${runId})`, { query: query.substring(0, 100) });
+        // Mark agent as running
+        agent.status = "running";
+        this.aborted.set(runId, false);
+        // Create AbortController for this agent run
+        const abortController = new AbortController();
+        this.abortControllers.set(runId, abortController);
+        // Initialize doom loop cache for this agent
+        if (!this.doomLoopCaches.has(runId)) {
+            this.doomLoopCaches.set(runId, new Map());
+        }
+        // Merge context
+        const effectiveContext = {
+            ...context,
+            agentType: agent.config.type,
+            model: agent.config.model,
+            // 设置 abort signal（支持通过 abort() 方法中断 LLM 调用）
+            abort: abortController.signal,
+        };
+        // Initialize result
+        const result = {
+            iterations: 0,
+            toolCalls: [],
+        };
+        // Create HookContext
+        const hookCtx = {
+            agent,
+            iteration: 0,
+            maxIterations: agent.config.maxIterations,
+            messages: [],
+            tools: this.getAvailableTools(agent, effectiveContext),
+            systemPrompt: agent.config.systemPrompt || "You are a helpful assistant.",
+            context: effectiveContext,
+        };
+        // Load session history messages
+        let historyMessageCount = 0;
+        if (effectiveContext.sessionId) {
+            try {
+                const sessionComponent = this.env.getComponent("session");
+                if (sessionComponent) {
+                    // Get conversation history starting from the N-th latest user message
+                    // This ensures we have complete conversation context
+                    // Determine filterHistory: context > agent config > default (false)
+                    const filterHistory = effectiveContext.filterHistory ?? agent.config.filterHistory ?? false;
+                    const messages = await this.getConversationHistory(sessionComponent, effectiveContext.sessionId, { minUserMessages: 100, filterHistory });
+                    hookCtx.messages = messages.map(msg => this.messageConverter.toModelMessage(msg));
+                    historyMessageCount = hookCtx.messages.length;
+                }
+            }
+            catch (err) {
+                logger.warn(`Failed to load session history: ${err}`);
+            }
+        }
+        // Send start event via env
+        this.pushEnvEvent({
+            type: "agent.start",
+            payload: {
+                sessionId: effectiveContext.sessionId,
+                model: effectiveContext.model,
+            },
+        });
+        // Always add user query to messages
+        // History messages are already loaded above, this is the new user input
+        this.pushMessage(hookCtx, {
+            role: "user",
+            content: query,
+        });
+        // before.start hook
+        await this.executePluginHooks(agent, "agent:before.start", hookCtx);
+        if (hookCtx._stopped) {
+            return this.finalizeResult(result, hookCtx);
+        }
+        // ReAct Loop
+        let iteration = 0;
+        let finalText;
+        while (iteration < agent.config.maxIterations) {
+            // Check _stopped state (may be set by previous iteration's hooks)
+            if (hookCtx._stopped) {
+                break;
+            }
+            // Check abort
+            if (this.aborted.get(runId)) {
+                hookCtx._stopped = true;
+                hookCtx._stopReason = "aborted";
+                break;
+            }
+            // Check abort signal
+            if (effectiveContext.abort?.aborted) {
+                hookCtx._stopped = true;
+                hookCtx._stopReason = "abort_signal";
+                break;
+            }
+            iteration++;
+            hookCtx.iteration = iteration;
+            result.iterations = iteration;
+            logger.debug(`Iteration ${iteration} started`);
+            // Reset doom loop cache at the start of each iteration
+            // Doom loop detection should only apply within a single LLM response cycle
+            this.doomLoopCaches.set(runId, new Map());
+            // 设置迭代信息，供 before.llm hook 使用（如 ReminderPlugin）
+            hookCtx.maxIterations = agent.config.maxIterations;
+            try {
+                // 记录消息构建结果
+                logger.debug(`[ReAct] Iteration ${iteration} buildMessages result: ${hookCtx.messages.length} messages`);
+                // before.llm hook
+                await this.executePluginHooks(agent, "agent:before.llm", hookCtx);
+                if (hookCtx._stopped)
+                    break;
+                // Call LLM
+                const llmOutput = await this.invokeLLM(hookCtx);
+                hookCtx.llmOutput = llmOutput;
+                // Check abort after LLM call (important: abort might have interrupted the call)
+                if (this.aborted.get(runId) || effectiveContext.abort?.aborted) {
+                    hookCtx._stopped = true;
+                    hookCtx._stopReason = "aborted";
+                    break;
+                }
+                // after.llm hook
+                await this.executePluginHooks(agent, "agent:after.llm", hookCtx);
+                if (hookCtx._stopped)
+                    break;
+                // Process LLM output
+                if (llmOutput.content && !llmOutput.toolCalls?.length) {
+                    // Text response - complete
+                    // Check abort before adding message and breaking
+                    if (this.aborted.get(runId) || effectiveContext.abort?.aborted) {
+                        hookCtx._stopped = true;
+                        hookCtx._stopReason = "aborted";
+                        break;
+                    }
+                    finalText = llmOutput.content;
+                    this.pushMessage(hookCtx, {
+                        role: "assistant",
+                        content: llmOutput.content,
+                    });
+                    break;
+                }
+                if (llmOutput.toolCalls?.length) {
+                    // Add assistant message with tool calls to messages (CRITICAL: must be before tool results)
+                    // AI SDK v6 format: assistant message with content array containing text/reasoning/tool-call parts
+                    // Build assistant message content parts: text/reasoning + tool-call parts
+                    const assistantParts = [];
+                    // 1. Add text content if present
+                    if (llmOutput.content) {
+                        assistantParts.push({
+                            type: "text",
+                            text: llmOutput.content,
+                        });
+                    }
+                    // 2. Add reasoning content if present (for reasoning models)
+                    if (llmOutput.reasoning) {
+                        assistantParts.push({
+                            type: "reasoning",
+                            text: llmOutput.reasoning,
+                            reasoningType: "core",
+                        });
+                    }
+                    // 3. Add tool-call parts
+                    for (const tc of llmOutput.toolCalls) {
+                        let argsStr = "";
+                        let argsObj = {};
+                        // 提取参数：优先从 function.arguments 获取
+                        if (tc.function?.arguments) {
+                            if (typeof tc.function.arguments === "string") {
+                                argsStr = tc.function.arguments;
+                                try {
+                                    argsObj = JSON.parse(argsStr);
+                                }
+                                catch {
+                                    argsObj = { _raw: argsStr };
+                                }
+                            }
+                            else {
+                                argsObj = tc.function.arguments;
+                                argsStr = JSON.stringify(argsObj);
+                            }
+                        }
+                        else if (tc.arguments) {
+                            if (typeof tc.arguments === "string") {
+                                argsStr = tc.arguments;
+                                try {
+                                    argsObj = JSON.parse(argsStr);
+                                }
+                                catch {
+                                    argsObj = { _raw: argsStr };
+                                }
+                            }
+                            else {
+                                argsObj = tc.arguments;
+                                argsStr = JSON.stringify(argsObj);
+                            }
+                        }
+                        assistantParts.push({
+                            type: "tool-call",
+                            toolCallId: tc.id,
+                            toolName: tc.function?.name || tc.name || "unknown",
+                            // 关键修复：添加 input 字段供 session-message-converter 读取和存储
+                            input: argsObj,
+                            // 保留 toolCall 以兼容某些依赖此结构的代码
+                            toolCall: {
+                                name: tc.function?.name || tc.name || "unknown",
+                                arguments: argsStr,
+                            }
+                        });
+                    }
+                    // 记录添加 assistant 消息
+                    const assistantContent = llmOutput.content?.substring(0, 80) || "(no text)";
+                    const toolCallNames = llmOutput.toolCalls?.map(tc => tc.function?.name || tc.name).join(", ") || "none";
+                    logger.debug(`[ReAct] Iteration ${iteration} Adding assistant message: text="${assistantContent}" toolCalls=[${toolCallNames}]`);
+                    this.pushMessage(hookCtx, {
+                        role: "assistant",
+                        content: assistantParts,
+                    });
+                    // Tool calls
+                    const allToolCalls = llmOutput.toolCalls;
+                    let processedCount = 0; // Track number of successfully processed tool calls
+                    for (const toolCall of allToolCalls) {
+                        // Check abort before tool execution
+                        if (this.aborted.get(runId) || effectiveContext.abort?.aborted) {
+                            hookCtx._stopped = true;
+                            hookCtx._stopReason = "aborted";
+                            // Add placeholder results for remaining unprocessed tool calls
+                            this.addRemainingToolResults(hookCtx, allToolCalls, processedCount, "Execution aborted");
+                            break;
+                        }
+                        // 优先使用 function.name，兼容旧格式
+                        const func = toolCall.function;
+                        const tcName = func?.name || toolCall.name || "unknown";
+                        const tcArgs = func?.arguments
+                            ? (typeof func.arguments === "string" ? JSON.parse(func.arguments) : func.arguments)
+                            : toolCall.arguments;
+                        hookCtx.currentToolCall = {
+                            id: toolCall.id,
+                            name: tcName,
+                            arguments: tcArgs,
+                        };
+                        // Doom loop detection
+                        const doomKey = `${tcName}:${JSON.stringify(tcArgs)}`;
+                        const agentCache = this.doomLoopCaches.get(runId) || new Map();
+                        const doomCount = agentCache.get(doomKey) || 0;
+                        if (doomCount >= agent.config.doomLoopThreshold) {
+                            hookCtx.error = new Error(`Doom loop detected: ${tcName}`);
+                            await this.executePluginHooks(agent, "on.error", hookCtx);
+                            result.error = hookCtx.error.message;
+                            // Add placeholder results for remaining unprocessed tool calls
+                            this.addRemainingToolResults(hookCtx, allToolCalls, processedCount, "Execution aborted: Doom loop detected");
+                            break;
+                        }
+                        agentCache.set(doomKey, doomCount + 1);
+                        this.doomLoopCaches.set(runId, agentCache);
+                        // before.tool hook
+                        await this.executePluginHooks(agent, "agent:before.tool", hookCtx);
+                        if (hookCtx._stopped) {
+                            // Add placeholder results for remaining unprocessed tool calls
+                            this.addRemainingToolResults(hookCtx, allToolCalls, processedCount, "Execution aborted by plugin hook");
+                            break;
+                        }
+                        // Execute tool
+                        const toolResult = await this.executeTool(hookCtx);
+                        hookCtx.toolResult = toolResult;
+                        // after.tool hook
+                        await this.executePluginHooks(agent, "agent:after.tool", hookCtx);
+                        if (hookCtx._stopped) {
+                            // Add placeholder results for remaining unprocessed tool calls
+                            this.addRemainingToolResults(hookCtx, allToolCalls, processedCount + 1, "Execution aborted by plugin hook");
+                            break;
+                        }
+                        // Add tool result to messages (AI SDK v6 format)
+                        const toolOutput = toolResult.success ? toolResult.result.output || "" : toolResult.result.error || "Unknown error";
+                        const toolOutputPreview = typeof toolOutput === "string" ? toolOutput.substring(0, 50) : JSON.stringify(toolOutput).substring(0, 50);
+                        logger.debug(`[ReAct] Iteration ${iteration} Adding tool message: tool=${toolResult.name} output="${toolOutputPreview}..."`);
+                        this.pushMessage(hookCtx, {
+                            role: "tool",
+                            content: [{
+                                    type: "tool-result",
+                                    toolCallId: hookCtx.currentToolCall.id,
+                                    toolName: toolResult.name,
+                                    output: toolOutput,
+                                }],
+                        });
+                        // Record tool call
+                        result.toolCalls.push(hookCtx.currentToolCall);
+                        processedCount++;
+                    }
+                    // on.iteration hook
+                    await this.executePluginHooks(agent, "agent:on.iteration", hookCtx);
+                }
+            }
+            catch (error) {
+                logger.error(`Iteration ${iteration} error`, { error });
+                hookCtx.error = error instanceof Error ? error : new Error(String(error));
+                await this.executePluginHooks(agent, "agent:on.error", hookCtx);
+                // 设置 _stopped 标志（如果还没有被设置）
+                if (!hookCtx._stopped) {
+                    hookCtx._stopped = true;
+                    // 如果是 AskUserError，特殊处理
+                    if (error instanceof AskUserError) {
+                        hookCtx._stopReason = "ask-user";
+                        // ✅ 关键修复：当 ask_user 抛出异常时，也需要添加 tool result 消息
+                        // 这样可以保证 session 中有完整的 tool-call + tool-result 配对
+                        // Resume 时可以用用户响应替换这个 tool result
+                        if (hookCtx.currentToolCall) {
+                            this.pushMessage(hookCtx, {
+                                role: "tool",
+                                content: [{
+                                        type: "tool-result",
+                                        toolCallId: hookCtx.currentToolCall.id,
+                                        toolName: "ask_user",
+                                        output: JSON.stringify({
+                                            error: "AskUserError",
+                                            query: error.query,
+                                            message: error.message,
+                                        }),
+                                    }],
+                            });
+                        }
+                        // 将 AskUserError 信息编码到 result.error 中，供 AgentComponentAdapter 检测和恢复抛出
+                        // 使用 JSON 编码避免 query 中包含冒号导致解析错误
+                        const errorInfo = {
+                            query: error.query,
+                            sessionId: error.sessionId,
+                            nodeId: error.nodeId,
+                            nodeType: error.nodeType,
+                        };
+                        result.error = `__ASK_USER_ERROR__:${JSON.stringify(errorInfo)}`;
+                    }
+                    else {
+                        // 其他错误 - 也需要添加 tool result 消息保持配对完整
+                        result.error = hookCtx.error.message;
+                        // 如果是 AbortError，保留 abort 相关的 reason
+                        if (error?.name === "AbortError") {
+                            hookCtx._stopReason = hookCtx._stopReason || "aborted";
+                        }
+                        else {
+                            hookCtx._stopReason = "error";
+                        }
+                        // ✅ 添加 tool result 消息（包含错误信息）
+                        if (hookCtx.currentToolCall) {
+                            this.pushMessage(hookCtx, {
+                                role: "tool",
+                                content: [{
+                                        type: "tool-result",
+                                        toolCallId: hookCtx.currentToolCall.id,
+                                        toolName: hookCtx.currentToolCall.name,
+                                        output: JSON.stringify({ error: hookCtx.error.message }),
+                                    }],
+                            });
+                        }
+                    }
+                }
+                else {
+                    // 如果 _stopped 已经被设置为 true（例如在 executeTool 中），保留错误信息
+                    result.error = hookCtx.error.message;
+                    // ✅ 即使 _stopped 已为 true，也需要添加 tool result 消息
+                    // 这确保即使在 abort/doom-loop 等场景下，消息配对也是完整的
+                    if (hookCtx.currentToolCall) {
+                        const errorMsg = hookCtx.error?.message || "Execution interrupted";
+                        this.pushMessage(hookCtx, {
+                            role: "tool",
+                            content: [{
+                                    type: "tool-result",
+                                    toolCallId: hookCtx.currentToolCall.id,
+                                    toolName: hookCtx.currentToolCall.name,
+                                    output: JSON.stringify({ error: errorMsg }),
+                                }],
+                        });
+                    }
+                }
+                break;
+            }
+        }
+        // Update result
+        result.finalText = finalText;
+        if (iteration >= agent.config.maxIterations && !result.finalText) {
+            result.finalText = "Maximum iterations reached.";
+        }
+        // ✅ agent:after.react hook - React 循环结束后，用于记忆提取
+        // 传递 reactContext 包含 messages, sessionId, summary
+        const reactContext = {
+            messages: hookCtx.messages,
+            sessionId: effectiveContext.sessionId,
+            summary: result.finalText,
+        };
+        await this.executePluginHooks(agent, "agent:after.react", {
+            ...hookCtx,
+            ...reactContext,
+        });
+        // after.complete hook
+        await this.executePluginHooks(agent, "agent:after.complete", hookCtx);
+        // Finalize - 根据 abort 状态设置 agent 状态
+        if (this.aborted.get(runId) === true || hookCtx._stopped) {
+            agent.status = "stopped";
+        }
+        else {
+            agent.status = "idle";
+        }
+        this.aborted.delete(runId);
+        // 清理 AbortController
+        this.abortControllers.delete(runId);
+        // 发送 agent.completed 或 agent.error 事件
+        if (result.error) {
+            this.pushEnvEvent({
+                type: "agent.error",
+                payload: {
+                    error: result.error,
+                    iterations: result.iterations,
+                    stopReason: result.stopReason,
+                },
+            });
+        }
+        else {
+            this.pushEnvEvent({
+                type: "agent.completed",
+                payload: {
+                    finalText: result.finalText,
+                    iterations: result.iterations,
+                    stopReason: result.stopReason,
+                },
+            });
+        }
+        let newMessages = hookCtx.messages.slice(historyMessageCount);
+        logger.info(`Agent run completed: ${agentName}`, {
+            iterations: result.iterations,
+            hasError: !!result.error,
+            hookCtxMessages: hookCtx.messages.length,
+            historyMessageCount: historyMessageCount,
+            sessionId: effectiveContext.sessionId,
+        });
+        await this.recordSessionMessages(effectiveContext.sessionId, newMessages);
+        return this.finalizeResult(result, hookCtx);
+    }
+    /**
+     * 中止 Agent
+     *
+     * 调用此方法会：
+     * 1. 设置 aborted 标志（用于 ReAct 循环检查）
+     * 2. 触发 AbortController.abort()（用于中断正在进行的 LLM 调用）
+     *
+     * 注意：不直接修改 agent.status，由 _run() 的 finally 统一处理
+     */
+    abort(agentName) {
+        // 设置 aborted 标志 - 遍历所有该 agent 的 runId
+        for (const key of this.aborted.keys()) {
+            if (key.startsWith(agentName + ":")) {
+                this.aborted.set(key, true);
+            }
+        }
+        // 触发 AbortController 中断正在进行的 LLM 调用
+        for (const [key, controller] of this.abortControllers) {
+            if (key.startsWith(agentName + ":")) {
+                controller.abort();
+                logger.debug(`[abort] AbortController.abort() called for run: ${key}`);
+            }
+        }
+        logger.info(`Agent aborted: ${agentName}`);
+    }
+    /**
+     * 构建消息列表
+     *
+     * 注意：ctx.messages 已经包含了历史消息（包括 system prompt 和 user query）
+     * 这里只需要构建当前请求的消息，不重复添加
+     */
+    async buildMessages(ctx) {
+        const messages = [];
+        if (ctx.systemPrompt) {
+            messages.push({
+                role: "system",
+                content: ctx.systemPrompt,
+            });
+        }
+        // Addition info (temporary context) - 也需要检查是否已存在
+        if (ctx.additionInfo) {
+            messages.push({
+                role: "user",
+                content: `额外信息：\n${ctx.additionInfo}`,
+            });
+        }
+        // History messages（包含之前的所有消息）
+        messages.push(...ctx.messages);
+        return messages;
+    }
+    /**
+     * 调用 LLM
+     *
+     * 流式事件由 LLMComponent 通过 env.pushEnvEvent() 发布
+     */
+    async invokeLLM(ctx) {
+        logger.debug("[invokeLLM] Starting LLM invocation");
+        // 如果有 LLMComponent，使用它
+        if (this.llmComponent?.invoke) {
+            const messages = await this.buildMessages(ctx);
+            const convertedMessages = messages.map(toLLMMessage);
+            logger.debug(`[invokeLLM] Calling LLMComponent.invoke with ${convertedMessages.length} messages`);
+            try {
+                const result = await this.llmComponent.invoke({
+                    // 类型转换：ModelMessage[] -> LLMMessage[]
+                    messages: convertedMessages,
+                    // 类型转换：Tool[] -> ToolInfo[]
+                    // 注意：Tool.parameters 是 ZodType，需要提取其 JSON schema
+                    tools: ctx.tools.map(t => ({
+                        name: t.name,
+                        description: t.description || "",
+                        parameters: t.parameters ?? {},
+                    })),
+                    model: ctx.context.model,
+                    // 传递上下文用于事件元数据
+                    context: {
+                        sessionId: ctx.context.sessionId,
+                        messageId: ctx.context.messageId,
+                    },
+                    // 传递 abort signal 以支持 Agent 的优雅终止
+                    abortSignal: ctx.context.abort,
+                });
+                logger.debug("[invokeLLM] LLMComponent.invoke returned successfully");
+                return {
+                    content: result.output?.content || "",
+                    reasoning: result.output?.reasoning,
+                    toolCalls: result.output?.toolCalls?.map((tc) => ({
+                        id: tc.id,
+                        function: tc.function ? {
+                            name: tc.function.name,
+                            arguments: typeof tc.function.arguments === "string"
+                                ? tc.function.arguments
+                                : JSON.stringify(tc.function.arguments),
+                        } : undefined,
+                        name: tc.name,
+                        arguments: tc.arguments,
+                    })),
+                    finishReason: result.output?.finishReason,
+                };
+            }
+            catch (error) {
+                logger.error("[invokeLLM] LLMComponent.invoke threw an error:", error);
+                throw error;
+            }
+        }
+        // Fallback: Mock response for testing
+        logger.warn("[invokeLLM] No LLMComponent available, using mock");
+        return {
+            content: "Mock response: Hello!",
+            finishReason: "stop",
+        };
+    }
+    /**
+     * 执行工具
+     */
+    async executeTool(ctx) {
+        const toolCall = ctx.currentToolCall;
+        // 获取工具名称：优先使用 function.name（AI SDK v6 格式），兼容 toolCall.name
+        // AI SDK v6 格式: { id, name, function: { name, arguments } }
+        const toolName = toolCall.function?.name || toolCall.name || "unknown";
+        // Debug: 打印工具查找信息
+        logger.debug(`[executeTool] Looking for tool: "${toolName}"`);
+        logger.debug(`[executeTool] Available tools: [${ctx.tools.map(t => t.name).join(", ")}]`);
+        // Find tool
+        const tool = ctx.tools.find(t => t.name === toolName);
+        if (!tool) {
+            // 发送错误事件
+            this.pushEnvEvent({
+                type: "tool.error",
+                payload: {
+                    error: `Tool not found: ${toolName}`,
+                    toolName: toolName,
+                },
+            });
+            return {
+                id: toolCall.id,
+                name: toolName,
+                success: false,
+                result: {
+                    success: false,
+                    output: "",
+                    error: `Tool not found: ${toolName}`,
+                },
+            };
+        }
+        try {
+            // Convert AgentContext to ToolContext format
+            // AgentContext uses sessionId (camelCase), ToolContext uses session_id (snake_case)
+            const toolContext = {
+                session_id: ctx.context.sessionId,
+                message_id: ctx.context.messageId,
+                abort: ctx.context.abort,
+                workdir: ctx.context.metadata?.workdir,
+                metadata: ctx.context.metadata,
+            };
+            // Build ToolExecuteRequest
+            const request = {
+                name: toolName,
+                args: toolCall.arguments,
+                context: toolContext,
+            };
+            // Use ToolComponent.execute() to trigger tool hooks
+            // Check if we have a ToolComponent reference (via refreshDependencies)
+            let result;
+            if (this.toolComponent?.execute) {
+                result = await this.toolComponent.execute(request);
+            }
+            else {
+                // Fallback to direct tool execution (for backwards compatibility / testing)
+                logger.debug(`[executeTool] No ToolComponent available, executing tool directly`);
+                result = await tool.execute(toolCall.arguments, toolContext);
+            }
+            // 发送工具结果事件
+            this.pushEnvEvent({
+                type: "tool.result",
+                payload: {
+                    id: toolCall.id,
+                    name: toolName,
+                    result: result,
+                    success: result.success,
+                },
+            });
+            return {
+                id: toolCall.id,
+                name: toolName,
+                success: result.success,
+                result,
+            };
+        }
+        catch (error) {
+            // 检测 AskUserError - 这是用于工作流暂停的特殊错误，需要向上传播
+            if (error instanceof AskUserError) {
+                throw error; // 重新抛出，让调用栈上层（AgentComponentAdapter）处理
+            }
+            // 发送错误事件
+            this.pushEnvEvent({
+                type: "tool.error",
+                payload: {
+                    error: error instanceof Error ? error.message : String(error),
+                    toolName: toolName,
+                },
+            });
+            return {
+                id: toolCall.id,
+                name: toolName,
+                success: false,
+                result: {
+                    success: false,
+                    output: "",
+                    error: error instanceof Error ? error.message : String(error),
+                },
+            };
+        }
+    }
+    /**
+     * 执行 Plugin Hooks (Agent 特有的 Hook 执行机制)
+     */
+    async executePluginHooks(agent, point, ctx) {
+        // Collect all hooks for this point
+        const hooks = [];
+        for (const [name, plugin] of agent.plugins) {
+            for (const hook of plugin.hooks) {
+                if (hook.point === point) {
+                    hooks.push({
+                        plugin,
+                        priority: hook.priority ?? 0,
+                        execute: plugin.execute,
+                    });
+                }
+            }
+        }
+        // Sort by priority (higher first)
+        hooks.sort((a, b) => b.priority - a.priority);
+        // Execute hooks
+        for (const { plugin, execute } of hooks) {
+            try {
+                const result = await execute(ctx);
+                if (!result.continue) {
+                    ctx._stopped = true;
+                    ctx._stopReason = `Plugin ${plugin.name} stopped execution`;
+                    logger.info(`Hook ${point} stopped by plugin ${plugin.name}`);
+                    break;
+                }
+                // Handle actions
+                if (result.action) {
+                    await this.handleHookAction(result.action, ctx);
+                }
+            }
+            catch (error) {
+                logger.error(`Hook ${point} error in plugin ${plugin.name}`, { error });
+                ctx._errors = ctx._errors || [];
+                ctx._errors.push({
+                    plugin: plugin.name,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+    }
+    /**
+     * 处理 Hook 动作
+     */
+    async handleHookAction(action, ctx) {
+        switch (action.type) {
+            case "stop":
+                ctx._stopped = true;
+                ctx._stopReason = "stopped_by_hook";
+                break;
+            case "inject_message":
+                if (action.payload && typeof action.payload === "object") {
+                    const msg = action.payload;
+                    ctx.messages.push(msg);
+                }
+                break;
+            case "skip_tool":
+                // Skip current tool execution
+                ctx._pendingAction = action;
+                break;
+            // Other actions can be extended
+        }
+    }
+    /**
+     * 通知消息添加（扩展点）
+     */
+    notifyMessageAdded(message) {
+        // 可被子类或插件覆盖
+        logger.debug(`Message added: ${message.role}`);
+    }
+    /**
+     * 结束结果
+     */
+    finalizeResult(result, ctx) {
+        return {
+            ...result,
+            stopped: ctx._stopped,
+            stopReason: ctx._stopReason,
+        };
+    }
+    /**
+     * Record messages to session
+     *
+     * 存储策略：
+     * 1. 存储 allMessages 中的所有 user、assistant、tool 消息
+     * 2. 跳过 system 消息
+     * 3. 跳过空内容的 assistant/tool 消息
+     */
+    async recordSessionMessages(sessionId, allMessages = []) {
+        if (!sessionId) {
+            return;
+        }
+        try {
+            const sessionComponent = this.env.getComponent("session");
+            if (!sessionComponent) {
+                logger.warn("SessionComponent not found, skipping session recording");
+                return;
+            }
+            for (const msg of allMessages) {
+                // 跳过 system 消息
+                if (msg.role === "system") {
+                    continue;
+                }
+                // 跳过空内容的 assistant/tool 消息
+                if (msg.role === "assistant" || msg.role === "tool") {
+                    if (this.isEmptyMessage(msg.content)) {
+                        continue;
+                    }
+                }
+                await sessionComponent.addMessage(sessionId, this.messageConverter.fromModelMessage(msg, { sessionID: sessionId }));
+            }
+        }
+        catch (err) {
+            logger.warn(`Failed to record session messages: ${err}`);
+        }
+    }
+    /**
+     * 检查消息内容是否为空
+     *
+     * 空内容定义：
+     * - 空字符串 ""
+     * - 空数组 []
+     * - null
+     * - undefined
+     *
+     * @param content - 消息内容
+     * @returns 是否为空
+     */
+    isEmptyMessage(content) {
+        if (content === null || content === undefined) {
+            return true;
+        }
+        if (typeof content === "string" && content.trim() === "") {
+            return true;
+        }
+        if (Array.isArray(content) && content.length === 0) {
+            return true;
+        }
+        return false;
+    }
+    /**
+     * 通过 Environment 发送事件
+     */
+    pushEnvEvent(event) {
+        if (this.env && "pushEnvEvent" in this.env) {
+            try {
+                const fullEvent = {
+                    id: `evt_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
+                    type: event.type,
+                    timestamp: Date.now(),
+                    metadata: {
+                        source: "agent",
+                        agent_name: this.name,
+                    },
+                    payload: event.payload,
+                };
+                this.env?.pushEnvEvent(fullEvent);
+            }
+            catch (err) {
+                logger.warn(`[pushEnvEvent] Failed to push event: ${err}`);
+            }
+        }
+    }
+    /**
+     * 获取会话对话历史
+     *
+     * 核心逻辑：
+     * 1. 使用 sessionComponent.getContext() 获取消息（自动从 checkpoint 开始）
+     * 2. 根据 messageLimit 限制消息数量（向后兼容 minUserMessages）
+     * 3. 过滤掉 tool_call/tool_result 消息（如果 filterHistory=true）
+     *
+     * 关键改进：利用 checkpoint 概念，避免重复获取已压缩的历史消息，
+     * 从而减少重复触发压缩的问题。
+     *
+     * @param sessionComponent - SessionComponent 实例
+     * @param sessionId - 会话 ID
+     * @param options - 配置选项
+     * @param options.minUserMessages - 最少包含的 user 消息数量（默认 100）
+     * @param options.filterHistory - 是否过滤 tool 消息（默认 true）
+     * @returns 过滤后的会话消息列表
+     */
+    async getConversationHistory(sessionComponent, sessionId, options = {}) {
+        const minUserMessages = options.minUserMessages ?? 100;
+        const filterHistory = options.filterHistory ?? false;
+        // 使用 getContext 获取消息，自动从最新 checkpoint 开始
+        // 且确保从 user 消息边界截取，避免 tool_call/tool_result 配对被截断
+        const ctx = await sessionComponent.getContext(sessionId, {
+            fullHistory: false,
+            minUserMessages,
+        });
+        let messages = ctx.messages;
+        // 根据 filterHistory 配置决定是否过滤 tool 消息
+        if (filterHistory) {
+            messages = messages.filter(msg => {
+                if (msg.metadata?.type === "tool_call" || msg.metadata?.type === "tool_result") {
+                    return false;
+                }
+                return msg.role === "user" || msg.role === "assistant";
+            });
+        }
+        return messages;
+    }
+}
+__decorate([
+    TracedAs("agent.component.run", { recordParams: true, recordResult: true, log: true }),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, String, Object]),
+    __metadata("design:returntype", Promise)
+], AgentComponent.prototype, "_run", null);
+__decorate([
+    TracedAs("agent.component.invokeLLM", { recordParams: true, recordResult: true, log: true }),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], AgentComponent.prototype, "invokeLLM", null);
+__decorate([
+    TracedAs("agent.component.executeTool", { recordParams: true, recordResult: true, log: true }),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], AgentComponent.prototype, "executeTool", null);
+__decorate([
+    TracedAs("agent.component.recordSessionMessages", { recordParams: true, recordResult: true, log: true }),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, Array]),
+    __metadata("design:returntype", Promise)
+], AgentComponent.prototype, "recordSessionMessages", null);
+__decorate([
+    TracedAs("agent.component.getConversationHistory", { recordParams: true, recordResult: true, log: true }),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Function, String, Object]),
+    __metadata("design:returntype", Promise)
+], AgentComponent.prototype, "getConversationHistory", null);
+//# sourceMappingURL=agent-component.js.map