swarm_sdk 2.7.14 → 3.0.0.alpha2

data/lib/swarm_sdk/observer/manager.rb

@@ -1,248 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  module Observer
-    # Manages observer agent executions
-    #
-    # Handles:
-    # - Event subscription via LogCollector
-    # - Spawning async tasks for observer agents
-    # - Self-consumption protection (observers don't trigger themselves)
-    # - Task lifecycle and cleanup
-    #
-    # @example
-    #   manager = Observer::Manager.new(swarm)
-    #   manager.add_config(profiler_config)
-    #   manager.setup
-    #   # ... main execution happens ...
-    #   manager.wait_for_completion
-    #   manager.cleanup
-    class Manager
-      # Initialize manager with swarm reference
-      #
-      # @param swarm [Swarm] Parent swarm instance
-      def initialize(swarm)
-        @swarm = swarm
-        @configs = []
-        @subscription_ids = []
-        @barrier = nil
-        @task_ids = {}
-      end
-
-      # Add an observer configuration
-      #
-      # @param config [Observer::Config] Observer configuration
-      # @return [void]
-      def add_config(config)
-        @configs << config
-      end
-
-      # Setup event subscriptions for all observer configs
-      #
-      # Creates LogCollector subscriptions for each event type, filtered by type.
-      # Must be called after setup_logging() in Swarm.execute().
-      #
-      # @return [void]
-      def setup
-        @barrier = Async::Barrier.new
-
-        @configs.each do |config|
-          config.event_handlers.each do |event_type, handler|
-            sub_id = LogCollector.subscribe(filter: { type: event_type.to_s }) do |event|
-              handle_event(config, handler, event)
-            end
-            @subscription_ids << sub_id
-          end
-        end
-      end
-
-      # Wait for all observer tasks to complete
-      #
-      # Uses Async::Barrier.wait to wait for all spawned tasks.
-      # Handles errors gracefully without stopping other observers.
-      #
-      # @return [void]
-      def wait_for_completion
-        return unless @barrier
-
-        # Wait for all tasks, handling errors gracefully
-        # Barrier.wait re-raises first exception by default, so we use block form
-        @barrier.wait do |task|
-          task.wait
-        rescue StandardError => error
-          # Log but don't stop waiting for other observers
-          RubyLLM.logger.error("Observer task failed: #{error.message}")
-        end
-      end
-
-      # Stop all observer tasks immediately
-      #
-      # Interrupts in-flight observer LLM calls by stopping the barrier.
-      # Called during swarm interruption instead of wait_for_completion.
-      #
-      # @return [void]
-      def stop
-        @barrier&.stop
-      rescue StandardError => e
-        RubyLLM.logger.debug("SwarmSDK: Error stopping observer barrier: #{e.message}")
-      end
-
-      # Cleanup all subscriptions
-      #
-      # Unsubscribes from LogCollector to prevent memory leaks.
-      # Called by Executor.cleanup_after_execution.
-      #
-      # @return [void]
-      def cleanup
-        @subscription_ids.each { |id| LogCollector.unsubscribe(id) }
-        @subscription_ids.clear
-      end
-
-      private
-
-      # Handle an incoming event
-      #
-      # Checks self-consumption protection, calls handler block,
-      # and spawns execution if handler returns a prompt.
-      #
-      # @param config [Observer::Config] Observer configuration
-      # @param handler [Proc] Event handler block
-      # @param event [Hash] Event data
-      # @return [void]
-      def handle_event(config, handler, event)
-        # CRITICAL: Prevent self-consumption - observer must not consume its own events
-        # This prevents infinite loops where an observer triggers itself
-        return if event[:agent] == config.agent_name
-
-        prompt = handler.call(event)
-        return unless prompt # nil means skip
-
-        spawn_execution(config, prompt, event)
-      end
-
-      # Spawn an async task for observer execution
-      #
-      # Creates a child async task via barrier for the observer agent.
-      # Sets observer-specific Fiber context.
-      #
-      # @param config [Observer::Config] Observer configuration
-      # @param prompt [String] Prompt to send to observer agent
-      # @param trigger_event [Hash] Event that triggered this execution
-      # @return [void]
-      def spawn_execution(config, prompt, trigger_event)
-        @barrier.async do
-          # Set observer-specific context in child fiber
-          # No need to restore - child fiber dies when task completes
-          Fiber[:swarm_id] = "#{Fiber[:swarm_id]}/observer:#{config.agent_name}"
-
-          execute_observer_agent(config, prompt, trigger_event)
-        end
-      end
-
-      # Execute the observer agent with the prompt
-      #
-      # Creates an isolated chat instance and sends the prompt.
-      # Emits lifecycle events (start, complete, error).
-      #
-      # @param config [Observer::Config] Observer configuration
-      # @param prompt [String] Prompt to execute
-      # @param trigger_event [Hash] Event that triggered this execution
-      # @return [RubyLLM::Message, nil] Response or nil on error
-      def execute_observer_agent(config, prompt, trigger_event)
-        agent_chat = create_isolated_chat(config.agent_name)
-
-        start_time = Time.now
-        emit_observer_start(config, trigger_event)
-
-        result = agent_chat.ask(prompt)
-
-        emit_observer_complete(config, trigger_event, result, Time.now - start_time)
-        result
-      rescue StandardError => e
-        emit_observer_error(config, trigger_event, e)
-        nil
-      end
-
-      # Create an isolated chat instance for the observer agent
-      #
-      # Uses AgentInitializer to create a fully configured agent chat
-      # without delegation tools (observers don't delegate).
-      #
-      # @param agent_name [Symbol] Name of the observer agent
-      # @return [Agent::Chat] Isolated chat instance
-      def create_isolated_chat(agent_name)
-        initializer = Swarm::AgentInitializer.new(@swarm)
-        initializer.initialize_isolated_agent(agent_name)
-      end
-
-      # Emit observer_agent_start event
-      #
-      # @param config [Observer::Config] Observer configuration
-      # @param trigger_event [Hash] Triggering event
-      # @return [void]
-      def emit_observer_start(config, trigger_event)
-        return unless LogStream.emitter
-
-        LogStream.emit(
-          type: "observer_agent_start",
-          agent: config.agent_name,
-          trigger_event: trigger_event[:type],
-          trigger_timestamp: trigger_event[:timestamp],
-          task_id: generate_task_id(config),
-          timestamp: Time.now.utc.iso8601,
-        )
-      end
-
-      # Emit observer_agent_complete event
-      #
-      # @param config [Observer::Config] Observer configuration
-      # @param trigger_event [Hash] Triggering event
-      # @param result [RubyLLM::Message] Agent response
-      # @param duration [Float] Execution duration in seconds
-      # @return [void]
-      def emit_observer_complete(config, trigger_event, result, duration)
-        return unless LogStream.emitter
-
-        LogStream.emit(
-          type: "observer_agent_complete",
-          agent: config.agent_name,
-          trigger_event: trigger_event[:type],
-          task_id: generate_task_id(config),
-          duration: duration.round(3),
-          success: true,
-          timestamp: Time.now.utc.iso8601,
-        )
-      end
-
-      # Emit observer_agent_error event
-      #
-      # @param config [Observer::Config] Observer configuration
-      # @param trigger_event [Hash] Triggering event
-      # @param error [StandardError] Error that occurred
-      # @return [void]
-      def emit_observer_error(config, trigger_event, error)
-        return unless LogStream.emitter
-
-        LogStream.emit(
-          type: "observer_agent_error",
-          agent: config.agent_name,
-          trigger_event: trigger_event[:type],
-          task_id: generate_task_id(config),
-          error: error.message,
-          backtrace: error.backtrace&.first(5),
-          timestamp: Time.now.utc.iso8601,
-        )
-      end
-
-      # Generate a unique task ID for an observer
-      #
-      # Cached per observer agent name for correlation.
-      #
-      # @param config [Observer::Config] Observer configuration
-      # @return [String] Task ID
-      def generate_task_id(config)
-        @task_ids[config.agent_name] ||= "observer_#{SecureRandom.hex(6)}"
-      end
-    end
-  end
-end

data/lib/swarm_sdk/patterns/agent_observer.rb

@@ -1,160 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  module Patterns
-    # Observes another agent's actions with optional real-time processing
-    #
-    # @example Basic observation
-    #   observer = AgentObserver.new(target: :backend)
-    #   observer.start
-    #   swarm.execute("task")
-    #   observer.stop
-    #   puts observer.observations
-    #
-    # @example Real-time analysis
-    #   observer = AgentObserver.new(
-    #     target: :backend,
-    #     on_event: ->(e) { analyze_security(e) }
-    #   )
-    #
-    # @example Filter specific event types
-    #   observer = AgentObserver.new(
-    #     target: :backend,
-    #     event_types: ["tool_call", "tool_result"]
-    #   )
-    class AgentObserver
-      attr_reader :observations, :target_agent
-
-      # Initialize observer
-      #
-      # @param target [Symbol] Agent to observe
-      # @param event_types [Array<String>] Event types to capture (default: all)
-      # @param on_event [Proc] Optional callback for real-time processing
-      def initialize(target:, event_types: nil, on_event: nil)
-        @target_agent = target
-        @event_types = event_types
-        @on_event = on_event
-        @observations = []
-        @subscription_id = nil
-        @started_at = nil
-      end
-
-      # Start observing
-      #
-      # @return [void]
-      def start
-        return if @subscription_id
-
-        @started_at = Time.now
-        @observations.clear
-
-        filter = { agent: @target_agent }
-        filter[:type] = @event_types if @event_types
-
-        @subscription_id = LogCollector.subscribe(filter: filter) do |event|
-          @observations << event.merge(observed_at: Time.now)
-          @on_event&.call(event)
-        end
-      end
-
-      # Stop observing
-      #
-      # @return [void]
-      def stop
-        return unless @subscription_id
-
-        LogCollector.unsubscribe(@subscription_id)
-        @subscription_id = nil
-      end
-
-      # Check if currently observing
-      #
-      # @return [Boolean] true if actively observing
-      def observing?
-        !@subscription_id.nil?
-      end
-
-      # Get summary of observations
-      #
-      # @return [Hash] Summary statistics
-      def summary
-        {
-          target: @target_agent,
-          started_at: @started_at,
-          duration_seconds: @started_at ? (Time.now - @started_at).round(2) : 0,
-          total_events: @observations.size,
-          event_breakdown: @observations.group_by { |e| e[:type] }.transform_values(&:count),
-          tool_calls: @observations.select { |e| e[:type] == "tool_call" }.map { |e| e[:tool_name] },
-          errors: @observations.select { |e| e[:type] == "internal_error" },
-        }
-      end
-
-      # Format observations for LLM consumption
-      #
-      # Useful for providing observation data to another agent for analysis
-      #
-      # @return [String] Formatted observation log
-      def to_llm_context
-        @observations.map do |event|
-          case event[:type]
-          when "tool_call"
-            "- Called #{event[:tool_name]} with: #{truncate_json(event[:arguments])}"
-          when "tool_result"
-            "- #{event[:tool_name]} returned: #{truncate(event[:result])}"
-          when "agent_step"
-            "- Thinking: #{truncate(event[:content])}"
-          when "agent_stop"
-            "- Final response: #{truncate(event[:content])}"
-          else
-            "- [#{event[:type]}] #{event.except(:type, :timestamp, :observed_at).to_json}"
-          end
-        end.join("\n")
-      end
-
-      # Clear collected observations
-      #
-      # @return [void]
-      def clear_observations
-        @observations.clear
-      end
-
-      # Execute block while observing
-      #
-      # Automatically starts and stops observation around the block
-      #
-      # @example
-      #   observer = AgentObserver.new(target: :backend)
-      #   observer.observe do
-      #     swarm.execute("Build API")
-      #   end
-      #   puts observer.summary
-      #
-      # @yield Block to execute while observing
-      # @return [Object] Result from the block
-      def observe
-        start
-        yield
-      ensure
-        stop
-      end
-
-      private
-
-      def truncate(text, max_length = 200)
-        return "" if text.nil?
-
-        text = text.to_s
-        return text if text.length <= max_length
-
-        "#{text[0...max_length]}..."
-      end
-
-      def truncate_json(obj, max_length = 100)
-        return "{}" if obj.nil?
-
-        json = obj.to_json
-        truncate(json, max_length)
-      end
-    end
-  end
-end

data/lib/swarm_sdk/permissions/config.rb

@@ -1,239 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  module Permissions
-    # Config parses and validates permission configuration for tools
-    #
-    # Handles:
-    # - Allowed path patterns (allowlist)
-    # - Denied path patterns (explicit denylist)
-    # - Allowed command patterns (regex for Bash tool)
-    # - Denied command patterns (regex for Bash tool)
-    # - Relative paths converted to absolute based on agent directory
-    # - Glob pattern matching with absolute paths
-    #
-    # All paths and patterns are converted to absolute:
-    # - Patterns starting with / are kept as-is
-    # - Relative patterns are expanded against the agent's base directory
-    # - Paths starting with / are kept as-is
-    # - Relative paths are expanded against the agent's base directory
-    #
-    # Example:
-    #   config = Config.new(
-    #     {
-    #       allowed_paths: ["tmp/**/*"],
-    #       denied_paths: ["tmp/secrets/**"],
-    #       allowed_commands: ["^git (status|diff|log)$"],
-    #       denied_commands: ["^rm -rf"]
-    #     },
-    #     base_directories: ["/home/user/project"]
-    #   )
-    #   config.allowed?("tmp/file.txt")  # => true (checks /home/user/project/tmp/file.txt)
-    #   config.allowed?("tmp/secrets/key.pem")  # => false (denied takes precedence)
-    #   config.command_allowed?("git status")  # => true
-    #   config.command_allowed?("rm -rf /")  # => false (denied takes precedence)
-    class Config
-      attr_reader :allowed_patterns, :denied_patterns, :allowed_commands, :denied_commands
-
-      # Initialize permission configuration
-      #
-      # @param config_hash [Hash] Permission configuration with :allowed_paths, :denied_paths, :allowed_commands, :denied_commands
-      # @param base_directory [String] Base directory for the agent
-      def initialize(config_hash, base_directory:)
-        # Use agent's directory as the base for path resolution
-        @base_directory = File.expand_path(base_directory)
-
-        # Expand all patterns to absolute paths
-        @allowed_patterns = expand_patterns(config_hash[:allowed_paths] || [])
-        @denied_patterns = expand_patterns(config_hash[:denied_paths] || [])
-
-        # Parse command patterns (regex strings)
-        @allowed_commands = compile_regex_patterns(config_hash[:allowed_commands] || [])
-        @denied_commands = compile_regex_patterns(config_hash[:denied_commands] || [])
-      end
-
-      # Check if a path is allowed according to this configuration
-      #
-      # Rules:
-      # 1. Denied patterns take precedence and always block
-      # 2. If allowed_paths specified: must match at least one pattern (allowlist)
-      # 3. If allowed_paths NOT specified: allow everything (except denied)
-      # 4. All paths are converted to absolute for consistent matching
-      # 5. For directories used as search bases (Glob/Grep), allow if any pattern would match inside
-      #
-      # @param path [String] Path to check (relative or absolute)
-      # @param directory_search [Boolean] True if this is a directory search base (Glob/Grep)
-      # @return [Boolean] True if path is allowed
-      def allowed?(path, directory_search: false)
-        # Convert path to absolute
-        absolute_path = to_absolute_path(path)
-
-        # Denied patterns take precedence - check first
-        return false if matches_any?(@denied_patterns, absolute_path)
-
-        # If no allowed patterns, allow everything (except denied)
-        return true if @allowed_patterns.empty?
-
-        # For directory searches, check if directory is a prefix of any allowed pattern
-        # Don't check if directory exists - allow non-existent directories as search bases
-        if directory_search
-          return true if allowed_as_search_base?(absolute_path)
-        end
-
-        # Must match at least one allowed pattern
-        matches_any?(@allowed_patterns, absolute_path)
-      end
-
-      # Find the specific pattern that denies or doesn't allow a path
-      #
-      # @param path [String] Path to check (relative or absolute)
-      # @param directory_search [Boolean] True if this is a directory search base (Glob/Grep)
-      # @return [String, nil] The pattern that blocks this path, or nil if allowed
-      def find_blocking_pattern(path, directory_search: false)
-        absolute_path = to_absolute_path(path)
-
-        # Check denied patterns first
-        denied_match = @denied_patterns.find { |pattern| PathMatcher.matches?(pattern, absolute_path) }
-        return denied_match if denied_match
-
-        # Check allowed patterns
-        if @allowed_patterns.any?
-          # For directory searches, check if allowed as search base
-          # Don't check if directory exists - allow non-existent directories as search bases
-          if directory_search
-            return if allowed_as_search_base?(absolute_path)
-          end
-
-          # Check if path matches any allowed pattern
-          return if @allowed_patterns.any? { |pattern| PathMatcher.matches?(pattern, absolute_path) }
-
-          # Path doesn't match any allowed pattern
-          return "(not in allowed list)"
-        end
-
-        nil
-      end
-
-      # Convert a path to absolute form
-      #
-      # @param path [String] Path to convert
-      # @return [String] Absolute path
-      def to_absolute(path)
-        to_absolute_path(path)
-      end
-
-      # Check if a command is allowed according to this configuration
-      #
-      # Rules:
-      # 1. Denied command patterns take precedence and always block
-      # 2. If allowed_commands specified: must match at least one pattern (allowlist)
-      # 3. If allowed_commands NOT specified: allow everything (except denied)
-      #
-      # @param command [String] Command to check
-      # @return [Boolean] True if command is allowed
-      def command_allowed?(command)
-        # Denied patterns take precedence - check first
-        return false if matches_any_regex?(@denied_commands, command)
-
-        # If no allowed patterns, allow everything (except denied)
-        return true if @allowed_commands.empty?
-
-        # Must match at least one allowed pattern
-        matches_any_regex?(@allowed_commands, command)
-      end
-
-      # Find the specific pattern that denies or doesn't allow a command
-      #
-      # @param command [String] Command to check
-      # @return [String, nil] The pattern that blocks this command, or nil if allowed
-      def find_blocking_command_pattern(command)
-        # Check denied patterns first
-        denied_match = @denied_commands.find { |pattern| pattern.match?(command) }
-        return denied_match.source if denied_match
-
-        # Check allowed patterns
-        if @allowed_commands.any?
-          # Check if command matches any allowed pattern
-          return if @allowed_commands.any? { |pattern| pattern.match?(command) }
-
-          # Command doesn't match any allowed pattern
-          return "(not in allowed list)"
-        end
-
-        nil
-      end
-
-      private
-
-      # Expand patterns to absolute paths
-      #
-      # Patterns starting with / are kept as-is
-      # Relative patterns are joined with base directory
-      def expand_patterns(patterns)
-        Array(patterns).map do |pattern|
-          if pattern.to_s.start_with?("/")
-            pattern.to_s
-          else
-            File.join(@base_directory, pattern.to_s)
-          end
-        end
-      end
-
-      # Convert path to absolute
-      #
-      # Paths starting with / are kept as-is
-      # Relative paths are expanded against base directory
-      def to_absolute_path(path)
-        if path.start_with?("/")
-          path
-        else
-          File.expand_path(path, @base_directory)
-        end
-      end
-
-      # Check if path matches any pattern in the list
-      def matches_any?(patterns, path)
-        patterns.any? { |pattern| PathMatcher.matches?(pattern, path) }
-      end
-
-      # Check if a directory is allowed as a search base
-      #
-      # A directory is allowed as a search base if any allowed pattern
-      # would match files or directories inside it.
-      #
-      # @param directory_path [String] Absolute path to directory
-      # @return [Boolean] True if directory can be used as search base
-      def allowed_as_search_base?(directory_path)
-        # Normalize directory path (ensure trailing slash for comparison)
-        dir_with_slash = directory_path.end_with?("/") ? directory_path : "#{directory_path}/"
-
-        @allowed_patterns.any? do |pattern|
-          # Check if the pattern starts with this directory
-          # This means files inside this directory would match the pattern
-          pattern.start_with?(dir_with_slash) || pattern == directory_path
-        end
-      end
-
-      # Compile regex patterns from strings
-      #
-      # @param patterns [Array<String>] Array of regex pattern strings
-      # @return [Array<Regexp>] Array of compiled regex objects
-      def compile_regex_patterns(patterns)
-        Array(patterns).map do |pattern|
-          Regexp.new(pattern)
-        rescue RegexpError => e
-          raise ConfigurationError, "Invalid regex pattern '#{pattern}': #{e.message}"
-        end
-      end
-
-      # Check if command matches any regex pattern in the list
-      #
-      # @param patterns [Array<Regexp>] Array of compiled regex patterns
-      # @param command [String] Command to check
-      # @return [Boolean] True if command matches any pattern
-      def matches_any_regex?(patterns, command)
-        patterns.any? { |pattern| pattern.match?(command) }
-      end
-    end
-  end
-end