@ai-setting/roy-agent-core 1.0.0

package/src/env/workflow/nodes/agent-node.ts

@@ -0,0 +1,598 @@
+/**
+ * @fileoverview AgentNode - Delegate work to an AI agent
+ * 
+ * AgentNode delegates work to an AI agent with task description and context.
+ */
+
+import { Node, NodeDefinition, NodeExecutionContext, NodeExecutionResult } from '../types';
+import type { SessionComponent } from '../../session/session-component';
+import { AskUserError } from '../types/workflow-hil';
+import { TracedAs } from '../../log-trace/decorator';
+
+// ============================================================================
+// Agent Types
+// ============================================================================
+
+/**
+ * Agent 注册配置
+ */
+export interface AgentRegistrationConfig {
+  /** Agent 类型 */
+  type?: string;
+  /** 系统提示词 */
+  systemPrompt?: string;
+  /** 模型名称 */
+  model?: string;
+  /** 最大迭代次数 */
+  maxIterations?: number;
+  /** 允许的工具列表 */
+  allowedTools?: string[];
+  /** 禁止的工具列表 */
+  deniedTools?: string[];
+}
+
+/**
+ * AgentRunner 接口
+ * 
+ * 用于运行 AI Agent 的接口
+ */
+export interface AgentRunner {
+  /**
+   * 运行 Agent
+   * @param config Agent 配置
+   * @param resumeOptions 可选的恢复选项（用于恢复暂停的 agent）
+   * @returns Agent 执行结果
+   */
+  run(config: AgentConfig, resumeOptions?: { userResponse?: string; agentSessionId?: string }): Promise<AgentResult>;
+  
+  /**
+   * 恢复暂停的 Agent
+   * 
+   * @param agentSessionId Agent session ID
+   * @param userResponse 用户的响应
+   * @param config 原始的 agent 配置
+   * @returns Agent 执行结果
+   */
+  resumeAgent?(agentSessionId: string, userResponse: string, config: AgentConfig): Promise<AgentResult>;
+  
+  /**
+   * 获取当前 agent session ID
+   */
+  getCurrentAgentSessionId?(): string | undefined;
+  
+  /**
+   * 设置 SessionComponent
+   */
+  setSessionComponent?(sessionComponent: SessionComponent): void;
+  
+  /**
+   * 获取待恢复的 session 信息
+   */
+  getPendingSession?(agentSessionId: string): { agentSessionId: string; nodeId: string; runId: string; createdAt: number } | undefined;
+  
+  /**
+   * 注册 Agent（如果不存在）
+   */
+  registerAgent?(name: string, config: AgentRegistrationConfig): void;
+  
+  /**
+   * 检查 Agent 是否已注册
+   */
+  hasAgent?(name: string): boolean;
+}
+
+/**
+ * Agent 配置
+ */
+export interface AgentConfig {
+  /** Agent 类型 */
+  type: string;
+  /** Prompt（任务描述） */
+  prompt: string;
+  /** 可选配置 */
+  options?: {
+    /** 超时时间（毫秒） */
+    timeout?: number;
+    /** 模型名称 */
+    model?: string;
+    /** 允许的工具列表（用于限制 agent 可用的工具） */
+    allowedTools?: string[];
+    /** 拒绝的工具列表 */
+    deniedTools?: string[];
+  };
+  /** Workflow 历史消息（来自前置 agent 节点） */
+  workflowHistory?: Array<{
+    role: 'user' | 'assistant' | 'tool';
+    content: string;
+    toolCallId?: string;
+    toolName?: string;
+    nodeId?: string;
+  }>;
+  /** 节点 ID（用于 history 标记） */
+  nodeId?: string;
+  /** Agent sub-session ID（用于 HiL resume） */
+  agentSessionId?: string;
+}
+
+/**
+ * Agent 执行结果
+ */
+export interface AgentResult {
+  /** Agent 输出 */
+  output: unknown;
+  /** 执行元数据 */
+  metadata?: {
+    /** 消耗的 token 数量 */
+    tokens?: number;
+    /** 执行耗时（毫秒） */
+    duration?: number;
+    /** 其他元数据 */
+    [key: string]: unknown;
+  };
+  /** 生成的消息列表（用于 workflow history 累积） */
+  messages?: Array<{
+    role: 'user' | 'assistant' | 'tool';
+    content: string;
+    toolCallId?: string;
+    toolName?: string;
+    nodeId?: string;
+  }>;
+}
+
+// ============================================================================
+// AgentNode Implementation
+// ============================================================================
+
+/**
+ * AgentNode 类
+ * 
+ * 委托 AI Agent 执行任务的节点类型
+ */
+export class AgentNode implements Node {
+  /** 节点类型 */
+  readonly type = 'agent';
+  /** 节点 ID */
+  readonly id: string;
+
+  /**
+   * 创建 AgentNode
+   * @param definition 节点定义
+   * @param agentRunner Agent 运行器
+   */
+  constructor(
+    private definition: NodeDefinition,
+    private agentRunner: AgentRunner
+  ) {
+    this.id = definition.id;
+  }
+
+  /**
+   * 执行 AgentNode
+   * 
+   * 流程：
+   * 1. 从 definition.config 获取 agent 配置
+   * 2. 解析 prompt 模板（可能引用前置节点输出）
+   * 3. 通过 agentRunner 运行 agent
+   * 4. 返回 agent 结果
+   * 
+   * @param context 执行上下文
+   * @returns 执行结果
+   */
+  @TracedAs("agent.node.execute", { recordParams: true, recordResult: true, log: true })
+  async execute(context: NodeExecutionContext): Promise<NodeExecutionResult> {
+    const startTime = Date.now();
+
+    try {
+      // 1. 从配置中获取 agent 参数
+      const config = this.definition.config as Record<string, unknown> || {};
+      const agentType = (config.agent_type as string) || 'general';
+      const promptTemplate = (config.prompt as string) || '';
+      const options = (config.options as AgentConfig['options']) || {};
+
+      // 2. 解析 prompt 模板
+      const resolvedPrompt = this.resolveTemplate(promptTemplate, context);
+
+      // 3. 自动注册 agent（如果不存在）
+      // 这样 workflow 定义中引用的 agent 类型会被自动注册，无需手动预注册
+      if (this.agentRunner.registerAgent && this.agentRunner.hasAgent) {
+        if (!this.agentRunner.hasAgent(agentType)) {
+          this.agentRunner.registerAgent(agentType, {
+            type: agentType,
+            systemPrompt: (config.system_prompt as string) || `You are a ${agentType} agent.`,
+            model: options.model,
+          });
+        }
+      }
+
+      // 4. 检查是否需要恢复执行（从 pause 恢复时传递了 userResponse）
+      // 从 context 中获取恢复选项（由 engine.resumeNode 设置）
+      const userResponse = (context as any).userResponse;
+      let agentSessionId = (context as any).agentSessionId;
+      
+      // 5. 如果不是恢复模式，创建 agent sub-session
+      // Sub-session 用于存储 agent 的对话历史，支持 resume
+      if (!userResponse && context.sessionComponent && !agentSessionId) {
+        agentSessionId = await this.createAgentSubSession(context);
+        
+        // 将 agentSessionId 设置到 context 中，供后续使用（如 AskUserError）
+        // 注意：NodeExecutionContext 是引用类型，直接修改会生效
+        (context as any).agentSessionId = agentSessionId;
+      }
+      
+      // 6. 构建 AgentConfig
+      // 注意：添加 allowedTools: ['ask_user'] 确保 ask_user 工具在 workflow agent 上下文中可用
+      // 这样 ask_user 只在 workflow agent 中可用，不影响 default agent 和 sub agent
+      const agentConfig: AgentConfig = {
+        type: agentType,
+        prompt: resolvedPrompt,
+        options: {
+          timeout: options.timeout,
+          model: options.model,
+          // 添加 ask_user 到 allowedTools，确保 workflow agent 可以调用此工具
+          allowedTools: ['ask_user'],
+        },
+        // 传递 workflow history（来自前置 agent 节点）
+        workflowHistory: context.workflowHistory,
+        // 传递节点信息（用于 history 标记）
+        nodeId: this.definition.id,
+        // 传递 agent sub-session ID
+        agentSessionId,
+      };
+
+      // 如果有 userResponse，说明是从 pause 恢复的，应该传递给 agentRunner
+      const resumeOptions = userResponse 
+        ? { userResponse, agentSessionId } 
+        : undefined;
+
+      // 7. 运行 agent（传递 resumeOptions 如果是从 pause 恢复的）
+      const result = await this.agentRunner.run(agentConfig, resumeOptions);
+
+      // 8. 计算执行耗时
+      const duration = Date.now() - startTime;
+
+      // 9. 返回成功结果
+      return {
+        output: {
+          result: result.output,
+          metadata: result.metadata,
+          // 返回 workflow history 供 WorkflowEngine 累积
+          workflowHistory: result.messages,
+        },
+        error: undefined,
+        duration,
+      };
+    } catch (error) {
+      // 检查是否是 AskUserError - 这是用于工作流暂停的特殊错误，需要向上传播
+      // 以便 Executor 能够正确处理暂停逻辑
+      if (error instanceof AskUserError) {
+        // 确保 AskUserError 携带 agentSessionId（如果有的话）
+        const contextAgentSessionId = (context as any).agentSessionId;
+        if (contextAgentSessionId && !error.agentSessionId) {
+          // 创建一个新的 AskUserError 携带 agentSessionId
+          throw new AskUserError(
+            error.runId,
+            error.sessionId,
+            error.nodeId,
+            error.nodeType,
+            error.query,
+            contextAgentSessionId,
+            error.timestamp
+          );
+        }
+        throw error; // 重新抛出，让 Executor 处理
+      }
+
+      // 其他错误处理
+      const duration = Date.now() - startTime;
+      const errorMessage = error instanceof Error ? error.message : String(error);
+
+      return {
+        output: undefined,
+        error: errorMessage,
+        duration,
+      };
+    }
+  }
+  
+  /**
+   * 创建 agent sub-session
+   * 
+   * Sub-session 用于存储 agent 的对话历史，支持 human-in-loop resume
+   */
+  @TracedAs("agent.node.createAgentSubSession", { recordParams: true, recordResult: true, log: true })
+  private async createAgentSubSession(context: NodeExecutionContext): Promise<string> {
+    const sessionComponent = context.sessionComponent;
+    if (!sessionComponent) {
+      return '';
+    }
+    
+    const agentSessionId = `agent_${this.definition.id}_${Date.now()}`;
+    
+    // 1. 创建 agent sub-session
+    await sessionComponent.create({
+      id: agentSessionId,
+      title: `Agent: ${this.definition.id}`,
+      metadata: {
+        type: 'agent',
+        parentSessionId: context.sessionId,
+        nodeId: this.definition.id,
+        workflowName: context.workflowName,
+      },
+    });
+    
+    // 2. 更新 workflow session 的 metadata，添加 agentSessions 引用
+    const workflowSession = await sessionComponent.get(context.sessionId);
+    if (workflowSession) {
+      const metadata = workflowSession.metadata as any || {};
+      const agentSessions = metadata.agentSessions || [];
+      
+      // 检查是否已经存在
+      const existingIndex = agentSessions.findIndex(
+        (s: any) => s.nodeId === this.definition.id
+      );
+      
+      if (existingIndex >= 0) {
+        agentSessions[existingIndex] = {
+          nodeId: this.definition.id,
+          sessionId: agentSessionId,
+          status: 'active',
+          createdAt: Date.now(),
+        };
+      } else {
+        agentSessions.push({
+          nodeId: this.definition.id,
+          sessionId: agentSessionId,
+          status: 'active',
+          createdAt: Date.now(),
+        });
+      }
+      
+      await sessionComponent.update(context.sessionId, {
+        metadata: {
+          ...metadata,
+          agentSessions,
+        },
+      });
+    }
+    
+    return agentSessionId;
+  }
+
+  /**
+   * 解析模板字符串
+   * 
+   * 支持以下模板变量：
+   * - {{input.key}} - 从 context.input 获取值
+   * - {{nodes.nodeId}} - 从前置节点输出获取值
+   * - {{nodes.nodeId.output}} - 从前置节点输出获取值
+   * - {{nodes.nodeId.output.path}} - 从前置节点输出的嵌套路径获取值
+   * 
+   * @param template 模板字符串
+   * @param context 执行上下文
+   * @returns 解析后的字符串
+   */
+  private resolveTemplate(template: string, context: NodeExecutionContext): string {
+    if (!template) {
+      return '';
+    }
+
+    let resolved = template;
+
+    // 解析 input 变量: {{input.key}} 或 {{input.key.nested}}
+    resolved = resolved.replace(/\{\{input\.([^}]+)\}\}/g, (match, path) => {
+      const value = this.getNestedValue(context.input as any, path);
+      return this.stringifyValue(value, match);
+    });
+
+    // 解析 node 输出变量: {{nodes.nodeId}} 或 {{nodes.nodeId.output}} 或 {{nodes.nodeId.output.path}}
+    resolved = resolved.replace(/\{\{nodes\.([^}]+)\}\}/g, (match, path) => {
+      // 路径格式: nodeId 或 nodeId.output 或 nodeId.output.path
+      const segments = path.split('.');
+      const nodeId = segments[0];
+      
+      // 从 previousOutputs 获取原始输出（尝试规范化匹配）
+      let nodeOutput = context.previousOutputs.get(nodeId);
+      
+      if (nodeOutput === undefined) {
+        // 尝试规范化版本（hyphen <-> underscore）
+        const normalizedUnderscore = nodeId.replace(/-/g, '_');
+        const normalizedHyphen = nodeId.replace(/_/g, '-');
+        
+        if (normalizedUnderscore !== nodeId) {
+          nodeOutput = context.previousOutputs.get(normalizedUnderscore);
+        }
+        if (nodeOutput === undefined && normalizedHyphen !== nodeId) {
+          nodeOutput = context.previousOutputs.get(normalizedHyphen);
+        }
+      }
+      
+      if (nodeOutput === undefined) {
+        return match;
+      }
+      
+      // 首先从包装格式中提取实际值
+      // 处理 DecoratorNode 格式: { success, output, ... } 和 AgentNode 格式: { result, metadata }
+      nodeOutput = this.extractFromWrapper(nodeOutput);
+      
+      // 然后从提取后的值中获取嵌套路径
+      if (segments.length === 1) {
+        // 只有 nodeId，直接返回提取后的值
+        // 如果是对象，序列化为 JSON；如果是原始值，转为字符串
+        return this.stringifyValue(nodeOutput, match);
+      }
+      
+      // 从嵌套路径获取（从 segments[1] 开始）
+      // 如果 segments[1] 是包装属性（"output"、"result"、"metadata"），跳过它因为 extractFromWrapper 已经提取了
+      let value: any = nodeOutput;
+      let startIndex = 1;
+      if (segments.length > 1 && 
+          (segments[1] === 'output' || segments[1] === 'result' || segments[1] === 'metadata')) {
+        startIndex = 2;
+      }
+      for (let i = startIndex; i < segments.length; i++) {
+        if (value === null || value === undefined) {
+          return match;
+        }
+        value = value[segments[i]];
+      }
+      
+      return this.stringifyValue(value, match);
+    });
+
+    // 解析裸 node 输出变量: {{nodeId}} 或 {{nodeId.output}} (不带 nodes. 前缀)
+    // 这需要放在 {{input.}} 和 {{nodes.}} 之后，以避免与它们冲突
+    resolved = resolved.replace(/\{\{([^}]+)\}\}/g, (match, path) => {
+      // 跳过已经是 input 或 nodes 开头的（已由前面的规则处理）
+      if (path.startsWith('input.') || path.startsWith('nodes.')) {
+        return match;
+      }
+      
+      const segments = path.split('.');
+      const nodeId = segments[0];
+      
+      // 从 previousOutputs 获取原始输出（尝试规范化匹配）
+      let nodeOutput = context.previousOutputs.get(nodeId);
+      
+      if (nodeOutput === undefined) {
+        // 尝试规范化版本（hyphen <-> underscore）
+        const normalizedUnderscore = nodeId.replace(/-/g, '_');
+        const normalizedHyphen = nodeId.replace(/_/g, '-');
+        
+        if (normalizedUnderscore !== nodeId) {
+          nodeOutput = context.previousOutputs.get(normalizedUnderscore);
+        }
+        if (nodeOutput === undefined && normalizedHyphen !== nodeId) {
+          nodeOutput = context.previousOutputs.get(normalizedHyphen);
+        }
+      }
+      
+      if (nodeOutput === undefined) {
+        return match;
+      }
+      
+      // 首先从包装格式中提取实际值
+      nodeOutput = this.extractFromWrapper(nodeOutput);
+      
+      // 然后从提取后的值中获取嵌套路径
+      if (segments.length === 1) {
+        // 只有 nodeId，直接返回提取后的值
+        // 如果是对象，序列化为 JSON；如果是原始值，转为字符串
+        return this.stringifyValue(nodeOutput, match);
+      }
+      
+      // 从嵌套路径获取（从 segments[1] 开始）
+      // 如果 segments[1] 是包装属性（"output"、"result"、"metadata"），跳过它因为 extractFromWrapper 已经提取了
+      let value: any = nodeOutput;
+      let startIndex = 1;
+      if (segments.length > 1 && 
+          (segments[1] === 'output' || segments[1] === 'result' || segments[1] === 'metadata')) {
+        startIndex = 2;
+      }
+      for (let i = startIndex; i < segments.length; i++) {
+        if (value === null || value === undefined) {
+          return match;
+        }
+        value = value[segments[i]];
+      }
+      
+      return this.stringifyValue(value, match);
+    });
+
+    return resolved;
+  }
+
+  /**
+   * Convert a value to string for template replacement.
+   * - If value is undefined, return the original template
+   * - If value is a string, return it directly
+   * - If value is null, return 'null'
+   * - If value is an object or array, serialize to JSON
+   * 
+   * @param value - The value to stringify
+   * @param originalTemplate - The original template string (returned if value is undefined)
+   * @returns String representation of the value
+   */
+  private stringifyValue(value: unknown, originalTemplate: string): string {
+    if (value === undefined) {
+      return originalTemplate;
+    }
+    if (value === null) {
+      return 'null';
+    }
+    if (typeof value === 'string') {
+      return value;
+    }
+    // For objects and arrays, serialize to JSON
+    return JSON.stringify(value);
+  }
+
+  /**
+   * 从包装格式中提取实际输出值
+   * 
+   * 处理以下格式：
+   * - AgentNode: { result, metadata } -> 返回 result
+   * - DecoratorNode: { success, output, ... } -> 返回 output
+   * - 其他格式直接返回
+   * 
+   * @param value 原始值
+   * @returns 提取后的值
+   */
+  private extractFromWrapper(value: unknown): unknown {
+    if (value === null || value === undefined) {
+      return value;
+    }
+    
+    if (typeof value !== 'object') {
+      return value;
+    }
+    
+    // 检查 AgentNode 包装格式: { result, metadata }
+    // 这是 AgentNode 输出的特征签名
+    if ('result' in value && 'metadata' in value) {
+      return (value as { result: unknown }).result;
+    }
+    
+    // 检查 DecoratorNode 包装格式: { success, output, ... }
+    // 有 'output' 但没有 'result'（AgentNode 的特征）
+    if ('output' in value) {
+      return (value as { output: unknown }).output;
+    }
+    
+    return value;
+  }
+
+  /**
+   * 获取嵌套对象的值
+   * 
+   * @param obj 对象
+   * @param path 属性路径
+   * @returns 值或 undefined
+   */
+  private getNestedValue(obj: Record<string, unknown> | undefined, path: string): unknown {
+    if (!obj) {
+      return undefined;
+    }
+    
+    // Special case: If obj has an 'input' key, we might be accessing a key inside it
+    // This happens when createExecutionContext wraps globalInput as {input: globalInput}
+    if ('input' in obj && path in (obj['input'] as Record<string, unknown>)) {
+      // Path exists inside 'input', so look there
+      return (obj['input'] as Record<string, unknown>)[path];
+    }
+    
+    // Normal case: path.split('.').reduce(...) with obj as initial value
+    // This allows {{input.city}} to work when path = "city" and obj = {input: {city: "..."}}
+    return path.split('.').reduce((current: unknown, key: string) => {
+      if (current && typeof current === 'object') {
+        return (current as Record<string, unknown>)[key];
+      }
+      return undefined;
+    }, obj as unknown);
+  }
+}
+
+// ============================================================================
+// Exports
+// ============================================================================
+
+export { AgentNode as default };

package/src/env/workflow/nodes/ask-user-node.ts

@@ -0,0 +1,113 @@
+/**
+ * @fileoverview AskUserNode - Node for requesting user input
+ * 
+ * This node is used for simple pause/resume scenarios where a workflow
+ * needs user input without going through an Agent.
+ */
+
+import type { Node, NodeExecutionResult } from '../types';
+import type { NodeDefinition } from '../types';
+import { AskUserError, createNodeInterruptEvent } from '../types/workflow-hil';
+import type { NodeInterruptEvent } from '../types/workflow-hil';
+
+// ==================== Types ====================
+
+/**
+ * AskUserNode Configuration
+ */
+export interface AskUserNodeConfig {
+  /** Question to ask the user */
+  query?: string;
+  /** Optional choices for the user */
+  options?: string[];
+  /** If true, user must explicitly confirm */
+  required_confirm?: boolean;
+}
+
+// ==================== AskUserNode Class ====================
+
+/**
+ * AskUserNode - Standalone node for user input requests
+ * 
+ * This node pauses the workflow and waits for user response.
+ * Used for simple human-in-loop scenarios without an Agent.
+ * 
+ * @example
+ * ```yaml
+ * nodes:
+ *   - id: confirm_step
+ *     type: ask_user
+ *     config:
+ *       query: "Do you want to proceed?"
+ *       options:
+ *         - "Yes"
+ *         - "No"
+ *         - "Cancel"
+ * ```
+ */
+export class AskUserNode implements Node {
+  readonly type = 'ask_user';
+  readonly id: string;
+  
+  private config: AskUserNodeConfig;
+  
+  /**
+   * Create a new AskUserNode
+   */
+  constructor(definition: NodeDefinition) {
+    this.id = definition.id;
+    this.config = (definition.config as AskUserNodeConfig) || {};
+  }
+  
+  /**
+   * Execute the AskUserNode
+   * 
+   * Publishes a node.interrupt event and throws AskUserError to pause workflow.
+   * 
+   * @param context - Node execution context
+   * @throws AskUserError - Always throws to pause workflow
+   */
+  async execute(context: {
+    runId: string;
+    sessionId: string;
+    eventBus: {
+      publish(event: NodeInterruptEvent): Promise<void>;
+    };
+    nodeOutputs: Map<string, unknown>;
+  }): Promise<NodeExecutionResult> {
+    const query = this.config.query || '确认继续吗？';
+    const options = this.config.options;
+    
+    // Build query with options if provided
+    const fullQuery = options 
+      ? `${query} (选项: ${options.join(', ')})`
+      : query;
+    
+    // Publish node.interrupt event
+    await context.eventBus.publish(
+      createNodeInterruptEvent(
+        context.runId,
+        this.id,
+        this.type,
+        fullQuery
+      )
+    );
+    
+    // Throw AskUserError to pause workflow
+    throw new AskUserError(
+      context.runId,
+      context.sessionId,
+      this.id,
+      this.type,
+      query
+    );
+  }
+  
+  /**
+   * Validate node configuration
+   */
+  validateConfig(_config: Record<string, unknown>): boolean {
+    // query is optional, has default value
+    return true;
+  }
+}