Feature/execution (#87)

* feat(executor): split executor into specialized components

* fix(executor): if there is a dependency on a block that is not along the selected path, ignore it; if we are at max iterations for a loop, stop

* feat(exector): cleanup inline comments in executor

* fix(executor): fix issue in removeDownstreamBlocks when we are breaking out of a loop to prevent infinite recursion

* feat(executor/tests): setup initial testing directory

* feat(executor): make the path selection for routing/conditional blocks independent of context, instead of deactivating paths we just activate others

executor/types.ts

@@ -1,86 +1,183 @@
 import { BlockOutput } from '@/blocks/types'
+import { SerializedBlock, SerializedWorkflow } from '@/serializer/types'
 
 /**
- * Describes a single block's logs, including timing and success/failure state.
+ * Standardized block output format that ensures compatibility with the execution engine.
+ */
+export interface NormalizedBlockOutput {
+  /** Primary response data from the block execution */
+  response: {
+    [key: string]: any
+    content?: string // Text content from LLM responses
+    model?: string // Model identifier used for generation
+    tokens?: {
+      prompt?: number
+      completion?: number
+      total?: number
+    }
+    toolCalls?: {
+      list: any[]
+      count: number
+    }
+    selectedPath?: {
+      blockId: string
+      blockType?: string
+      blockTitle?: string
+    }
+    selectedConditionId?: string // ID of selected condition
+    conditionResult?: boolean // Whether condition evaluated to true
+    result?: any // Generic result value
+    stdout?: string // Standard output from function execution
+    executionTime?: number // Time taken to execute
+    data?: any // Response data from API calls
+    status?: number // HTTP status code
+    headers?: Record<string, string> // HTTP headers
+  }
+  [key: string]: any // Additional properties
+}
+
+/**
+ * Execution log entry for a single block.
  */
 export interface BlockLog {
-  blockId: string
-  blockName?: string
-  blockType?: string
-  startedAt: string
-  endedAt: string
-  durationMs: number
-  success: boolean
-  output?: any
-  error?: string
+  blockId: string // Unique identifier of the executed block
+  blockName?: string // Display name of the block
+  blockType?: string // Type of the block (agent, router, etc.)
+  startedAt: string // ISO timestamp when execution started
+  endedAt: string // ISO timestamp when execution completed
+  durationMs: number // Duration of execution in milliseconds
+  success: boolean // Whether execution completed successfully
+  output?: any // Output data from successful execution
+  error?: string // Error message if execution failed
 }
 
 /**
- * Describes the runtime context for executing a workflow,
- * including all block outputs (blockStates), metadata for timing, and block logs.
+ * Timing metadata for workflow execution.
  */
 export interface ExecutionMetadata {
-  startTime?: string
-  endTime?: string
-}
-
-export interface ExecutionContext {
-  workflowId: string
-  blockStates: Map<string, BlockOutput>
-  blockLogs: BlockLog[]
-  metadata: ExecutionMetadata
-  environmentVariables?: Record<string, string>
+  startTime?: string // ISO timestamp when workflow execution started
+  endTime?: string // ISO timestamp when workflow execution completed
 }
 
 /**
- * The complete result from executing the workflow. Includes success/fail,
- * the "last block" output, optional error, timing metadata, and logs of each block's run.
+ * Current state of a block during workflow execution.
+ */
+export interface BlockState {
+  output: NormalizedBlockOutput // Current output data from the block
+  executed: boolean // Whether the block has been executed
+  executionTime?: number // Time taken to execute in milliseconds
+}
+
+/**
+ * Runtime context for workflow execution.
+ */
+export interface ExecutionContext {
+  workflowId: string // Unique identifier for this workflow execution
+  blockStates: Map<string, BlockState> // Map of block states indexed by block ID
+  blockLogs: BlockLog[] // Chronological log of block executions
+  metadata: ExecutionMetadata // Timing metadata for the execution
+  environmentVariables: Record<string, string> // Environment variables available during execution
+
+  // Routing decisions for path determination
+  decisions: {
+    router: Map<string, string> // Router block ID -> Target block ID
+    condition: Map<string, string> // Condition block ID -> Selected condition ID
+  }
+
+  loopIterations: Map<string, number> // Tracks current iteration count for each loop
+
+  // Execution tracking
+  executedBlocks: Set<string> // Set of block IDs that have been executed
+  activeExecutionPath: Set<string> // Set of block IDs in the current execution path
+
+  workflow?: SerializedWorkflow // Reference to the workflow being executed
+}
+
+/**
+ * Complete result from executing a workflow.
  */
 export interface ExecutionResult {
-  success: boolean
-  output: BlockOutput
-  error?: string
-  logs?: BlockLog[]
+  success: boolean // Whether the workflow executed successfully
+  output: NormalizedBlockOutput // Final output data from the workflow
+  error?: string // Error message if execution failed
+  logs?: BlockLog[] // Execution logs for all blocks
   metadata?: {
-    duration: number
-    startTime: string
-    endTime: string
+    duration: number // Total execution time in milliseconds
+    startTime: string // ISO timestamp when execution started
+    endTime: string // ISO timestamp when execution completed
   }
 }
 
 /**
- * Defines how a particular tool is invoked (URLs, headers, etc.), how it transforms responses
- * and handles errors. Used by blocks that reference a particular tool ID.
+ * Configuration options for workflow execution.
+ */
+export interface ExecutionOptions {
+  maxLoopIterations?: number // Maximum iterations for any loop (default: 5)
+  continueOnError?: boolean // Whether to continue execution after errors
+  timeoutMs?: number // Maximum execution time in milliseconds before timeout
+}
+
+/**
+ * Interface for a block executor component.
+ */
+export interface BlockExecutor {
+  /**
+   * Determines if this executor can process the given block.
+   */
+  canExecute(block: SerializedBlock): boolean
+
+  /**
+   * Executes the block with the given inputs and context.
+   */
+  execute(
+    block: SerializedBlock,
+    inputs: Record<string, any>,
+    context: ExecutionContext
+  ): Promise<BlockOutput>
+}
+
+/**
+ * Definition of a tool that can be invoked by blocks.
+ *
+ * @template P - Parameter type for the tool
+ * @template O - Output type from the tool
  */
 export interface Tool<P = any, O = Record<string, any>> {
-  id: string
-  name: string
-  description: string
-  version: string
+  id: string // Unique identifier for the tool
+  name: string // Display name of the tool
+  description: string // Description of what the tool does
+  version: string // Version string for the tool
+
+  // Parameter definitions for the tool
   params: {
     [key: string]: {
-      type: string
-      required?: boolean
-      description?: string
-      default?: any
+      type: string // Data type of the parameter
+      required?: boolean // Whether the parameter is required
+      description?: string // Description of the parameter
+      default?: any // Default value if not provided
     }
   }
+
+  // HTTP request configuration for API tools
   request?: {
-    url?: string | ((params: P) => string)
-    method?: string
-    headers?: (params: P) => Record<string, string>
-    body?: (params: P) => Record<string, any>
+    url?: string | ((params: P) => string) // URL or function to generate URL
+    method?: string // HTTP method to use
+    headers?: (params: P) => Record<string, string> // Function to generate request headers
+    body?: (params: P) => Record<string, any> // Function to generate request body
   }
+
+  // Function to transform API response to tool output
   transformResponse?: (response: any) => Promise<{
     success: boolean
     output: O
     error?: string
   }>
-  transformError?: (error: any) => string
+
+  transformError?: (error: any) => string // Function to format error messages
 }
 
 /**
- * A registry of Tools, keyed by their IDs or names.
+ * Registry of available tools indexed by ID.
  */
 export interface ToolRegistry {
   [key: string]: Tool