swarm_memory 2.1.2 → 2.1.4

data/lib/swarm_sdk/events_to_messages.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  # Reconstructs RubyLLM::Message objects from SwarmSDK event streams
+  #
+  # This class enables conversation replay and analysis from event logs.
+  # It uses timestamps to maintain chronological ordering of messages.
+  #
+  # ## Limitations
+  #
+  # This reconstructs ONLY conversation messages. It does NOT restore:
+  # - Context state (warning thresholds, compression, todowrite index)
+  # - Scratchpad contents
+  # - Read tracking information
+  # - Full swarm state
+  #
+  # For full state restoration, use StateSnapshot/StateRestorer or SnapshotFromEvents.
+  #
+  # ## Usage
+  #
+  #   # Collect events during execution
+  #   events = []
+  #   swarm.execute("Build feature") do |event|
+  #     events << event
+  #   end
+  #
+  #   # Reconstruct conversation for an agent
+  #   messages = SwarmSDK::EventsToMessages.reconstruct(events, agent: :backend)
+  #
+  #   # View conversation
+  #   messages.each do |msg|
+  #     puts "[#{msg.role}] #{msg.content}"
+  #   end
+  #
+  # ## Event Requirements
+  #
+  # Events must have:
+  # - `:timestamp` field (ISO 8601 format) for ordering
+  # - `:agent` field to filter by agent
+  # - `:type` field to identify event type
+  #
+  # Supported event types:
+  # - `user_prompt`: Reconstructs user message (prompt in metadata or top-level)
+  # - `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
+      #
+      # @param events [Array<Hash>] Event stream with timestamps
+      # @param agent [Symbol, String] Agent name to reconstruct messages for
+      # @return [Array<RubyLLM::Message>] Reconstructed messages in chronological order
+      #
+      # @example
+      #   messages = EventsToMessages.reconstruct(events, agent: :backend)
+      #   messages.each { |msg| puts msg.content }
+      def reconstruct(events, agent:)
+        new(events, agent).reconstruct
+      end
+    end
+
+    # Initialize reconstructor
+    #
+    # @param events [Array<Hash>] Event stream
+    # @param agent [Symbol, String] Agent name
+    def initialize(events, agent)
+      @events = events
+      @agent = agent.to_sym
+    end
+
+    # Reconstruct messages from events
+    #
+    # Filters events by agent, sorts by timestamp, and converts to RubyLLM::Message objects.
+    #
+    # @return [Array<RubyLLM::Message>] Reconstructed messages
+    def reconstruct
+      messages = []
+
+      # Filter events for this agent and sort by timestamp
+      agent_events = @events
+        .select { |e| normalize_agent(e[:agent]) == @agent }
+        .sort_by { |e| parse_timestamp(e[:timestamp]) }
+
+      agent_events.each do |event|
+        message = case event[:type]&.to_s
+        when "user_prompt"
+          reconstruct_user_message(event)
+        when "agent_step", "agent_stop"
+          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
+      end
+
+      messages
+    end
+
+    private
+
+    # Reconstruct user message from user_prompt event
+    #
+    # Extracts prompt from metadata or top-level field.
+    #
+    # @param event [Hash] user_prompt event
+    # @return [RubyLLM::Message, nil] User message or nil if prompt not found
+    def reconstruct_user_message(event)
+      # Try to extract prompt from metadata (current location) or top-level (potential future location)
+      prompt = event.dig(:metadata, :prompt) || event[:prompt]
+      return unless prompt && !prompt.to_s.empty?
+
+      RubyLLM::Message.new(
+        role: :user,
+        content: prompt,
+      )
+    end
+
+    # Reconstruct assistant message from agent_step or agent_stop event
+    #
+    # Converts tool_calls array to hash format expected by RubyLLM.
+    #
+    # @param event [Hash] agent_step or agent_stop event
+    # @return [RubyLLM::Message] Assistant message
+    def reconstruct_assistant_message(event)
+      # Convert tool_calls array to hash (RubyLLM format)
+      # Events emit tool_calls as Array, but RubyLLM expects Hash<String, ToolCall>
+      tool_calls_hash = if event[:tool_calls] && !event[:tool_calls].empty?
+        event[:tool_calls].each_with_object({}) do |tc, hash|
+          hash[tc[:id].to_s] = RubyLLM::ToolCall.new(
+            id: tc[:id],
+            name: tc[:name],
+            arguments: tc[:arguments] || {},
+          )
+        end
+      end
+
+      RubyLLM::Message.new(
+        role: :assistant,
+        content: event[:content] || "",
+        tool_calls: tool_calls_hash,
+        input_tokens: event.dig(:usage, :input_tokens),
+        output_tokens: event.dig(:usage, :output_tokens),
+        model_id: event[:model],
+      )
+    end
+
+    # Reconstruct tool result message from tool_result event
+    #
+    # @param event [Hash] tool_result event
+    # @return [RubyLLM::Message] Tool result message
+    def reconstruct_tool_result_message(event)
+      RubyLLM::Message.new(
+        role: :tool,
+        content: event[:result].to_s,
+        tool_call_id: event[:tool_call_id],
+      )
+    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
+    # @return [Time] Parsed time or epoch if nil/invalid
+    def parse_timestamp(timestamp)
+      return Time.at(0) unless timestamp
+
+      Time.parse(timestamp)
+    rescue ArgumentError
+      Time.at(0)
+    end
+
+    # Normalize agent name to symbol
+    #
+    # @param agent [Symbol, String, nil] Agent name
+    # @return [Symbol] Normalized agent name
+    def normalize_agent(agent)
+      agent.to_s.to_sym
+    end
+  end
+end

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,50 +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)
+  #
+  # 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 (@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 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 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
+      #
+      # 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)
-        @callbacks ||= []
-        @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
+
+      # 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 registered callbacks
+      # Emit an event to all matching subscribers
+      #
+      # Automatically adds a timestamp if one doesn't exist.
+      # 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)
-        Array(@callbacks).each do |callback|
-          callback.call(entry)
+        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!
-        @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

@@ -16,9 +16,15 @@ module SwarmSDK
   #     message_count: 5
   #   )
   #
-  # ## Fiber Safety
+  # ## Thread Safety
   #
-  # LogStream is fiber-safe when following this pattern:
+  # LogStream is thread-safe and fiber-safe:
+  # - Uses Fiber storage for per-request isolation in multi-threaded servers (Puma, Sidekiq)
+  # - Each thread/request has its own emitter instance
+  # - Child fibers inherit the emitter from their parent fiber
+  # - No cross-thread contamination of log events
+  #
+  # Usage pattern:
   # 1. Set emitter BEFORE starting Async execution
   # 2. During Async execution, only emit() (reads emitter)
   # 3. Each event includes agent context for identification
@@ -35,34 +41,86 @@ module SwarmSDK
       # Emit a log event
       #
       # Adds timestamp and forwards to the registered emitter.
+      # Auto-injects execution_id, swarm_id, and parent_swarm_id from Fiber storage.
+      # Explicit values in data override auto-injected ones.
       #
       # @param data [Hash] Event data (type, agent, and event-specific fields)
       # @return [void]
       def emit(**data)
-        return unless @emitter
+        emitter = Fiber[:log_stream_emitter]
+        return unless emitter
+
+        # Auto-inject execution context from Fiber storage
+        # Explicit values in data override auto-injected ones
+        auto_injected = {
+          execution_id: Fiber[:execution_id],
+          swarm_id: Fiber[:swarm_id],
+          parent_swarm_id: Fiber[:parent_swarm_id],
+        }.compact
 
-        entry = data.merge(timestamp: Time.now.utc.iso8601).compact
+        entry = auto_injected.merge(data).merge(timestamp: Time.now.utc.iso8601(6)).compact
 
-        @emitter.emit(entry)
+        emitter.emit(entry)
       end
 
       # Set the emitter (for dependency injection in tests)
       #
+      # Stores emitter in Fiber storage for thread-safe, per-request isolation.
+      #
       # @param emitter [#emit] Object responding to emit(Hash)
-      attr_accessor :emitter
+      # @return [void]
+      def emitter=(emitter)
+        Fiber[:log_stream_emitter] = emitter
+      end
+
+      # Get the current emitter
+      #
+      # @return [#emit, nil] Current emitter or nil if not set
+      def emitter
+        Fiber[:log_stream_emitter]
+      end
 
       # Reset the emitter (for test cleanup)
       #
       # @return [void]
       def reset!
-        @emitter = nil
+        Fiber[:log_stream_emitter] = nil
       end
 
       # Check if logging is enabled
       #
       # @return [Boolean] true if an emitter is configured
       def enabled?
-        !@emitter.nil?
+        !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

data/lib/swarm_sdk/model_aliases.json

@@ -1,5 +1,8 @@
 {
   "sonnet": "claude-sonnet-4-5-20250929",
   "opus": "claude-opus-4-1-20250805",
-  "haiku": "claude-haiku-4-5-20251001"
+  "haiku": "claude-haiku-4-5-20251001",
+  "claude-sonnet-4-5": "claude-sonnet-4-5-20250929",
+  "claude-opus-4-1": "claude-opus-4-1-20250805",
+  "claude-haiku-4-5": "claude-haiku-4-5-20251001"
 }

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