@ai-setting/roy-agent-core 1.0.0

package/src/env/workflow/nodes/agent-component-adapter.ts

@@ -0,0 +1,448 @@
+/**
+ * @fileoverview AgentComponentAdapter - Bridge between Workflow AgentNode and AgentComponent
+ * 
+ * This adapter implements the AgentRunner interface required by AgentNode,
+ * delegating actual execution to the AgentComponent.
+ * 
+ * Usage:
+ * ```typescript
+ * const agentComponent = env.getComponent<AgentComponent>('agent');
+ * const adapter = new AgentComponentAdapter(agentComponent);
+ * 
+ * // Register agents that can be used in workflows
+ * adapter.registerAgent('researcher', {
+ *   systemPrompt: 'You are a research assistant...',
+ *   type: 'general',
+ *   model: 'gpt-4'
+ * });
+ * 
+ * // Now AgentNode can use 'researcher' agent type
+ * const workflow = {
+ *   nodes: [{
+ *     type: 'agent',
+ *     config: { agent_type: 'researcher', prompt: '...' }
+ *   }]
+ * };
+ * ```
+ */
+
+import type { AgentComponent } from '../../agent/agent-component';
+import type { AgentContext } from '../../agent/types';
+import type { AgentRunner, AgentConfig, AgentResult } from './agent-node';
+import type { SessionComponent } from '../../session/session-component';
+import { AskUserError } from '../types/workflow-hil';
+
+// ============================================================================
+// AgentComponentAdapter Class
+// ============================================================================
+
+/**
+ * Pending Agent Session - Stores info needed to resume an agent after user input
+ */
+export interface PendingAgentSession {
+  agentSessionId: string;
+  nodeId: string;
+  runId: string;
+  createdAt: number;
+}
+
+/**
+ * AgentComponentAdapter
+ * 
+ * Adapts AgentComponent to the AgentRunner interface expected by Workflow's AgentNode.
+ * Provides session isolation for agent execution within workflow context.
+ * 
+ * Features:
+ * - Creates dedicated agent sessions for each workflow agent node execution
+ * - Tracks pending sessions for resume after user input
+ * - Supports mapping agent sessions to workflow run session messages
+ */
+export class AgentComponentAdapter implements AgentRunner {
+  /** Session prefix for agent sessions */
+  private agentSessionPrefix = 'agent';
+  
+  /** Current agent session ID */
+  private _currentAgentSessionId?: string;
+  
+  /** Pending agent sessions (waiting for user input) */
+  private pendingSessions: Map<string, PendingAgentSession> = new Map();
+  
+  /** Map from workflow run session to agent sessions */
+  private runSessionToAgentSessions: Map<string, string[]> = new Map();
+
+  constructor(
+    private agentComponent: AgentComponent,
+    private options: AgentComponentAdapterOptions = {},
+    private _sessionComponent?: SessionComponent
+  ) {}
+
+  /**
+   * Set the SessionComponent for agent session management
+   */
+  setSessionComponent(sessionComponent: SessionComponent): void {
+    this._sessionComponent = sessionComponent;
+  }
+
+  /**
+   * Get the current agent session ID
+   */
+  getCurrentAgentSessionId(): string | undefined {
+    return this._currentAgentSessionId;
+  }
+
+  /**
+   * Register an agent that can be used in workflows
+   * 
+   * @param name - Agent name (used as agent_type in workflow definition)
+   * @param config - Agent configuration
+   */
+  registerAgent(
+    name: string,
+    config: AgentRegistrationConfig
+  ): void {
+    this.agentComponent.registerAgent(name, {
+      type: (config.type || 'general') as any,
+      model: config.model,
+      systemPrompt: config.systemPrompt,
+      maxIterations: config.maxIterations,
+      allowedTools: config.allowedTools,
+      deniedTools: config.deniedTools,
+      timeout: (config as any).timeout,
+      maxErrorRetries: config.maxErrorRetries,
+    } as any);
+    
+    // Store session prefix for this agent
+    if (config.sessionIdPrefix) {
+      this.agentSessionPrefixes.set(name, config.sessionIdPrefix);
+    }
+  }
+
+  /**
+   * Run an agent
+   * 
+   * Implements AgentRunner interface.
+   * Creates a dedicated agent session for each execution within workflow context.
+   * 
+   * @param config - Agent configuration
+   * @param resumeOptions - Optional options for resuming a paused agent
+   * @returns Agent execution result
+   */
+  async run(config: AgentConfig, resumeOptions?: { userResponse?: string; agentSessionId?: string }): Promise<AgentResult> {
+    const startTime = Date.now();
+    
+    // Extract context info from config (set by Executor)
+    const nodeId = (config as any).nodeId || 'unknown';
+    const runId = (config as any).runId || 'unknown';
+    const workflowSessionId = (config as any).workflowSessionId;
+    const existingAgentSessionId = (config as any).agentSessionId;
+    
+    // Also extract agentSessionId from resumeOptions if provided (set by engine.resumeNode)
+    const resumeAgentSessionId = resumeOptions?.agentSessionId;
+    
+    // Check if this is a resume (user response or existing session)
+    const isResume = !!resumeOptions?.userResponse || !!existingAgentSessionId || !!resumeAgentSessionId;
+    
+    // Determine agent session ID
+    let agentSessionId: string | undefined;
+    
+    if (isResume && (this._currentAgentSessionId || existingAgentSessionId || resumeAgentSessionId)) {
+      // Resume existing session - use agentSessionId from resumeOptions if available
+      agentSessionId = resumeAgentSessionId || existingAgentSessionId || this._currentAgentSessionId;
+      
+      // Add user response to session if provided
+      if (resumeOptions?.userResponse && this._sessionComponent && agentSessionId) {
+        try {
+          await this._sessionComponent.addMessage(agentSessionId, {
+            role: 'user',
+            content: resumeOptions.userResponse,
+            metadata: {
+              type: 'user_intent',
+              intent: 'workflow.resume',
+              workflowNodeId: nodeId,
+            },
+          });
+        } catch (error) {
+          console.warn(`Failed to add user response to agent session ${agentSessionId}:`, error);
+        }
+      }
+    } else {
+      // Create new agent session
+      if (this._sessionComponent) {
+        agentSessionId = `${this.agentSessionPrefix}_${runId}_${nodeId}_${Date.now()}`;
+        
+        try {
+          // Create agent session for workflow isolation
+          await this._sessionComponent.create({
+            title: `Agent Session: ${config.type} (${agentSessionId})`,
+            metadata: {
+              type: 'agent',
+              workflowRunId: runId,
+              workflowNodeId: nodeId,
+            },
+          });
+          
+          // Set as current session
+          this._currentAgentSessionId = agentSessionId;
+          
+          // Track mapping from workflow session to agent session
+          if (workflowSessionId) {
+            const mapping = this.runSessionToAgentSessions.get(workflowSessionId) || [];
+            mapping.push(agentSessionId);
+            this.runSessionToAgentSessions.set(workflowSessionId, mapping);
+          }
+          
+          // Store as pending session for resume
+          this.pendingSessions.set(agentSessionId, {
+            agentSessionId,
+            nodeId,
+            runId,
+            createdAt: Date.now(),
+          });
+        } catch (error) {
+          // Session might already exist, continue with fallback ID
+          console.warn(`Failed to create agent session ${agentSessionId}:`, error);
+        }
+      }
+    }
+    
+    try {
+      // Build context from options
+      const context: AgentContext = {};
+      
+      // Add timeout if specified
+      if (config.options?.timeout) {
+        // @ts-ignore - AbortController compatible with AbortSignal
+        context.abort = new AbortController();
+      }
+      
+      // Use the agent session ID for isolation
+      if (agentSessionId) {
+        context.sessionId = agentSessionId;
+      }
+      
+      // Pass allowedTools from options to context
+      // This is used by AgentComponent to filter available tools
+      // For workflow agents, this includes 'ask_user' tool
+      if (config.options?.allowedTools) {
+        context.allowedTools = config.options.allowedTools;
+      }
+      
+      // Pass deniedTools from options to context
+      if (config.options?.deniedTools) {
+        context.deniedTools = config.options.deniedTools;
+      }
+      
+      // Pass workflow history to agent context
+      if (config.workflowHistory) {
+        (context as any).workflowHistory = config.workflowHistory;
+      }
+      
+      // Execute agent
+      // Use config.type or fallback to 'general' agent type
+      const result = await this.agentComponent.run(
+        config.type || 'general',
+        config.prompt,
+        context
+      );
+
+      // Calculate duration
+      // Check if agent stopped due to ask_user (encoded in result.error)
+      if (result.error?.startsWith('__ASK_USER_ERROR__:')) {
+        // Parse the JSON-encoded AskUserError info
+        const jsonStr = result.error.substring('__ASK_USER_ERROR__:'.length);
+        const errorInfo = JSON.parse(jsonStr);
+        
+        // Reconstruct and throw AskUserError
+        throw new AskUserError(
+          runId,
+          errorInfo.sessionId,
+          errorInfo.nodeId,
+          errorInfo.nodeType || 'agent',
+          errorInfo.query
+        );
+      }
+      
+      const duration = Date.now() - startTime;
+      
+      // Clear pending session on success
+      if (agentSessionId) {
+        this.pendingSessions.delete(agentSessionId);
+      }
+
+      // Convert AgentRunResult to AgentResult
+      // Include messages in result for workflow history accumulation
+      const messages = (result as any)._messages || [];
+      
+      return {
+        output: result.finalText || (result as any).output,
+        metadata: {
+          duration,
+          iterations: result.iterations,
+          toolCalls: result.toolCalls?.length,
+          agentSessionId,
+        },
+        messages,
+      };
+    } catch (error) {
+      // Check if this is AskUserError - don't clear pending session
+      const isAskUserError = error instanceof Error && error.name === 'AskUserError';
+      
+      // Convert error to AgentResult format (unless AskUserError which should propagate)
+      if (isAskUserError) {
+        throw error; // Re-throw AskUserError to be handled by Executor
+      }
+      
+      const duration = Date.now() - startTime;
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      
+      // Clear pending session on other errors
+      if (agentSessionId) {
+        this.pendingSessions.delete(agentSessionId);
+      }
+
+      return {
+        output: undefined,
+        metadata: {
+          duration,
+          error: errorMessage,
+          agentSessionId,
+        },
+      };
+    } finally {
+      // Only clear current session if not pending
+      if (!isResume) {
+        this._currentAgentSessionId = undefined;
+      }
+    }
+  }
+  
+  /**
+   * Resume a paused agent with user response
+   * 
+   * This method is called when workflow resumes after user input.
+   * It retrieves the pending agent session and continues execution.
+   * 
+   * @param agentSessionId - The agent session ID to resume
+   * @param userResponse - User's response to the ask_user query
+   * @param config - Original agent config
+   * @returns Agent execution result
+   */
+  async resumeAgent(
+    agentSessionId: string,
+    userResponse: string,
+    config: AgentConfig
+  ): Promise<AgentResult> {
+    // Add user response to agent session
+    if (this._sessionComponent) {
+      try {
+        await this._sessionComponent.addMessage(agentSessionId, {
+          role: 'user',
+          content: userResponse,
+          metadata: {
+            type: 'user_intent',
+            intent: 'workflow.resume',
+          },
+        });
+        
+        // Remove from pending
+        this.pendingSessions.delete(agentSessionId);
+        
+        // Restore as current session
+        this._currentAgentSessionId = agentSessionId;
+      } catch (error) {
+        console.warn(`Failed to add user response to agent session ${agentSessionId}:`, error);
+      }
+    }
+    
+    // Set agentSessionId in config so AgentComponent knows which session to load
+    (config as any).agentSessionId = agentSessionId;
+    
+    // Resume agent execution
+    return this.run(config, { userResponse });
+  }
+  
+  /**
+   * Get pending agent session by agent session ID
+   */
+  getPendingSession(agentSessionId: string): PendingAgentSession | undefined {
+    return this.pendingSessions.get(agentSessionId);
+  }
+  
+  /**
+   * Get pending agent sessions for a workflow run
+   */
+  getPendingSessionsForRun(runId: string): PendingAgentSession[] {
+    return Array.from(this.pendingSessions.values()).filter(
+      session => session.runId === runId
+    );
+  }
+  
+  /**
+   * Get all agent session IDs associated with a workflow session
+   */
+  getAgentSessionsForWorkflowSession(workflowSessionId: string): string[] {
+    return this.runSessionToAgentSessions.get(workflowSessionId) || [];
+  }
+
+  /**
+   * Check if an agent is registered
+   */
+  hasAgent(name: string): boolean {
+    return this.agentComponent.getAgent(name) !== undefined;
+  }
+
+  /**
+   * List all registered agents
+   */
+  listAgents(): string[] {
+    return this.agentComponent.listAgents().map(a => a.name);
+  }
+
+  /**
+   * Get the underlying AgentComponent
+   */
+  getAgentComponent(): AgentComponent {
+    return this.agentComponent;
+  }
+
+  // Session prefix map for workflow isolation
+  private agentSessionPrefixes: Map<string, string> = new Map();
+}
+
+// ============================================================================
+// Type Definitions
+// ============================================================================
+
+/**
+ * Options for AgentComponentAdapter
+ */
+export interface AgentComponentAdapterOptions {
+  /** Default timeout for agent execution (ms) */
+  defaultTimeout?: number;
+  /** Default session ID prefix */
+  defaultSessionPrefix?: string;
+}
+
+/**
+ * Configuration for registering an agent
+ */
+export interface AgentRegistrationConfig {
+  /** Agent type */
+  type?: 'general' | 'research' | 'coder' | 'critic';
+  /** Model to use */
+  model?: string;
+  /** System prompt */
+  systemPrompt?: string;
+  /** Max iterations */
+  maxIterations?: number;
+  /** Allowed tools */
+  allowedTools?: string[];
+  /** Denied tools */
+  deniedTools?: string[];
+  /** Timeout (ms) */
+  timeout?: number;
+  /** Max error retries */
+  maxErrorRetries?: number;
+  /** Session ID prefix for workflow isolation */
+  sessionIdPrefix?: string;
+}