@ai-setting/roy-agent-core 1.3.9 → 1.3.11

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

@@ -1,598 +0,0 @@
-/**
- * @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

@@ -1,113 +0,0 @@
-/**
- * @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;
-  }
-}