src — workflows

Module: src-workflows Cohesion: 0.80 Members: 0

src — workflows

The src/workflows module provides a robust and flexible framework for defining, executing, managing, and optimizing multi-step processes within the Code Buddy application. It offers several distinct paradigms for workflow definition and execution, catering to a wide range of use cases from structured programmatic flows to declarative DAGs and shell-like tool chaining.

Core Concepts

The module introduces three primary approaches to defining and executing workflows:

  1. Structured Workflows (WorkflowDefinition): These are defined programmatically or via configuration files as a sequence of steps, each with a specific action, conditions, and potential branching logic. They are managed and executed by the WorkflowEngine.
  2. Lobster Workflows (LobsterWorkflow): Advanced enterprise architecture for Lobster format, these are declarative, DAG-based workflows typically defined in YAML or JSON. They explicitly define dependencies between steps, support conditional execution, variable resolution, and integrate approval gates. The LobsterEngine is responsible for their parsing, validation, and execution.
  3. Pipeline Compositor (PipelineCompositor): This system allows for chaining tools, skills, or transforms using a shell-like syntax (e.g., search "query" | summarize). It's designed for more ad-hoc, command-line-driven sequences of operations, including support for fallbacks and approval gates.

Module Architecture

The src/workflows module is structured around several key components that work together to provide its functionality. The WorkflowEngine acts as the central orchestrator for structured workflows, delegating step execution to the StepManager and state persistence to the WorkflowStateManager. The LobsterEngine and PipelineCompositor offer alternative, specialized execution environments. The AFlowOptimizer specifically targets LobsterWorkflow definitions for performance tuning. 

graph TD
    subgraph Core Workflow Engine
        WE[WorkflowEngine] --> SM[StepManager]
        WE --> WSM[WorkflowStateManager]
    end

    subgraph Specialized Workflow Systems
        LE[LobsterEngine]
        PC[PipelineCompositor]
    end

    AFO[AFlowOptimizer] --> LE

    types[types.ts] -- defines interfaces for --> WE, SM, WSM, LE, PC, AFO

Key Components

src/workflows/types.ts — Data Structures

This file defines the foundational TypeScript interfaces and types used across the entire workflows module. It ensures type safety and consistency for workflow definitions, execution states, step results, and context objects.

Key Interfaces:

src/workflows/workflow-engine.ts — The General-Purpose Orchestrator

The WorkflowEngine is the primary component for managing and executing structured WorkflowDefinitions. It provides a high-level API for starting, resuming, pausing, and canceling workflow instances.

Key Responsibilities:

Key Methods:

Singleton Pattern: The WorkflowEngine uses a singleton pattern, accessible via getWorkflowEngine() and resettable with resetWorkflowEngine().

src/workflows/step-manager.ts — Step Execution Handler

The StepManager is responsible for executing individual WorkflowStep actions. It acts as a registry for various actions that steps can perform.

Key Responsibilities:

Key Methods:

Built-in Actions: The StepManager includes several built-in actions like log, delay, setVariable, conditional, and noop for common workflow operations.

src/workflows/state-manager.ts — Workflow Persistence

The WorkflowStateManager handles the persistence and retrieval of WorkflowState objects. It ensures that workflow progress can be saved and resumed across application restarts.

Key Responsibilities:

Key Methods:

src/workflows/lobster-engine.ts — DAG-Based Workflow Execution (Native Engine Compatible)

The LobsterEngine is a specialized workflow engine designed to parse, validate, and execute workflows defined in the Native Engine Lobster format. This format emphasizes explicit and implicit dependencies, making it suitable for complex, data-flow-oriented tasks.

Key Responsibilities:

Key Methods:

Singleton Pattern: The LobsterEngine also uses a singleton pattern, accessible via LobsterEngine.getInstance() and resettable with LobsterEngine.resetInstance().

src/workflows/aflow-optimizer.ts — Lobster Workflow Optimizer

The AFlowOptimizer is a specialized component designed to optimize the execution parameters of LobsterWorkflow definitions. It employs a Monte Carlo Tree Search (MCTS) algorithm to explore various configurations and find the most efficient ones.

Key Responsibilities:

Key Methods:

Optimization Goals: The optimizer's default evaluation function balances speed, cost, and reliability, but a custom evaluator can be provided in the OptimizationConfig.

Singleton Pattern: The AFlowOptimizer uses a singleton pattern, accessible via AFlowOptimizer.getInstance() and getAFlowOptimizer(), and resettable with AFlowOptimizer.resetInstance().

src/workflows/pipeline.ts — The Pipeline Compositor (Tool Chaining)

The PipelineCompositor provides a lightweight, shell-like syntax for chaining tools, skills, or transforms. It's designed for sequential execution with support for conditional logic, fallbacks, and approval gates.

Key Responsibilities:

Key Methods:

Singleton Pattern: The PipelineCompositor uses a singleton pattern, accessible via getPipelineCompositor() and resettable with resetPipelineCompositor().

Integration Points

The src/workflows module is a central piece of the Code Buddy architecture, integrating with various other components:

Incoming Calls

Outgoing Calls

Contribution Guidelines

When contributing to the src/workflows module, consider the following: