swarm_sdk 2.7.14 → 3.0.0.alpha1

data/lib/swarm_sdk/hooks/tool_call.rb

@@ -1,35 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  module Hooks
-    # Represents a tool call in the hooks system
-    #
-    # This is a simple value object that wraps tool call information
-    # from RubyLLM in a consistent, immutable format for hooks.
-    #
-    # @example Access tool call information in a hook
-    #   swarm.add_callback(:pre_tool_use) do |context|
-    #     puts "Tool: #{context.tool_call.name}"
-    #     puts "Parameters: #{context.tool_call.parameters.inspect}"
-    #   end
-    class ToolCall
-      attr_reader :id, :name, :parameters
-
-      # @param id [String] Unique identifier for this tool call
-      # @param name [String] Name of the tool being called
-      # @param parameters [Hash] Parameters passed to the tool
-      def initialize(id:, name:, parameters:)
-        @id = id
-        @name = name
-        @parameters = parameters
-      end
-
-      # Convert to hash representation
-      #
-      # @return [Hash] Hash with id, name, and parameters
-      def to_h
-        { id: @id, name: @name, parameters: @parameters }
-      end
-    end
-  end
-end

data/lib/swarm_sdk/hooks/tool_result.rb

@@ -1,62 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  module Hooks
-    # Represents the result of a tool execution
-    #
-    # This is a simple value object that wraps tool execution results
-    # in a consistent format for post-tool-use hooks.
-    #
-    # @example Access tool result in a hook
-    #   swarm.add_callback(:post_tool_use) do |context|
-    #     if context.tool_result.success?
-    #       puts "Tool succeeded: #{context.tool_result.content}"
-    #     else
-    #       puts "Tool failed: #{context.tool_result.error}"
-    #     end
-    #   end
-    class ToolResult
-      attr_reader :tool_call_id, :tool_name, :content, :success, :error
-
-      # @param tool_call_id [String] ID of the tool call this result corresponds to
-      # @param tool_name [String] Name of the tool that was executed
-      # @param content [String, nil] Result content (if successful)
-      # @param success [Boolean] Whether the tool execution succeeded
-      # @param error [String, nil] Error message (if failed)
-      def initialize(tool_call_id:, tool_name:, content: nil, success: true, error: nil)
-        @tool_call_id = tool_call_id
-        @tool_name = tool_name
-        @content = content
-        @success = success
-        @error = error
-      end
-
-      # Check if the tool execution succeeded
-      #
-      # @return [Boolean] true if successful
-      def success?
-        @success
-      end
-
-      # Check if the tool execution failed
-      #
-      # @return [Boolean] true if failed
-      def failure?
-        !@success
-      end
-
-      # Convert to hash representation
-      #
-      # @return [Hash] Hash with all result attributes
-      def to_h
-        {
-          tool_call_id: @tool_call_id,
-          tool_name: @tool_name,
-          content: @content,
-          success: @success,
-          error: @error,
-        }
-      end
-    end
-  end
-end

data/lib/swarm_sdk/log_collector.rb

@@ -1,227 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  # 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
-  #
-  #   # 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}"
-  #   }
-  #
-  #   # 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
-      # 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
-      # @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 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)
-        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 subscriptions for next execution)
-      #
-      # @return [void]
-      def reset!
-        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
-end

data/lib/swarm_sdk/log_stream.rb

@@ -1,127 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  # LogStream provides a module-level singleton for emitting log events.
-  #
-  # This allows any component (tools, providers, agents) to emit structured
-  # log events without needing references to logger instances.
-  #
-  # ## Usage
-  #
-  #   # Emit an event from anywhere in the SDK
-  #   LogStream.emit(
-  #     type: "user_prompt",
-  #     agent: :backend,
-  #     model: "claude-sonnet-4",
-  #     message_count: 5
-  #   )
-  #
-  # ## Thread Safety
-  #
-  # 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
-  #
-  # ## Testing
-  #
-  #   # Inject a test emitter
-  #   LogStream.emitter = TestEmitter.new
-  #   # ... run tests ...
-  #   LogStream.reset!
-  #
-  module LogStream
-    class << self
-      # 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)
-        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 = auto_injected.merge(data).merge(timestamp: Time.now.utc.iso8601(6)).compact
-
-        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)
-      # @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!
-        Fiber[:log_stream_emitter] = nil
-      end
-
-      # Check if logging is enabled
-      #
-      # @return [Boolean] true if an emitter is configured
-      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/markdown_parser.rb

@@ -1,75 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  # Parser for agent markdown files with YAML frontmatter
-  #
-  # Supports two formats:
-  # 1. SwarmSDK format - YAML frontmatter with array-based tools
-  # 2. Claude Code format - Detected and converted via ClaudeCodeAgentAdapter
-  #
-  # Format detection is automatic based on frontmatter structure.
-  class MarkdownParser
-    FRONTMATTER_PATTERN = /\A---\s*\n(.*?)\n---\s*\n(.*)\z/m
-
-    class << self
-      # Parse markdown content into an Agent::Definition
-      #
-      # Automatically detects format (SwarmSDK or Claude Code) and routes
-      # to appropriate parser.
-      #
-      # @param content [String] Markdown content with YAML frontmatter
-      # @param agent_name [Symbol, String, nil] Name of the agent
-      # @return [Agent::Definition] Parsed agent definition
-      # @raise [ConfigurationError] if format is invalid
-      def parse(content, agent_name = nil)
-        # Detect Claude Code format and route to adapter
-        if ClaudeCodeAgentAdapter.claude_code_format?(content)
-          config = ClaudeCodeAgentAdapter.parse(content, agent_name)
-          # For Claude Code format, agent_name parameter is required since
-          # the 'name' field in frontmatter is Claude Code specific and not used
-          unless agent_name
-            raise ConfigurationError, "Agent name must be provided when parsing Claude Code format"
-          end
-
-          Agent::Definition.new(agent_name.to_sym, config)
-        else
-          # Use standard SwarmSDK format parsing
-          new(content, agent_name).parse
-        end
-      end
-    end
-
-    def initialize(content, agent_name = nil)
-      @content = content
-      @agent_name = agent_name
-    end
-
-    def parse
-      if @content =~ FRONTMATTER_PATTERN
-        frontmatter_yaml = Regexp.last_match(1)
-        prompt_content = Regexp.last_match(2).strip
-
-        frontmatter = YAML.safe_load(frontmatter_yaml, permitted_classes: [Symbol], aliases: true)
-
-        unless frontmatter.is_a?(Hash)
-          raise ConfigurationError, "Invalid frontmatter format in agent definition"
-        end
-
-        # Symbolize keys for AgentDefinition
-        config = Utils.symbolize_keys(frontmatter).merge(system_prompt: prompt_content)
-
-        name = @agent_name || frontmatter["name"]
-        unless name
-          raise ConfigurationError, "Agent definition must include 'name' in frontmatter or be specified externally"
-        end
-
-        # Convert name to symbol
-        name = name.to_sym
-
-        Agent::Definition.new(name, config)
-      else
-        raise ConfigurationError, "Invalid Markdown agent definition format. Expected YAML frontmatter followed by prompt content."
-      end
-    end
-  end
-end

data/lib/swarm_sdk/model_aliases.json

@@ -1,8 +0,0 @@
-{
-  "sonnet": "claude-sonnet-4-5-20250929",
-  "opus": "claude-opus-4-1-20250805",
-  "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"
-}