onbuzz 3.3.0

package/src/core/flowExecutor.js

@@ -0,0 +1,928 @@
+/**
+ * FlowExecutor - Executes visual flow pipelines
+ *
+ * Purpose:
+ * - Execute flow nodes in topologically sorted order
+ * - Queue messages to agents via MessageProcessor
+ * - Detect completion via jobdone tool results
+ * - Track node states and outputs
+ * - Broadcast execution progress via WebSocket
+ */
+
+import { AGENT_MODES } from '../utilities/constants.js';
+
+class FlowExecutor {
+  constructor(config, logger, stateManager, agentPool, messageProcessor) {
+    this.config = config;
+    this.logger = logger;
+    this.stateManager = stateManager;
+    this.agentPool = agentPool;
+    this.messageProcessor = messageProcessor;
+
+    // WebSocket manager for broadcasting progress
+    this.webSocketManager = null;
+
+    // Active flow executions
+    this.activeExecutions = new Map();
+
+    // Completion listeners per run
+    this.completionListeners = new Map();
+  }
+
+  /**
+   * Set WebSocket manager for real-time updates
+   * @param {Object} webSocketManager - WebSocket manager instance
+   */
+  setWebSocketManager(webSocketManager) {
+    this.webSocketManager = webSocketManager;
+  }
+
+  /**
+   * Execute a flow
+   * @param {string} flowId - Flow identifier
+   * @param {Object} initialInput - Initial input data
+   * @param {string} sessionId - WebSocket session ID for broadcasts
+   * @returns {Promise<Object>} Flow run result
+   */
+  async executeFlow(flowId, initialInput = {}, sessionId = null) {
+    // Load flow definition
+    const flow = await this.stateManager.getFlow(flowId);
+    if (!flow) {
+      throw new Error(`Flow not found: ${flowId}`);
+    }
+
+    // Create flow run record
+    const run = await this.stateManager.createFlowRun(flowId, initialInput);
+    const runId = run.id;
+
+    this.logger.info(`Starting flow execution: ${flowId}`, {
+      runId,
+      nodeCount: flow.nodes?.length || 0,
+      edgeCount: flow.edges?.length || 0
+    });
+
+    // Track this execution
+    this.activeExecutions.set(runId, {
+      flowId,
+      flow,
+      runId,
+      sessionId,
+      status: 'running',
+      startedAt: new Date()
+    });
+
+    // Update run status to running
+    await this.stateManager.updateFlowRun(runId, { status: 'running' });
+    const startedAt = new Date().toISOString();
+    this.broadcastFlowUpdate(sessionId, {
+      type: 'flow_run_started',
+      runId,
+      flowId,
+      status: 'running',
+      startedAt
+    });
+
+    try {
+      // Ensure all referenced agents are loaded before execution
+      await this.ensureAgentsLoaded(flow.nodes);
+
+      // Topologically sort nodes
+      const sortedNodes = this.topologicalSort(flow.nodes, flow.edges);
+
+      if (sortedNodes.length === 0) {
+        throw new Error('Flow has no executable nodes');
+      }
+
+      // Initialize execution context
+      const context = {
+        input: initialInput.userInput || initialInput.input || '',
+        nodeOutputs: {},
+        variables: { ...flow.variables },
+        sortedNodes, // Store for position tracking
+        flow // Store flow reference
+      };
+
+      // Execute nodes in order
+      for (const node of sortedNodes) {
+        // Check if execution was stopped
+        const execution = this.activeExecutions.get(runId);
+        if (!execution || execution.status === 'stopped') {
+          this.logger.info(`Flow execution stopped: ${runId}`);
+          await this.stateManager.updateFlowRun(runId, {
+            status: 'stopped',
+            completedAt: new Date().toISOString()
+          });
+          this.broadcastFlowUpdate(sessionId, {
+            type: 'flow_run_stopped',
+            runId,
+            flowId
+          });
+          return { runId, status: 'stopped' };
+        }
+
+        // Execute node
+        const nodeResult = await this.executeNode(node, context, runId, sessionId, flow);
+
+        // Store node output by node ID
+        context.nodeOutputs[node.id] = nodeResult;
+
+        // Also store by outputKey if specified (for named references like {{result}})
+        if (node.data?.outputKey) {
+          context.nodeOutputs[node.data.outputKey] = nodeResult;
+        }
+
+        // Update node state in run
+        await this.updateNodeState(runId, node.id, 'completed', nodeResult);
+      }
+
+      // Flow completed successfully
+      const finalOutput = this.collectFinalOutput(sortedNodes, context);
+
+      await this.stateManager.updateFlowRun(runId, {
+        status: 'completed',
+        output: finalOutput,
+        completedAt: new Date().toISOString()
+      });
+
+      this.broadcastFlowUpdate(sessionId, {
+        type: 'flow_run_completed',
+        runId,
+        flowId,
+        output: finalOutput
+      });
+
+      this.activeExecutions.delete(runId);
+
+      this.logger.info(`Flow execution completed: ${flowId}`, { runId });
+
+      return { runId, status: 'completed', output: finalOutput };
+
+    } catch (error) {
+      this.logger.error(`Flow execution failed: ${flowId}`, {
+        runId,
+        error: error.message
+      });
+
+      await this.stateManager.updateFlowRun(runId, {
+        status: 'failed',
+        error: error.message,
+        completedAt: new Date().toISOString()
+      });
+
+      this.broadcastFlowUpdate(sessionId, {
+        type: 'flow_run_failed',
+        runId,
+        flowId,
+        error: error.message
+      });
+
+      this.activeExecutions.delete(runId);
+
+      return { runId, status: 'failed', error: error.message };
+    }
+  }
+
+  /**
+   * Stop a flow execution
+   * @param {string} runId - Run identifier
+   * @returns {Promise<boolean>} True if stopped
+   */
+  async stopExecution(runId) {
+    const execution = this.activeExecutions.get(runId);
+    if (!execution) {
+      return false;
+    }
+
+    execution.status = 'stopped';
+
+    // Clean up any completion listeners
+    this.completionListeners.delete(runId);
+
+    return true;
+  }
+
+  /**
+   * Ensure all agents referenced in the flow are loaded
+   * Automatically loads unloaded agents from disk
+   * @param {Array} nodes - Flow nodes
+   * @returns {Promise<void>}
+   */
+  async ensureAgentsLoaded(nodes) {
+    if (!nodes || nodes.length === 0) return;
+
+    // Extract agent IDs from agent nodes
+    const agentNodes = nodes.filter(n => n.type === 'agent' && n.data?.agentId);
+    const agentIds = [...new Set(agentNodes.map(n => n.data.agentId))];
+
+    if (agentIds.length === 0) return;
+
+    this.logger.info(`Checking ${agentIds.length} agent(s) for flow execution`);
+
+    // Get project directory from config
+    const projectDir = this.config.projectDir || process.cwd();
+
+    for (const agentId of agentIds) {
+      // Check if already loaded
+      const existingAgent = await this.agentPool.getAgent(agentId);
+      if (existingAgent) {
+        this.logger.debug(`Agent ${agentId} already loaded`);
+        continue;
+      }
+
+      // Agent not loaded - try to load from disk
+      this.logger.info(`Loading agent from disk: ${agentId}`);
+      try {
+        const agent = await this.stateManager.importArchivedAgent(agentId, projectDir, this.agentPool);
+        this.logger.info(`Successfully loaded agent: ${agentId}`);
+
+        // Broadcast agent-loaded event so UI sidebar updates
+        if (this.webSocketManager && agent) {
+          this.webSocketManager.broadcast({
+            type: 'agent-loaded',
+            agent: {
+              id: agent.id,
+              name: agent.name,
+              status: agent.status,
+              model: agent.currentModel || agent.preferredModel,
+              capabilities: agent.capabilities
+            }
+          });
+        }
+      } catch (error) {
+        throw new Error(`Failed to load agent ${agentId}: ${error.message}. Make sure the agent exists.`);
+      }
+    }
+  }
+
+  /**
+   * Get list of unloaded agents referenced in a flow
+   * Useful for UI to show which agents need to be loaded
+   * @param {Object} flow - Flow definition
+   * @returns {Promise<Array>} Array of { agentId, isLoaded, agentInfo }
+   */
+  async getFlowAgentStatus(flow) {
+    if (!flow?.nodes) return [];
+
+    const agentNodes = flow.nodes.filter(n => n.type === 'agent' && n.data?.agentId);
+    const agentIds = [...new Set(agentNodes.map(n => n.data.agentId))];
+    const projectDir = this.config.projectDir || process.cwd();
+
+    const results = [];
+    for (const agentId of agentIds) {
+      const existingAgent = await this.agentPool.getAgent(agentId);
+      if (existingAgent) {
+        results.push({
+          agentId,
+          isLoaded: true,
+          name: existingAgent.name,
+          model: existingAgent.currentModel
+        });
+      } else {
+        // Try to get info from disk
+        try {
+          const metadata = await this.stateManager.getAgentMetadata(agentId, projectDir);
+          results.push({
+            agentId,
+            isLoaded: false,
+            name: metadata?.name || agentId,
+            model: metadata?.model
+          });
+        } catch {
+          results.push({
+            agentId,
+            isLoaded: false,
+            name: agentId,
+            notFound: true
+          });
+        }
+      }
+    }
+
+    return results;
+  }
+
+  /**
+   * Topologically sort nodes based on edges
+   * @param {Array} nodes - Array of nodes
+   * @param {Array} edges - Array of edges
+   * @returns {Array} Sorted nodes array
+   */
+  topologicalSort(nodes, edges) {
+    if (!nodes || nodes.length === 0) {
+      return [];
+    }
+
+    const nodeMap = new Map(nodes.map(n => [n.id, n]));
+    const inDegree = new Map(nodes.map(n => [n.id, 0]));
+    const adjacency = new Map(nodes.map(n => [n.id, []]));
+
+    // Build adjacency list and calculate in-degrees
+    for (const edge of (edges || [])) {
+      const source = edge.source;
+      const target = edge.target;
+
+      if (adjacency.has(source) && inDegree.has(target)) {
+        adjacency.get(source).push(target);
+        inDegree.set(target, inDegree.get(target) + 1);
+      }
+    }
+
+    // Find all nodes with in-degree 0 (starting nodes)
+    const queue = [];
+    for (const [nodeId, degree] of inDegree) {
+      if (degree === 0) {
+        queue.push(nodeId);
+      }
+    }
+
+    // Process queue
+    const sorted = [];
+    while (queue.length > 0) {
+      const nodeId = queue.shift();
+      const node = nodeMap.get(nodeId);
+      if (node) {
+        sorted.push(node);
+      }
+
+      for (const neighbor of adjacency.get(nodeId) || []) {
+        const newDegree = inDegree.get(neighbor) - 1;
+        inDegree.set(neighbor, newDegree);
+        if (newDegree === 0) {
+          queue.push(neighbor);
+        }
+      }
+    }
+
+    // Check for cycles
+    if (sorted.length !== nodes.length) {
+      this.logger.warn('Flow contains cycles, some nodes may not execute');
+    }
+
+    return sorted;
+  }
+
+  /**
+   * Execute a single node
+   * @param {Object} node - Node to execute
+   * @param {Object} context - Execution context
+   * @param {string} runId - Run identifier
+   * @param {string} sessionId - Session ID for broadcasts
+   * @param {Object} flow - Flow definition
+   * @returns {Promise<Object>} Node execution result
+   */
+  async executeNode(node, context, runId, sessionId, flow) {
+    this.logger.info(`Executing node: ${node.id}`, {
+      type: node.type,
+      label: node.data?.label
+    });
+
+    // Update node state to running
+    await this.updateNodeState(runId, node.id, 'running', null);
+    this.broadcastFlowUpdate(sessionId, {
+      type: 'flow_node_started',
+      runId,
+      nodeId: node.id,
+      nodeType: node.type
+    });
+
+    let result;
+
+    try {
+      switch (node.type) {
+        case 'input':
+          result = await this.executeInputNode(node, context);
+          break;
+        case 'agent':
+          result = await this.executeAgentNode(node, context, runId, sessionId, flow);
+          break;
+        case 'output':
+          result = await this.executeOutputNode(node, context, flow);
+          break;
+        default:
+          throw new Error(`Unknown node type: ${node.type}`);
+      }
+
+      this.broadcastFlowUpdate(sessionId, {
+        type: 'flow_node_completed',
+        runId,
+        nodeId: node.id,
+        nodeType: node.type,
+        output: this.truncateOutput(result)
+      });
+
+      return result;
+
+    } catch (error) {
+      await this.updateNodeState(runId, node.id, 'failed', { error: error.message });
+      this.broadcastFlowUpdate(sessionId, {
+        type: 'flow_node_failed',
+        runId,
+        nodeId: node.id,
+        nodeType: node.type,
+        error: error.message
+      });
+      throw error;
+    }
+  }
+
+  /**
+   * Execute an input node
+   * @param {Object} node - Input node
+   * @param {Object} context - Execution context
+   * @returns {Promise<Object>} Input result
+   */
+  async executeInputNode(node, context) {
+    // Apply prompt template if provided
+    const template = node.data?.promptTemplate || '{{userInput}}';
+    const output = this.applyTemplate(template, {
+      userInput: context.input,
+      ...context.variables
+    });
+
+    return {
+      type: 'input',
+      output,
+      raw: context.input
+    };
+  }
+
+  /**
+   * Execute an agent node
+   * @param {Object} node - Agent node
+   * @param {Object} context - Execution context
+   * @param {string} runId - Run identifier
+   * @param {string} sessionId - Session ID
+   * @param {Object} flow - Flow definition
+   * @returns {Promise<Object>} Agent response
+   */
+  async executeAgentNode(node, context, runId, sessionId, flow) {
+    const agentId = node.data?.agentId;
+    if (!agentId) {
+      throw new Error(`Agent node ${node.id} has no agent assigned`);
+    }
+
+    // Get agent
+    const agent = await this.agentPool.getAgent(agentId);
+    if (!agent) {
+      throw new Error(`Agent not found: ${agentId}`);
+    }
+
+    // Get input from previous nodes
+    const inputNodeIds = this.getInputNodeIds(node.id, flow.edges);
+    const previousOutput = this.collectPreviousOutput(inputNodeIds, context.nodeOutputs);
+
+    // Apply prompt template
+    const template = node.data?.promptTemplate || '{{input}}';
+    const prompt = this.applyTemplate(template, {
+      input: previousOutput,
+      previousOutput,
+      ...context.variables,
+      ...context.nodeOutputs
+    });
+
+    this.logger.info(`Sending message to agent: ${agentId}`, {
+      promptLength: prompt.length,
+      nodeId: node.id
+    });
+
+    // Store current agent mode to restore later
+    const originalMode = agent.mode;
+
+    // Reset completion state from any previous run, then put in AGENT mode
+    agent.autonomousWorkComplete = false;
+    agent.lastCompletionSummary = null;
+    agent.lastCompletionDetails = null;
+    agent.mode = AGENT_MODES.AGENT;
+    await this.agentPool.persistAgentState(agentId);
+
+    // Clear conversation history for a fresh execution context
+    try {
+      await this.agentPool.clearConversation(agentId);
+      this.logger.info(`Cleared conversation for agent ${agentId} before flow execution`);
+    } catch (error) {
+      this.logger.warn(`Failed to clear conversation for agent ${agentId}`, { error: error.message });
+    }
+
+    // Create completion promise
+    const completionPromise = this.waitForAgentCompletion(agentId, runId);
+
+    // Build flow metadata for context injection
+    const sortedNodes = context.sortedNodes || [];
+    const nodePosition = sortedNodes.findIndex(n => n.id === node.id) + 1;
+    const flowMetadata = {
+      flowId: flow.id,
+      flowName: flow.name || 'Unnamed Flow',
+      nodeName: node.data?.label || 'Agent',
+      nodePosition: nodePosition || 1,
+      totalNodes: sortedNodes.length
+    };
+
+    // Build previous agent data for context passing
+    const previousAgentData = this.buildPreviousAgentData(node, context, flow);
+
+    this.logger.info(`Flow context for agent ${agentId}`, {
+      flowMetadata,
+      hasPreviousAgent: !!previousAgentData,
+      previousAgentId: previousAgentData?.agentId
+    });
+
+    // Queue message to agent with enhanced flow context
+    await this.messageProcessor.processMessage(agentId, prompt, {
+      sessionId,
+      isFlowExecution: true,
+      flowRunId: runId,
+      flowNodeId: node.id,
+      flowMetadata,
+      previousAgentData
+    });
+
+    // Wait for agent to complete (via jobdone tool)
+    const completionResult = await Promise.race([
+      completionPromise,
+      this.createTimeoutPromise(this.config.flows?.nodeTimeout || 300000) // 5 min default
+    ]);
+
+    if (completionResult.timeout) {
+      throw new Error(`Agent ${agentId} timed out`);
+    }
+
+    // Get the agent's response (last assistant message)
+    const updatedAgent = await this.agentPool.getAgent(agentId);
+    const lastResponse = this.getLastAssistantMessage(updatedAgent);
+
+    // Extract files created during this agent's execution (from completion result or messages)
+    const filesCreated = completionResult.filesCreated || this.extractFilesFromCompletion(completionResult);
+
+    return {
+      type: 'agent',
+      agentId,
+      agentName: agent.name,
+      output: completionResult.summary || lastResponse || '',
+      details: completionResult.details,
+      filesCreated,
+      success: completionResult.success !== false
+    };
+  }
+
+  /**
+   * Build previous agent data for context passing to next agent
+   * @param {Object} currentNode - Current agent node
+   * @param {Object} context - Execution context with nodeOutputs
+   * @param {Object} flow - Flow definition
+   * @returns {Object|null} Previous agent data or null if first agent
+   */
+  buildPreviousAgentData(currentNode, context, flow) {
+    // Find the previous agent node that feeds into this one
+    const inputNodeIds = this.getInputNodeIds(currentNode.id, flow.edges);
+
+    // Look for the most recent agent node in the inputs
+    for (const inputId of inputNodeIds) {
+      const nodeOutput = context.nodeOutputs[inputId];
+
+      // Check if this is an agent node output
+      if (nodeOutput && nodeOutput.type === 'agent') {
+        return {
+          agentId: nodeOutput.agentId,
+          agentName: nodeOutput.agentName || nodeOutput.agentId,
+          summary: nodeOutput.output,
+          details: nodeOutput.details,
+          filesCreated: nodeOutput.filesCreated || [],
+          output: nodeOutput.output
+        };
+      }
+    }
+
+    // No previous agent found (first agent in flow or only non-agent predecessors)
+    return null;
+  }
+
+  /**
+   * Extract file paths from completion result
+   * Parses the summary/details for file path mentions
+   * @param {Object} completionResult - Job-done completion result
+   * @returns {Array<string>} Array of file paths
+   */
+  extractFilesFromCompletion(completionResult) {
+    const files = new Set();
+
+    const textToSearch = [
+      completionResult.summary || '',
+      completionResult.details || '',
+      typeof completionResult.output === 'string' ? completionResult.output : ''
+    ].join(' ');
+
+    // Common patterns for file paths
+    const patterns = [
+      /(?:created|wrote|saved|generated|modified|updated)\s+(?:file\s+)?["']?([\/\\][\w\-\.\/\\]+\.\w+)["']?/gi,
+      /(?:at|to|in)\s+["']?([\/\\][\w\-\.\/\\]+\.\w+)["']?/gi,
+      /File\s+(?:created|written|saved):\s*([\/\\][\w\-\.\/\\]+\.\w+)/gi
+    ];
+
+    for (const pattern of patterns) {
+      let match;
+      while ((match = pattern.exec(textToSearch)) !== null) {
+        const path = match[1];
+        if (path && !path.includes('http') && path.length > 3) {
+          files.add(path);
+        }
+      }
+    }
+
+    return Array.from(files);
+  }
+
+  /**
+   * Execute an output node
+   * @param {Object} node - Output node
+   * @param {Object} context - Execution context
+   * @param {Object} flow - Flow definition
+   * @returns {Promise<Object>} Output result
+   */
+  async executeOutputNode(node, context, flow) {
+    // Collect all previous outputs
+    const inputNodeIds = this.getInputNodeIds(node.id, flow.edges);
+    const output = this.collectPreviousOutput(inputNodeIds, context.nodeOutputs);
+
+    // Apply output format
+    const format = node.data?.outputFormat || 'text';
+    let formattedOutput;
+
+    switch (format) {
+      case 'json':
+        formattedOutput = typeof output === 'object' ? output : { result: output };
+        break;
+      case 'markdown':
+        formattedOutput = typeof output === 'string' ? output : JSON.stringify(output, null, 2);
+        break;
+      case 'text':
+      default:
+        formattedOutput = typeof output === 'string' ? output : JSON.stringify(output);
+        break;
+    }
+
+    return {
+      type: 'output',
+      format,
+      output: formattedOutput
+    };
+  }
+
+  /**
+   * Wait for an agent to complete via jobdone tool.
+   * Completion is detected two ways:
+   * 1. Direct signal: notifyAgentCompletion() called from jobDoneTool
+   * 2. Polling fallback: checks autonomousWorkComplete flag every 2s
+   * @param {string} agentId - Agent ID
+   * @param {string} runId - Run ID
+   * @returns {Promise<Object>} Completion result
+   */
+  waitForAgentCompletion(agentId, runId) {
+    return new Promise((resolve) => {
+      const key = `${runId}-${agentId}`;
+      let checkInterval = null;
+
+      const onComplete = (result) => {
+        if (checkInterval) clearInterval(checkInterval);
+        this.completionListeners.delete(key);
+        resolve(result);
+      };
+
+      // Store listener so notifyAgentCompletion() can resolve directly
+      this.completionListeners.set(key, {
+        resolve: onComplete,
+        agentId,
+        runId
+      });
+
+      // Polling fallback: check autonomousWorkComplete flag
+      checkInterval = setInterval(async () => {
+        try {
+          const agent = await this.agentPool.getAgent(agentId);
+          if (agent && agent.autonomousWorkComplete) {
+            onComplete({
+              completed: true,
+              summary: agent.lastCompletionSummary || '',
+              details: agent.lastCompletionDetails || null,
+              success: true
+            });
+          }
+        } catch (error) {
+          // Ignore errors during polling
+        }
+      }, 2000);
+
+      // Clean up interval on timeout
+      setTimeout(() => {
+        if (checkInterval) clearInterval(checkInterval);
+      }, this.config.flows?.nodeTimeout || 300000);
+    });
+  }
+
+  /**
+   * Notify that an agent has completed its work (called from jobDoneTool).
+   * Directly resolves the completion promise instead of waiting for next poll.
+   * @param {string} agentId - Agent ID
+   * @param {Object} completionData - { summary, success, details }
+   */
+  notifyAgentCompletion(agentId, completionData = {}) {
+    // Find any listener waiting for this agent
+    for (const [key, listener] of this.completionListeners.entries()) {
+      if (listener.agentId === agentId) {
+        this.logger.info(`Flow: Agent ${agentId} completed via direct signal`, {
+          runId: listener.runId,
+          success: completionData.success
+        });
+        listener.resolve({
+          completed: true,
+          summary: completionData.summary || '',
+          details: completionData.details || null,
+          success: completionData.success !== false
+        });
+        return true;
+      }
+    }
+    return false; // No listener found (agent not in a flow)
+  }
+
+  /**
+   * Create a timeout promise
+   * @param {number} ms - Timeout in milliseconds
+   * @returns {Promise<Object>} Timeout result
+   */
+  createTimeoutPromise(ms) {
+    return new Promise((resolve) => {
+      setTimeout(() => {
+        resolve({ timeout: true });
+      }, ms);
+    });
+  }
+
+  /**
+   * Get IDs of nodes that connect to a target node
+   * @param {string} targetNodeId - Target node ID
+   * @param {Array} edges - Flow edges
+   * @returns {Array} Source node IDs
+   */
+  getInputNodeIds(targetNodeId, edges) {
+    return (edges || [])
+      .filter(e => e.target === targetNodeId)
+      .map(e => e.source);
+  }
+
+  /**
+   * Collect output from previous nodes
+   * @param {Array} nodeIds - Node IDs to collect from
+   * @param {Object} nodeOutputs - Map of node outputs
+   * @returns {string} Combined output
+   */
+  collectPreviousOutput(nodeIds, nodeOutputs) {
+    const outputs = nodeIds
+      .map(id => nodeOutputs[id])
+      .filter(o => o)
+      .map(o => o.output || o)
+      .filter(o => o);
+
+    if (outputs.length === 0) return '';
+    if (outputs.length === 1) return outputs[0];
+
+    // Combine multiple outputs
+    return outputs.join('\n\n---\n\n');
+  }
+
+  /**
+   * Collect final output from output nodes
+   * @param {Array} sortedNodes - Sorted nodes
+   * @param {Object} context - Execution context
+   * @returns {Object} Final output
+   */
+  collectFinalOutput(sortedNodes, context) {
+    const outputNodes = sortedNodes.filter(n => n.type === 'output');
+
+    if (outputNodes.length === 0) {
+      // No output node, return last node's output
+      const lastNode = sortedNodes[sortedNodes.length - 1];
+      return context.nodeOutputs[lastNode?.id]?.output || null;
+    }
+
+    if (outputNodes.length === 1) {
+      return context.nodeOutputs[outputNodes[0].id]?.output;
+    }
+
+    // Multiple output nodes
+    const outputs = {};
+    for (const node of outputNodes) {
+      const key = node.data?.label || node.id;
+      outputs[key] = context.nodeOutputs[node.id]?.output;
+    }
+    return outputs;
+  }
+
+  /**
+   * Apply template with variable substitution
+   * @param {string} template - Template string
+   * @param {Object} variables - Variables to substitute
+   * @returns {string} Processed template
+   */
+  applyTemplate(template, variables) {
+    let result = template;
+
+    for (const [key, value] of Object.entries(variables)) {
+      const placeholder = `{{${key}}}`;
+      const valueStr = typeof value === 'object'
+        ? JSON.stringify(value)
+        : String(value || '');
+      result = result.split(placeholder).join(valueStr);
+    }
+
+    return result;
+  }
+
+  /**
+   * Update node state in the run record
+   * @param {string} runId - Run ID
+   * @param {string} nodeId - Node ID
+   * @param {string} status - Node status
+   * @param {Object} result - Node result
+   */
+  async updateNodeState(runId, nodeId, status, result) {
+    const run = await this.stateManager.getFlowRun(runId);
+    if (!run) return;
+
+    const nodeStates = run.nodeStates || {};
+    nodeStates[nodeId] = {
+      status,
+      result: result ? this.truncateOutput(result) : null,
+      updatedAt: new Date().toISOString()
+    };
+
+    await this.stateManager.updateFlowRun(runId, { nodeStates });
+  }
+
+  /**
+   * Get the last assistant message from an agent
+   * @param {Object} agent - Agent object
+   * @returns {string|null} Last assistant message content
+   */
+  getLastAssistantMessage(agent) {
+    const messages = agent?.conversations?.full?.messages || [];
+    for (let i = messages.length - 1; i >= 0; i--) {
+      if (messages[i].role === 'assistant') {
+        return messages[i].content;
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Truncate output for storage/transmission
+   * @param {Object} output - Output to truncate
+   * @returns {Object} Truncated output
+   */
+  truncateOutput(output) {
+    if (typeof output === 'string' && output.length > 1000) {
+      return output.substring(0, 1000) + '... (truncated)';
+    }
+    if (typeof output === 'object') {
+      const str = JSON.stringify(output);
+      if (str.length > 1000) {
+        return { truncated: true, preview: str.substring(0, 1000) };
+      }
+    }
+    return output;
+  }
+
+  /**
+   * Broadcast flow update via WebSocket
+   * @param {string} sessionId - Session ID (null broadcasts to all)
+   * @param {Object} data - Update data
+   */
+  broadcastFlowUpdate(sessionId, data) {
+    if (!this.webSocketManager) return;
+
+    try {
+      // broadcastToSession with null sessionId broadcasts to all connections
+      this.webSocketManager.broadcastToSession(sessionId, {
+        type: 'flow_update',
+        data,
+        timestamp: new Date().toISOString()
+      });
+    } catch (error) {
+      this.logger.warn('Failed to broadcast flow update', { error: error.message });
+    }
+  }
+
+  /**
+   * Get active executions
+   * @returns {Array} Active execution info
+   */
+  getActiveExecutions() {
+    return Array.from(this.activeExecutions.entries()).map(([runId, exec]) => ({
+      runId,
+      flowId: exec.flowId,
+      status: exec.status,
+      startedAt: exec.startedAt
+    }));
+  }
+}
+
+export default FlowExecutor;