swarm_sdk 2.7.13 → 3.0.0.alpha1

data/lib/swarm_sdk/hooks/executor.rb

@@ -1,146 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  module Hooks
-    # Executes hooks with proper chaining, error handling, and logging
-    #
-    # The executor:
-    # - Chains multiple hooks for the same event
-    # - Handles errors and blocking (via Error or Result.halt)
-    # - Respects matcher patterns (only runs matching hooks)
-    # - Logs execution for debugging
-    # - Returns Result indicating action to take
-    #
-    # @example Execute hooks
-    #   executor = SwarmSDK::Hooks::Executor.new(registry, logger)
-    #   context = SwarmSDK::Hooks::Context.new(...)
-    #   result = executor.execute(event: :pre_tool_use, context: context, hooks: agent_hooks)
-    #   if result.halt?
-    #     # Handle halt
-    #   elsif result.replace?
-    #     # Use replacement value
-    #   end
-    class Executor
-      # @param registry [Registry] Hook registry for resolving named hooks
-      # @param logger [Logger, nil] Logger for debugging (optional)
-      def initialize(registry, logger: nil)
-        @registry = registry
-        @logger = logger || Logger.new(nil) # Null logger if not provided
-      end
-
-      # Execute all hooks for an event
-      #
-      # Execution order:
-      # 1. Swarm-level defaults (from registry)
-      # 2. Agent-specific hooks
-      # 3. Within each group, by priority (highest first)
-      #
-      # Hooks must return:
-      # - Result - to control execution flow (halt, replace, reprompt, continue)
-      # - nil - treated as continue with unmodified context
-      #
-      # @param event [Symbol] Event type
-      # @param context [Context] Context to pass to hooks
-      # @param callbacks [Array<Definition>] Agent-specific hooks
-      # @return [Result] Result indicating action and value
-      # @raise [Error] If a hook raises an error
-      def execute(event:, context:, callbacks: [])
-        # Combine swarm defaults and agent hooks
-        all_hooks = @registry.get_defaults(event) + callbacks
-
-        # Filter by matcher (for tool events)
-        if context.tool_event? && context.tool_name
-          all_hooks = all_hooks.select { |hook| hook.matches?(context.tool_name) }
-        end
-
-        # Execute hooks in order
-        all_hooks.each do |hook_def|
-          result = execute_single(hook_def, context)
-
-          # Only Result controls flow - nil means continue
-          next unless result.is_a?(Result)
-
-          # Early return for control flow actions
-          return result if result.halt? || result.replace? || result.reprompt? || result.finish_agent? || result.finish_swarm?
-
-          # Update context if continue with modified context
-          context = result.value if result.continue? && result.value.is_a?(Context)
-        end
-
-        # All hooks executed successfully - continue with final context
-        Result.continue(context)
-      rescue Error => e
-        # Re-raise with context for better error messages
-        @logger.error("Hook blocked execution: #{e.message}")
-        raise
-      rescue StandardError => e
-        # Wrap unexpected errors
-        @logger.error("Hook failed unexpectedly: #{e.class} - #{e.message}")
-        @logger.error(e.backtrace.join("\n"))
-        raise Error.new(
-          "Hook failed: #{e.message}",
-          context: context,
-        )
-      end
-
-      # Execute a single hook
-      #
-      # @param hook_def [Definition] Hook to execute
-      # @param context [Context] Current context
-      # @return [Result, nil] Result from hook (Result or nil)
-      # @raise [Error] If hook execution fails
-      def execute_single(hook_def, context)
-        proc = hook_def.resolve_proc(@registry)
-
-        @logger.debug("Executing hook for #{context.event} (agent: #{context.agent_name})")
-
-        # Execute hook with context as parameter
-        # Users can access convenience methods via context parameter:
-        #   hook(:event) { |ctx| ctx.halt("msg") }
-        # This preserves lexical scope and access to surrounding instance variables
-        proc.call(context)
-      rescue Error
-        # Pass through blocking errors
-        raise
-      rescue StandardError => e
-        # Wrap other errors with context and detailed debugging
-        hook_name = hook_def.named_hook? ? hook_def.proc : "anonymous"
-
-        # Log detailed error info for debugging
-        @logger.error("=" * 80)
-        @logger.error("HOOK EXECUTION ERROR")
-        @logger.error("  Hook: #{hook_name}")
-        @logger.error("  Event: #{context.event}")
-        @logger.error("  Agent: #{context.agent_name}")
-        @logger.error("  Proc class: #{proc.class}")
-        @logger.error("  Proc arity: #{proc.arity} (expected: 1 for |context|)")
-        @logger.error("  Error: #{e.class.name}: #{e.message}")
-        @logger.error("  Backtrace:")
-        e.backtrace.first(15).each { |line| @logger.error("    #{line}") }
-        @logger.error("=" * 80)
-
-        raise Error.new(
-          "Hook #{hook_name} failed: #{e.message}",
-          hook_name: hook_name,
-          context: context,
-        )
-      end
-
-      # Execute hooks and return result safely (without raising)
-      #
-      # This is a convenience method that catches Error and converts it
-      # to a halt result, making it easier to use in control flow.
-      #
-      # @param event [Symbol] Event type
-      # @param context [Context] Context to pass to hooks
-      # @param callbacks [Array<Definition>] Agent-specific hooks
-      # @return [Result] Result from hooks
-      def execute_safe(event:, context:, callbacks: [])
-        execute(event: event, context: context, callbacks: callbacks)
-      rescue Error => e
-        @logger.warn("Execution blocked by hook: #{e.message}")
-        Result.halt(e.message)
-      end
-    end
-  end
-end

data/lib/swarm_sdk/hooks/registry.rb

@@ -1,147 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  module Hooks
-    # Central registry for managing named hooks and swarm-level defaults
-    #
-    # The Registry stores:
-    # - Named hooks that can be referenced by symbol in YAML or code
-    # - Swarm-level default hooks that apply to all agents
-    #
-    # @example Register a named hook
-    #   registry = SwarmSDK::Hooks::Registry.new
-    #   registry.register(:validate_code) do |context|
-    #     raise SwarmSDK::Hooks::Error, "Invalid code" unless valid?(context.tool_call)
-    #   end
-    #
-    # @example Add swarm-level default
-    #   registry.add_default(:pre_tool_use, matcher: "Write|Edit") do |context|
-    #     puts "Tool #{context.tool_call.name} called by #{context.agent_name}"
-    #   end
-    class Registry
-      # Available hook event types
-      VALID_EVENTS = [
-        # Swarm lifecycle events
-        :swarm_start,       # When Swarm.execute is called (before first user message)
-        :swarm_stop,        # When Swarm.execute completes (after execution)
-        :first_message,     # When first user message is sent to swarm (Swarm.execute)
-
-        # Agent/LLM events
-        :user_prompt,       # Before sending user message to LLM
-        :agent_step,        # After agent makes intermediate response with tool calls
-        :agent_stop,        # After agent completes with final response (no more tool calls)
-
-        # Tool events
-        :pre_tool_use,      # Before tool execution (can block/modify)
-        :post_tool_use,     # After tool execution
-
-        # Delegation events
-        :pre_delegation,    # Before delegating to another agent
-        :post_delegation,   # After delegation completes
-
-        # Context events
-        :context_warning, # When context usage crosses threshold
-
-        # Debug events
-        :breakpoint_enter,  # When entering interactive debugging (binding.irb)
-        :breakpoint_exit,   # When exiting interactive debugging
-      ].freeze
-
-      def initialize
-        @named_hooks = {} # { hook_name: proc }
-        @defaults = Hash.new { |h, k| h[k] = [] } # { event_type: [Definition, ...] }
-      end
-
-      # Register a named hook that can be referenced elsewhere
-      #
-      # @param name [Symbol] Unique name for this hook
-      # @param block [Proc] Hook implementation
-      # @raise [ArgumentError] if name already registered or invalid
-      #
-      # @example
-      #   registry.register(:log_tool_use) { |ctx| puts "Tool: #{ctx.tool_call.name}" }
-      def register(name, &block)
-        raise ArgumentError, "Hook name must be a symbol" unless name.is_a?(Symbol)
-        raise ArgumentError, "Hook #{name} already registered" if @named_hooks.key?(name)
-        raise ArgumentError, "Block required" unless block
-
-        @named_hooks[name] = block
-      end
-
-      # Get a named hook by symbol
-      #
-      # @param name [Symbol] Hook name
-      # @return [Proc, nil] The hook proc or nil if not found
-      def get(name)
-        @named_hooks[name]
-      end
-
-      # Add a swarm-level default hook
-      #
-      # These hooks apply to all agents unless overridden at agent level.
-      #
-      # @param event [Symbol] Event type (must be in VALID_EVENTS)
-      # @param matcher [String, Regexp, nil] Optional regex pattern to match tool names
-      # @param priority [Integer] Execution priority (higher runs first)
-      # @param block [Proc] Hook implementation
-      # @raise [ArgumentError] if event invalid or block missing
-      #
-      # @example Add default logging
-      #   registry.add_default(:pre_tool_use) { |ctx| log(ctx) }
-      #
-      # @example Add validation for specific tools
-      #   registry.add_default(:pre_tool_use, matcher: "Write|Edit") do |ctx|
-      #     validate_tool_call(ctx.tool_call)
-      #   end
-      def add_default(event, matcher: nil, priority: 0, &block)
-        validate_event!(event)
-        raise ArgumentError, "Block required" unless block
-
-        definition = Definition.new(
-          event: event,
-          matcher: matcher,
-          priority: priority,
-          proc: block,
-        )
-
-        @defaults[event] << definition
-        @defaults[event].sort_by! { |d| -d.priority } # Higher priority first
-      end
-
-      # Get all default hooks for an event type
-      #
-      # @param event [Symbol] Event type
-      # @return [Array<Definition>] List of hook definitions
-      def get_defaults(event)
-        @defaults[event]
-      end
-
-      # Get all registered named hook names
-      #
-      # @return [Array<Symbol>] List of hook names
-      def named_hooks
-        @named_hooks.keys
-      end
-
-      # Check if a hook name is registered
-      #
-      # @param name [Symbol] Hook name
-      # @return [Boolean] true if registered
-      def registered?(name)
-        @named_hooks.key?(name)
-      end
-
-      private
-
-      # Validate event type
-      #
-      # @param event [Symbol] Event to validate
-      # @raise [ArgumentError] if event invalid
-      def validate_event!(event)
-        return if VALID_EVENTS.include?(event)
-
-        raise ArgumentError, "Invalid event type: #{event}. Valid types: #{VALID_EVENTS.join(", ")}"
-      end
-    end
-  end
-end

data/lib/swarm_sdk/hooks/result.rb

@@ -1,150 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  module Hooks
-    # Result object returned by hooks to control execution flow
-    #
-    # Hooks can return a Result to:
-    # - Continue normal execution (default)
-    # - Halt execution and return an error/message
-    # - Replace a value (e.g., tool result, delegation result)
-    # - Reprompt the agent with a new prompt
-    # - Finish the current agent's execution (agent scope)
-    # - Finish the entire swarm execution (swarm scope)
-    #
-    # @example Continue normal execution (default)
-    #   SwarmSDK::Hooks::Result.continue
-    #
-    # @example Halt execution with error message
-    #   SwarmSDK::Hooks::Result.halt("Validation failed: invalid input")
-    #
-    # @example Replace tool result
-    #   SwarmSDK::Hooks::Result.replace("Custom tool result")
-    #
-    # @example Reprompt agent with modified prompt
-    #   SwarmSDK::Hooks::Result.reprompt("Modified task: #{original_task}")
-    #
-    # @example Finish current agent with message
-    #   SwarmSDK::Hooks::Result.finish_agent("Agent task completed")
-    #
-    # @example Finish entire swarm with message
-    #   SwarmSDK::Hooks::Result.finish_swarm("All tasks complete!")
-    class Result
-      attr_reader :action, :value
-
-      # Valid actions that control execution flow
-      VALID_ACTIONS = [:continue, :halt, :replace, :reprompt, :finish_agent, :finish_swarm].freeze
-
-      # @param action [Symbol] Action to take (:continue, :halt, :replace, :reprompt)
-      # @param value [Object, nil] Associated value (context for :continue, message for :halt, etc.)
-      def initialize(action:, value: nil)
-        unless VALID_ACTIONS.include?(action)
-          raise ArgumentError, "Invalid action: #{action}. Valid actions: #{VALID_ACTIONS.join(", ")}"
-        end
-
-        @action = action
-        @value = value
-      end
-
-      # Check if this result indicates halting execution
-      #
-      # @return [Boolean] true if action is :halt
-      def halt?
-        @action == :halt
-      end
-
-      # Check if this result provides a replacement value
-      #
-      # @return [Boolean] true if action is :replace
-      def replace?
-        @action == :replace
-      end
-
-      # Check if this result requests reprompting
-      #
-      # @return [Boolean] true if action is :reprompt
-      def reprompt?
-        @action == :reprompt
-      end
-
-      # Check if this result continues normal execution
-      #
-      # @return [Boolean] true if action is :continue
-      def continue?
-        @action == :continue
-      end
-
-      # Check if this result finishes the current agent
-      #
-      # @return [Boolean] true if action is :finish_agent
-      def finish_agent?
-        @action == :finish_agent
-      end
-
-      # Check if this result finishes the entire swarm
-      #
-      # @return [Boolean] true if action is :finish_swarm
-      def finish_swarm?
-        @action == :finish_swarm
-      end
-
-      class << self
-        # Create a result that continues normal execution
-        #
-        # @param context [Context, nil] Updated context (optional)
-        # @return [Result] Result with continue action
-        def continue(context = nil)
-          new(action: :continue, value: context)
-        end
-
-        # Create a result that halts execution
-        #
-        # @param message [String] Error or halt message
-        # @return [Result] Result with halt action
-        def halt(message)
-          new(action: :halt, value: message)
-        end
-
-        # Create a result that replaces a value
-        #
-        # @param value [Object] Replacement value
-        # @return [Result] Result with replace action
-        def replace(value)
-          new(action: :replace, value: value)
-        end
-
-        # Create a result that reprompts the agent
-        #
-        # @param prompt [String] New prompt to send to agent
-        # @return [Result] Result with reprompt action
-        def reprompt(prompt)
-          new(action: :reprompt, value: prompt)
-        end
-
-        # Create a result that finishes the current agent
-        #
-        # Exits the agent's chat loop and returns the message as the agent's
-        # final response. If this agent was delegated to, control returns to
-        # the calling agent. The swarm continues if there's more work.
-        #
-        # @param message [String] Final message from the agent
-        # @return [Result] Result with finish_agent action
-        def finish_agent(message)
-          new(action: :finish_agent, value: message)
-        end
-
-        # Create a result that finishes the entire swarm
-        #
-        # Immediately exits the Swarm.execute() loop and returns the message
-        # as the final Result#output. All agent execution stops and the user
-        # receives this message.
-        #
-        # @param message [String] Final message from the swarm
-        # @return [Result] Result with finish_swarm action
-        def finish_swarm(message)
-          new(action: :finish_swarm, value: message)
-        end
-      end
-    end
-  end
-end

data/lib/swarm_sdk/hooks/shell_executor.rb

@@ -1,256 +0,0 @@
-# frozen_string_literal: true
-
-require "open3"
-require "json"
-require "timeout"
-
-module SwarmSDK
-  module Hooks
-    # Executes shell command hooks with JSON I/O and exit code handling
-    #
-    # ShellExecutor runs external shell commands (defined in YAML hooks) and
-    # converts their exit codes to Result objects that control execution flow.
-    #
-    # ## Exit Code Behavior (following Claude Code convention)
-    #
-    # - **0**: Success - continue execution (Result.continue)
-    # - **2**: Block with error feedback to LLM (Result.halt)
-    # - **Other**: Non-blocking error - log warning and continue (Result.continue)
-    #
-    # ## JSON I/O Format
-    #
-    # **stdin (to hook script)**:
-    # ```json
-    # {
-    #   "event": "pre_tool_use",
-    #   "agent": "backend",
-    #   "tool": "Write",
-    #   "parameters": { "file_path": "api.rb", "content": "..." }
-    # }
-    # ```
-    #
-    # **stdout (from hook script)**:
-    # ```json
-    # {
-    #   "success": false,
-    #   "error": "Validation failed: syntax error"
-    # }
-    # ```
-    #
-    # @example Execute a validation hook
-    #   result = SwarmSDK::Hooks::ShellExecutor.execute(
-    #     command: "python scripts/validate.py",
-    #     input_json: { event: "pre_tool_use", tool: "Write", parameters: {...} },
-    #     timeout: 10,
-    #     agent_name: :backend,
-    #     swarm_name: "Dev Team"
-    #   )
-    #   # => Result (continue or halt based on exit code)
-    class ShellExecutor
-      # NOTE: Timeout now accessed via SwarmSDK.config.hook_shell_timeout
-
-      class << self
-        # Execute a shell command hook
-        #
-        # @param command [String] Shell command to execute
-        # @param input_json [Hash] JSON data to provide on stdin
-        # @param timeout [Integer] Timeout in seconds (default: 60)
-        # @param agent_name [Symbol, String, nil] Agent name for environment variables
-        # @param swarm_name [String, nil] Swarm name for environment variables
-        # @param event [Symbol] Event type for context-aware behavior
-        # @return [Result] Result based on exit code (continue or halt)
-        def execute(command:, input_json:, timeout: nil, agent_name: nil, swarm_name: nil, event: nil)
-          timeout ||= SwarmSDK.config.hook_shell_timeout
-
-          # Build environment variables
-          env = build_environment(agent_name: agent_name, swarm_name: swarm_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 per Claude Code convention (context-aware)
-          result = handle_exit_code(status.exitstatus, stdout, stderr, event)
-
-          # Emit log event for hook execution
-          case status.exitstatus
-          when 0
-            # Success - log stdout/stderr
-            emit_hook_log(
-              event: event,
-              agent_name: agent_name,
-              command: command,
-              exit_code: status.exitstatus,
-              success: true,
-              stdout: stdout,
-              stderr: stderr,
-            )
-          when 2
-            # Blocking error - always log stderr
-            emit_hook_log(
-              event: event,
-              agent_name: agent_name,
-              command: command,
-              exit_code: status.exitstatus,
-              success: false,
-              stderr: stderr,
-              blocked: true,
-            )
-          else
-            # Non-blocking error - log stderr
-            emit_hook_log(
-              event: event,
-              agent_name: agent_name,
-              command: command,
-              exit_code: status.exitstatus,
-              success: false,
-              stderr: stderr,
-              blocked: false,
-            )
-          end
-
-          result
-        rescue Timeout::Error
-          emit_hook_log(
-            event: event,
-            agent_name: agent_name,
-            command: command,
-            exit_code: nil,
-            success: false,
-            stderr: "Timeout after #{timeout}s",
-          )
-          # Don't block on timeout - log and continue
-          Result.continue
-        rescue StandardError => e
-          emit_hook_log(
-            event: event,
-            agent_name: agent_name,
-            command: command,
-            exit_code: nil,
-            success: false,
-            stderr: e.message,
-          )
-          # Don't block on errors - log and continue
-          Result.continue
-        end
-
-        private
-
-        # Build environment variables for hook execution
-        #
-        # @param agent_name [Symbol, String, nil] Agent name
-        # @param swarm_name [String, nil] Swarm name
-        # @return [Hash] Environment variables
-        def build_environment(agent_name:, swarm_name:)
-          {
-            "SWARM_SDK_PROJECT_DIR" => Dir.pwd,
-            "SWARM_SDK_AGENT_NAME" => agent_name.to_s,
-            "SWARM_SDK_SWARM_NAME" => swarm_name.to_s,
-            "PATH" => ENV.fetch("PATH", ""),
-          }
-        end
-
-        # Handle exit code and return appropriate Result
-        #
-        # @param exit_code [Integer] Process exit code
-        # @param stdout [String] Standard output
-        # @param stderr [String] Standard error
-        # @param event [Symbol] Hook event type
-        # @return [Result] Result based on exit code
-        def handle_exit_code(exit_code, stdout, stderr, event)
-          case exit_code
-          when 0
-            # Success - continue execution
-            # For user_prompt and swarm_start: return stdout to be shown to agent
-            if [:user_prompt, :swarm_start].include?(event) && !stdout.strip.empty?
-              # Return Result with stdout that will be appended to prompt
-              Result.replace(stdout.strip)
-            else
-              # Normal success
-              Result.continue
-            end
-          when 2
-            # Blocking error - behavior depends on event type
-            handle_exit_code_2(event, stdout, stderr)
-          else
-            # Non-blocking error - continue (stderr logged above)
-            Result.continue
-          end
-        end
-
-        # Handle exit code 2 (blocking error)
-        #
-        # @param event [Symbol] Hook event type
-        # @param _stdout [String] Standard output (unused)
-        # @param stderr [String] Standard error
-        # @return [Result] Result based on event type
-        def handle_exit_code_2(event, _stdout, stderr)
-          error_msg = stderr.strip
-
-          case event
-          when :pre_tool_use
-            # Block tool call, show stderr to agent (stderr already logged above)
-            Result.halt(error_msg)
-          when :post_tool_use
-            # Tool already ran, show stderr to agent (stderr already logged above)
-            Result.halt(error_msg)
-          when :user_prompt
-            # Block prompt processing, erase prompt
-            # stderr is logged (above) for user to see, but NOT shown to agent
-            # Return empty halt (prompt is erased, no message to agent)
-            Result.halt("")
-          when :agent_stop
-            # Block stoppage, show stderr to agent (stderr already logged above)
-            Result.halt(error_msg)
-          when :context_warning, :swarm_start, :swarm_stop
-            # N/A - stderr logged above, don't halt
-            Result.continue
-          else
-            # Default: halt with stderr
-            Result.halt(error_msg)
-          end
-        end
-
-        # Emit hook execution log entry
-        #
-        # @param event [Symbol] Hook event type
-        # @param agent_name [String, Symbol, nil] Agent name
-        # @param command [String] Shell command executed
-        # @param exit_code [Integer, nil] Process exit code
-        # @param success [Boolean] Whether execution succeeded
-        # @param stdout [String, nil] Standard output
-        # @param stderr [String, nil] Standard error
-        # @param blocked [Boolean] Whether execution was blocked (exit code 2)
-        def emit_hook_log(event:, agent_name:, command:, exit_code:, success:, stdout: nil, stderr: nil, blocked: false)
-          # Only emit if LogStream is enabled (has emitter)
-          return unless LogStream.enabled?
-
-          log_entry = {
-            type: "hook_executed",
-            hook_event: event&.to_s, # Which hook event triggered this (pre_tool_use, swarm_start, etc.)
-            agent: agent_name,
-            command: command,
-            exit_code: exit_code,
-            success: success,
-          }
-
-          # Add stdout if present (exit code 0)
-          log_entry[:stdout] = stdout.strip if stdout && !stdout.strip.empty?
-
-          # Add stderr if present (any exit code)
-          log_entry[:stderr] = stderr.strip if stderr && !stderr.strip.empty?
-
-          # Add blocked flag for exit code 2
-          log_entry[:blocked] = true if blocked
-
-          LogStream.emit(**log_entry)
-        end
-      end
-    end
-  end
-end