swarm_sdk 2.2.0 → 2.4.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/adapter.rb

@@ -167,7 +167,7 @@ module SwarmSDK
         def create_hook_callback(hook_def, event_symbol, agent_name, swarm_name)
           # Support both string and symbol keys (YAML may be symbolized)
           command = hook_def[:command] || hook_def["command"]
-          timeout = hook_def[:timeout] || hook_def["timeout"] || ShellExecutor::DEFAULT_TIMEOUT
+          timeout = hook_def[:timeout] || hook_def["timeout"] || SwarmSDK.config.hook_shell_timeout
 
           lambda do |context|
             input_json = build_input_json(context, event_symbol, agent_name)
@@ -191,7 +191,7 @@ module SwarmSDK
         def create_all_agents_hook_callback(hook_def, event_symbol, swarm_name)
           # Support both string and symbol keys (YAML may be symbolized)
           command = hook_def[:command] || hook_def["command"]
-          timeout = hook_def[:timeout] || hook_def["timeout"] || ShellExecutor::DEFAULT_TIMEOUT
+          timeout = hook_def[:timeout] || hook_def["timeout"] || SwarmSDK.config.hook_shell_timeout
 
           lambda do |context|
             # Agent name comes from context
@@ -217,7 +217,7 @@ module SwarmSDK
         def create_swarm_hook_callback(hook_def, event_symbol, swarm_name)
           # Support both string and symbol keys (YAML may be symbolized)
           command = hook_def[:command] || hook_def["command"]
-          timeout = hook_def[:timeout] || hook_def["timeout"] || ShellExecutor::DEFAULT_TIMEOUT
+          timeout = hook_def[:timeout] || hook_def["timeout"] || SwarmSDK.config.hook_shell_timeout
 
           lambda do |context|
             input_json = build_swarm_input_json(context, event_symbol, swarm_name)

data/lib/swarm_sdk/hooks/shell_executor.rb

@@ -47,7 +47,7 @@ module SwarmSDK
     #   )
     #   # => Result (continue or halt based on exit code)
     class ShellExecutor
-      DEFAULT_TIMEOUT = 60
+      # NOTE: Timeout now accessed via SwarmSDK.config.hook_shell_timeout
 
       class << self
         # Execute a shell command hook
@@ -59,7 +59,9 @@ module SwarmSDK
         # @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: DEFAULT_TIMEOUT, agent_name: nil, swarm_name: nil, event: nil)
+        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)
 

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