claude_swarm 1.0.0 → 1.0.2

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

data/lib/swarm_sdk/node_context.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  # NodeContext provides context information to node transformers
+  #
+  # This class is passed to input and output transformers, giving them access to:
+  # - The original user prompt
+  # - Results from all previous nodes
+  # - Current node metadata
+  # - Convenience accessors for common operations
+  #
+  # @example Input transformer
+  #   input do |ctx|
+  #     ctx.content              # Previous node's content (convenience)
+  #     ctx.original_prompt      # Original user prompt
+  #     ctx.all_results[:plan]   # Access any previous node
+  #     ctx.node_name            # Current node name
+  #   end
+  #
+  # @example Output transformer
+  #   output do |ctx|
+  #     ctx.content              # Current result's content (convenience)
+  #     ctx.original_prompt      # Original user prompt
+  #     ctx.all_results[:plan]   # Access previous nodes
+  #   end
+  class NodeContext
+    attr_reader :original_prompt, :all_results, :node_name, :dependencies
+
+    # For input transformers: result from previous node(s)
+    attr_reader :previous_result
+
+    # For output transformers: current node's result
+    attr_reader :result
+
+    class << self
+      # Create a NodeContext for input transformers
+      #
+      # @param previous_result [Result, Hash, String] Previous node's result or hash of results
+      # @param all_results [Hash<Symbol, Result>] Results from all completed nodes
+      # @param original_prompt [String] The original user prompt
+      # @param node_name [Symbol] Current node name
+      # @param dependencies [Array<Symbol>] Node dependencies
+      # @param transformed_content [String, nil] Already-transformed content from previous output transformer
+      # @return [NodeContext]
+      def for_input(previous_result:, all_results:, original_prompt:, node_name:, dependencies:, transformed_content: nil)
+        new(
+          previous_result: previous_result,
+          all_results: all_results,
+          original_prompt: original_prompt,
+          node_name: node_name,
+          dependencies: dependencies,
+          result: nil,
+          transformed_content: transformed_content,
+        )
+      end
+
+      # Create a NodeContext for output transformers
+      #
+      # @param result [Result] Current node's execution result
+      # @param all_results [Hash<Symbol, Result>] Results from all completed nodes (including current)
+      # @param original_prompt [String] The original user prompt
+      # @param node_name [Symbol] Current node name
+      # @return [NodeContext]
+      def for_output(result:, all_results:, original_prompt:, node_name:)
+        new(
+          result: result,
+          all_results: all_results,
+          original_prompt: original_prompt,
+          node_name: node_name,
+          dependencies: [],
+          previous_result: nil,
+          transformed_content: nil,
+        )
+      end
+    end
+
+    def initialize(previous_result:, all_results:, original_prompt:, node_name:, dependencies:, result:, transformed_content:)
+      @previous_result = previous_result
+      @result = result
+      @all_results = all_results
+      @original_prompt = original_prompt
+      @node_name = node_name
+      @dependencies = dependencies
+      @transformed_content = transformed_content
+    end
+
+    # Convenience accessor: Get content from previous_result or result
+    #
+    # For input transformers:
+    #   - Returns transformed_content if available (from previous output transformer)
+    #   - Otherwise returns previous_result.content (original content)
+    #   - Returns nil for multiple dependencies (use all_results instead)
+    # For output transformers: returns result.content
+    #
+    # @return [String, nil]
+    def content
+      if @result
+        # Output transformer context: return current result's content
+        @result.content
+      elsif @transformed_content
+        # Input transformer with transformed content from previous output
+        @transformed_content
+      elsif @previous_result.respond_to?(:content)
+        # Input transformer context with Result object (original content)
+        @previous_result.content
+      elsif @previous_result.is_a?(Hash)
+        # Input transformer with multiple dependencies (hash of results)
+        nil # No single "content" - user must pick from all_results hash
+      else
+        # String or other type (initial prompt, no dependencies)
+        @previous_result.to_s
+      end
+    end
+
+    # Convenience accessor: Get agent from previous_result or result
+    #
+    # @return [String, nil]
+    def agent
+      if @result
+        @result.agent
+      elsif @previous_result.respond_to?(:agent)
+        @previous_result.agent
+      end
+    end
+
+    # Convenience accessor: Get logs from previous_result or result
+    #
+    # @return [Array, nil]
+    def logs
+      if @result
+        @result.logs
+      elsif @previous_result.respond_to?(:logs)
+        @previous_result.logs
+      end
+    end
+
+    # Convenience accessor: Get duration from previous_result or result
+    #
+    # @return [Float, nil]
+    def duration
+      if @result
+        @result.duration
+      elsif @previous_result.respond_to?(:duration)
+        @previous_result.duration
+      end
+    end
+
+    # Convenience accessor: Get error from previous_result or result
+    #
+    # @return [Exception, nil]
+    def error
+      if @result
+        @result.error
+      elsif @previous_result.respond_to?(:error)
+        @previous_result.error
+      end
+    end
+
+    # Convenience accessor: Check success status
+    #
+    # @return [Boolean, nil]
+    def success?
+      if @result
+        @result.success?
+      elsif @previous_result.respond_to?(:success?)
+        @previous_result.success?
+      end
+    end
+  end
+end