@ai-setting/roy-agent-core 1.0.0

package/src/env/workflow/engine/executor.ts

@@ -0,0 +1,593 @@
+/**
+ * @fileoverview Executor - Executes nodes in a workflow
+ * 
+ * The Executor is responsible for:
+ * - Executing individual nodes
+ * - Handling retries
+ * - Managing timeouts
+ * - Tracking execution state
+ */
+
+import type { 
+  NodeDefinition, 
+  RetryConfig,
+  NodeExecutionContext,
+  NodeExecutionResult,
+} from '../types/index';
+import { createWorkflowEvent } from '../types/event';
+import { EventBus } from './event-bus';
+import { NodeRegistry, NodeContext } from './node-registry';
+import type { SessionComponent } from '../../session/session-component';
+import { 
+  AskUserError,
+  createNodeInterruptEvent,
+  type WorkflowMessagePart,
+  type WorkflowNodeCallPart,
+  type WorkflowNodeInterruptPart,
+} from '../types/index';
+import { TracedAs } from '../../log-trace/decorator';
+
+// ============================================================================
+// Type Definitions
+// ============================================================================
+
+/**
+ * Executor Options
+ */
+export interface ExecutorOptions {
+  /** Global timeout for node execution (ms). null = no timeout */
+  globalTimeout: number | null;
+  /** Global retry configuration */
+  globalRetry: RetryConfig | null;
+  /** Debug mode */
+  debug: boolean;
+}
+
+// ============================================================================
+// Executor Class
+// ============================================================================
+
+/**
+ * Executor
+ * 
+ * Executes nodes in a workflow with support for:
+ * - Timeout handling
+ * - Retry with configurable backoff
+ * - Error propagation
+ * - Session message writing
+ * - AskUserError handling
+ * 
+ * @example
+ * ```typescript
+ * const executor = new Executor(nodeRegistry, eventBus, {
+ *   globalTimeout: 60000,
+ *   globalRetry: { max_attempts: 3, backoff: 'exponential', initial_delay: 1000 },
+ *   debug: false
+ * });
+ * 
+ * const result = await executor.executeNode(nodeDefinition, context);
+ * ```
+ */
+export class Executor {
+  private abortControllers: Map<string, AbortController> = new Map();
+
+  constructor(
+    private nodeRegistry: NodeRegistry,
+    private eventBus: EventBus,
+    private options: ExecutorOptions,
+    private sessionComponent?: SessionComponent
+  ) {}
+
+  /**
+   * Execute a node with timeout and retry handling
+   */
+  @TracedAs("workflow.executor.executeNode", { recordParams: true, recordResult: true, log: true })
+  async executeNode(
+    definition: NodeDefinition,
+    context: NodeExecutionContext
+  ): Promise<NodeExecutionResult> {
+    const nodeId = definition.id;
+    const nodeType = definition.type;
+
+    // Get agent session ID if this is an agent node
+    const agentSessionId = (context as any).agentSessionId;
+
+    // Publish node started event
+    await this.eventBus.publish(
+      createWorkflowEvent('node.started', context.runId, {
+        node_id: nodeId,
+        input: context.input,
+      })
+    );
+
+    // Write workflow.node.call message with agent session ID
+    await this.writeNodeCall(
+      context.sessionId,
+      nodeId,
+      nodeType,
+      context.input,
+      agentSessionId
+    );
+
+    // Create abort controller for this execution
+    const abortController = new AbortController();
+    this.abortControllers.set(nodeId, abortController);
+
+    // Determine timeout (node config overrides global)
+    const timeout = definition.timeout ?? this.options.globalTimeout ?? undefined;
+
+    // Determine retry config (node config overrides global)
+    const retryConfig = definition.retry ?? this.options.globalRetry;
+
+    try {
+      let result: NodeExecutionResult;
+
+      if (retryConfig && retryConfig.max_attempts > 1) {
+        // Execute with retry
+        result = await this.executeWithRetry(
+          definition,
+          context,
+          abortController.signal,
+          timeout
+        );
+      } else {
+        // Execute without retry
+        result = await this.executeWithTimeout(
+          definition,
+          context,
+          abortController.signal,
+          timeout
+        );
+      }
+
+      // Handle AskUserError specially
+      if (result.error instanceof AskUserError) {
+        // Publish node.interrupt event with agentSessionId
+        const interruptEvent = createNodeInterruptEvent(
+          context.runId,
+          nodeId,
+          nodeType,
+          result.error.query,
+          result.error.agentSessionId || agentSessionId
+        );
+        await this.eventBus.publish(interruptEvent);
+        
+        // Write workflow.node.interrupt message with agentSessionId
+        await this.writeNodeInterrupt(
+          context.sessionId,
+          nodeId,
+          nodeType,
+          result.error.query,
+          result.error.agentSessionId || agentSessionId
+        );
+        
+        // Re-throw AskUserError
+        throw result.error;
+      }
+
+      // Publish completion or failure event
+      if (result.error) {
+        const errorMessage = result.error instanceof Error ? result.error.message : String(result.error);
+        const errorStack = result.error instanceof Error ? result.error.stack : undefined;
+        await this.eventBus.publish(
+          createWorkflowEvent('node.failed', context.runId, {
+            node_id: nodeId,
+            error: {
+              message: errorMessage,
+              stack: errorStack,
+            },
+          })
+        );
+        
+        // Write workflow.node.result message (error case)
+        await this.writeNodeResult(
+          context.sessionId,
+          nodeId,
+          nodeType,
+          result.output,
+          errorMessage,
+          result.durationMs ?? 0
+        );
+      } else {
+        await this.eventBus.publish(
+          createWorkflowEvent('node.completed', context.runId, {
+            node_id: nodeId,
+            output: result.output,
+            duration_ms: result.durationMs ?? 0,
+          })
+        );
+        
+        // Write workflow.node.result message (success case)
+        await this.writeNodeResult(
+          context.sessionId,
+          nodeId,
+          nodeType,
+          result.output,
+          undefined,
+          result.durationMs ?? 0
+        );
+      }
+
+      return result;
+    } finally {
+      // Clean up abort controller
+      this.abortControllers.delete(nodeId);
+    }
+  }
+
+  /**
+   * Execute node with timeout handling
+   */
+  private async executeWithTimeout(
+    definition: NodeDefinition,
+    context: NodeExecutionContext,
+    signal: AbortSignal,
+    timeout: number | undefined
+  ): Promise<NodeExecutionResult> {
+    const startTime = Date.now();
+
+    // Create the node instance
+    const nodeContext: NodeContext = {
+      runId: context.runId,
+      workflowName: context.workflowName,
+      eventBus: this.eventBus,
+      debug: context.debug,
+    };
+
+    const node = this.nodeRegistry.createNode(definition, nodeContext);
+
+    if (timeout) {
+      // Execute with timeout
+      const timeoutPromise = new Promise<never>((_, reject) => {
+        const handle = setTimeout(() => {
+          reject(new Error(`Node execution timeout: ${timeout}ms`));
+        }, timeout);
+        signal.addEventListener('abort', () => clearTimeout(handle));
+      });
+
+      try {
+        const result = await Promise.race([
+          node.execute(context),
+          timeoutPromise,
+        ]);
+        return {
+          output: result.output,
+          error: result.error ?? undefined,
+          durationMs: Date.now() - startTime,
+        };
+      } catch (error) {
+        // AskUserError 需要特殊处理，向上传播而不是包装为错误
+        if (error instanceof AskUserError) {
+          throw error;
+        }
+        return {
+          output: undefined,
+          error: error instanceof Error ? error : new Error(String(error)),
+          durationMs: Date.now() - startTime,
+        };
+      }
+    } else {
+      // Execute without timeout
+      try {
+        const result = await node.execute(context);
+        return {
+          output: result.output,
+          durationMs: Date.now() - startTime,
+        };
+      } catch (error) {
+        // AskUserError 需要特殊处理，向上传播而不是包装为错误
+        if (error instanceof AskUserError) {
+          throw error;
+        }
+        return {
+          output: undefined,
+          error: error instanceof Error ? error : new Error(String(error)),
+          durationMs: Date.now() - startTime,
+        };
+      }
+    }
+  }
+
+  /**
+   * Execute node with retry handling
+   */
+  private async executeWithRetry(
+    definition: NodeDefinition,
+    context: NodeExecutionContext,
+    signal: AbortSignal,
+    timeout: number | undefined
+  ): Promise<NodeExecutionResult> {
+    const retryConfig = definition.retry!;
+    let lastError: Error | undefined;
+    let delay = retryConfig.initial_delay;
+
+    for (let attempt = 1; attempt <= retryConfig.max_attempts; attempt++) {
+      // Check if aborted before attempt
+      if (signal.aborted) {
+        return {
+          output: undefined,
+          error: new Error('Execution aborted'),
+          durationMs: 0,
+        };
+      }
+
+      // Create new abort controller for this attempt
+      const attemptAbort = new AbortController();
+      const combinedSignal = this.combineAbortSignals(signal, attemptAbort.signal);
+
+      try {
+        const result = await this.executeWithTimeout(
+          definition,
+          context,
+          combinedSignal,
+          timeout
+        );
+
+        if (!result.error) {
+          return result;
+        }
+
+        // Convert string error to Error instance if needed
+        lastError = result.error instanceof Error ? result.error : new Error(String(result.error));
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error));
+      }
+
+      // If not last attempt, wait before retry
+      if (attempt < retryConfig.max_attempts) {
+        // Wait with delay
+        await this.sleep(delay);
+        
+        // Increase delay for exponential backoff
+        if (retryConfig.backoff === 'exponential') {
+          delay *= 2;
+        }
+      }
+    }
+
+    return {
+      output: undefined,
+      error: lastError ?? new Error('Unknown error after retries'),
+      durationMs: 0,
+    };
+  }
+
+  /**
+   * Cancel execution of a specific node
+   */
+  cancelNode(nodeId: string): void {
+    const controller = this.abortControllers.get(nodeId);
+    if (controller) {
+      controller.abort();
+      this.abortControllers.delete(nodeId);
+    }
+  }
+
+  /**
+   * Cancel all running nodes
+   */
+  cancelAll(): void {
+    for (const controller of this.abortControllers.values()) {
+      controller.abort();
+    }
+    this.abortControllers.clear();
+  }
+
+  /**
+   * Combine two abort signals
+   */
+  private combineAbortSignals(signal1: AbortSignal, signal2: AbortSignal): AbortSignal {
+    const controller = new AbortController();
+
+    signal1.addEventListener('abort', () => controller.abort());
+    signal2.addEventListener('abort', () => controller.abort());
+
+    return controller.signal;
+  }
+
+  /**
+   * Sleep for specified milliseconds
+   */
+  private sleep(ms: number): Promise<void> {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+
+  /**
+   * Write workflow.node.call message
+   */
+  @TracedAs("workflow.executor.writeNodeCall", { recordParams: true, recordResult: true, log: true })
+  async writeNodeCall(
+    sessionId: string,
+    nodeId: string,
+    nodeType: string,
+    input: unknown,
+    agentSessionId?: string
+  ): Promise<void> {
+    if (!this.sessionComponent) return;
+    
+    const startTime = Date.now();
+    const part: WorkflowNodeCallPart = {
+      type: 'workflow-node-call',
+      nodeId,
+      nodeType,
+      input,
+      startTime,
+      ...(agentSessionId ? { agentSessionId } : {}),
+    };
+    
+    // Create meaningful content summary for display
+    const contentSummary = this.summarizeCall(nodeType, nodeId, input);
+    
+    await this.sessionComponent.addMessage(sessionId, {
+      role: 'workflow.node.call' as any,
+      content: contentSummary,
+      parts: [part] as any,
+      metadata: {
+        _workflowNodeMetadata: true,
+        type: 'workflow.node.call',  // Required for parseNodeOutputs
+        workflowNodeId: nodeId,
+        workflowNodeType: nodeType,
+        ...(agentSessionId ? { agentSessionId } : {}),  // For agent sub-session recovery
+      } as any,
+    });
+  }
+  
+  /**
+   * Create a meaningful content summary for call message
+   */
+  private summarizeCall(nodeType: string, nodeId: string, input: unknown): string {
+    if (input === undefined || input === null) {
+      return `[${nodeType}] ${nodeId} started`;
+    }
+    
+    if (typeof input === 'object') {
+      const keys = Object.keys(input);
+      if (keys.length === 0) {
+        return `[${nodeType}] ${nodeId} started`;
+      }
+      // Show first few keys as summary
+      const summary = keys.slice(0, 3).map(k => `${k}: ${JSON.stringify(input[k])}`).join(', ');
+      return `[${nodeType}] ${nodeId}: ${summary}`;
+    }
+    
+    return `[${nodeType}] ${nodeId}: ${String(input)}`;
+  }
+
+  /**
+   * Write workflow.node.interrupt message
+   */
+  @TracedAs("workflow.executor.writeNodeInterrupt", { recordParams: true, recordResult: true, log: true })
+  async writeNodeInterrupt(
+    sessionId: string,
+    nodeId: string,
+    nodeType: string,
+    query: string,
+    agentSessionId?: string
+  ): Promise<void> {
+    if (!this.sessionComponent) return;
+    
+    const timestamp = Date.now();
+    const part: WorkflowNodeInterruptPart = {
+      type: 'workflow-node-interrupt',
+      nodeId,
+      nodeType,
+      query,
+      timestamp,
+      ...(agentSessionId ? { agentSessionId } : {}),
+    };
+    
+    await this.sessionComponent.addMessage(sessionId, {
+      role: 'workflow.node.interrupt' as any,
+      content: query,
+      parts: [part] as any,
+      metadata: {
+        _workflowNodeMetadata: true,
+        type: 'workflow.node.interrupt',  // Required for findLastInterruptMessage
+        workflowNodeId: nodeId,
+        workflowNodeType: nodeType,
+        query,
+        agentSessionId,
+      } as any,
+    });
+  }
+
+  /**
+   * Write workflow.node.result message
+   */
+  @TracedAs("workflow.executor.writeNodeResult", { recordParams: true, recordResult: true, log: true })
+  async writeNodeResult(
+    sessionId: string,
+    nodeId: string,
+    nodeType: string,
+    output: unknown,
+    error: string | undefined,
+    durationMs: number
+  ): Promise<void> {
+    if (!this.sessionComponent) return;
+    
+    const part: WorkflowMessagePart = {
+      type: 'workflow-node-result',
+      nodeId,
+      nodeType,
+      output,
+      error,
+      durationMs,
+    };
+    
+    // Create meaningful content summary for display
+    const contentSummary = this.summarizeResult(nodeId, output, error, durationMs);
+    
+    await this.sessionComponent.addMessage(sessionId, {
+      role: 'workflow.node.result' as any,
+      content: contentSummary,
+      parts: [part] as any,
+      metadata: {
+        _workflowNodeMetadata: true,
+        type: 'workflow.node.result',  // Required for parseNodeOutputs
+        workflowNodeId: nodeId,
+        workflowNodeType: nodeType,
+        success: !error,
+      } as any,
+    });
+  }
+  
+  /**
+   * Create a meaningful content summary for result display
+   */
+  private summarizeResult(
+    nodeId: string,
+    output: unknown,
+    error: string | undefined,
+    durationMs: number
+  ): string {
+    if (error) {
+      return `❌ ${nodeId} failed: ${error}`;
+    }
+    
+    if (output === undefined || output === null) {
+      return `✅ ${nodeId} completed (${durationMs}ms)`;
+    }
+    
+    if (typeof output === 'object') {
+      const keys = Object.keys(output);
+      if (keys.length === 0) {
+        return `✅ ${nodeId} completed (${durationMs}ms)`;
+      }
+      // Show first few keys as summary
+      const summary = keys.slice(0, 3).join(', ');
+      return `✅ ${nodeId}: ${summary} (${durationMs}ms)`;
+    }
+    
+    // Truncate long strings
+    const strOutput = String(output);
+    const truncated = strOutput.length > 100 ? strOutput.substring(0, 100) + '...' : strOutput;
+    return `✅ ${nodeId}: ${truncated} (${durationMs}ms)`;
+  }
+
+  /**
+   * Write workflow.node.resume message
+   */
+  @TracedAs("workflow.executor.writeNodeResume", { recordParams: true, recordResult: true, log: true })
+  async writeNodeResume(
+    sessionId: string,
+    response: string
+  ): Promise<void> {
+    if (!this.sessionComponent) return;
+    
+    const timestamp = Date.now();
+    const part: WorkflowMessagePart = {
+      type: 'workflow-node-resume',
+      response,
+      timestamp,
+    };
+    
+    await this.sessionComponent.addMessage(sessionId, {
+      role: 'workflow.node.resume' as any,
+      content: response,
+      parts: [part] as any,
+      metadata: {
+        _workflowNodeMetadata: true,
+      } as any,
+    });
+  }
+}

package/src/env/workflow/engine/index.ts

@@ -0,0 +1,24 @@
+/**
+ * @fileoverview Engine exports
+ */
+
+// Re-export types from types module for convenience
+export type {
+  NodeExecutionContext,
+  RunOptions,
+  RunResult,
+  RunStatus,
+  NodeStatus,
+} from '../types/index';
+
+export { EventBus } from './event-bus';
+export { DAGManager } from './dag-manager';
+export type { DAGAnalysis } from './dag-manager';
+export { Scheduler } from './scheduler';
+export type { SchedulerOptions, SchedulerState } from './scheduler';
+export { Executor } from './executor';
+export type { ExecutorOptions } from './executor';
+export { WorkflowEngine } from './engine';
+export type { WorkflowEngineConfig, WorkflowEngineCreateOptions, WorkflowRepository } from './engine';
+export { NodeRegistry } from './node-registry';
+export type { NodeContext, NodeFactory } from './node-registry';