swarm_sdk 2.0.0.pre.2 → 2.0.1

data/lib/swarm_sdk/node/builder.rb

@@ -0,0 +1,439 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Node
+    # Builder provides DSL for configuring nodes (mini-swarms within a workflow)
+    #
+    # A node represents a stage in a multi-step workflow where a specific set
+    # of agents collaborate. Each node creates an independent swarm execution.
+    #
+    # @example Solo agent node
+    #   node :planning do
+    #     agent(:architect)
+    #   end
+    #
+    # @example Multi-agent node with delegation
+    #   node :implementation do
+    #     agent(:backend).delegates_to(:tester, :database)
+    #     agent(:tester).delegates_to(:database)
+    #     agent(:database)
+    #
+    #     depends_on :planning
+    #   end
+    class Builder
+      attr_reader :name,
+        :agent_configs,
+        :dependencies,
+        :lead_override,
+        :input_transformer,
+        :output_transformer,
+        :input_transformer_command,
+        :output_transformer_command
+
+      def initialize(name)
+        @name = name
+        @agent_configs = []
+        @dependencies = []
+        @lead_override = nil
+        @input_transformer = nil # Ruby block
+        @output_transformer = nil # Ruby block
+        @input_transformer_command = nil # Bash command
+        @output_transformer_command = nil # Bash command
+      end
+
+      # Configure an agent for this node
+      #
+      # Returns an AgentConfig object that supports fluent delegation syntax.
+      # If delegates_to is not called, the agent is registered with no delegation.
+      #
+      # @param name [Symbol] Agent name
+      # @return [AgentConfig] Fluent configuration object
+      #
+      # @example With delegation
+      #   agent(:backend).delegates_to(:tester, :database)
+      #
+      # @example Without delegation
+      #   agent(:planner)
+      def agent(name)
+        config = AgentConfig.new(name, self)
+
+        # Register immediately with empty delegation
+        # If delegates_to is called later, it will update this
+        register_agent(name, [])
+
+        config
+      end
+
+      # Register an agent configuration (called by AgentConfig)
+      #
+      # @param agent_name [Symbol] Agent name
+      # @param delegates_to [Array<Symbol>] Delegation targets
+      # @return [void]
+      def register_agent(agent_name, delegates_to)
+        # Check if agent already registered
+        existing = @agent_configs.find { |ac| ac[:agent] == agent_name }
+
+        if existing
+          # Update delegation (happens when delegates_to is called after agent())
+          existing[:delegates_to] = delegates_to
+        else
+          # Add new agent configuration
+          @agent_configs << { agent: agent_name, delegates_to: delegates_to }
+        end
+      end
+
+      # Declare dependencies (nodes that must execute before this one)
+      #
+      # @param node_names [Array<Symbol>] Names of prerequisite nodes
+      # @return [void]
+      #
+      # @example Single dependency
+      #   depends_on :planning
+      #
+      # @example Multiple dependencies
+      #   depends_on :frontend, :backend
+      def depends_on(*node_names)
+        @dependencies.concat(node_names.map(&:to_sym))
+      end
+
+      # Override the lead agent (first agent is lead by default)
+      #
+      # @param agent_name [Symbol] Name of agent to make lead
+      # @return [void]
+      #
+      # @example
+      #   agent(:backend).delegates_to(:tester)
+      #   agent(:tester)
+      #   lead :tester  # tester is lead instead of backend
+      def lead(agent_name)
+        @lead_override = agent_name.to_sym
+      end
+
+      # Define input transformer for this node
+      #
+      # The transformer receives a NodeContext object with access to:
+      # - Previous node's result (convenience: ctx.content)
+      # - Original user prompt (ctx.original_prompt)
+      # - All previous node results (ctx.all_results[:node_name])
+      # - Current node metadata (ctx.node_name, ctx.dependencies)
+      #
+      # Can also be used for side effects (logging, file I/O) since the block
+      # runs at execution time, not declaration time.
+      #
+      # **Skip Execution**: Return a hash with `skip_execution: true` to skip
+      # the node's swarm execution and immediately return the provided content.
+      # Useful for caching, validation, or conditional execution.
+      #
+      # @yield [NodeContext] Context with previous results and metadata
+      # @return [String, Hash] Transformed input OR skip hash
+      #
+      # @example Access previous result and original prompt
+      #   input do |ctx|
+      #     # Convenience accessor
+      #     previous_content = ctx.content
+      #
+      #     # Access original prompt
+      #     "Original: #{ctx.original_prompt}\nPrevious: #{previous_content}"
+      #   end
+      #
+      # @example Access results from specific nodes
+      #   input do |ctx|
+      #     plan = ctx.all_results[:planning].content
+      #     design = ctx.all_results[:design].content
+      #
+      #     "Implement based on:\nPlan: #{plan}\nDesign: #{design}"
+      #   end
+      #
+      # @example Skip execution (caching)
+      #   input do |ctx|
+      #     cached = check_cache(ctx.content)
+      #     if cached
+      #       # Skip LLM call, return cached result
+      #       { skip_execution: true, content: cached }
+      #     else
+      #       ctx.content
+      #     end
+      #   end
+      #
+      # @example Skip execution (validation)
+      #   input do |ctx|
+      #     if ctx.content.length > 10000
+      #       # Fail early without LLM call
+      #       { skip_execution: true, content: "ERROR: Input too long" }
+      #     else
+      #       ctx.content
+      #     end
+      #   end
+      def input(&block)
+        @input_transformer = block
+      end
+
+      # Set input transformer as bash command (YAML API)
+      #
+      # The command receives NodeContext as JSON on STDIN and outputs transformed content.
+      #
+      # **Exit codes:**
+      # - 0: Success, use STDOUT as transformed content
+      # - 1: Skip node execution, use current_input unchanged (STDOUT ignored)
+      # - 2: Halt workflow with error, show STDERR (STDOUT ignored)
+      #
+      # @param command [String] Bash command to execute
+      # @param timeout [Integer] Timeout in seconds (default: 60)
+      # @return [void]
+      #
+      # @example
+      #   input_command("scripts/validate.sh", timeout: 30)
+      def input_command(command, timeout: TransformerExecutor::DEFAULT_TIMEOUT)
+        @input_transformer_command = { command: command, timeout: timeout }
+      end
+
+      # Define output transformer for this node
+      #
+      # The transformer receives a NodeContext object with access to:
+      # - Current node's result (convenience: ctx.content)
+      # - Original user prompt (ctx.original_prompt)
+      # - All completed node results (ctx.all_results[:node_name])
+      # - Current node metadata (ctx.node_name)
+      #
+      # Can also be used for side effects (logging, file I/O) since the block
+      # runs at execution time, not declaration time.
+      #
+      # @yield [NodeContext] Context with current result and metadata
+      # @return [String] Transformed output
+      #
+      # @example Transform and save to file
+      #   output do |ctx|
+      #     # Side effect: save to file
+      #     File.write("results/plan.txt", ctx.content)
+      #
+      #     # Return transformed output for next node
+      #     "Key decisions: #{extract_decisions(ctx.content)}"
+      #   end
+      #
+      # @example Access original prompt
+      #   output do |ctx|
+      #     # Include original context in output
+      #     "Task: #{ctx.original_prompt}\nResult: #{ctx.content}"
+      #   end
+      #
+      # @example Access multiple node results
+      #   output do |ctx|
+      #     plan = ctx.all_results[:planning].content
+      #     impl = ctx.content
+      #
+      #     "Completed:\nPlan: #{plan}\nImpl: #{impl}"
+      #   end
+      def output(&block)
+        @output_transformer = block
+      end
+
+      # Set output transformer as bash command (YAML API)
+      #
+      # The command receives NodeContext as JSON on STDIN and outputs transformed content.
+      #
+      # **Exit codes:**
+      # - 0: Success, use STDOUT as transformed content
+      # - 1: Pass through unchanged, use result.content (STDOUT ignored)
+      # - 2: Halt workflow with error, show STDERR (STDOUT ignored)
+      #
+      # @param command [String] Bash command to execute
+      # @param timeout [Integer] Timeout in seconds (default: 60)
+      # @return [void]
+      #
+      # @example
+      #   output_command("scripts/format.sh", timeout: 30)
+      def output_command(command, timeout: TransformerExecutor::DEFAULT_TIMEOUT)
+        @output_transformer_command = { command: command, timeout: timeout }
+      end
+
+      # Check if node has any input transformer (block or command)
+      #
+      # @return [Boolean]
+      def has_input_transformer?
+        @input_transformer || @input_transformer_command
+      end
+
+      # Check if node has any output transformer (block or command)
+      #
+      # @return [Boolean]
+      def has_output_transformer?
+        @output_transformer || @output_transformer_command
+      end
+
+      # Transform input using configured transformer (block or command)
+      #
+      # Executes either Ruby block or bash command transformer.
+      #
+      # **Exit code behavior (bash commands only):**
+      # - Exit 0: Use STDOUT as transformed content
+      # - Exit 1: Skip node execution, use current_input unchanged (STDOUT ignored)
+      # - Exit 2: Halt workflow with error (STDOUT ignored)
+      #
+      # @param context [NodeContext] Context with previous results and metadata
+      # @param current_input [String] Fallback content for exit 1 (skip), also used for halt error context
+      # @return [String, Hash] Transformed input OR skip hash `{ skip_execution: true, content: "..." }`
+      # @raise [ConfigurationError] If bash transformer halts workflow (exit 2)
+      def transform_input(context, current_input:)
+        # No transformer configured: return content as-is
+        return context.content unless @input_transformer || @input_transformer_command
+
+        # Ruby block transformer
+        # Ruby blocks can return String (transformed content) OR Hash (skip_execution)
+        if @input_transformer
+          return @input_transformer.call(context)
+        end
+
+        # Bash command transformer
+        # Bash commands use exit codes to control behavior:
+        # - Exit 0: Success, use STDOUT as transformed content
+        # - Exit 1: Skip node execution, use current_input unchanged (STDOUT ignored)
+        # - Exit 2: Halt workflow with error (STDOUT ignored)
+        if @input_transformer_command
+          result = TransformerExecutor.execute(
+            command: @input_transformer_command[:command],
+            context: context,
+            event: "input",
+            node_name: @name,
+            fallback_content: current_input, # Used for exit 1 (skip)
+            timeout: @input_transformer_command[:timeout],
+          )
+
+          # Handle transformer result based on exit code
+          if result.halt?
+            # Exit 2: Halt workflow with error
+            raise ConfigurationError,
+              "Input transformer halted workflow for node '#{@name}': #{result.error_message}"
+          elsif result.skip_execution?
+            # Exit 1: Skip node execution, return skip hash
+            # Content is current_input unchanged (STDOUT was ignored)
+            { skip_execution: true, content: result.content }
+          else
+            # Exit 0: Return transformed content from STDOUT
+            result.content
+          end
+        end
+      end
+
+      # Transform output using configured transformer (block or command)
+      #
+      # Executes either Ruby block or bash command transformer.
+      #
+      # **Exit code behavior (bash commands only):**
+      # - Exit 0: Use STDOUT as transformed content
+      # - Exit 1: Pass through unchanged, use result.content (STDOUT ignored)
+      # - Exit 2: Halt workflow with error (STDOUT ignored)
+      #
+      # @param context [NodeContext] Context with current result and metadata
+      # @return [String] Transformed output
+      # @raise [ConfigurationError] If bash transformer halts workflow (exit 2)
+      def transform_output(context)
+        # No transformer configured: return content as-is
+        return context.content unless @output_transformer || @output_transformer_command
+
+        # Ruby block transformer
+        # Simply calls the block with context and returns result
+        if @output_transformer
+          return @output_transformer.call(context)
+        end
+
+        # Bash command transformer
+        # Bash commands use exit codes to control behavior:
+        # - Exit 0: Success, use STDOUT as transformed content
+        # - Exit 1: Pass through unchanged, use result.content (STDOUT ignored)
+        # - Exit 2: Halt workflow with error from STDERR (STDOUT ignored)
+        if @output_transformer_command
+          result = TransformerExecutor.execute(
+            command: @output_transformer_command[:command],
+            context: context,
+            event: "output",
+            node_name: @name,
+            fallback_content: context.content, # result.content for exit 1
+            timeout: @output_transformer_command[:timeout],
+          )
+
+          # Handle transformer result based on exit code
+          if result.halt?
+            # Exit 2: Halt workflow with error
+            raise ConfigurationError,
+              "Output transformer halted workflow for node '#{@name}': #{result.error_message}"
+          else
+            # Exit 0: Return transformed content from STDOUT
+            # Exit 1: Return fallback (result.content unchanged)
+            result.content
+          end
+        end
+      end
+
+      # Get the lead agent for this node
+      #
+      # @return [Symbol] Lead agent name
+      def lead_agent
+        @lead_override || @agent_configs.first&.dig(:agent)
+      end
+
+      # Check if this is an agent-less (computation-only) node
+      #
+      # Agent-less nodes run pure Ruby code without LLM execution.
+      # They must have at least one transformer (input or output).
+      #
+      # @return [Boolean]
+      def agent_less?
+        @agent_configs.empty?
+      end
+
+      # Validate node configuration
+      #
+      # Also auto-adds agents that are referenced in delegates_to but not explicitly declared.
+      # This allows writing: agent(:backend).delegates_to(:verifier)
+      # without needing: agent(:verifier)
+      #
+      # @return [void]
+      # @raise [ConfigurationError] If configuration is invalid
+      def validate!
+        # Auto-add agents mentioned in delegates_to but not explicitly declared
+        auto_add_delegate_agents
+
+        # Agent-less nodes (pure computation) are allowed but need transformers
+        if @agent_configs.empty?
+          unless has_input_transformer? || has_output_transformer?
+            raise ConfigurationError,
+              "Agent-less node '#{@name}' must have at least one transformer (input or output). " \
+                "Either add agents with agent(:name) or add input/output transformers."
+          end
+        end
+
+        # If has agents, validate lead override
+        if @lead_override && !@agent_configs.any? { |ac| ac[:agent] == @lead_override }
+          raise ConfigurationError,
+            "Node '#{@name}' lead agent '#{@lead_override}' not found in node's agents"
+        end
+      end
+
+      private
+
+      # Auto-add agents that are mentioned in delegates_to but not explicitly declared
+      #
+      # This allows:
+      #   agent(:backend).delegates_to(:tester)
+      # Without needing:
+      #   agent(:tester)
+      #
+      # The tester agent is automatically added to the node with no delegation.
+      #
+      # @return [void]
+      def auto_add_delegate_agents
+        # Collect all agents mentioned in delegates_to
+        all_delegates = @agent_configs.flat_map { |ac| ac[:delegates_to] }.uniq
+
+        # Find delegates that aren't explicitly declared
+        declared_agents = @agent_configs.map { |ac| ac[:agent] }
+        missing_delegates = all_delegates - declared_agents
+
+        # Auto-add missing delegates with empty delegation
+        missing_delegates.each do |delegate_name|
+          @agent_configs << { agent: delegate_name, delegates_to: [] }
+        end
+      end
+    end
+  end
+end

data/lib/swarm_sdk/node/transformer_executor.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+require "open3"
+require "json"
+require "timeout"
+
+module SwarmSDK
+  module Node
+    # Executes bash command transformers for node input/output transformation
+    #
+    # Transformers are shell commands that receive NodeContext data on STDIN as JSON
+    # and produce transformed content on STDOUT.
+    #
+    # ## Exit Code Behavior
+    #
+    # - **Exit 0**: Transform success
+    #   - Use STDOUT as the transformed content
+    #   - Node execution proceeds with transformed content
+    #
+    # - **Exit 1**: Skip node execution (pass-through)
+    #   - STDOUT is IGNORED
+    #   - Input transformer: Use current_input unchanged (no transformation)
+    #   - Output transformer: Use result.content unchanged (no transformation)
+    #   - For input transformer: Also skips the node's LLM execution
+    #
+    # - **Exit 2**: Halt entire workflow
+    #   - STDOUT is IGNORED
+    #   - STDERR is shown as error message
+    #   - Workflow stops immediately with error
+    #
+    # ## JSON Input Format (STDIN)
+    #
+    # **Input transformer receives:**
+    # ```json
+    # {
+    #   "event": "input",
+    #   "node": "implementation",
+    #   "original_prompt": "Build auth API",
+    #   "content": "PLAN: Create endpoints...",
+    #   "all_results": {
+    #     "planning": {
+    #       "content": "Create endpoints...",
+    #       "agent": "planner",
+    #       "duration": 2.5,
+    #       "success": true
+    #     }
+    #   },
+    #   "dependencies": ["planning"]
+    # }
+    # ```
+    #
+    # **Output transformer receives:**
+    # ```json
+    # {
+    #   "event": "output",
+    #   "node": "implementation",
+    #   "original_prompt": "Build auth API",
+    #   "content": "Implementation complete",
+    #   "all_results": {
+    #     "planning": {...},
+    #     "implementation": {...}
+    #   }
+    # }
+    # ```
+    #
+    # @example Input transformer that validates
+    #   # validate.sh
+    #   #!/bin/bash
+    #   INPUT=$(cat)
+    #   CONTENT=$(echo "$INPUT" | jq -r '.content')
+    #
+    #   if [ ${#CONTENT} -gt 10000 ]; then
+    #     echo "Content too long" >&2
+    #     exit 2  # Halt workflow
+    #   fi
+    #
+    #   echo "$CONTENT"
+    #   exit 0
+    #
+    # @example Input transformer that caches (skip execution)
+    #   # cache_check.sh
+    #   #!/bin/bash
+    #   INPUT=$(cat)
+    #   CONTENT=$(echo "$INPUT" | jq -r '.content')
+    #
+    #   if cached "$CONTENT"; then
+    #     exit 1  # Skip node execution, pass through unchanged
+    #   fi
+    #
+    #   echo "$CONTENT"
+    #   exit 0
+    class TransformerExecutor
+      DEFAULT_TIMEOUT = 60
+
+      # Result object for transformer execution
+      TransformerResult = Struct.new(:success, :content, :skip_execution, :halt, :error_message, keyword_init: true) do
+        def skip_execution?
+          skip_execution
+        end
+
+        def halt?
+          halt
+        end
+      end
+
+      class << self
+        # Execute a transformer shell command
+        #
+        # @param command [String] Shell command to execute
+        # @param context [NodeContext] Node context for building JSON input
+        # @param event [String] Event type ("input" or "output")
+        # @param node_name [Symbol] Current node name
+        # @param fallback_content [String] Content to use if skip (exit 1)
+        # @param timeout [Integer] Timeout in seconds (default: 60)
+        # @return [TransformerResult] Result with transformed content or skip/halt flags
+        def execute(command:, context:, event:, node_name:, fallback_content:, timeout: DEFAULT_TIMEOUT)
+          # Build JSON input for transformer
+          input_json = build_transformer_input(context, event, node_name)
+
+          # Build environment variables
+          env = build_environment(node_name: node_name)
+
+          # Execute command with JSON stdin and timeout
+          stdout, stderr, status = Timeout.timeout(timeout) do
+            Open3.capture3(
+              env,
+              command,
+              stdin_data: JSON.generate(input_json),
+            )
+          end
+
+          # Handle exit code
+          # Exit 0: Transform success, use STDOUT
+          # Exit 1: Skip node execution, use fallback_content (IGNORE STDOUT)
+          # Exit 2: Halt workflow with error (IGNORE STDOUT)
+          case status.exitstatus
+          when 0
+            # Success: use STDOUT as transformed content (strip trailing newline)
+            TransformerResult.new(
+              success: true,
+              content: stdout.chomp, # Remove trailing newline from echo
+              skip_execution: false,
+              halt: false,
+              error_message: nil,
+            )
+          when 1
+            # Skip node execution: use fallback_content unchanged (IGNORE STDOUT)
+            # For input transformer: skip_execution = true (skip LLM call)
+            # For output transformer: skip_execution = false (just pass through)
+            TransformerResult.new(
+              success: true,
+              content: fallback_content,
+              skip_execution: (event == "input"), # Only skip LLM for input transformers
+              halt: false,
+              error_message: nil,
+            )
+          when 2
+            # Halt workflow: return error (IGNORE STDOUT)
+            error_msg = stderr.strip.empty? ? "Transformer halted workflow (exit 2)" : stderr.strip
+            TransformerResult.new(
+              success: false,
+              content: nil,
+              skip_execution: false,
+              halt: true,
+              error_message: error_msg,
+            )
+          else
+            # Unknown exit code: treat as error (halt)
+            error_msg = "Transformer exited with code #{status.exitstatus}\nSTDERR: #{stderr}"
+            TransformerResult.new(
+              success: false,
+              content: nil,
+              skip_execution: false,
+              halt: true,
+              error_message: error_msg,
+            )
+          end
+        rescue Timeout::Error
+          # Timeout: halt workflow
+          TransformerResult.new(
+            success: false,
+            content: nil,
+            skip_execution: false,
+            halt: true,
+            error_message: "Transformer command timed out after #{timeout}s",
+          )
+        rescue StandardError => e
+          # Execution error: halt workflow
+          TransformerResult.new(
+            success: false,
+            content: nil,
+            skip_execution: false,
+            halt: true,
+            error_message: "Transformer command failed: #{e.message}",
+          )
+        end
+
+        private
+
+        # Build JSON input for transformer command
+        #
+        # @param context [NodeContext] Node context
+        # @param event [String] Event type ("input" or "output")
+        # @param node_name [Symbol] Node name
+        # @return [Hash] JSON data to pass on stdin
+        def build_transformer_input(context, event, node_name)
+          base = {
+            event: event,
+            node: node_name.to_s,
+            original_prompt: context.original_prompt,
+            content: context.content,
+          }
+
+          # Add all_results (convert Result objects to hashes)
+          if context.all_results && !context.all_results.empty?
+            base[:all_results] = context.all_results.transform_values do |result|
+              {
+                content: result.content,
+                agent: result.agent,
+                duration: result.duration,
+                success: result.success?,
+              }
+            end
+          end
+
+          # Add dependencies for input transformers
+          if event == "input" && context.dependencies
+            base[:dependencies] = context.dependencies.map(&:to_s)
+          end
+
+          base
+        end
+
+        # Build environment variables for transformer execution
+        #
+        # @param node_name [Symbol] Current node name
+        # @return [Hash] Environment variables
+        def build_environment(node_name:)
+          {
+            "SWARM_SDK_PROJECT_DIR" => Dir.pwd,
+            "SWARM_SDK_NODE_NAME" => node_name.to_s,
+            "PATH" => ENV.fetch("PATH", ""),
+          }
+        end
+      end
+    end
+  end
+end