claude_swarm 1.0.9 → 1.0.11

data/lib/swarm_sdk/models.rb

@@ -18,16 +18,57 @@ module SwarmSDK
     MODELS_JSON_PATH = File.expand_path("models.json", __dir__)
     ALIASES_JSON_PATH = File.expand_path("model_aliases.json", __dir__)
 
+    # Model information wrapper providing method access to model data
+    #
+    # Wraps the raw Hash from models.json to provide RubyLLM::Model::Info-like
+    # interface for compatibility with code expecting method access.
+    #
+    # @example
+    #   model = SwarmSDK::Models.find("claude-sonnet-4-5-20250929")
+    #   model.context_window  #=> 200000
+    #   model.id              #=> "claude-sonnet-4-5-20250929"
+    class ModelInfo
+      attr_reader :id,
+        :name,
+        :provider,
+        :family,
+        :context_window,
+        :max_output_tokens,
+        :knowledge_cutoff,
+        :modalities,
+        :capabilities,
+        :pricing,
+        :metadata
+
+      # Create a ModelInfo from a Hash
+      #
+      # @param data [Hash] Model data from models.json
+      def initialize(data)
+        @id = data["id"] || data[:id]
+        @name = data["name"] || data[:name]
+        @provider = data["provider"] || data[:provider]
+        @family = data["family"] || data[:family]
+        @context_window = data["context_window"] || data[:context_window]
+        @max_output_tokens = data["max_output_tokens"] || data[:max_output_tokens]
+        @knowledge_cutoff = data["knowledge_cutoff"] || data[:knowledge_cutoff]
+        @modalities = data["modalities"] || data[:modalities]
+        @capabilities = data["capabilities"] || data[:capabilities]
+        @pricing = data["pricing"] || data[:pricing]
+        @metadata = data["metadata"] || data[:metadata]
+      end
+    end
+
     class << self
       # Find a model by ID or alias
       #
       # @param model_id [String] Model ID or alias to find
-      # @return [Hash, nil] Model data or nil if not found
+      # @return [ModelInfo, nil] Model info or nil if not found
       def find(model_id)
         # Check if it's an alias first
         resolved_id = resolve_alias(model_id)
 
-        all.find { |m| m["id"] == resolved_id || m[:id] == resolved_id }
+        model_hash = all.find { |m| m["id"] == resolved_id || m[:id] == resolved_id }
+        model_hash ? ModelInfo.new(model_hash) : nil
       end
 
       # Resolve a model alias to full model ID

data/lib/swarm_sdk/node_context.rb

@@ -168,7 +168,7 @@ module SwarmSDK
     end
 
     # Control flow methods for transformers
-    # These return special hashes that NodeOrchestrator recognizes
+    # These return special hashes that Workflow recognizes
 
     # Skip current node's LLM execution and return content immediately
     #

data/lib/swarm_sdk/observer/builder.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Observer
+    # DSL for configuring observer agents
+    #
+    # Used by Swarm::Builder#observer to provide a clean DSL for defining
+    # event handlers and observer configuration options.
+    #
+    # @example Basic usage
+    #   observer :profiler do
+    #     on :swarm_start do |event|
+    #       "Analyze this prompt: #{event[:prompt]}"
+    #     end
+    #
+    #     timeout 120
+    #     max_concurrent 2
+    #   end
+    class Builder
+      # Initialize builder with agent name and config
+      #
+      # @param agent_name [Symbol] Name of the observer agent
+      # @param config [Observer::Config] Configuration object to populate
+      def initialize(agent_name, config)
+        @agent_name = agent_name
+        @config = config
+      end
+
+      # Register an event handler
+      #
+      # The block receives the event hash and should return:
+      # - A prompt string to trigger the observer agent
+      # - nil to skip execution for this event
+      #
+      # @param event_type [Symbol] Type of event to handle (e.g., :swarm_start, :tool_call)
+      # @yield [Hash] Event hash
+      # @yieldreturn [String, nil] Prompt or nil to skip
+      # @return [void]
+      #
+      # @example
+      #   on :tool_call do |event|
+      #     next unless event[:tool_name] == "Bash"
+      #     "Check this command: #{event[:arguments][:command]}"
+      #   end
+      def on(event_type, &block)
+        @config.add_handler(event_type, &block)
+      end
+
+      # Set maximum concurrent executions for this observer
+      #
+      # Limits how many instances of this observer agent can run simultaneously.
+      # Useful for resource-intensive observers.
+      #
+      # @param n [Integer] Maximum concurrent executions
+      # @return [void]
+      def max_concurrent(n)
+        @config.options[:max_concurrent] = n
+      end
+
+      # Set timeout for observer execution
+      #
+      # Observer tasks will be cancelled after this duration.
+      #
+      # @param seconds [Integer] Timeout in seconds (default: 60)
+      # @return [void]
+      def timeout(seconds)
+        @config.options[:timeout] = seconds
+      end
+
+      # Wait for observer to complete before swarm execution ends
+      #
+      # By default, observers are fire-and-forget. This option causes
+      # the main execution to wait for this observer to complete.
+      #
+      # @return [void]
+      def wait_for_completion!
+        @config.options[:fire_and_forget] = false
+      end
+    end
+  end
+end

data/lib/swarm_sdk/observer/config.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Observer
+    # Configuration for an observer agent
+    #
+    # Holds the agent name, event handlers (blocks that return prompts or nil),
+    # and execution options.
+    #
+    # @example
+    #   config = Observer::Config.new(:profiler)
+    #   config.add_handler(:swarm_start) { |event| "Analyze: #{event[:prompt]}" }
+    #   config.options[:timeout] = 120
+    class Config
+      attr_reader :agent_name, :event_handlers, :options
+
+      # Initialize a new observer configuration
+      #
+      # @param agent_name [Symbol] Name of the agent to use as observer
+      def initialize(agent_name)
+        @agent_name = agent_name
+        @event_handlers = {} # { event_type => block }
+        @options = {
+          max_concurrent: nil,
+          timeout: 60,
+          fire_and_forget: true,
+        }
+      end
+
+      # Add an event handler for a specific event type
+      #
+      # The block receives the event hash and should return:
+      # - A prompt string to trigger the observer agent
+      # - nil to skip execution for this event
+      #
+      # @param event_type [Symbol] Type of event to handle (e.g., :swarm_start, :tool_call)
+      # @yield [Hash] Event hash with type, agent, and other data
+      # @yieldreturn [String, nil] Prompt to execute or nil to skip
+      # @return [void]
+      def add_handler(event_type, &block)
+        @event_handlers[event_type] = block
+      end
+    end
+  end
+end

data/lib/swarm_sdk/observer/manager.rb

@@ -0,0 +1,236 @@
+# 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
+
+      # 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

@@ -0,0 +1,160 @@
+# 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