@ai-setting/roy-agent-core 1.0.0

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

@@ -0,0 +1,1422 @@
+/**
+ * @fileoverview WorkflowEngine - Session-based workflow execution engine
+ * 
+ * 基于 Session 实现 run/resume 机制：
+ * - Session 直接作为 workflow run 的实例
+ * - 使用 workflow.node.* 消息记录节点执行状态
+ * - resume 时从 Session 消息恢复状态
+ * 
+ * @version v2.0
+ */
+
+import { EventEmitter } from 'events';
+import type { 
+  WorkflowDefinition, 
+  Workflow,
+  RunOptions, 
+  RunResult,
+  RunStatus,
+  NodeExecutionContext,
+} from '../types/index';
+import { createWorkflowEvent, WorkflowEvent } from '../types/event';
+import { createNodeInterruptEvent, AskUserError } from '../types/workflow-hil';
+import { DAGManager } from './dag-manager';
+import { EventBus } from './event-bus';
+import { Scheduler } from './scheduler';
+import { Executor, ExecutorOptions } from './executor';
+import { NodeRegistry } from './node-registry';
+import type { SessionComponent } from '../../session/session-component';
+import type { WorkflowSessionMetadata, AgentSessionRef } from '../types/workflow-message';
+import type { Environment } from '../../interface';
+import { createLogger } from '../../log-trace/logger';
+import { TracedAs } from '../../log-trace/decorator';
+
+// Logger
+const logger = createLogger("workflow:engine");
+
+// ============================================================================
+// Type Definitions
+// ============================================================================
+
+/**
+ * Agent Session Recovery Info
+ */
+export interface AgentSessionRecoveryInfo {
+  nodeId: string;
+  agentSessionId: string;
+}
+
+/**
+ * Options for creating WorkflowEngine via static factory
+ */
+export interface WorkflowEngineCreateOptions {
+  env?: {
+    getComponent<T>(name: string): T | undefined;
+  };
+  toolRegistry?: any;
+  skillRegistry?: any;
+  workflowRunner?: any;
+  sessionComponent?: SessionComponent;
+  /** Repository for loading workflow definitions during resume */
+  workflowRepository?: WorkflowRepository;
+}
+
+/**
+ * Workflow Repository interface (abstraction)
+ */
+export interface WorkflowRepository {
+  getById(id: string): Workflow | null;
+  getByName(name: string): Workflow | null;
+}
+
+/**
+ * Active Session State
+ * 内存中追踪正在运行的 workflow session
+ */
+interface ActiveSessionState {
+  sessionId: string;
+  workflowId: string;
+  workflowName: string;
+  status: RunStatus;
+  startedAt: Date;
+  eventBus: EventBus;
+  dagManager: DAGManager;
+  scheduler: Scheduler;
+  executor: Executor;
+  nodeRegistry: NodeRegistry;
+  nodeOutputs: Map<string, any>;
+  config: WorkflowEngineConfig;
+  abortController: AbortController;
+  completedPromise: Promise<RunResult>;
+  resolveCompleted: (result: RunResult) => void;
+  rejectCompleted: (error: Error) => void;
+  // LLM history for agent nodes
+  workflowHistory: Array<{
+    role: 'user' | 'assistant' | 'tool';
+    content: string;
+    toolCallId?: string;
+    toolName?: string;
+    nodeId?: string;
+  }>;
+  // Agent sessions reference
+  agentSessions: Map<string, string>;  // nodeId -> agentSessionId
+}
+
+/**
+ * WorkflowEngine Configuration
+ */
+export interface WorkflowEngineConfig {
+  parallelLimit: number | null;
+  timeout: number | null;
+  debug: boolean;
+}
+
+/**
+ * Runtime State from Session Messages
+ * 从 Session 消息恢复的状态
+ */
+interface RuntimeState {
+  nodeOutputs: Map<string, unknown>;
+  pendingNodeId: string | null;
+  waitingForUser: boolean;
+  agentSessionId?: string;
+  lastInterruptMessage?: any;
+}
+
+// ============================================================================
+// WorkflowEngine Class
+// ============================================================================
+
+/**
+ * WorkflowEngine
+ * 
+ * Session-based workflow execution engine.
+ * Uses Session to manage workflow run state and node execution history.
+ */
+export class WorkflowEngine extends EventEmitter {
+  /** 活跃的 session 状态，key 为 sessionId */
+  private activeSessions: Map<string, ActiveSessionState> = new Map();
+
+  /** Session ID 计数器 */
+  private sessionIdCounter = 0;
+
+  /** Session component */
+  private sessionComponent?: SessionComponent;
+
+  /** Node registry */
+  private nodeRegistry: NodeRegistry;
+
+  /** Workflow repository for loading definitions during resume */
+  private workflowRepository?: WorkflowRepository;
+
+  /**
+   * Create a new WorkflowEngine
+   */
+  constructor(
+    nodeRegistry: NodeRegistry,
+    sessionComponent?: SessionComponent,
+    workflowRepository?: WorkflowRepository
+  ) {
+    super();
+    this.nodeRegistry = nodeRegistry;
+    this.sessionComponent = sessionComponent;
+    this.workflowRepository = workflowRepository;
+  }
+
+  /**
+   * Create a WorkflowEngine with automatic AgentComponent integration
+   */
+  static async create(options: WorkflowEngineCreateOptions): Promise<WorkflowEngine> {
+    const agentComponent = options.env?.getComponent<any>('agent');
+    const sessionComponent = options.sessionComponent;
+
+    const nodeRegistry = new NodeRegistry({
+      toolRegistry: options.toolRegistry,
+      skillRegistry: options.skillRegistry,
+      agentComponent,
+      workflowRunner: options.workflowRunner,
+      sessionComponent,
+    });
+
+    return new WorkflowEngine(nodeRegistry, sessionComponent, options.workflowRepository);
+  }
+
+  // =========================================================================
+  // Session ID Utilities
+  // =========================================================================
+
+  /**
+   * Generate a unique run ID
+   */
+  private generateRunId(): string {
+    const random = Math.random().toString(36).substring(2, 8);
+    return `run_${Date.now()}_${++this.sessionIdCounter}_${random}`;
+  }
+
+  /**
+   * Extract runId from sessionId
+   * sessionId format: workflow_{runId}
+   */
+  private getRunIdFromSessionId(sessionId: string): string {
+    return sessionId.replace(/^workflow_/, '');
+  }
+
+  /**
+   * Get session ID for a run
+   */
+  getSessionId(runId: string): string {
+    return `workflow_${runId}`;
+  }
+
+  // =========================================================================
+  // Public API: Session Management
+  // =========================================================================
+
+  /**
+   * Create a new workflow session
+   * 
+   * @param workflow - Workflow definition or entity
+   * @param options - Optional configuration
+   * @returns Promise resolving to sessionId (format: workflow_{runId})
+   */
+  @TracedAs("workflow.engine.createSession", { recordParams: true, recordResult: true, log: true })
+  async createSession(
+    workflow: Workflow | WorkflowDefinition,
+    options?: RunOptions
+  ): Promise<string> {
+    const definition = 'definition' in workflow 
+      ? workflow.definition 
+      : workflow;
+    
+    const workflowId = 'id' in workflow 
+      ? workflow.id 
+      : `inline_${definition.name}`;
+    
+    const workflowName = definition.name;
+
+    // Generate run ID and session ID
+    const runId = this.generateRunId();
+    const sessionId = this.getSessionId(runId);
+
+    // Create Session
+    const metadata: WorkflowSessionMetadata = {
+      type: 'workflow',
+      workflowId,
+      workflowName,
+      workflowVersion: definition.version,
+      status: 'running',
+      input: options?.input,
+      agentSessions: [],
+    };
+
+    if (this.sessionComponent) {
+      await this.sessionComponent.create({
+        id: sessionId,
+        title: `Workflow: ${workflowName} (${runId})`,
+        metadata,
+      });
+    }
+
+    logger.info(`[WorkflowEngine] Created session: ${sessionId}`);
+
+    return sessionId;
+  }
+
+  /**
+   * Run a workflow by sessionId (unified entry point)
+   * 
+   * This method supports both:
+   * 1. First run: session doesn't exist → create session, start from entry node
+   * 2. Resume: session exists with messages → infer next node from messages
+   * 
+   * @param sessionId - Session ID (format: workflow_{runId} or any string)
+   * @param options - Optional configuration
+   * @returns Promise resolving to RunResult
+   */
+  @TracedAs("workflow.engine.run", { recordParams: true, recordResult: true, log: true })
+  async run(
+    sessionId: string,
+    options?: RunOptions & { workflowId?: string }
+  ): Promise<RunResult> {
+    // 1. Try to get existing session
+    let session = this.sessionComponent 
+      ? await this.sessionComponent.get(sessionId) 
+      : null;
+    
+    let workflowDef: WorkflowDefinition | null = null;
+    let workflowId: string = '';
+    let workflowName: string = '';
+    
+    if (session) {
+      // Session exists - load workflow definition
+      const metadata = session.metadata as WorkflowSessionMetadata;
+      if (metadata.type === 'workflow' && metadata.workflowId) {
+        workflowDef = this.findDefinitionForWorkflow(metadata.workflowId);
+        workflowId = metadata.workflowId;
+        workflowName = metadata.workflowName;
+      }
+      if (!workflowDef && metadata.workflowName) {
+        workflowDef = this.findDefinitionForWorkflow(metadata.workflowName);
+        workflowId = metadata.workflowName;
+        workflowName = metadata.workflowName;
+      }
+    } else {
+      // No session - this is a new run
+      if (!options?.workflowId) {
+        throw new Error('workflowId required for new session');
+      }
+      
+      workflowDef = this.findDefinitionForWorkflow(options.workflowId);
+      if (!workflowDef) {
+        throw new Error(`Workflow not found: ${options.workflowId}`);
+      }
+      
+      workflowId = options.workflowId;
+      workflowName = workflowDef.name;
+      
+      // Create session
+      if (this.sessionComponent) {
+        const sessionMetadata: WorkflowSessionMetadata = {
+          type: 'workflow',
+          workflowId,
+          workflowName,
+          workflowVersion: workflowDef.version,
+          status: 'running',
+        };
+        
+        await this.sessionComponent.create({
+          id: sessionId,
+          title: `Workflow: ${workflowName}`,
+          metadata: sessionMetadata,
+        });
+        
+        session = await this.sessionComponent.get(sessionId);
+      }
+    }
+    
+    if (!session || !workflowDef) {
+      throw new Error(`Cannot start workflow: session or workflow not found`);
+    }
+    
+    // 2. Check session status
+    const metadata = session.metadata as WorkflowSessionMetadata;
+    if (metadata.status === 'completed') {
+      return { runId: this.getRunIdFromSessionId(sessionId), status: 'completed' };
+    }
+    if (metadata.status === 'failed') {
+      return { runId: this.getRunIdFromSessionId(sessionId), status: 'failed' };
+    }
+    
+    // 3. Load messages and infer next node
+    const messages = this.sessionComponent 
+      ? await this.sessionComponent.getMessages(sessionId) 
+      : [];
+    
+    // 4. Import and use session-recovery utilities
+    const { inferNextNode } = await import('../utils/session-recovery');
+    
+    // Get entry node from workflow definition
+    const entry = workflowDef.entry;
+    const entryNode = Array.isArray(entry) ? entry[0] : entry;
+    
+    const resumePoint = inferNextNode(messages, {
+      entryNode: entryNode !== '__default_entry__' ? entryNode : undefined,
+      edges: undefined, // edges not available in WorkflowDefinition, derived at runtime
+    });
+    
+    // 5. Initialize session state and execute
+    const sessionState = await this.initializeSessionState(
+      sessionId,
+      workflowDef,
+      workflowId,
+      workflowName,
+      options
+    );
+    
+    this.activeSessions.set(sessionId, sessionState);
+
+    // 6. Run with resume point
+    return this.runWithResume(sessionId, resumePoint, options);
+  }
+
+  /**
+   * Initialize session state
+   */
+  private async initializeSessionState(
+    sessionId: string,
+    definition: WorkflowDefinition,
+    workflowId: string,
+    workflowName: string,
+    options?: RunOptions
+  ): Promise<ActiveSessionState> {
+    // Create DAG manager
+    const dagManager = new DAGManager(definition);
+
+    // Validate DAG
+    const validation = dagManager.validate();
+    if (!validation.valid) {
+      throw new Error(`Invalid workflow: ${validation.errors.join(', ')}`);
+    }
+
+    // Get parallel limit
+    const parallelLimit = options?.parallelLimit 
+      ?? definition.config?.parallel_limit 
+      ?? null;
+
+    // Create scheduler
+    const scheduler = new Scheduler(dagManager, { parallelLimit });
+
+    // Create event bus
+    const eventBus = new EventBus();
+
+    // Create executor
+    const executorOptions: ExecutorOptions = {
+      globalTimeout: options?.timeout ?? definition.config?.timeout ?? null,
+      globalRetry: definition.config?.retry ?? null,
+      debug: options?.debug ?? definition.config?.debug ?? false,
+    };
+    const executor = new Executor(this.nodeRegistry, eventBus, executorOptions, this.sessionComponent);
+
+    // Create engine config
+    const config: WorkflowEngineConfig = {
+      parallelLimit,
+      timeout: options?.timeout ?? definition.config?.timeout ?? null,
+      debug: options?.debug ?? definition.config?.debug ?? false,
+    };
+
+    // Create abort controller
+    const abortController = new AbortController();
+
+    // Create completion promise
+    let resolveCompleted!: (result: RunResult) => void;
+    let rejectCompleted!: (error: Error) => void;
+    const completedPromise = new Promise<RunResult>((resolve, reject) => {
+      resolveCompleted = resolve;
+      rejectCompleted = reject;
+    });
+
+    // Create session state
+    const sessionState: ActiveSessionState = {
+      sessionId,
+      workflowId,
+      workflowName,
+      status: 'running',
+      startedAt: new Date(),
+      eventBus,
+      dagManager,
+      scheduler,
+      executor,
+      nodeRegistry: this.nodeRegistry,
+      nodeOutputs: new Map(),
+      config,
+      abortController,
+      completedPromise,
+      resolveCompleted,
+      rejectCompleted,
+      workflowHistory: [],
+      agentSessions: new Map(),
+    };
+
+    // Setup event handlers
+    this.setupEventHandlers(sessionState);
+
+    return sessionState;
+  }
+
+  /**
+   * Run with resume point
+   */
+  private async runWithResume(
+    sessionId: string,
+    resumePoint: { type: string; nodeId?: string; nodeIds?: string[]; agentSessionId?: string },
+    options?: RunOptions & { input?: unknown }
+  ): Promise<RunResult> {
+    const sessionState = this.activeSessions.get(sessionId);
+    if (!sessionState) {
+      throw new Error(`Session not found: ${sessionId}`);
+    }
+
+    const runId = this.getRunIdFromSessionId(sessionId);
+
+    // Publish workflow started event
+    await sessionState.eventBus.publish(
+      createWorkflowEvent('workflow.started', runId, {
+        workflow_name: sessionState.workflowName,
+        input: options?.input,
+      })
+    );
+
+    // Determine what to execute based on resume point
+    let pendingNodeId: string | undefined;
+    let agentSessionId: string | undefined;
+    
+    switch (resumePoint.type) {
+      case 'entry_node':
+      case 'next_nodes':
+        // Normal execution - scheduler will handle it
+        pendingNodeId = undefined;
+        break;
+      case 'resume_node':
+      case 'ask_user':
+        // Resume specific node
+        pendingNodeId = resumePoint.nodeId;
+        agentSessionId = resumePoint.agentSessionId;
+        break;
+    }
+
+    // Start scheduling
+    // Note: userResponse is extracted from input if it's a string (for resume)
+    const userResponse = typeof options?.input === 'string' ? options.input as string : undefined;
+    this.scheduleAndExecute(sessionState, { 
+      input: options?.input as Record<string, any>,
+      pendingNodeId,
+      agentSessionId,
+      userResponse,
+    }).catch((error) => {
+      logger.error(`Workflow ${sessionId} scheduling error:`, error);
+      this.failWorkflow(sessionState, error);
+    });
+
+    // If sync mode, wait for completion
+    if (options?.sync !== false) {
+      return this.waitForCompletion(sessionId, options?.timeout);
+    }
+
+    return { runId, status: 'running' };
+  }
+
+  /**
+   * Convenience method to run a workflow directly
+   */
+  @TracedAs("workflow.engine.runWorkflow", { recordParams: true, recordResult: true, log: true })
+  async runWorkflow(
+    workflow: Workflow | WorkflowDefinition,
+    options?: RunOptions
+  ): Promise<RunResult> {
+    const definition = 'definition' in workflow 
+      ? workflow.definition 
+      : workflow;
+    
+    const workflowId = 'id' in workflow 
+      ? workflow.id 
+      : `inline_${definition.name}`;
+    
+    const workflowName = definition.name;
+
+    // Create session
+    const sessionId = await this.createSession(workflow, options);
+    
+    // Initialize session state
+    const sessionState = await this.initializeSessionState(
+      sessionId,
+      definition,
+      workflowId,
+      workflowName,
+      options
+    );
+    
+    this.activeSessions.set(sessionId, sessionState);
+
+    // Run with default entry node
+    return this.runWithResume(sessionId, { type: 'entry_node' }, options);
+  }
+
+  /**
+   * Pause a running workflow
+   */
+  @TracedAs("workflow.engine.pause", { recordParams: true, recordResult: true, log: true })
+  async pause(sessionId: string): Promise<void> {
+    const sessionState = this.activeSessions.get(sessionId);
+    
+    if (!sessionState) {
+      throw new Error(`Session not found: ${sessionId}`);
+    }
+
+    if (sessionState.status !== 'running') {
+      throw new Error(`Session ${sessionId} is not running (current: ${sessionState.status})`);
+    }
+
+    sessionState.status = 'paused';
+    sessionState.abortController.abort();
+    sessionState.executor.cancelAll();
+
+    // Update session metadata
+    if (this.sessionComponent) {
+      const metadata = await this.getSessionMetadata(sessionId);
+      await this.sessionComponent.update(sessionId, {
+        metadata: { ...metadata, status: 'paused' },
+      });
+    }
+
+    // Publish pause event
+    await sessionState.eventBus.publish(
+      createWorkflowEvent('workflow.paused', this.getRunIdFromSessionId(sessionId), {})
+    );
+
+    logger.info(`[WorkflowEngine] Workflow paused: ${sessionId}`);
+  }
+
+  /**
+   * Resume a paused workflow
+   */
+  @TracedAs("workflow.engine.resume", { recordParams: true, recordResult: true, log: true })
+  async resume(
+    sessionId: string,
+    options?: { response?: string }
+  ): Promise<RunResult> {
+    const sessionState = this.activeSessions.get(sessionId);
+    
+    if (!sessionState) {
+      // Session not in memory, try to restore from database
+      logger.info(`[WorkflowEngine] Session not in memory, attempting to restore from DB: ${sessionId}`);
+      return this.resumeFromDatabase(sessionId, options);
+    }
+
+    // Write resume message
+    if (options?.response) {
+      await this.writeNodeResume(sessionId, options.response);
+    }
+
+    if (sessionState.status === 'running') {
+      // Already running
+      return { runId: this.getRunIdFromSessionId(sessionId), status: 'running' };
+    }
+    
+    if (sessionState.status !== 'paused') {
+      throw new Error(`Session ${sessionId} is not paused (current: ${sessionState.status})`);
+    }
+
+    // Resume state
+    sessionState.status = 'running';
+    sessionState.abortController = new AbortController();
+
+    // Update session metadata
+    if (this.sessionComponent) {
+      const metadata = await this.getSessionMetadata(sessionId);
+      await this.sessionComponent.update(sessionId, {
+        metadata: { ...metadata, status: 'running' },
+      });
+    }
+
+    // Publish resume event
+    await sessionState.eventBus.publish(
+      createWorkflowEvent('workflow.resumed', this.getRunIdFromSessionId(sessionId), {
+        userResponse: options?.response,
+      })
+    );
+
+    // Restore runtime state from messages and continue execution
+    const runtimeState = await this.restoreRuntimeState(sessionId);
+    
+    this.scheduleAndExecute(sessionState, {
+      pendingNodeId: runtimeState.pendingNodeId || undefined,
+      agentSessionId: runtimeState.agentSessionId,
+      userResponse: options?.response,
+      restoredOutputs: runtimeState.nodeOutputs,
+    });
+
+    return {
+      runId: this.getRunIdFromSessionId(sessionId),
+      status: 'running',
+    };
+  }
+
+  /**
+   * Resume from database when CLI restarts
+   */
+  @TracedAs("workflow.engine.resumeFromDatabase", { recordParams: true, recordResult: true, log: true })
+  private async resumeFromDatabase(
+    sessionId: string,
+    options?: { response?: string }
+  ): Promise<RunResult> {
+    // Get session
+    const session = await this.sessionComponent?.get(sessionId);
+    if (!session) {
+      throw new Error(`Session not found: ${sessionId}`);
+    }
+
+    const metadata = session.metadata as WorkflowSessionMetadata;
+    if (metadata.type !== 'workflow') {
+      throw new Error(`Session is not a workflow session: ${sessionId}`);
+    }
+
+    if (metadata.status !== 'paused') {
+      throw new Error(`Workflow is not paused: ${sessionId}, status: ${metadata.status}`);
+    }
+
+    // Restore runtime state from messages
+    const runtimeState = await this.restoreRuntimeState(sessionId);
+    
+    if (!runtimeState.pendingNodeId) {
+      throw new Error(`No pending node found in session: ${sessionId}`);
+    }
+
+    // Write resume message
+    if (options?.response) {
+      await this.writeNodeResume(sessionId, options.response);
+    }
+
+    // Update session metadata to running
+    if (this.sessionComponent) {
+      await this.sessionComponent.update(sessionId, {
+        metadata: { ...metadata, status: 'running' },
+      });
+    }
+
+    logger.info(`[WorkflowEngine] Resumed from database: ${sessionId}, pendingNode: ${runtimeState.pendingNodeId}`);
+
+    // Note: Cannot fully restore without workflow definition
+    // This is a current design limitation
+    throw new Error(
+      `Cannot resume from database without workflow definition. ` +
+      `Session ${sessionId} is paused at node "${runtimeState.pendingNodeId}". ` +
+      `Please ensure the workflow is registered before resuming.`
+    );
+  }
+
+  /**
+   * Restore runtime state from Session messages
+   */
+  @TracedAs("workflow.engine.restoreRuntimeState", { recordParams: true, recordResult: true, log: true })
+  private async restoreRuntimeState(sessionId: string): Promise<RuntimeState> {
+    const messages = this.sessionComponent 
+      ? await this.sessionComponent.getMessages(sessionId) 
+      : [];
+    
+    const nodeOutputs = new Map<string, unknown>();
+    let lastCallNodeId: string | null = null;
+    let lastInterruptMessage: any = null;
+    let agentSessionId: string | undefined;
+
+    for (const msg of messages) {
+      const msgMetadata = msg.metadata as any;
+      
+      if (msgMetadata?.type === 'workflow.node.call') {
+        lastCallNodeId = msgMetadata.workflowNodeId;
+      } else if (msgMetadata?.type === 'workflow.node.result') {
+        if (lastCallNodeId) {
+          try {
+            nodeOutputs.set(lastCallNodeId, JSON.parse(msg.content));
+          } catch {
+            nodeOutputs.set(lastCallNodeId, msg.content);
+          }
+        }
+        lastCallNodeId = null;
+      } else if (msgMetadata?.type === 'workflow.node.interrupt') {
+        lastInterruptMessage = msg;
+        lastCallNodeId = msgMetadata.workflowNodeId;
+        agentSessionId = msgMetadata.agentSessionId;
+      }
+    }
+
+    return {
+      nodeOutputs,
+      pendingNodeId: lastCallNodeId,
+      waitingForUser: !!lastInterruptMessage,
+      agentSessionId,
+      lastInterruptMessage,
+    };
+  }
+
+  /**
+   * Write node resume message
+   */
+  @TracedAs("workflow.engine.writeNodeResume", { recordParams: true, recordResult: true, log: true })
+  private async writeNodeResume(sessionId: string, response: string): Promise<void> {
+    if (this.sessionComponent) {
+      await this.sessionComponent.addMessage(sessionId, {
+        role: 'workflow.node.resume',
+        content: response,
+        metadata: {
+          type: 'workflow.node.resume',
+          response,
+          timestamp: Date.now(),
+        },
+      });
+    }
+  }
+
+  /**
+   * Stop a running or paused workflow
+   */
+  @TracedAs("workflow.engine.stop", { recordParams: true, recordResult: true, log: true })
+  async stop(sessionId: string, reason?: string): Promise<void> {
+    const sessionState = this.activeSessions.get(sessionId);
+    
+    if (!sessionState) {
+      // Not in memory, try to update database
+      if (this.sessionComponent) {
+        await this.sessionComponent.update(sessionId, {
+          metadata: { status: 'stopped' } as any,
+        });
+      }
+      return;
+    }
+
+    sessionState.status = 'stopped';
+    sessionState.abortController.abort();
+    sessionState.executor.cancelAll();
+
+    // Update session metadata
+    if (this.sessionComponent) {
+      const metadata = await this.getSessionMetadata(sessionId);
+      await this.sessionComponent.update(sessionId, {
+        metadata: { ...metadata, status: 'stopped' },
+      });
+    }
+
+    // Publish stop event
+    await sessionState.eventBus.publish(
+      createWorkflowEvent('workflow.stopped', this.getRunIdFromSessionId(sessionId), {
+        reason: reason ?? 'User requested stop',
+      })
+    );
+
+    // Cleanup
+    this.cleanupSession(sessionState);
+  }
+
+  /**
+   * Get session status
+   */
+  getSessionStatus(sessionId: string): RunStatus | null {
+    const sessionState = this.activeSessions.get(sessionId);
+    return sessionState?.status ?? null;
+  }
+
+  /**
+   * Check if session is active
+   */
+  isSessionActive(sessionId: string): boolean {
+    return this.activeSessions.has(sessionId);
+  }
+
+  // =========================================================================
+  // Private Methods
+  // =========================================================================
+
+  /**
+   * Setup event handlers for a run
+   */
+  private setupEventHandlers(sessionState: ActiveSessionState): void {
+    const { sessionId, eventBus, scheduler } = sessionState;
+    const runId = this.getRunIdFromSessionId(sessionId);
+
+    // Handle node completed
+    eventBus.on('node.completed', async (event: WorkflowEvent) => {
+      if (event.type !== 'node.completed') return;
+      
+      sessionState.nodeOutputs.set(event.node_id, event.output);
+      scheduler.markCompleted(event.node_id);
+
+      // Accumulate workflow history
+      if (event.output && typeof event.output === 'object' && 'workflowHistory' in event.output) {
+        const messages = (event.output as any).workflowHistory;
+        if (Array.isArray(messages)) {
+          sessionState.workflowHistory.push(...messages);
+        }
+      }
+
+      // Check if workflow is complete
+      this.checkAndFinalize(sessionState);
+    });
+
+    // Handle node failed
+    eventBus.on('node.failed', async (event: WorkflowEvent) => {
+      if (event.type !== 'node.failed') return;
+
+      scheduler.markFailed(event.node_id);
+      await this.failWorkflow(sessionState, new Error(event.error.message));
+    });
+
+    // Handle node interrupt (ask_user pause)
+    eventBus.on('node.interrupt', async (event: WorkflowEvent) => {
+      if (event.type !== 'node.interrupt') return;
+
+      logger.info(`Workflow paused at node "${event.node_id}" - ask_user pending`);
+
+      sessionState.status = 'paused';
+      sessionState.abortController.abort();
+
+      // Update session metadata
+      if (this.sessionComponent) {
+        const metadata = await this.getSessionMetadata(sessionId);
+        await this.sessionComponent.update(sessionId, {
+          metadata: { ...metadata, status: 'paused' },
+        });
+      }
+
+      // Publish workflow.paused event
+      await eventBus.publish(
+        createWorkflowEvent('workflow.paused', runId, {
+          pendingNodeId: event.node_id,
+          query: (event as any).query,
+        })
+      );
+
+      // Write interrupt message to session
+      await this.writeNodeInterrupt(sessionId, event.node_id, event.node_type, (event as any).query, (event as any).agent_session_id);
+
+      // Resolve with paused status
+      sessionState.resolveCompleted({
+        runId,
+        status: 'paused',
+        pendingNodeId: event.node_id,
+        query: (event as any).query,
+        agentSessionId: (event as any).agent_session_id,
+      });
+    });
+  }
+
+  /**
+   * Write node interrupt message
+   */
+  @TracedAs("workflow.engine.writeNodeInterrupt", { recordParams: true, recordResult: true, log: true })
+  @TracedAs("workflow.engine.writeNodeInterrupt", { recordParams: true, recordResult: true, log: true })
+  private async writeNodeInterrupt(
+    sessionId: string,
+    nodeId: string,
+    nodeType: string,
+    query: string,
+    agentSessionId?: string
+  ): Promise<void> {
+    if (this.sessionComponent) {
+      await this.sessionComponent.addMessage(sessionId, {
+        role: 'workflow.node.interrupt',
+        content: query,
+        metadata: {
+          type: 'workflow.node.interrupt',
+          workflowNodeId: nodeId,
+          workflowNodeType: nodeType,
+          query,
+          agentSessionId,
+          timestamp: Date.now(),
+        },
+      });
+    }
+  }
+
+  /**
+   * Main scheduling loop
+   */
+  @TracedAs("workflow.engine.scheduleAndExecute", { recordParams: true, recordResult: true, log: true })
+  @TracedAs("workflow.engine.scheduleAndExecute", { recordParams: true, recordResult: true, log: true })
+  private async scheduleAndExecute(
+    sessionState: ActiveSessionState,
+    options?: {
+      input?: Record<string, any>;
+      pendingNodeId?: string;
+      agentSessionId?: string;
+      userResponse?: string;
+      restoredOutputs?: Map<string, unknown>;
+    }
+  ): Promise<void> {
+    const { scheduler, executor, eventBus, abortController, nodeOutputs } = sessionState;
+    const { input: globalInput, pendingNodeId, agentSessionId, userResponse, restoredOutputs } = options || {};
+
+    // Merge restored outputs if any
+    if (restoredOutputs) {
+      for (const [nodeId, output] of restoredOutputs) {
+        nodeOutputs.set(nodeId, output);
+      }
+    }
+
+    // Helper to schedule available nodes
+    const scheduleAvailableNodes = async (): Promise<boolean> => {
+      const state = scheduler.getState();
+      const completedNodes = new Set(state.completed);
+      
+      const readyNodes = scheduler.getReadyNodes(completedNodes);
+      const canStart = scheduler.canStartMore();
+      
+      if (readyNodes.length === 0 || !canStart) {
+        return false;
+      }
+
+      let scheduled = 0;
+      for (const nodeId of readyNodes) {
+        if (!scheduler.canStartMore()) break;
+        if (scheduled >= (sessionState.config.parallelLimit ?? Infinity)) break;
+        
+        await this.startNode(sessionState, nodeId, globalInput);
+        scheduled++;
+      }
+      
+      return true;
+    };
+
+    // Initial scheduling
+    if (pendingNodeId) {
+      // Resume mode: only schedule the pending node
+      await this.resumeNode(sessionState, pendingNodeId, {
+        agentSessionId,
+        userResponse,
+      });
+    } else {
+      await scheduleAvailableNodes();
+    }
+
+    // Event-driven loop
+    while (sessionState.status === 'running' && !abortController.signal.aborted) {
+      const state = scheduler.getState();
+      if (state.pending.length === 0 && state.running.length === 0) {
+        break;
+      }
+
+      try {
+        await this.waitForNextNodeEvent(sessionState, abortController.signal);
+      } catch {
+        break;
+      }
+
+      await scheduleAvailableNodes();
+    }
+  }
+
+  /**
+   * Wait for next node event
+   */
+  @TracedAs("workflow.engine.waitForNextNodeEvent", { recordParams: true, recordResult: true, log: true })
+  private waitForNextNodeEvent(
+    sessionState: ActiveSessionState,
+    signal: AbortSignal
+  ): Promise<void> {
+    return new Promise((resolve) => {
+      const timeoutId = setTimeout(() => {
+        cleanup();
+        resolve();
+      }, 100);
+      
+      const cleanup = () => {
+        clearTimeout(timeoutId);
+        sessionState.eventBus.off('node.completed', onCompleted);
+        sessionState.eventBus.off('node.failed', onFailed);
+      };
+      
+      const onCompleted = (event: WorkflowEvent) => {
+        if (event.type === 'node.completed') {
+          cleanup();
+          resolve();
+        }
+      };
+      
+      const onFailed = (event: WorkflowEvent) => {
+        if (event.type === 'node.failed') {
+          cleanup();
+          resolve();
+        }
+      };
+      
+      sessionState.eventBus.on('node.completed', onCompleted);
+      sessionState.eventBus.on('node.failed', onFailed);
+      
+      if (signal.aborted) {
+        cleanup();
+        resolve();
+      }
+    });
+  }
+
+  /**
+   * Start execution of a single node
+   */
+  @TracedAs("workflow.engine.startNode", { recordParams: true, recordResult: true, log: true })
+  @TracedAs("workflow.engine.startNode", { recordParams: true, recordResult: true, log: true })
+  private async startNode(
+    sessionState: ActiveSessionState,
+    nodeId: string,
+    input?: Record<string, any>
+  ): Promise<void> {
+    const { scheduler, executor, eventBus, dagManager } = sessionState;
+    const sessionId = sessionState.sessionId;
+    const runId = this.getRunIdFromSessionId(sessionId);
+    
+    scheduler.markStarted(nodeId);
+
+    // Publish scheduled event
+    await eventBus.publish(
+      createWorkflowEvent('node.scheduled', runId, {
+        node_id: nodeId,
+      })
+    );
+
+    // Get node definition
+    const nodeDef = dagManager.getNode(nodeId);
+    if (!nodeDef) {
+      scheduler.markFailed(nodeId);
+      return;
+    }
+
+    // Write workflow.node.call message
+    await this.writeNodeCall(sessionId, nodeId, nodeDef.type, input);
+
+    // Create execution context
+    const context = this.createExecutionContext(sessionState, nodeId, input);
+
+    // Execute node
+    executor.executeNode(nodeDef, context).catch(async (error) => {
+      if (error instanceof AskUserError) {
+        await eventBus.publish(createNodeInterruptEvent(
+          runId,
+          nodeId,
+          nodeDef.type,
+          error.query,
+          error.agentSessionId
+        ));
+        return;
+      }
+      
+      scheduler.markFailed(nodeId);
+    });
+  }
+
+  /**
+   * Write node call message
+   */
+  @TracedAs("workflow.engine.writeNodeCall", { recordParams: true, recordResult: true, log: true })
+  @TracedAs("workflow.engine.writeNodeCall", { recordParams: true, recordResult: true, log: true })
+  private async writeNodeCall(
+    sessionId: string,
+    nodeId: string,
+    nodeType: string,
+    input?: any
+  ): Promise<void> {
+    if (this.sessionComponent) {
+      await this.sessionComponent.addMessage(sessionId, {
+        role: 'workflow.node.call',
+        content: JSON.stringify({ input }),
+        metadata: {
+          type: 'workflow.node.call',
+          workflowNodeId: nodeId,
+          workflowNodeType: nodeType,
+          timestamp: Date.now(),
+        },
+      });
+    }
+  }
+
+  /**
+   * Resume execution of a paused node
+   */
+  @TracedAs("workflow.engine.resumeNode", { recordParams: true, recordResult: true, log: true })
+  @TracedAs("workflow.engine.resumeNode", { recordParams: true, recordResult: true, log: true })
+  private async resumeNode(
+    sessionState: ActiveSessionState,
+    nodeId: string,
+    options?: {
+      agentSessionId?: string;
+      userResponse?: string;
+    }
+  ): Promise<void> {
+    const { scheduler, executor, eventBus, dagManager } = sessionState;
+    const sessionId = sessionState.sessionId;
+    const runId = this.getRunIdFromSessionId(sessionId);
+    
+    scheduler.markStarted(nodeId);
+
+    // Publish resume event
+    await eventBus.publish(
+      createWorkflowEvent('node.started', runId, {
+        node_id: nodeId,
+        agentSessionId: options?.agentSessionId,
+        userResponse: options?.userResponse,
+      })
+    );
+
+    // Get node definition
+    const nodeDef = dagManager.getNode(nodeId);
+    if (!nodeDef) {
+      scheduler.markFailed(nodeId);
+      return;
+    }
+
+    // Create execution context
+    const context = this.createExecutionContext(sessionState, nodeId, undefined);
+    
+    // Add resume options to context
+    if (options?.agentSessionId || options?.userResponse) {
+      (context as any).agentSessionId = options.agentSessionId;
+      (context as any).userResponse = options.userResponse;
+    }
+
+    // Execute node
+    executor.executeNode(nodeDef, context).catch((error) => {
+      if (error instanceof AskUserError) {
+        const event = createNodeInterruptEvent(
+          runId,
+          nodeId,
+          nodeDef.type,
+          error.query,
+          error.agentSessionId
+        );
+        eventBus.publish(event);
+        return;
+      }
+      scheduler.markFailed(nodeId);
+    });
+  }
+
+  /**
+   * Create execution context for a node
+   */
+  private createExecutionContext(
+    sessionState: ActiveSessionState,
+    nodeId: string,
+    globalInput?: Record<string, any>
+  ): NodeExecutionContext {
+    const nodeDef = sessionState.dagManager.getNode(nodeId)!;
+    const runId = this.getRunIdFromSessionId(sessionState.sessionId);
+    
+    // Collect inputs from dependencies
+    const deps = nodeDef.depends_on || [];
+    const input: Record<string, any> = {};
+    
+    for (const depId of deps) {
+      const depOutput = sessionState.nodeOutputs.get(depId);
+      if (depOutput !== undefined) {
+        input[depId] = depOutput;
+      }
+    }
+
+    // Merge global input if this is an entry node
+    const analysis = sessionState.dagManager.analyze();
+    if (analysis.entryNodes.includes(nodeId) && globalInput) {
+      Object.assign(input, globalInput);
+    }
+
+    // Ask user function
+    const askUser = (query: string): never => {
+      throw new AskUserError(
+        runId,
+        sessionState.sessionId,
+        nodeId,
+        nodeDef.type,
+        query
+      );
+    };
+
+    return {
+      runId,
+      sessionId: sessionState.sessionId,
+      workflowName: sessionState.workflowName,
+      nodeId,
+      input,
+      previousOutputs: sessionState.nodeOutputs,
+      config: nodeDef.config ?? {},
+      debug: sessionState.config.debug,
+      eventBus: sessionState.eventBus,
+      nodeOutputs: sessionState.nodeOutputs,
+      workflowHistory: sessionState.workflowHistory,
+      sessionComponent: this.sessionComponent,
+      askUser,
+    };
+  }
+
+  /**
+   * Check if workflow is complete and finalize
+   */
+  @TracedAs("workflow.engine.checkAndFinalize", { recordParams: true, recordResult: true, log: true })
+  private checkAndFinalize(sessionState: ActiveSessionState): void {
+    const state = sessionState.scheduler.getState();
+
+    if (state.pending.length === 0 && 
+        state.running.length === 0 && 
+        state.ready.length === 0) {
+      
+      if (state.failed.length > 0) {
+        this.failWorkflow(sessionState, new Error(`Nodes failed: ${state.failed.join(', ')}`));
+      } else {
+        this.completeWorkflow(sessionState);
+      }
+    }
+  }
+
+  /**
+   * Complete a workflow successfully
+   */
+  @TracedAs("workflow.engine.completeWorkflow", { recordParams: true, recordResult: true, log: true })
+  private async completeWorkflow(sessionState: ActiveSessionState): Promise<void> {
+    const durationMs = Date.now() - sessionState.startedAt.getTime();
+    const sessionId = sessionState.sessionId;
+    const runId = this.getRunIdFromSessionId(sessionId);
+
+    // Collect output
+    const output: Record<string, any> = {};
+    for (const [nodeId, nodeOutput] of sessionState.nodeOutputs) {
+      output[nodeId] = nodeOutput;
+    }
+
+    // Update session metadata
+    if (this.sessionComponent) {
+      const metadata = await this.getSessionMetadata(sessionId);
+      await this.sessionComponent.update(sessionId, {
+        metadata: { ...metadata, status: 'completed' },
+      });
+    }
+
+    // Publish completed event
+    await sessionState.eventBus.publish(
+      createWorkflowEvent('workflow.completed', runId, {
+        result: output,
+        duration_ms: durationMs,
+      }),
+      true
+    );
+
+    // Resolve completion
+    sessionState.resolveCompleted({
+      runId,
+      status: 'completed',
+      output,
+      durationMs,
+    });
+
+    // Cleanup
+    this.cleanupSession(sessionState);
+  }
+
+  /**
+   * Fail a workflow
+   */
+  @TracedAs("workflow.engine.failWorkflow", { recordParams: true, recordResult: true, log: true })
+  private async failWorkflow(sessionState: ActiveSessionState, error: Error): Promise<void> {
+    const durationMs = Date.now() - sessionState.startedAt.getTime();
+    const sessionId = sessionState.sessionId;
+    const runId = this.getRunIdFromSessionId(sessionId);
+
+    sessionState.executor.cancelAll();
+
+    // Update session metadata
+    if (this.sessionComponent) {
+      const metadata = await this.getSessionMetadata(sessionId);
+      await this.sessionComponent.update(sessionId, {
+        metadata: { ...metadata, status: 'failed' },
+      });
+    }
+
+    // Publish failed event
+    await sessionState.eventBus.publish(
+      createWorkflowEvent('workflow.failed', runId, {
+        error: { message: error.message, stack: error.stack },
+        failed_at: new Date().toISOString(),
+      }),
+      true
+    );
+
+    // Resolve with error
+    sessionState.resolveCompleted({
+      runId,
+      status: 'failed',
+      error: error.message,
+      durationMs,
+    });
+
+    // Cleanup
+    this.cleanupSession(sessionState);
+  }
+
+  /**
+   * Cleanup session resources
+   */
+  private cleanupSession(sessionState: ActiveSessionState): void {
+    sessionState.eventBus.clear();
+    this.activeSessions.delete(sessionState.sessionId);
+  }
+
+  /**
+   * Wait for a run to complete
+   */
+  private async waitForCompletion(
+    sessionId: string,
+    timeout?: number | null
+  ): Promise<RunResult> {
+    const sessionState = this.activeSessions.get(sessionId);
+    
+    if (!sessionState) {
+      throw new Error(`Session not found: ${sessionId}`);
+    }
+
+    const timeoutMs = timeout ?? 300000;
+
+    const timeoutPromise = new Promise<RunResult>((_, reject) => {
+      setTimeout(() => {
+        reject(new Error(`Workflow execution timeout: ${timeoutMs}ms`));
+      }, timeoutMs);
+    });
+
+    return Promise.race([
+      sessionState.completedPromise,
+      timeoutPromise,
+    ]);
+  }
+
+  /**
+   * Get session metadata
+   */
+  private async getSessionMetadata(sessionId: string): Promise<WorkflowSessionMetadata> {
+    if (!this.sessionComponent) {
+      return { type: 'workflow', workflowId: '', workflowName: '', status: 'running' };
+    }
+    const session = await this.sessionComponent.get(sessionId);
+    return (session?.metadata as WorkflowSessionMetadata) || { type: 'workflow', workflowId: '', workflowName: '', status: 'running' };
+  }
+
+  /**
+   * Find workflow definition from repository
+   */
+  private findDefinitionForWorkflow(workflowIdOrName: string): WorkflowDefinition | null {
+    if (!this.workflowRepository) {
+      return null;
+    }
+    
+    // Try by ID first
+    let workflow = this.workflowRepository.getById(workflowIdOrName);
+    if (workflow) return workflow.definition;
+    
+    // Try by name
+    workflow = this.workflowRepository.getByName(workflowIdOrName);
+    if (workflow) return workflow.definition;
+    
+    return null;
+  }
+}