swarm_sdk 2.1.3 → 2.2.0

data/lib/swarm_sdk/events_to_messages.rb

@@ -0,0 +1,181 @@
+# 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
+  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)
+        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
+
+    # 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/log_collector.rb

@@ -7,6 +7,20 @@ module SwarmSDK
   # to user-registered callbacks. It's designed to be set as the LogStream
   # emitter during swarm execution.
   #
+  # ## Thread Safety for Multi-Threaded Environments (Puma, Sidekiq)
+  #
+  # Callbacks are stored in Fiber-local storage (Fiber[:log_callbacks]) 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
+  # and don't properly propagate to child fibers. Using Fiber-local storage ensures
+  # events emitted from within Async blocks can reach registered callbacks.
+  #
+  # 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.
+  #
   # ## Usage
   #
   #   # Register a callback (before execution starts)
@@ -24,19 +38,31 @@ module SwarmSDK
     class << self
       # Register a callback to receive log events
       #
+      # Stores callback in Fiber-local storage to ensure accessibility
+      # from child fibers in multi-threaded environments.
+      #
       # @yield [Hash] Log event entry
       def on_log(&block)
-        @callbacks ||= []
-        @callbacks << block
+        Fiber[:log_callbacks] ||= []
+        Fiber[:log_callbacks] << block
       end
 
       # Emit an event to all registered callbacks
       #
+      # Automatically adds a timestamp if one doesn't exist.
+      # Reads callbacks from Fiber-local storage to support multi-threaded execution.
+      #
       # @param entry [Hash] Log event entry
       # @return [void]
       def emit(entry)
-        Array(@callbacks).each do |callback|
-          callback.call(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)
         end
       end
 
@@ -44,7 +70,7 @@ module SwarmSDK
       #
       # @return [void]
       def reset!
-        @callbacks = []
+        Fiber[:log_callbacks] = []
       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,57 @@ 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
     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/agent_config.rb

@@ -7,6 +7,7 @@ module SwarmSDK
     # This class enables the chainable syntax:
     #   agent(:backend).delegates_to(:tester, :database)
     #   agent(:backend, reset_context: false)  # Preserve context across nodes
+    #   agent(:backend).tools(:Read, :Edit)    # Override tools for this node
     #
     # @example Basic delegation
     #   agent(:backend).delegates_to(:tester)
@@ -16,6 +17,12 @@ module SwarmSDK
     #
     # @example Preserve agent context
     #   agent(:architect, reset_context: false)
+    #
+    # @example Override tools for this node
+    #   agent(:backend).tools(:Read, :Think)
+    #
+    # @example Combine delegation and tool override
+    #   agent(:backend).delegates_to(:tester).tools(:Read, :Edit, :Write)
     class AgentConfig
       attr_reader :agent_name
 
@@ -24,6 +31,7 @@ module SwarmSDK
         @node_builder = node_builder
         @delegates_to = []
         @reset_context = reset_context
+        @tools = nil # nil means use global agent definition tools
         @finalized = false
       end
 
@@ -33,21 +41,38 @@ module SwarmSDK
       # @return [self] For method chaining
       def delegates_to(*agent_names)
         @delegates_to = agent_names.map(&:to_sym)
-        finalize
+        update_registration
         self
       end
 
-      # Finalize agent configuration (called automatically)
+      # Override tools for this agent in this node
+      #
+      # @param tool_names [Array<Symbol>] Tool names to use (overrides global agent definition)
+      # @return [self] For method chaining
       #
-      # Registers this agent configuration with the parent node builder.
-      # If delegates_to was never called, registers with empty delegation.
+      # @example
+      #   agent(:backend).tools(:Read, :Edit)
+      def tools(*tool_names)
+        @tools = tool_names.map(&:to_sym)
+        update_registration
+        self
+      end
+
+      # Update agent registration (called after each fluent method)
+      #
+      # Always updates the registration with current state.
+      # This allows chaining: .delegates_to(...).tools(...)
       #
       # @return [void]
-      def finalize
-        return if @finalized
+      def update_registration
+        @node_builder.register_agent(@agent_name, @delegates_to, @reset_context, @tools)
+      end
 
-        @node_builder.register_agent(@agent_name, @delegates_to, @reset_context)
-        @finalized = true
+      # Finalize agent configuration (backward compatibility)
+      #
+      # @return [void]
+      def finalize
+        update_registration
       end
     end
   end

data/lib/swarm_sdk/node/builder.rb

@@ -43,8 +43,8 @@ module SwarmSDK
 
       # Configure an agent for this node
       #
-      # Returns an AgentConfig object that supports fluent delegation syntax.
-      # If delegates_to is not called, the agent is registered with no delegation.
+      # Returns an AgentConfig object that supports fluent delegation and tool override syntax.
+      # If delegates_to/tools are not called, the agent uses global configuration.
       #
       # By default, agents get fresh context in each node (reset_context: true).
       # Set reset_context: false to preserve conversation history across nodes.
@@ -61,12 +61,18 @@ module SwarmSDK
       #
       # @example Preserve context across nodes
       #   agent(:architect, reset_context: false)
+      #
+      # @example Override tools for this node
+      #   agent(:backend).tools(:Read, :Think)
+      #
+      # @example Combine delegation and tools
+      #   agent(:backend).delegates_to(:tester).tools(:Read, :Edit, :Write)
       def agent(name, reset_context: true)
         config = AgentConfig.new(name, self, reset_context: reset_context)
 
-        # Register immediately with empty delegation
-        # If delegates_to is called later, it will update this
-        register_agent(name, [], reset_context)
+        # Register immediately with empty delegation and no tool override
+        # If delegates_to/tools are called later, they will update this
+        register_agent(name, [], reset_context, nil)
 
         config
       end
@@ -76,18 +82,25 @@ module SwarmSDK
       # @param agent_name [Symbol] Agent name
       # @param delegates_to [Array<Symbol>] Delegation targets
       # @param reset_context [Boolean] Whether to reset agent context
+      # @param tools [Array<Symbol>, nil] Tool override for this node (nil = use global)
       # @return [void]
-      def register_agent(agent_name, delegates_to, reset_context = true)
+      def register_agent(agent_name, delegates_to, reset_context = true, tools = nil)
         # Check if agent already registered
         existing = @agent_configs.find { |ac| ac[:agent] == agent_name }
 
         if existing
-          # Update delegation and reset_context (happens when delegates_to is called after agent())
+          # Update delegation, reset_context, and tools (happens when methods are called after agent())
           existing[:delegates_to] = delegates_to
           existing[:reset_context] = reset_context
+          existing[:tools] = tools unless tools.nil?
         else
           # Add new agent configuration
-          @agent_configs << { agent: agent_name, delegates_to: delegates_to, reset_context: reset_context }
+          @agent_configs << {
+            agent: agent_name,
+            delegates_to: delegates_to,
+            reset_context: reset_context,
+            tools: tools,
+          }
         end
       end
 
@@ -154,32 +167,36 @@ module SwarmSDK
       #     "Implement based on:\nPlan: #{plan}\nDesign: #{design}"
       #   end
       #
-      # @example Skip execution (caching)
+      # @example Skip execution (caching) - using return
       #   input do |ctx|
       #     cached = check_cache(ctx.content)
       #     return ctx.skip_execution(content: cached) if cached
       #     ctx.content
       #   end
       #
-      # @example Halt workflow (validation)
+      # @example Halt workflow (validation) - using return
       #   input do |ctx|
       #     if ctx.content.length > 10000
-      #       # Halt entire workflow
+      #       # Halt entire workflow - return works safely!
       #       return ctx.halt_workflow(content: "ERROR: Input too long")
       #     end
       #     ctx.content
       #   end
       #
-      # @example Jump to different node (conditional routing)
+      # @example Jump to different node (conditional routing) - using return
       #   input do |ctx|
       #     if ctx.content.include?("NEEDS_REVIEW")
-      #       # Jump to review node instead
+      #       # Jump to review node instead - return works safely!
       #       return ctx.goto_node(:review, content: ctx.content)
       #     end
       #     ctx.content
       #   end
+      #
+      # @note The input block is automatically converted to a lambda, which means
+      #   return statements work safely and only exit the transformer, not the
+      #   entire program. This allows natural control flow patterns.
       def input(&block)
-        @input_transformer = block
+        @input_transformer = ProcHelpers.to_lambda(block)
       end
 
       # Set input transformer as bash command (YAML API)
@@ -234,22 +251,26 @@ module SwarmSDK
       #     "Task: #{ctx.original_prompt}\nResult: #{ctx.content}"
       #   end
       #
-      # @example Halt workflow (convergence check)
+      # @example Halt workflow (convergence check) - using return
       #   output do |ctx|
       #     return ctx.halt_workflow(content: ctx.content) if converged?(ctx.content)
       #     ctx.content
       #   end
       #
-      # @example Jump to different node (conditional routing)
+      # @example Jump to different node (conditional routing) - using return
       #   output do |ctx|
       #     if needs_revision?(ctx.content)
-      #       # Go back to revision node
+      #       # Go back to revision node - return works safely!
       #       return ctx.goto_node(:revision, content: ctx.content)
       #     end
       #     ctx.content
       #   end
+      #
+      # @note The output block is automatically converted to a lambda, which means
+      #   return statements work safely and only exit the transformer, not the
+      #   entire program. This allows natural control flow patterns.
       def output(&block)
-        @output_transformer = block
+        @output_transformer = ProcHelpers.to_lambda(block)
       end
 
       # Set output transformer as bash command (YAML API)