@ai-setting/roy-agent-core 1.0.0

package/src/env/agent/agent-component.ts

@@ -0,0 +1,1711 @@
+/**
+ * @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 用于日志
+ */
+
+import { BaseComponent, type ComponentConfig } from "../component";
+import { createLogger } from "../log-trace/logger";
+import type {
+  AgentInstance,
+  AgentInstanceConfig,
+  AgentRunResult,
+  AgentContext,
+  Plugin,
+  HookContext,
+  HookPoint,
+  Tool,
+  ToolCallResult,
+  AgentLLMOutput,
+  HookActionType,
+} from "./types";
+import type { EnvEvent } from "../types";
+import type { ModelMessage } from "ai";
+import type { LLMMessage } from "../llm/types";
+import { z } from "zod";
+
+// LLMComponent 和 ToolComponent 类型
+import type { LLMComponent } from "../llm/llm";
+import type { ToolComponent } from "../tool/tool-component";
+import type { ToolContext, ToolExecuteRequest } from "../tool/types";
+import type { ConfigComponent } from "../../config/config-component";
+import { envKeyToConfigKey } from "../../config/env-key";
+import { AGENT_CONFIG_REGISTRATION, AGENT_DEFAULTS } from "./agent-config-registration";
+import { TracedAs } from "../log-trace/decorator";
+// SessionComponent 类型
+import type { SessionComponent, SessionMessage } from "../session/session-component";
+
+// Session Message 转换器
+import { SessionMessageConverter } from "../session/session-message-converter";
+
+// AskUserError - 用于工作流暂停的特定错误
+import { AskUserError } from "../workflow/types/workflow-hil";
+
+// ============================================================================
+// Logger
+// ============================================================================
+
+const logger = createLogger("agent:component");
+
+// ============================================================================
+// Type Conversion Utilities
+// ============================================================================
+
+/**
+ * 将 ModelMessage 转换为 LLMMessage
+ * 
+ * ModelMessage 来自 ai SDK，LLMMessage 是内部格式
+ */
+function toLLMMessage(msg: ModelMessage): LLMMessage {
+  // 处理 content 字段
+  let content: string;
+  let toolCallId: string | undefined;
+  let toolName: string | undefined;
+  // 使用 any 类型避免 ai SDK 和内部 ToolCall 类型不兼容
+  let toolCalls: any[] | undefined;
+
+  if (typeof msg.content === "string") {
+    content = msg.content;
+    // 对于 tool 消息，提取 toolCallId 和 toolName
+    if (msg.role === "tool") {
+      toolCallId = (msg as any).toolCallId;
+      toolName = (msg as any).toolName;
+    }
+    // assistant 消息可能包含 toolCalls（ai SDK v6 格式）
+    if (msg.role === "assistant" && (msg as any).toolCalls) {
+      toolCalls = (msg as any).toolCalls;
+    }
+  } else if (Array.isArray(msg.content)) {
+    // 处理 tool 消息（AI SDK v6 格式）
+    if (msg.role === "tool") {
+      // 提取 tool-result 的 output
+      const toolResult = msg.content.find((part: any) => part.type === "tool-result") as any;
+      // 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: any) => part.type === "text");
+      const toolCallParts = msg.content.filter((part: any) => part.type === "tool-call");
+      
+      // 提取文本内容
+      content = textParts.map((part: any) => 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: any) => {
+          // 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 as "system" | "user" | "assistant" | "tool",
+    content,
+    ...(toolCallId ? { toolCallId } : {}),
+    ...(toolName ? { name: toolName } : {}),
+    ...(toolCalls && toolCalls.length > 0 ? { toolCalls } : {}),
+  };
+}
+
+// ============================================================================
+// Config Schema
+// ============================================================================
+
+/**
+ * AgentComponent 默认配置
+ */
+const DEFAULT_AGENT_CONFIG = {
+  type: "primary" as const,
+  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,
+});
+
+export type AgentComponentConfig = z.infer<typeof AgentComponentConfigSchema>;
+
+// ============================================================================
+// AgentComponentOptions (统一配置机制)
+// ============================================================================
+
+/**
+ * AgentComponent 配置选项（通过 options 传递）
+ * 
+ * 配置加载顺序（优先级从低到高）：
+ * 1. File - 配置文件（通过 configPath 指定）
+ * 2. Env - 环境变量（通过 envPrefix 配置前缀）
+ * 3. Object - 直接传入的 config 对象（最高优先级）
+ */
+export interface AgentComponentOptions {
+  /** ConfigComponent 实例（必填） */
+  configComponent: ConfigComponent;
+  
+  /** 配置文件相对路径（可选，基于 XDG_DATA_HOME） */
+  configPath?: string;
+  
+  /** 环境变量前缀（可选，默认 "AGENT"） */
+  envPrefix?: string;
+  
+  /** 直接传入的配置对象（可选，优先级最高） */
+  config?: Partial<AgentComponentConfig>;
+}
+
+// ============================================================================
+// AgentComponent
+// ============================================================================
+
+/**
+ * AgentComponent
+ * 
+ * 提供 Agent 执行能力和 Hook 扩展机制
+ */
+export class AgentComponent extends BaseComponent {
+  readonly name = "agent";
+  readonly version = "1.0.0";
+
+  private agents: Map<string, AgentInstance> = new Map();
+  private config: AgentComponentConfig;
+  private llmComponent: LLMComponent | null = null;
+  private toolComponent: ToolComponent | null = null;
+  private aborted: Map<string, boolean> = new Map();
+  private abortControllers: Map<string, AbortController> = new Map();  // Agent Run 的 AbortController，使用 runId 作为 key
+  private defaultTools: Tool[] = [];
+
+  // Doom loop detection cache (per-agent for isolation)
+  private doomLoopCaches: Map<string, Map<string, number>> = new Map();
+  
+  /** ConfigComponent 用于配置管理 */
+  private configComponent?: ConfigComponent;
+  
+  /** 配置变更 watcher 清理函数 */
+  private configWatcher?: () => void;
+  
+  /** Session 消息转换器 */
+  private messageConverter = new SessionMessageConverter();
+  
+  /** 构造函数传入的配置（最高优先级） */
+  private _constructorConfig?: { defaultAgent?: Partial<AgentComponentConfig["defaultAgent"]> };
+
+  /** Run ID 计数器（用于生成唯一的 runId） */
+  private runCounter = 0;
+
+  constructor(options: {
+    config?: Partial<AgentComponentConfig>;
+  } = {}) {
+    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: ComponentConfig): Promise<void> {
+    // 调用基类 init，注入 env
+    await super.init(config);
+
+    // 从 options 获取 ConfigComponent
+    const options = config.options as unknown as AgentComponentOptions | undefined;
+    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 对象 - 直接传入的配置（最高）
+   */
+  private async registerConfig(options: AgentComponentOptions): Promise<void> {
+    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") as number) 
+        ?? 200,
+      maxErrorRetries: constructorDefaultAgent?.maxErrorRetries
+        ?? (configComponent.get("agent.defaultAgent.maxErrorRetries") as number) 
+        ?? 3,
+      doomLoopThreshold: constructorDefaultAgent?.doomLoopThreshold
+        ?? (configComponent.get("agent.defaultAgent.doomLoopThreshold") as number) 
+        ?? 5,
+      toolTimeout: constructorDefaultAgent?.toolTimeout
+        ?? (configComponent.get("agent.defaultAgent.toolTimeout") as number) 
+        ?? 60000,
+      toolRetries: constructorDefaultAgent?.toolRetries
+        ?? (configComponent.get("agent.defaultAgent.toolRetries") as number) 
+        ?? 3,
+      filterHistory: constructorDefaultAgent?.filterHistory
+        ?? (configComponent.get("agent.defaultAgent.filterHistory") as boolean) 
+        ?? false,
+      type: constructorDefaultAgent?.type
+        ?? (configComponent.get("agent.defaultAgent.type") as "primary" | "sub") 
+        ?? "primary",
+      systemPrompt: constructorDefaultAgent?.systemPrompt
+        ?? (configComponent.get("agent.defaultAgent.systemPrompt") as string | undefined),
+      model: constructorDefaultAgent?.model
+        ?? (configComponent.get("agent.defaultAgent.model") as string | undefined),
+      behaviorSpecId: constructorDefaultAgent?.behaviorSpecId
+        ?? (configComponent.get("agent.defaultAgent.behaviorSpecId") as string | undefined),
+    };
+
+    logger.info(`[registerConfig] Synced config from ConfigComponent: maxIterations=${this.config.defaultAgent.maxIterations}`);
+
+    // 9. 注册配置热更新监听
+    this.registerConfigWatcher(configComponent);
+  }
+
+  /**
+   * 将配置对象展平为点号路径
+   */
+  private flattenConfig(
+    obj: Record<string, unknown>,
+    prefix = "agent"
+  ): Record<string, unknown> {
+    const result: Record<string, unknown> = {};
+    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 as Record<string, unknown>, fullKey)
+        );
+      } else {
+        result[fullKey] = value;
+      }
+    }
+    return result;
+  }
+
+  /**
+   * 注册配置热更新监听
+   */
+  private registerConfigWatcher(configComponent: ConfigComponent): void {
+    if (typeof configComponent.watch !== "function") {
+      return;
+    }
+    
+    this.configWatcher = configComponent.watch("agent.*", (event) => {
+      this.onConfigChange(event);
+    });
+  }
+
+  /**
+   * 处理配置变更
+   */
+  protected onConfigChange(event: { key: string; oldValue?: unknown; newValue?: unknown }): void {
+    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 注册表
+   */
+  protected async onStop(): Promise<void> {
+    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(): void {
+    if (this.env) {
+      const llm = this.env.getComponent("llm");
+      const tool = this.env.getComponent("tool");
+      this.llmComponent = llm ? llm as unknown as LLMComponent : null;
+      this.toolComponent = tool ? tool as unknown as ToolComponent : null;
+      
+      logger.debug("[refreshDependencies] AgentComponent refreshed", {
+        hasLLM: !!this.llmComponent,
+        hasTool: !!this.toolComponent,
+      });
+    }
+  }
+
+  /**
+   * 获取 Agent 实例
+   */
+  getAgent(agentName: string): AgentInstance | undefined {
+    return this.agents.get(agentName);
+  }
+
+  /**
+   * 获取所有 Agent 实例
+   */
+  listAgents(): AgentInstance[] {
+    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
+   */
+  private addRemainingToolResults(
+    ctx: HookContext,
+    allToolCalls: Array<{ id: string; name?: string; function?: { name?: string; arguments?: string | unknown } }>,
+    processedCount: number,
+    reason: string
+  ): void {
+    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" as const,
+          toolCallId: tc.id,
+          toolName: tcName,
+          output: JSON.stringify({ error: reason }),
+        }],
+      } as unknown as ModelMessage);
+    }
+  }
+
+  /**
+   * 注册 Agent
+   * 
+   * 配置优先级（从高到低）：
+   * 1. registerAgent 传入的 config（来自 PromptComponent）
+   * 2. defaultAgent 配置（来自 ConfigComponent，作为 fallback）
+   */
+  registerAgent(name: string, config: Partial<AgentInstanceConfig>): AgentInstance {
+    // 合并配置：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: AgentInstance = {
+      name,
+      config: mergedConfig as AgentInstance["config"],
+      status: "idle",
+      plugins: new Map(),
+    };
+
+    this.agents.set(name, instance);
+    logger.info(`Agent registered: ${name}`, { type: instance.config.type });
+    return instance;
+  }
+
+  /**
+   * 注销 Agent
+   */
+  unregisterAgent(name: string): boolean {
+    const deleted = this.agents.delete(name);
+    if (deleted) {
+      logger.info(`Agent unregistered: ${name}`);
+    }
+    return deleted;
+  }
+
+  /**
+   * 注册 Plugin 到指定 Agent
+   */
+  registerPlugin(agentName: string, plugin: Plugin): void {
+    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: string, pluginName: string): boolean {
+    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: Tool[]): void {
+    this.defaultTools = tools;
+  }
+
+  /**
+   * 获取可用工具
+   */
+  getAvailableTools(agent: AgentInstance, context?: AgentContext): Tool[] {
+    // 首先添加 defaultTools（来自 setDefaultTools 的 Memory Agent tools）
+    let tools: Tool[] = [...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() as unknown as Tool[];
+      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: string,
+    query: string,
+    context?: AgentContext
+  ): Promise<AgentRunResult> {
+    return this._run(agentName, query, context);
+  }
+
+  private pushMessage(hookCtx: HookContext, message: ModelMessage){
+    hookCtx.messages.push(message);
+    this.notifyMessageAdded(message);
+  }
+
+  /**
+   * 执行 Agent（核心方法，内部实现）
+   */
+  @TracedAs("agent.component.run", { recordParams: true, recordResult: true, log: true })
+  private async _run(
+    agentName: string,
+    query: string,
+    context?: AgentContext
+  ): Promise<AgentRunResult> {
+    // 刷新依赖组件引用（确保获取到最新的组件）
+    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: AgentContext = {
+      ...context,
+      agentType: agent.config.type,
+      model: agent.config.model,
+      // 设置 abort signal（支持通过 abort() 方法中断 LLM 调用）
+      abort: abortController.signal,
+    };
+
+    // Initialize result
+    const result: AgentRunResult = {
+      iterations: 0,
+      toolCalls: [],
+    };
+
+    // Create HookContext
+    const hookCtx: HookContext = {
+      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<SessionComponent>("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)) as unknown as ModelMessage[];
+          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,
+    } as unknown as ModelMessage);
+    
+    // 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: string | undefined;
+
+    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,
+          } as unknown as ModelMessage);
+          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: any[] = [];
+          
+          // 1. Add text content if present
+          if (llmOutput.content) {
+            assistantParts.push({
+              type: "text" as const,
+              text: llmOutput.content,
+            });
+          }
+          
+          // 2. Add reasoning content if present (for reasoning models)
+          if (llmOutput.reasoning) {
+            assistantParts.push({
+              type: "reasoning" as const,
+              text: llmOutput.reasoning,
+              reasoningType: "core",
+            });
+          }
+          
+          // 3. Add tool-call parts
+          for (const tc of llmOutput.toolCalls) {
+            let argsStr = "";
+            let argsObj: Record<string, unknown> = {};
+            
+            // 提取参数：优先从 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 as Record<string, unknown>;
+                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 as Record<string, unknown>;
+                argsStr = JSON.stringify(argsObj);
+              }
+            }
+            
+            assistantParts.push({
+              type: "tool-call" as const,
+              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,
+          } as unknown as ModelMessage);
+
+          // 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 as Record<string, unknown>,
+            };
+
+            // 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,
+              }],
+            } as unknown as ModelMessage);
+
+            // 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,
+                  }),
+                }],
+              } as unknown as ModelMessage);
+            }
+            
+            // 将 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 as any)?.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 }),
+                }],
+              } as unknown as ModelMessage);
+            }
+          }
+        } 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 }),
+              }],
+            } as unknown as ModelMessage);
+          }
+        }
+        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: string): void {
+    // 设置 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）
+   * 这里只需要构建当前请求的消息，不重复添加
+   */
+  private async buildMessages(
+    ctx: HookContext,
+  ): Promise<ModelMessage[]> {
+    const messages: ModelMessage[] = [];
+
+    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() 发布
+   */
+  @TracedAs("agent.component.invokeLLM", { recordParams: true, recordResult: true, log: true })
+  private async invokeLLM(ctx: HookContext): Promise<AgentLLMOutput> {
+    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 as unknown as Record<string, unknown>) ?? {},
+          })),
+          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",
+    };
+  }
+
+  /**
+   * 执行工具
+   */
+  @TracedAs("agent.component.executeTool", { recordParams: true, recordResult: true, log: true })
+  private async executeTool(ctx: HookContext): Promise<ToolCallResult> {
+    const toolCall = ctx.currentToolCall!;
+    
+    // 获取工具名称：优先使用 function.name（AI SDK v6 格式），兼容 toolCall.name
+    // AI SDK v6 格式: { id, name, function: { name, arguments } }
+    const toolName = (toolCall as any).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: ToolContext = {
+        session_id: ctx.context.sessionId,
+        message_id: ctx.context.messageId,
+        abort: ctx.context.abort,
+        workdir: ctx.context.metadata?.workdir as string | undefined,
+        metadata: ctx.context.metadata,
+      };
+
+      // Build ToolExecuteRequest
+      const request: ToolExecuteRequest = {
+        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 执行机制)
+   */
+  private async executePluginHooks(
+    agent: AgentInstance,
+    point: HookPoint,
+    ctx: HookContext
+  ): Promise<void> {
+    // Collect all hooks for this point
+    const hooks: Array<{ plugin: Plugin; priority: number; execute: Function }> = [];
+    
+    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 动作
+   */
+  private async handleHookAction(
+    action: { type: string; payload?: unknown },
+    ctx: HookContext
+  ): Promise<void> {
+    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 as ModelMessage;
+          ctx.messages.push(msg);
+        }
+        break;
+      case "skip_tool":
+        // Skip current tool execution
+        ctx._pendingAction = action as { type: HookActionType; payload?: unknown };
+        break;
+      // Other actions can be extended
+    }
+  }
+
+  /**
+   * 通知消息添加（扩展点）
+   */
+  protected notifyMessageAdded(message: ModelMessage): void {
+    // 可被子类或插件覆盖
+    logger.debug(`Message added: ${message.role}`);
+  }
+
+  /**
+   * 结束结果
+   */
+  private finalizeResult(result: AgentRunResult, ctx: HookContext): AgentRunResult {
+    return {
+      ...result,
+      stopped: ctx._stopped,
+      stopReason: ctx._stopReason,
+    };
+  }
+
+  /**
+   * Record messages to session
+   * 
+   * 存储策略：
+   * 1. 存储 allMessages 中的所有 user、assistant、tool 消息
+   * 2. 跳过 system 消息
+   * 3. 跳过空内容的 assistant/tool 消息
+   */
+  @TracedAs("agent.component.recordSessionMessages", { recordParams: true, recordResult: true, log: true })
+  private async recordSessionMessages(
+    sessionId: string | undefined,
+    allMessages: ModelMessage[] = []
+  ): Promise<void> {
+    if (!sessionId) {
+      return;
+    }
+
+    try {
+      const sessionComponent = this.env.getComponent<SessionComponent>("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 as unknown as ModelMessage, { sessionID: sessionId })
+        );
+      }
+
+    } catch (err) {
+      logger.warn(`Failed to record session messages: ${err}`);
+    }
+  }
+  
+  /**
+   * 检查消息内容是否为空
+   * 
+   * 空内容定义：
+   * - 空字符串 ""
+   * - 空数组 []
+   * - null
+   * - undefined
+   * 
+   * @param content - 消息内容
+   * @returns 是否为空
+   */
+  private isEmptyMessage(content: unknown): boolean {
+    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 发送事件
+   */
+  private pushEnvEvent(event: { type: string; payload: Record<string, unknown> }): void {
+    if (this.env && "pushEnvEvent" in this.env) {
+      try {
+        const fullEvent: EnvEvent = {
+          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 过滤后的会话消息列表
+   */
+  @TracedAs("agent.component.getConversationHistory", { recordParams: true, recordResult: true, log: true })
+  private async getConversationHistory(
+    sessionComponent: SessionComponent,
+    sessionId: string,
+    options: { minUserMessages?: number; filterHistory?: boolean } = {}
+  ): Promise<SessionMessage[]> {
+    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;
+  }
+}