swarm_sdk 2.2.0 → 2.3.0

data/lib/swarm_sdk/events_to_messages.rb

@@ -44,6 +44,7 @@ module SwarmSDK
   # - `agent_step`: Reconstructs assistant message with tool calls
   # - `agent_stop`: Reconstructs final assistant message
   # - `tool_result`: Reconstructs tool result message
+  # - `delegation_result`: Reconstructs tool result message from delegation
   class EventsToMessages
     class << self
       # Reconstruct messages for an agent from event stream
@@ -90,6 +91,8 @@ module SwarmSDK
           reconstruct_assistant_message(event)
         when "tool_result"
           reconstruct_tool_result_message(event)
+        when "delegation_result"
+          reconstruct_delegation_result_message(event)
         end
 
         messages << message if message
@@ -158,6 +161,21 @@ module SwarmSDK
       )
     end
 
+    # Reconstruct tool result message from delegation_result event
+    #
+    # delegation_result events are emitted when a delegation completes,
+    # and they should be converted to tool result messages in the conversation.
+    #
+    # @param event [Hash] delegation_result event
+    # @return [RubyLLM::Message] Tool result message
+    def reconstruct_delegation_result_message(event)
+      RubyLLM::Message.new(
+        role: :tool,
+        content: event[:result].to_s,
+        tool_call_id: event[:tool_call_id],
+      )
+    end
+
     # Parse timestamp string to Time object
     #
     # @param timestamp [String, nil] ISO 8601 timestamp

data/lib/swarm_sdk/hooks/shell_executor.rb

@@ -47,7 +47,8 @@ module SwarmSDK
     #   )
     #   # => Result (continue or halt based on exit code)
     class ShellExecutor
-      DEFAULT_TIMEOUT = 60
+      # Backward compatibility alias - use Defaults module for new code
+      DEFAULT_TIMEOUT = Defaults::Timeouts::HOOK_SHELL_SECONDS
 
       class << self
         # Execute a shell command hook

data/lib/swarm_sdk/log_collector.rb

@@ -1,76 +1,226 @@
 # frozen_string_literal: true
 
 module SwarmSDK
-  # LogCollector manages subscriber callbacks for log events.
+  # LogCollector manages subscriber callbacks for log events with filtering support.
   #
   # This module acts as an emitter implementation that forwards events
   # to user-registered callbacks. It's designed to be set as the LogStream
   # emitter during swarm execution.
   #
+  # ## Features
+  #
+  # - **Filtered Subscriptions**: Subscribe to specific agents, event types, or swarm IDs
+  # - **Unsubscribe Support**: Remove subscriptions by ID to prevent memory leaks
+  # - **Error Isolation**: One subscriber's error doesn't break others
+  # - **Thread Safety**: Fiber-local storage for multi-threaded environments
+  #
   # ## Thread Safety for Multi-Threaded Environments (Puma, Sidekiq)
   #
-  # Callbacks are stored in Fiber-local storage (Fiber[:log_callbacks]) instead
+  # Subscriptions are stored in Fiber-local storage (Fiber[:log_subscriptions]) instead
   # of class instance variables. This ensures callbacks registered in the parent
   # thread/fiber are accessible to child fibers created by Async reactor.
   #
-  # Why: In Puma/Sidekiq, class instance variables (@callbacks) are thread-isolated
+  # Why: In Puma/Sidekiq, class instance variables (@subscriptions) are thread-isolated
   # and don't properly propagate to child fibers. Using Fiber-local storage ensures
-  # events emitted from within Async blocks can reach registered callbacks.
+  # events emitted from within Async blocks can reach registered subscriptions.
   #
   # Child fibers inherit parent fiber-local storage automatically, so events
   # emitted from agent callbacks (on_tool_call, on_end_message, etc.) executing
-  # in child fibers can still reach the parent's registered callbacks.
+  # in child fibers can still reach the parent's registered subscriptions.
   #
   # ## Usage
   #
-  #   # Register a callback (before execution starts)
-  #   LogCollector.on_log do |event|
-  #     puts JSON.generate(event)
-  #   end
+  #   # Subscribe to all events
+  #   sub_id = LogCollector.subscribe { |event| puts event }
+  #
+  #   # Subscribe to specific agent
+  #   sub_id = LogCollector.subscribe(filter: { agent: :backend }) { |event|
+  #     puts "Backend: #{event}"
+  #   }
   #
-  #   # During execution, LogStream calls emit
-  #   LogCollector.emit(type: "user_prompt", agent: :backend)
+  #   # Subscribe to specific event types
+  #   sub_id = LogCollector.subscribe(filter: { type: ["tool_call", "tool_result"] }) { |event|
+  #     log_tool_activity(event)
+  #   }
+  #
+  #   # Subscribe with regex matching
+  #   sub_id = LogCollector.subscribe(filter: { type: /^tool_/ }) { |event|
+  #     track_tool_usage(event)
+  #   }
+  #
+  #   # Unsubscribe when done
+  #   LogCollector.unsubscribe(sub_id)
   #
   #   # After execution, reset for next use
   #   LogCollector.reset!
   #
   module LogCollector
+    # Subscription object with filtering capabilities
+    #
+    # Encapsulates a callback with optional filters. Filters can match
+    # against agent name, event type, swarm_id, or any event field.
+    class Subscription
+      attr_reader :id, :filter, :callback
+
+      # Initialize a subscription
+      #
+      # @param filter [Hash] Filter criteria
+      # @param callback [Proc] Block to call when event matches
+      def initialize(filter: {}, &callback)
+        @id = SecureRandom.uuid
+        @filter = normalize_filter(filter)
+        @callback = callback
+      end
+
+      # Check if event matches filter criteria
+      #
+      # Empty filter matches all events. Multiple filter keys are AND'd together.
+      #
+      # @param event [Hash] Event entry with :type, :agent, etc.
+      # @return [Boolean] True if event matches filter
+      def matches?(event)
+        return true if @filter.empty?
+
+        @filter.all? do |key, matcher|
+          value = event[key]
+          case matcher
+          when Array
+            # Match if value is in array (handles symbols/strings)
+            matcher.include?(value) || matcher.map(&:to_s).include?(value.to_s)
+          when Regexp
+            # Regex matching
+            value.to_s.match?(matcher)
+          when Proc
+            # Custom matcher
+            matcher.call(value)
+          else
+            # Exact match (handles symbols/strings)
+            matcher == value || matcher.to_s == value.to_s
+          end
+        end
+      end
+
+      private
+
+      # Normalize filter keys to symbols for consistent matching
+      #
+      # @param filter [Hash] Raw filter
+      # @return [Hash] Normalized filter with symbol keys
+      def normalize_filter(filter)
+        filter.transform_keys(&:to_sym)
+      end
+    end
+
     class << self
-      # Register a callback to receive log events
+      # Subscribe to log events with optional filtering
       #
-      # Stores callback in Fiber-local storage to ensure accessibility
-      # from child fibers in multi-threaded environments.
+      # Registers a callback that will receive events matching the filter criteria.
+      # Returns a subscription ID that can be used to unsubscribe later.
       #
+      # @param filter [Hash] Filter criteria (empty = all events)
+      #   - :agent [Symbol, String, Array, Regexp] Agent name(s) to observe
+      #   - :type [String, Array, Regexp] Event type(s) to receive
+      #   - :swarm_id [String] Specific swarm instance
+      #   - Any other key matches against event fields
       # @yield [Hash] Log event entry
-      def on_log(&block)
-        Fiber[:log_callbacks] ||= []
-        Fiber[:log_callbacks] << block
+      # @return [String] Subscription ID for unsubscribe
+      #
+      # @example Subscribe to all events
+      #   LogCollector.subscribe { |event| puts event }
+      #
+      # @example Subscribe to specific agent's tool calls
+      #   sub_id = LogCollector.subscribe(
+      #     filter: { agent: :backend, type: /^tool_/ }
+      #   ) do |event|
+      #     puts "Backend used tool: #{event[:tool]}"
+      #   end
+      #
+      # @example Subscribe to multiple agents
+      #   LogCollector.subscribe(
+      #     filter: { agent: [:backend, :frontend], type: "agent_stop" }
+      #   ) { |e| record_completion(e) }
+      def subscribe(filter: {}, &block)
+        subscription = Subscription.new(filter: filter, &block)
+        subscriptions << subscription
+        subscription.id
       end
 
-      # Emit an event to all registered callbacks
+      # Unsubscribe by ID
+      #
+      # Removes a subscription to prevent memory leaks and stop receiving events.
+      #
+      # @param subscription_id [String] ID returned from subscribe
+      # @return [Subscription, nil] Removed subscription or nil if not found
+      def unsubscribe(subscription_id)
+        index = subscriptions.find_index { |s| s.id == subscription_id }
+        return unless index
+
+        subscriptions.delete_at(index)
+      end
+
+      # Clear all subscriptions
+      #
+      # Removes all subscriptions. Useful for testing or execution cleanup.
+      #
+      # @return [void]
+      def clear_subscriptions
+        subscriptions.clear
+      end
+
+      # Get current subscription count
+      #
+      # @return [Integer] Number of active subscriptions
+      def subscription_count
+        subscriptions.size
+      end
+
+      # Emit an event to all matching subscribers
       #
       # Automatically adds a timestamp if one doesn't exist.
-      # Reads callbacks from Fiber-local storage to support multi-threaded execution.
+      # Errors in individual subscribers are isolated - one bad subscriber
+      # won't prevent others from receiving events.
       #
       # @param entry [Hash] Log event entry
       # @return [void]
       def emit(entry)
-        # Ensure timestamp exists (LogStream adds it, but direct calls might not)
-        # Use microsecond precision (6 digits) for proper event ordering
-        entry_with_timestamp = entry.key?(:timestamp) ? entry : entry.merge(timestamp: Time.now.utc.iso8601(6))
-
-        # Read callbacks from Fiber-local storage (set by on_log in parent fiber)
-        callbacks = Fiber[:log_callbacks] || []
-        callbacks.each do |callback|
-          callback.call(entry_with_timestamp)
+        entry_with_timestamp = ensure_timestamp(entry)
+
+        subscriptions.each do |subscription|
+          next unless subscription.matches?(entry_with_timestamp)
+
+          begin
+            subscription.callback.call(entry_with_timestamp)
+          rescue StandardError => e
+            # Error isolation - don't let one subscriber break others
+            RubyLLM.logger.error("SwarmSDK: Subscription #{subscription.id} error: #{e.message}")
+          end
         end
       end
 
-      # Reset the collector (clears callbacks for next execution)
+      # Reset the collector (clears subscriptions for next execution)
       #
       # @return [void]
       def reset!
-        Fiber[:log_callbacks] = []
+        Fiber[:log_subscriptions] = []
+      end
+
+      private
+
+      # Get subscriptions from Fiber-local storage
+      #
+      # @return [Array<Subscription>] Current subscriptions
+      def subscriptions
+        Fiber[:log_subscriptions] ||= []
+      end
+
+      # Ensure event has a timestamp
+      #
+      # @param entry [Hash] Event entry
+      # @return [Hash] Entry with timestamp
+      def ensure_timestamp(entry)
+        return entry if entry.key?(:timestamp)
+
+        entry.merge(timestamp: Time.now.utc.iso8601(6))
       end
     end
   end

data/lib/swarm_sdk/log_stream.rb

@@ -93,6 +93,35 @@ module SwarmSDK
       def enabled?
         !Fiber[:log_stream_emitter].nil?
       end
+
+      # Emit an internal error event
+      #
+      # Provides consistent error event emission for all internal errors.
+      # These are errors that occur during execution but are handled gracefully
+      # (with fallback behavior) rather than causing failures.
+      #
+      # @param error [Exception] The caught exception
+      # @param source [String] Source module/class (e.g., "hook_triggers", "context_compactor")
+      # @param context [String] Specific operation context (e.g., "swarm_stop", "summarization")
+      # @param agent [Symbol, String, nil] Agent name if applicable
+      # @param metadata [Hash] Additional context data
+      # @return [void]
+      def emit_error(error, source:, context:, agent: nil, **metadata)
+        emit(
+          type: "internal_error",
+          source: source,
+          context: context,
+          agent: agent,
+          error_class: error.class.name,
+          error_message: error.message,
+          backtrace: error.backtrace&.first(5),
+          **metadata,
+        )
+      rescue StandardError
+        # Absolute fallback - if emit_error itself fails, don't break execution
+        # This should never happen, but we must be defensive
+        nil
+      end
     end
   end
 end

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