swarm_sdk 2.7.13 → 3.0.0.alpha1

data/lib/swarm_sdk/swarm/logging_callbacks.rb

@@ -1,360 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  class Swarm
-    # Logging callbacks for swarm events
-    #
-    # Extracted from Swarm to reduce class size and eliminate repetitive callback patterns.
-    # These callbacks emit structured log events to LogStream for monitoring and debugging.
-    module LoggingCallbacks
-      # Register default logging callbacks for all swarm events
-      #
-      # Sets up low-priority callbacks that emit structured events to LogStream.
-      # These callbacks only fire when LogStream.emitter is set (logging enabled).
-      def register_default_logging_callbacks
-        register_swarm_lifecycle_callbacks
-        register_agent_lifecycle_callbacks
-        register_tool_execution_callbacks
-        register_context_warning_callback
-      end
-
-      # Setup logging infrastructure for an execution
-      #
-      # @param logs [Array] Log collection array
-      # @yield [entry] Block called for each log entry
-      def setup_logging(logs)
-        # Force fresh subscription array for this execution
-        Fiber[:log_subscriptions] = []
-
-        # Subscribe to collect logs and forward to user's block
-        LogCollector.subscribe do |entry|
-          logs << entry
-          yield(entry) if block_given?
-        end
-
-        # Set LogStream to use LogCollector as emitter
-        LogStream.emitter = LogCollector
-      end
-
-      # Emit agent_start events if agents were initialized before logging was set up
-      #
-      # When agents are initialized BEFORE logging (e.g., via restore()),
-      # we need to retroactively set up logging callbacks and emit agent_start events.
-      def emit_retroactive_agent_start_events
-        return if !@agents_initialized || @agent_start_events_emitted
-
-        # Setup logging callbacks for all agents (they were skipped during initialization)
-        setup_logging_for_all_agents
-
-        # Emit agent_start events now that logging is ready
-        emit_agent_start_events
-        @agent_start_events_emitted = true
-      end
-
-      # Setup logging callbacks for all initialized agents
-      #
-      # Called after restore() when logging is enabled. Sets up logging callbacks
-      # for each agent so that subsequent events are captured.
-      def setup_logging_for_all_agents
-        # Setup for PRIMARY agents
-        @agents.each_value do |chat|
-          chat.setup_logging if chat.respond_to?(:setup_logging)
-        end
-
-        # Setup for DELEGATION instances
-        @delegation_instances.each_value do |chat|
-          chat.setup_logging if chat.respond_to?(:setup_logging)
-        end
-      end
-
-      # Emit agent_start events for all initialized agents
-      #
-      # Called retroactively when agents were initialized before logging was enabled.
-      # Emits agent_start events so log stream captures complete agent lifecycle.
-      def emit_agent_start_events
-        return unless LogStream.emitter
-
-        # Emit for PRIMARY agents
-        @agents.each do |agent_name, chat|
-          emit_agent_start_for(agent_name, chat, is_delegation: false)
-        end
-
-        # Emit for DELEGATION instances
-        @delegation_instances.each do |instance_name, chat|
-          base_name = extract_base_name(instance_name)
-          emit_agent_start_for(instance_name.to_sym, chat, is_delegation: true, base_name: base_name)
-        end
-
-        # Mark as emitted to prevent duplicate emissions
-        @agent_start_events_emitted = true
-      end
-
-      # Emit a single agent_start event
-      #
-      # @param agent_name [Symbol] Agent name (or instance name for delegations)
-      # @param chat [Agent::Chat] Agent chat instance
-      # @param is_delegation [Boolean] Whether this is a delegation instance
-      # @param base_name [String, nil] Base agent name for delegations
-      def emit_agent_start_for(agent_name, chat, is_delegation:, base_name: nil)
-        base_name ||= agent_name
-        agent_def = @agent_definitions[base_name]
-
-        # Build plugin storage info using base name
-        plugin_storage_info = {}
-        @plugin_storages.each do |plugin_name, agent_storages|
-          next unless agent_storages.key?(base_name)
-
-          plugin_storage_info[plugin_name] = {
-            enabled: true,
-            config: agent_def.respond_to?(plugin_name) ? extract_plugin_config_info(agent_def.public_send(plugin_name)) : nil,
-          }
-        end
-
-        LogStream.emit(
-          type: "agent_start",
-          agent: agent_name,
-          swarm_id: @swarm_id,
-          parent_swarm_id: @parent_swarm_id,
-          swarm_name: @name,
-          model: agent_def.model,
-          provider: agent_def.provider || "openai",
-          directory: agent_def.directory,
-          system_prompt: agent_def.system_prompt,
-          tools: chat.tool_names,
-          delegates_to: agent_def.delegates_to,
-          plugin_storages: plugin_storage_info,
-          is_delegation_instance: is_delegation,
-          base_agent: (base_name if is_delegation),
-          timestamp: Time.now.utc.strftime("%Y-%m-%dT%H:%M:%SZ"),
-        )
-      end
-
-      private
-
-      # Register swarm lifecycle callbacks (swarm_start, swarm_stop)
-      def register_swarm_lifecycle_callbacks
-        add_default_callback(:swarm_start, priority: -100) do |context|
-          emit_swarm_start_event(context)
-        end
-
-        add_default_callback(:swarm_stop, priority: -100) do |context|
-          emit_swarm_stop_event(context)
-        end
-      end
-
-      # Register agent lifecycle callbacks (user_prompt, agent_step, agent_stop)
-      def register_agent_lifecycle_callbacks
-        add_default_callback(:user_prompt, priority: -100) do |context|
-          emit_user_prompt_event(context)
-        end
-
-        add_default_callback(:agent_step, priority: -100) do |context|
-          emit_agent_step_event(context)
-        end
-
-        add_default_callback(:agent_stop, priority: -100) do |context|
-          emit_agent_stop_event(context)
-        end
-      end
-
-      # Register tool execution callbacks (pre_tool_use, post_tool_use)
-      def register_tool_execution_callbacks
-        add_default_callback(:pre_tool_use, priority: -100) do |context|
-          emit_tool_call_event(context)
-        end
-
-        add_default_callback(:post_tool_use, priority: -100) do |context|
-          emit_tool_result_event(context)
-        end
-      end
-
-      # Register context warning callback
-      def register_context_warning_callback
-        add_default_callback(:context_warning, priority: -100) do |context|
-          emit_context_warning_event(context)
-        end
-      end
-
-      # Emit swarm_start event
-      def emit_swarm_start_event(context)
-        return unless LogStream.emitter
-
-        LogStream.emit(
-          type: "swarm_start",
-          agent: context.metadata[:lead_agent],
-          swarm_id: @swarm_id,
-          parent_swarm_id: @parent_swarm_id,
-          swarm_name: context.metadata[:swarm_name],
-          lead_agent: context.metadata[:lead_agent],
-          prompt: context.metadata[:prompt],
-          timestamp: context.metadata[:timestamp],
-        )
-      end
-
-      # Emit swarm_stop event
-      def emit_swarm_stop_event(context)
-        return unless LogStream.emitter
-
-        LogStream.emit(
-          type: "swarm_stop",
-          swarm_id: @swarm_id,
-          parent_swarm_id: @parent_swarm_id,
-          swarm_name: context.metadata[:swarm_name],
-          lead_agent: context.metadata[:lead_agent],
-          last_agent: context.metadata[:last_agent],
-          content: context.metadata[:content],
-          success: context.metadata[:success],
-          duration: context.metadata[:duration],
-          total_cost: context.metadata[:total_cost],
-          total_tokens: context.metadata[:total_tokens],
-          agents_involved: context.metadata[:agents_involved],
-          per_agent_usage: context.metadata[:per_agent_usage],
-          timestamp: context.metadata[:timestamp],
-        )
-      end
-
-      # Emit user_prompt event
-      def emit_user_prompt_event(context)
-        return unless LogStream.emitter
-
-        LogStream.emit(
-          type: "user_prompt",
-          agent: context.agent_name,
-          swarm_id: @swarm_id,
-          parent_swarm_id: @parent_swarm_id,
-          prompt: context.metadata[:prompt],
-          model: context.metadata[:model] || "unknown",
-          provider: context.metadata[:provider] || "unknown",
-          message_count: context.metadata[:message_count] || 0,
-          tools: context.metadata[:tools] || [],
-          delegates_to: context.metadata[:delegates_to] || [],
-          source: context.metadata[:source] || "user",
-          metadata: context.metadata,
-        )
-      end
-
-      # Emit agent_step event (intermediate response with tool calls)
-      def emit_agent_step_event(context)
-        return unless LogStream.emitter
-
-        metadata_without_duplicates = context.metadata.except(
-          :model,
-          :content,
-          :tool_calls,
-          :finish_reason,
-          :usage,
-          :tool_executions,
-          :citations,
-          :search_results,
-        )
-
-        LogStream.emit(
-          type: "agent_step",
-          agent: context.agent_name,
-          swarm_id: @swarm_id,
-          parent_swarm_id: @parent_swarm_id,
-          model: context.metadata[:model],
-          content: context.metadata[:content],
-          tool_calls: context.metadata[:tool_calls],
-          finish_reason: context.metadata[:finish_reason],
-          usage: context.metadata[:usage],
-          citations: context.metadata[:citations],
-          search_results: context.metadata[:search_results],
-          tool_executions: context.metadata[:tool_executions],
-          metadata: metadata_without_duplicates,
-        )
-      end
-
-      # Emit agent_stop event (final response)
-      def emit_agent_stop_event(context)
-        return unless LogStream.emitter
-
-        metadata_without_duplicates = context.metadata.except(
-          :model,
-          :content,
-          :tool_calls,
-          :finish_reason,
-          :usage,
-          :tool_executions,
-          :citations,
-          :search_results,
-        )
-
-        LogStream.emit(
-          type: "agent_stop",
-          agent: context.agent_name,
-          swarm_id: @swarm_id,
-          parent_swarm_id: @parent_swarm_id,
-          model: context.metadata[:model],
-          content: context.metadata[:content],
-          tool_calls: context.metadata[:tool_calls],
-          finish_reason: context.metadata[:finish_reason],
-          usage: context.metadata[:usage],
-          citations: context.metadata[:citations],
-          search_results: context.metadata[:search_results],
-          tool_executions: context.metadata[:tool_executions],
-          metadata: metadata_without_duplicates,
-        )
-      end
-
-      # Emit tool_call event (pre_tool_use)
-      def emit_tool_call_event(context)
-        return unless LogStream.emitter
-
-        LogStream.emit(
-          type: "tool_call",
-          agent: context.agent_name,
-          swarm_id: @swarm_id,
-          parent_swarm_id: @parent_swarm_id,
-          tool_call_id: context.tool_call.id,
-          tool: context.tool_call.name,
-          arguments: context.tool_call.parameters,
-          metadata: context.metadata,
-        )
-      end
-
-      # Emit tool_result event (post_tool_use)
-      def emit_tool_result_event(context)
-        return unless LogStream.emitter
-
-        LogStream.emit(
-          type: "tool_result",
-          agent: context.agent_name,
-          swarm_id: @swarm_id,
-          parent_swarm_id: @parent_swarm_id,
-          tool_call_id: context.tool_result.tool_call_id,
-          tool: context.tool_result.tool_name,
-          result: context.tool_result.content,
-          metadata: context.metadata,
-        )
-      end
-
-      # Emit context_limit_warning event
-      def emit_context_warning_event(context)
-        return unless LogStream.emitter
-
-        LogStream.emit(
-          type: "context_limit_warning",
-          agent: context.agent_name,
-          swarm_id: @swarm_id,
-          parent_swarm_id: @parent_swarm_id,
-          model: context.metadata[:model] || "unknown",
-          threshold: "#{context.metadata[:threshold]}%",
-          current_usage: "#{context.metadata[:percentage]}%",
-          tokens_used: context.metadata[:tokens_used],
-          tokens_remaining: context.metadata[:tokens_remaining],
-          context_limit: context.metadata[:context_limit],
-          metadata: context.metadata,
-        )
-      end
-
-      # Extract base name from delegation instance name
-      #
-      # @param instance_name [String, Symbol] Instance name (e.g., "agent@1234")
-      # @return [Symbol] Base agent name (e.g., :agent)
-      def extract_base_name(instance_name)
-        instance_name.to_s.split("@").first.to_sym
-      end
-    end
-  end
-end

data/lib/swarm_sdk/swarm/mcp_configurator.rb

@@ -1,270 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  class Swarm
-    # Handles MCP (Model Context Protocol) server configuration and client management
-    #
-    # Responsibilities:
-    # - Register MCP servers for agents
-    # - Initialize MCP clients (stdio, SSE, streamable transports)
-    # - Build transport-specific configurations
-    # - Track clients for cleanup
-    #
-    # This encapsulates all MCP-related logic that was previously in Swarm.
-    class McpConfigurator
-      def initialize(swarm)
-        @swarm = swarm
-        @mcp_clients = swarm.mcp_clients
-      end
-
-      # Register MCP servers for an agent
-      #
-      # Connects to MCP servers and registers their tools with the agent's chat instance.
-      # Supports stdio, SSE, and HTTP (streamable) transports.
-      #
-      # ## Boot Optimization (Plan 025)
-      #
-      # - If tools specified: Create stubs without tools/list RPC (fast boot, lazy schema)
-      # - If tools omitted: Call tools/list to discover all tools (discovery mode)
-      #
-      # @param chat [AgentChat] The agent's chat instance
-      # @param mcp_server_configs [Array<Hash>] MCP server configurations
-      # @param agent_name [Symbol] Agent name for tracking clients
-      #
-      # @example Fast boot mode
-      #   mcp_server :codebase, type: :stdio, command: "mcp-server", tools: [:search, :list]
-      #   # Creates tool stubs instantly, no tools/list RPC
-      #
-      # @example Discovery mode
-      #   mcp_server :codebase, type: :stdio, command: "mcp-server"
-      #   # Calls tools/list to discover all available tools
-      def register_mcp_servers(chat, mcp_server_configs, agent_name:)
-        return if mcp_server_configs.nil? || mcp_server_configs.empty?
-
-        # Ensure MCP logging is configured before creating clients
-        Swarm.apply_mcp_logging_configuration
-
-        mcp_server_configs.each do |server_config|
-          tools_config = server_config[:tools]
-          mode = tools_config.nil? ? :discovery : :optimized
-
-          # Emit event before initialization
-          emit_mcp_init_start(agent_name, server_config, mode)
-
-          client = initialize_mcp_client(server_config)
-
-          # Store client for cleanup
-          @mcp_clients[agent_name] << client
-
-          if tools_config.nil?
-            # Discovery mode: Fetch all tools from server (calls tools/list)
-            # client.tools returns RubyLLM::Tool instances (already wrapped by internal Coordinator)
-            all_tools = client.tools
-            tool_names = all_tools.map { |t| t.respond_to?(:name) ? t.name : t.to_s }
-
-            all_tools.each do |tool|
-              chat.tool_registry.register(
-                tool,
-                source: :mcp,
-                metadata: { server_name: server_config[:name] },
-              )
-            end
-
-            # Emit completion event for discovery mode
-            emit_mcp_init_complete(agent_name, server_config, mode, all_tools.size, tool_names)
-            RubyLLM.logger.debug("SwarmSDK: Discovered and registered #{all_tools.size} tools from MCP server '#{server_config[:name]}'")
-          else
-            # Optimized mode: Create tool stubs without tools/list RPC (Plan 025)
-            # Use client directly (it has internal coordinator)
-            tool_names = tools_config.map(&:to_s)
-
-            tools_config.each do |tool_name|
-              stub = Tools::McpToolStub.new(
-                client: client,
-                name: tool_name.to_s,
-                server_name: server_config[:name],
-              )
-              chat.tool_registry.register(
-                stub,
-                source: :mcp,
-                metadata: { server_name: server_config[:name] },
-              )
-            end
-
-            # Emit completion event for optimized mode
-            emit_mcp_init_complete(agent_name, server_config, mode, tools_config.size, tool_names)
-            RubyLLM.logger.debug("SwarmSDK: Registered #{tools_config.size} tool stubs from MCP server '#{server_config[:name]}' (lazy schema)")
-          end
-        rescue StandardError => e
-          RubyLLM.logger.error("SwarmSDK: Failed to initialize MCP server '#{server_config[:name]}' for agent #{agent_name}: #{e.class.name}: #{e.message}")
-          RubyLLM.logger.error("SwarmSDK: Backtrace: #{e.backtrace.first(5).join("\n  ")}")
-          raise ConfigurationError, "Failed to initialize MCP server '#{server_config[:name]}': #{e.message}"
-        end
-      end
-
-      # Build transport-specific configuration for MCP client
-      #
-      # This method is public for testing delegation from Swarm.
-      #
-      # @param transport_type [Symbol] Transport type (:stdio, :sse, :streamable)
-      # @param config [Hash] MCP server configuration
-      # @return [Hash] Transport-specific configuration
-      def build_transport_config(transport_type, config)
-        case transport_type
-        when :stdio
-          build_stdio_config(config)
-        when :sse
-          build_sse_config(config)
-        when :streamable
-          build_streamable_config(config)
-        else
-          raise ArgumentError, "Unsupported transport type: #{transport_type}"
-        end
-      end
-
-      private
-
-      # Initialize an MCP client from configuration
-      #
-      # @param config [Hash] MCP server configuration
-      # @return [RubyLLM::MCP::Client] Initialized MCP client
-      def initialize_mcp_client(config)
-        # Convert timeout from seconds to milliseconds
-        # Use explicit config[:timeout] if provided, otherwise use global default
-        timeout_seconds = config[:timeout] || SwarmSDK.config.mcp_request_timeout
-        timeout_ms = timeout_seconds * 1000
-
-        # Determine transport type
-        transport_type = determine_transport_type(config[:type])
-
-        # Build transport-specific configuration
-        client_config = build_transport_config(transport_type, config)
-
-        # Create and start MCP client
-        RubyLLM::MCP.client(
-          name: config[:name],
-          transport_type: transport_type,
-          request_timeout: timeout_ms,
-          config: client_config,
-        )
-      end
-
-      # Determine transport type from configuration
-      #
-      # @param type [Symbol, String, nil] Transport type from config
-      # @return [Symbol] Normalized transport type
-      def determine_transport_type(type)
-        case type&.to_sym
-        when :stdio then :stdio
-        when :sse then :sse
-        when :http, :streamable then :streamable
-        else
-          raise ArgumentError, "Unknown MCP transport type: #{type}"
-        end
-      end
-
-      # Build stdio transport configuration
-      #
-      # @param config [Hash] MCP server configuration
-      # @return [Hash] Stdio configuration
-      def build_stdio_config(config)
-        {
-          command: config[:command],
-          args: config[:args] || [],
-          env: Utils.stringify_keys(config[:env] || {}),
-        }
-      end
-
-      # Build SSE transport configuration
-      #
-      # @param config [Hash] MCP server configuration
-      # @return [Hash] SSE configuration
-      def build_sse_config(config)
-        sse_config = {
-          url: config[:url],
-          headers: config[:headers] || {},
-          version: config[:version]&.to_sym || :http2,
-        }
-
-        # Add reconnection options for resilient SSE connections
-        sse_config[:reconnection] = build_reconnection_options(config)
-
-        sse_config
-      end
-
-      # Build streamable (HTTP) transport configuration
-      #
-      # @param config [Hash] MCP server configuration
-      # @return [Hash] Streamable configuration
-      def build_streamable_config(config)
-        streamable_config = {
-          url: config[:url],
-          headers: config[:headers] || {},
-          version: config[:version]&.to_sym || :http2,
-        }
-
-        # Only include rate_limit if present
-        streamable_config[:rate_limit] = config[:rate_limit] if config[:rate_limit]
-
-        # Add reconnection options for resilient streamable connections
-        streamable_config[:reconnection] = build_reconnection_options(config)
-
-        streamable_config
-      end
-
-      # Build reconnection options from config or defaults
-      #
-      # Provides exponential backoff reconnection for SSE/streamable transports.
-      # Can be customized per-server or uses global defaults.
-      #
-      # @param config [Hash] MCP server configuration
-      # @return [Hash] Reconnection options
-      def build_reconnection_options(config)
-        reconnection_config = config[:reconnection] || {}
-
-        {
-          max_retries: reconnection_config[:max_retries] || Defaults::McpReconnection::MAX_RETRIES,
-          initial_reconnection_delay: reconnection_config[:initial_delay] || Defaults::McpReconnection::INITIAL_DELAY_MS,
-          reconnection_delay_grow_factor: reconnection_config[:delay_grow_factor] || Defaults::McpReconnection::DELAY_GROW_FACTOR,
-          max_reconnection_delay: reconnection_config[:max_delay] || Defaults::McpReconnection::MAX_DELAY_MS,
-        }
-      end
-
-      # Emit MCP server initialization start event
-      #
-      # @param agent_name [Symbol] Agent name
-      # @param server_config [Hash] MCP server configuration
-      # @param mode [Symbol] Initialization mode (:discovery or :optimized)
-      # @return [void]
-      def emit_mcp_init_start(agent_name, server_config, mode)
-        LogStream.emit(
-          type: "mcp_server_init_start",
-          agent: agent_name,
-          server_name: server_config[:name],
-          transport_type: server_config[:type],
-          mode: mode,
-        )
-      end
-
-      # Emit MCP server initialization complete event
-      #
-      # @param agent_name [Symbol] Agent name
-      # @param server_config [Hash] MCP server configuration
-      # @param mode [Symbol] Initialization mode (:discovery or :optimized)
-      # @param tool_count [Integer] Number of tools registered
-      # @param tool_names [Array<String>] Names of registered tools
-      # @return [void]
-      def emit_mcp_init_complete(agent_name, server_config, mode, tool_count, tool_names)
-        LogStream.emit(
-          type: "mcp_server_init_complete",
-          agent: agent_name,
-          server_name: server_config[:name],
-          transport_type: server_config[:type],
-          mode: mode,
-          tool_count: tool_count,
-          tools: tool_names,
-        )
-      end
-    end
-  end
-end

data/lib/swarm_sdk/swarm/swarm_registry_builder.rb

@@ -1,67 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  class Swarm
-    # Builder for swarm registry in DSL
-    #
-    # Supports registering external swarms for composable swarms pattern.
-    #
-    # @example
-    #   swarms do
-    #     register "code_review", file: "./swarms/code_review.rb"
-    #     register "testing", file: "./swarms/testing.yml", keep_context: false
-    #   end
-    #
-    # @example Inline swarm definition
-    #   swarms do
-    #     register "tester" do
-    #       lead :tester
-    #       agent :tester do
-    #         model "gpt-4o-mini"
-    #         system "You test code"
-    #       end
-    #     end
-    #   end
-    #
-    class SwarmRegistryBuilder
-      attr_reader :registrations
-
-      def initialize
-        @registrations = []
-      end
-
-      # Register a swarm from file, YAML string, or inline block
-      #
-      # @param name [String, Symbol] Registration name
-      # @param file [String, nil] Path to swarm file (.rb or .yml)
-      # @param yaml [String, nil] YAML content string
-      # @param keep_context [Boolean] Whether to preserve conversation state (default: true)
-      # @yield Optional block for inline swarm definition
-      # @raise [ArgumentError] If neither file, yaml, nor block provided
-      def register(name, file: nil, yaml: nil, keep_context: true, &block)
-        # Validate that exactly one source is provided
-        sources = [file, yaml, block].compact
-        if sources.empty?
-          raise ArgumentError, "register '#{name}' requires either file:, yaml:, or a block"
-        elsif sources.size > 1
-          raise ArgumentError, "register '#{name}' accepts only one of: file:, yaml:, or block (got #{sources.size})"
-        end
-
-        # Determine source type and store
-        source = if file
-          { type: :file, value: file }
-        elsif yaml
-          { type: :yaml, value: yaml }
-        else
-          { type: :block, value: block }
-        end
-
-        @registrations << {
-          name: name.to_s,
-          source: source,
-          keep_context: keep_context,
-        }
-      end
-    end
-  end
-end