swarm_memory 2.1.5 → 2.1.6

data/lib/swarm_sdk/swarm/hook_triggers.rb

@@ -1,150 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  class Swarm
-    # Hook triggering methods for swarm lifecycle events
-    #
-    # Extracted from Swarm to reduce class size and centralize hook execution logic.
-    # These methods build contexts and execute hooks via the hook registry.
-    module HookTriggers
-      # Add a default callback for an event
-      #
-      # @param event [Symbol] Event type (:pre_tool_use, :post_tool_use, etc.)
-      # @param matcher [Hash, nil] Optional matcher to filter events
-      # @param priority [Integer] Callback priority (higher = later)
-      # @param block [Proc] Hook implementation
-      # @return [self]
-      def add_default_callback(event, matcher: nil, priority: 0, &block)
-        @hook_registry.add_default(event, matcher: matcher, priority: priority, &block)
-        self
-      end
-
-      # Trigger swarm_stop hooks and check for reprompt
-      #
-      # @param result [Result] The execution result
-      # @return [Hooks::Result, nil] Hook result (reprompt action if applicable)
-      def trigger_swarm_stop(result)
-        context = build_swarm_stop_context(result)
-        executor = Hooks::Executor.new(@hook_registry, logger: RubyLLM.logger)
-        executor.execute_safe(event: :swarm_stop, context: context, callbacks: [])
-      rescue StandardError => e
-        LogStream.emit_error(e, source: "hook_triggers", context: "swarm_stop", agent: @lead_agent)
-        RubyLLM.logger.debug("SwarmSDK: Error in swarm_stop hook: #{e.message}")
-        nil
-      end
-
-      # Trigger swarm_stop for final event emission (called in ensure block)
-      #
-      # @param result [Result, nil] Execution result
-      # @param start_time [Time] Execution start time
-      # @param logs [Array] Collected logs
-      # @return [void]
-      def trigger_swarm_stop_final(result, start_time, logs)
-        result ||= Result.new(
-          content: nil,
-          agent: @lead_agent&.to_s || "unknown",
-          logs: logs,
-          duration: Time.now - start_time,
-          error: StandardError.new("Unknown error"),
-        )
-
-        context = build_swarm_stop_context(result)
-        executor = Hooks::Executor.new(@hook_registry, logger: RubyLLM.logger)
-        executor.execute_safe(event: :swarm_stop, context: context, callbacks: [])
-      rescue StandardError => e
-        LogStream.emit_error(e, source: "hook_triggers", context: "swarm_stop_final", agent: @lead_agent)
-        RubyLLM.logger.debug("SwarmSDK: Error in swarm_stop final emission: #{e.message}")
-      end
-
-      private
-
-      # Build swarm_stop context (DRY - used by both trigger methods)
-      #
-      # @param result [Result] Execution result
-      # @return [Hooks::Context] Hook context for swarm_stop event
-      def build_swarm_stop_context(result)
-        Hooks::Context.new(
-          event: :swarm_stop,
-          agent_name: @lead_agent.to_s,
-          swarm: self,
-          metadata: {
-            swarm_name: @name,
-            lead_agent: @lead_agent,
-            last_agent: result.agent,
-            content: result.content,
-            success: result.success?,
-            duration: result.duration,
-            total_cost: result.total_cost,
-            total_tokens: result.total_tokens,
-            agents_involved: result.agents_involved,
-            result: result,
-            timestamp: Time.now.utc.iso8601,
-          },
-        )
-      end
-
-      # Trigger swarm_start hooks when swarm execution begins
-      #
-      # @param prompt [String] The user's task prompt
-      # @return [Hooks::Result, nil] Result with stdout to append (if exit 0) or nil
-      # @raise [Hooks::Error] If hook halts execution
-      def trigger_swarm_start(prompt)
-        context = Hooks::Context.new(
-          event: :swarm_start,
-          agent_name: @lead_agent.to_s,
-          swarm: self,
-          metadata: {
-            swarm_name: @name,
-            lead_agent: @lead_agent,
-            prompt: prompt,
-            timestamp: Time.now.utc.iso8601,
-          },
-        )
-
-        executor = Hooks::Executor.new(@hook_registry, logger: RubyLLM.logger)
-        result = executor.execute_safe(event: :swarm_start, context: context, callbacks: [])
-
-        # Halt execution if hook requests it
-        raise Hooks::Error, "Swarm start halted by hook: #{result.value}" if result.halt?
-
-        # Return result so caller can check for replace (stdout injection)
-        result
-      rescue StandardError => e
-        LogStream.emit_error(e, source: "hook_triggers", context: "swarm_start", agent: @lead_agent)
-        RubyLLM.logger.debug("SwarmSDK: Error in swarm_start hook: #{e.message}")
-        raise
-      end
-
-      # Trigger first_message hooks when first user message is sent
-      #
-      # @param prompt [String] The first user message
-      # @return [void]
-      # @raise [Hooks::Error] If hook halts execution
-      def trigger_first_message(prompt)
-        return if @hook_registry.get_defaults(:first_message).empty?
-
-        context = Hooks::Context.new(
-          event: :first_message,
-          agent_name: @lead_agent.to_s,
-          swarm: self,
-          metadata: {
-            swarm_name: @name,
-            lead_agent: @lead_agent,
-            prompt: prompt,
-            timestamp: Time.now.utc.iso8601,
-          },
-        )
-
-        executor = Hooks::Executor.new(@hook_registry, logger: RubyLLM.logger)
-        result = executor.execute_safe(event: :first_message, context: context, callbacks: [])
-
-        # Halt execution if hook requests it
-        raise Hooks::Error, "First message halted by hook: #{result.value}" if result.halt?
-      rescue StandardError => e
-        LogStream.emit_error(e, source: "hook_triggers", context: "first_message", agent: @lead_agent)
-        RubyLLM.logger.debug("SwarmSDK: Error in first_message hook: #{e.message}")
-        raise
-      end
-    end
-  end
-end

data/lib/swarm_sdk/swarm/logging_callbacks.rb

@@ -1,340 +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],
-          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,
-          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
-        )
-
-        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],
-          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
-        )
-
-        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],
-          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,154 +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.
-      #
-      # @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
-      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|
-          client = initialize_mcp_client(server_config)
-
-          # Store client for cleanup
-          @mcp_clients[agent_name] << client
-
-          # Fetch tools from MCP server and register with chat
-          # Tools are already in RubyLLM::Tool format
-          tools = client.tools
-          tools.each { |tool| chat.add_tool(tool) }
-
-          RubyLLM.logger.debug("SwarmSDK: Registered #{tools.size} tools from MCP server '#{server_config[:name]}' for agent #{agent_name}")
-        rescue StandardError => e
-          RubyLLM.logger.error("SwarmSDK: Failed to initialize MCP server '#{server_config[:name]}' for agent #{agent_name}: #{e.message}")
-          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
-        timeout_seconds = config[:timeout] || 30
-        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)
-        {
-          url: config[:url],
-          headers: config[:headers] || {},
-          version: config[:version]&.to_sym || :http2,
-        }
-      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]
-
-        streamable_config
-      end
-    end
-  end
-end