swarm_sdk 2.0.0.pre.2

data/lib/swarm_sdk/swarm/agent_initializer.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  class Swarm
+    # Handles the complex 5-pass agent initialization process
+    #
+    # Responsibilities:
+    # - Create all agent chat instances (pass 1)
+    # - Register delegation tools (pass 2)
+    # - Setup agent contexts (pass 3)
+    # - Configure hook system (pass 4)
+    # - Apply YAML hooks if present (pass 5)
+    #
+    # This encapsulates the complex initialization logic that was previously
+    # embedded in Swarm#initialize_agents.
+    class AgentInitializer
+      def initialize(swarm, agent_definitions, global_semaphore, hook_registry, scratchpad, config_for_hooks: nil)
+        @swarm = swarm
+        @agent_definitions = agent_definitions
+        @global_semaphore = global_semaphore
+        @hook_registry = hook_registry
+        @scratchpad = scratchpad
+        @config_for_hooks = config_for_hooks
+        @agents = {}
+        @agent_contexts = {}
+      end
+
+      # Initialize all agents with their chat instances and tools
+      #
+      # This implements a 5-pass algorithm:
+      # 1. Create all Agent::Chat instances
+      # 2. Register delegation tools (agents can call each other)
+      # 3. Setup agent contexts for tracking
+      # 4. Configure hook system
+      # 5. Apply YAML hooks (if loaded from YAML)
+      #
+      # @return [Hash] agents hash { agent_name => Agent::Chat }
+      def initialize_all
+        pass_1_create_agents
+        pass_2_register_delegation_tools
+        pass_3_setup_contexts
+        pass_4_configure_hooks
+        pass_5_apply_yaml_hooks
+
+        @agents
+      end
+
+      # Provide access to agent contexts for Swarm
+      attr_reader :agent_contexts
+
+      # Create a tool that delegates work to another agent
+      #
+      # This method is public for testing delegation from Swarm.
+      #
+      # @param name [String] Delegate agent name
+      # @param description [String] Delegate agent description
+      # @param delegate_chat [Agent::Chat] The delegate's chat instance
+      # @param agent_name [Symbol] Name of the delegating agent
+      # @return [Tools::Delegate] Delegation tool
+      def create_delegation_tool(name:, description:, delegate_chat:, agent_name:)
+        Tools::Delegate.new(
+          delegate_name: name,
+          delegate_description: description,
+          delegate_chat: delegate_chat,
+          agent_name: agent_name,
+          swarm: @swarm,
+          hook_registry: @hook_registry,
+        )
+      end
+
+      private
+
+      # Pass 1: Create all agent chat instances
+      #
+      # This creates the Agent::Chat instances but doesn't wire them together yet.
+      # Each agent gets its own chat instance with configured tools.
+      def pass_1_create_agents
+        tool_configurator = ToolConfigurator.new(@swarm, @scratchpad)
+
+        @agent_definitions.each do |name, agent_definition|
+          chat = create_agent_chat(name, agent_definition, tool_configurator)
+          @agents[name] = chat
+        end
+      end
+
+      # Pass 2: Register agent delegation tools
+      #
+      # Now that all agents exist, we can create delegation tools
+      # that allow agents to call each other.
+      def pass_2_register_delegation_tools
+        @agent_definitions.each do |name, agent_definition|
+          register_delegation_tools(@agents[name], agent_definition.delegates_to, agent_name: name)
+        end
+      end
+
+      # Pass 3: Setup agent contexts
+      #
+      # Create Agent::Context for each agent to track delegations and metadata.
+      # This is needed regardless of whether logging is enabled.
+      def pass_3_setup_contexts
+        @agents.each do |agent_name, chat|
+          agent_definition = @agent_definitions[agent_name]
+          delegate_tool_names = agent_definition.delegates_to.map do |delegate_name|
+            "DelegateTaskTo#{delegate_name.to_s.capitalize}"
+          end
+
+          # Create agent context
+          context = Agent::Context.new(
+            name: agent_name,
+            delegation_tools: delegate_tool_names,
+            metadata: {},
+          )
+          @agent_contexts[agent_name] = context
+
+          # Always set agent context (needed for delegation tracking)
+          chat.setup_context(context) if chat.respond_to?(:setup_context)
+
+          # Configure logging callbacks if logging is enabled
+          next unless LogStream.emitter
+
+          chat.setup_logging if chat.respond_to?(:setup_logging)
+
+          # Emit any model lookup warnings that occurred during initialization
+          chat.emit_model_lookup_warning(agent_name) if chat.respond_to?(:emit_model_lookup_warning)
+        end
+      end
+
+      # Pass 4: Configure hook system
+      #
+      # Setup the callback system for each agent, integrating with RubyLLM callbacks.
+      def pass_4_configure_hooks
+        @agents.each do |agent_name, chat|
+          agent_definition = @agent_definitions[agent_name]
+
+          # Configure callback system (integrates with RubyLLM callbacks)
+          chat.setup_hooks(
+            registry: @hook_registry,
+            agent_definition: agent_definition,
+            swarm: @swarm,
+          ) if chat.respond_to?(:setup_hooks)
+        end
+      end
+
+      # Pass 5: Apply YAML hooks
+      #
+      # If the swarm was loaded from YAML with agent-specific hooks,
+      # apply them now via HooksAdapter.
+      def pass_5_apply_yaml_hooks
+        return unless @config_for_hooks
+
+        @agents.each do |agent_name, chat|
+          agent_def = @config_for_hooks.agents[agent_name]
+          next unless agent_def&.hooks
+
+          # Apply agent-specific hooks via Hooks::Adapter
+          Hooks::Adapter.apply_agent_hooks(chat, agent_name, agent_def.hooks, @swarm.name)
+        end
+      end
+
+      # Create Agent::Chat instance with rate limiting
+      #
+      # @param agent_name [Symbol] Agent name
+      # @param agent_definition [Agent::Definition] Agent definition object
+      # @param tool_configurator [ToolConfigurator] Tool configuration helper
+      # @return [Agent::Chat] Configured agent chat instance
+      def create_agent_chat(agent_name, agent_definition, tool_configurator)
+        chat = Agent::Chat.new(
+          definition: agent_definition.to_h,
+          global_semaphore: @global_semaphore,
+        )
+
+        # Set agent name on provider for logging (if provider supports it)
+        chat.provider.agent_name = agent_name if chat.provider.respond_to?(:agent_name=)
+
+        # Register tools using ToolConfigurator
+        tool_configurator.register_all_tools(
+          chat: chat,
+          agent_name: agent_name,
+          agent_definition: agent_definition,
+        )
+
+        # Register MCP servers using McpConfigurator
+        if agent_definition.mcp_servers.any?
+          mcp_configurator = McpConfigurator.new(@swarm)
+          mcp_configurator.register_mcp_servers(chat, agent_definition.mcp_servers, agent_name: agent_name)
+        end
+
+        chat
+      end
+
+      # Register agent delegation tools
+      #
+      # Creates delegation tools that allow one agent to call another.
+      #
+      # @param chat [Agent::Chat] The chat instance
+      # @param delegate_names [Array<Symbol>] Names of agents to delegate to
+      # @param agent_name [Symbol] Name of the agent doing the delegating
+      def register_delegation_tools(chat, delegate_names, agent_name:)
+        return if delegate_names.empty?
+
+        delegate_names.each do |delegate_name|
+          delegate_name = delegate_name.to_sym
+
+          unless @agents.key?(delegate_name)
+            raise ConfigurationError, "Agent delegates to unknown agent '#{delegate_name}'"
+          end
+
+          # Create a tool that delegates to the specified agent
+          delegate_agent = @agents[delegate_name]
+          delegate_definition = @agent_definitions[delegate_name]
+
+          tool = create_delegation_tool(
+            name: delegate_name.to_s,
+            description: delegate_definition.description,
+            delegate_chat: delegate_agent,
+            agent_name: agent_name,
+          )
+
+          chat.with_tool(tool)
+        end
+      end
+    end
+  end
+end

data/lib/swarm_sdk/swarm/all_agents_builder.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  class Swarm
+    # AllAgentsBuilder for configuring settings that apply to all agents
+    class AllAgentsBuilder
+      attr_reader :hooks, :permissions_config
+
+      def initialize
+        @tools_list = []
+        @hooks = []
+        @permissions_config = {}
+      end
+
+      # Get tools list
+      attr_reader :tools_list
+
+      # Add tools that all agents will have
+      def tools(*tool_names)
+        @tools_list.concat(tool_names)
+      end
+
+      # Add hook for all agents (agent-level events only)
+      #
+      # @example
+      #   hook :pre_tool_use, matcher: "Write" do |ctx|
+      #     # Applies to all agents
+      #   end
+      def hook(event, matcher: nil, command: nil, timeout: nil, &block)
+        # Validate agent-level events
+        agent_events = [
+          :pre_tool_use,
+          :post_tool_use,
+          :user_prompt,
+          :agent_stop,
+          :first_message,
+          :pre_delegation,
+          :post_delegation,
+          :context_warning,
+        ]
+
+        unless agent_events.include?(event)
+          raise ArgumentError, "Invalid all_agents hook: #{event}. Swarm-level events (:swarm_start, :swarm_stop) cannot be used in all_agents block."
+        end
+
+        @hooks << { event: event, matcher: matcher, command: command, timeout: timeout, block: block }
+      end
+
+      # Configure permissions for all agents
+      #
+      # @example
+      #   permissions do
+      #     Write.allow_paths "tmp/**/*"
+      #     Write.deny_paths "tmp/secrets/**"
+      #     Bash.allow_commands "^git status$"
+      #   end
+      def permissions(&block)
+        @permissions_config = PermissionsBuilder.build(&block)
+      end
+    end
+  end
+end

data/lib/swarm_sdk/swarm/builder.rb

@@ -0,0 +1,240 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  class Swarm
+    # Builder provides a beautiful Ruby DSL for building swarms
+    #
+    # The DSL combines YAML simplicity with Ruby power, enabling:
+    # - Fluent, chainable configuration
+    # - Hooks as Ruby blocks OR shell commands
+    # - Full Ruby language features (variables, conditionals, loops)
+    # - Type-safe, IDE-friendly API
+    #
+    # @example Basic usage
+    #   swarm = SwarmSDK.build do
+    #     name "Dev Team"
+    #     lead :backend
+    #
+    #     agent :backend do
+    #       model "gpt-5"
+    #       prompt "You build APIs"
+    #       tools :Read, :Write, :Bash
+    #
+    #       # Hook as Ruby block - inline logic!
+    #       hook :pre_tool_use, matcher: "Bash" do |ctx|
+    #         SwarmSDK::Hooks::Result.halt("Blocked!") if ctx.tool_call.parameters[:command].include?("rm -rf")
+    #       end
+    #     end
+    #   end
+    #
+    #   swarm.execute("Build auth API")
+    class Builder
+      # Main entry point for DSL
+      #
+      # @example
+      #   swarm = SwarmSDK.build do
+      #     name "Team"
+      #     agent :backend { ... }
+      #   end
+      class << self
+        def build(&block)
+          builder = new
+          builder.instance_eval(&block)
+          builder.build_swarm
+        end
+      end
+
+      def initialize
+        @swarm_name = nil
+        @lead_agent = nil
+        @agents = {}
+        @all_agents_config = nil
+        @swarm_hooks = []
+      end
+
+      # Set swarm name
+      def name(swarm_name)
+        @swarm_name = swarm_name
+      end
+
+      # Set lead agent
+      def lead(agent_name)
+        @lead_agent = agent_name
+      end
+
+      # Define an agent with fluent API
+      #
+      # @example
+      #   agent :backend do
+      #     model "gpt-5"
+      #     prompt "You build APIs"
+      #     tools :Read, :Write
+      #
+      #     hook :pre_tool_use, matcher: "Bash" do |ctx|
+      #       # Inline validation logic!
+      #     end
+      #   end
+      def agent(name, &block)
+        builder = Agent::Builder.new(name)
+        builder.instance_eval(&block)
+        @agents[name] = builder
+      end
+
+      # Add swarm-level hook (swarm_start, swarm_stop only)
+      #
+      # @example Shell command
+      #   hook :swarm_start, command: "echo 'Starting' >> log.txt"
+      #
+      # @example Ruby block
+      #   hook :swarm_start do |ctx|
+      #     puts "Swarm starting: #{ctx.metadata[:prompt]}"
+      #   end
+      def hook(event, command: nil, timeout: nil, &block)
+        # Validate swarm-level events
+        unless [:swarm_start, :swarm_stop].include?(event)
+          raise ArgumentError, "Invalid swarm-level hook: #{event}. Only :swarm_start and :swarm_stop allowed at swarm level. Use all_agents { hook ... } or agent { hook ... } for other events."
+        end
+
+        @swarm_hooks << { event: event, command: command, timeout: timeout, block: block }
+      end
+
+      # Configure all agents with a block
+      #
+      # @example
+      #   all_agents do
+      #     tools :Read, :Write
+      #
+      #     hook :pre_tool_use, matcher: "Write" do |ctx|
+      #       # Validation for all agents
+      #     end
+      #   end
+      def all_agents(&block)
+        builder = AllAgentsBuilder.new
+        builder.instance_eval(&block)
+        @all_agents_config = builder
+      end
+
+      # Build the actual Swarm instance
+      def build_swarm
+        raise ConfigurationError, "Swarm name not set. Use: name 'My Swarm'" unless @swarm_name
+        raise ConfigurationError, "Lead agent not set. Use: lead :agent_name" unless @lead_agent
+        raise ConfigurationError, "No agents defined. Use: agent :name { ... }" if @agents.empty?
+
+        # Create swarm using SDK
+        swarm = Swarm.new(name: @swarm_name)
+
+        # Merge all_agents config into each agent
+        merge_all_agents_config_into_agents if @all_agents_config
+
+        # Build definitions and add to swarm
+        @agents.each do |_agent_name, agent_builder|
+          definition = agent_builder.to_definition
+          swarm.add_agent(definition)
+        end
+
+        # Set lead
+        swarm.lead = @lead_agent
+
+        # Apply swarm hooks (Ruby blocks)
+        # These are swarm-level hooks (swarm_start, swarm_stop)
+        @swarm_hooks.each do |hook_config|
+          apply_swarm_hook(swarm, hook_config)
+        end
+
+        # Apply all_agents hooks (Ruby blocks)
+        # These become swarm-level default callbacks that apply to all agents
+        @all_agents_config&.hooks&.each do |hook_config|
+          apply_all_agents_hook(swarm, hook_config)
+        end
+
+        # NOTE: Agent-specific hooks are already stored in Agent::Definition.callbacks
+        # They'll be applied automatically during agent initialization (pass_4_configure_hooks)
+        # This ensures they're applied at the right time, after LogStream is set up
+
+        swarm
+      end
+
+      private
+
+      # Merge all_agents configuration into each agent
+      def merge_all_agents_config_into_agents
+        return unless @all_agents_config
+
+        @agents.each_value do |agent_builder|
+          # Merge tools (prepend all_agents tools)
+          all_agents_tools = @all_agents_config.tools_list
+          agent_builder.prepend_tools(*all_agents_tools) if all_agents_tools.any?
+
+          # Pass all_agents permissions as default_permissions
+          if @all_agents_config.permissions_config.any?
+            agent_builder.default_permissions = @all_agents_config.permissions_config
+          end
+        end
+      end
+
+      def apply_swarm_hook(swarm, config)
+        event = config[:event]
+
+        if config[:block]
+          # Ruby block hook - register directly
+          swarm.add_default_callback(event, &config[:block])
+        elsif config[:command]
+          # Shell command hook - use ShellExecutor
+          swarm.add_default_callback(event) do |context|
+            input_json = build_hook_input(context, event)
+            Hooks::ShellExecutor.execute(
+              command: config[:command],
+              input_json: input_json,
+              timeout: config[:timeout] || 60,
+              swarm_name: swarm.name,
+              event: event,
+            )
+          end
+        end
+      end
+
+      def apply_all_agents_hook(swarm, config)
+        event = config[:event]
+        matcher = config[:matcher]
+
+        if config[:block]
+          # Ruby block hook
+          swarm.add_default_callback(event, matcher: matcher, &config[:block])
+        elsif config[:command]
+          # Shell command hook
+          swarm.add_default_callback(event, matcher: matcher) do |context|
+            input_json = build_hook_input(context, event)
+            Hooks::ShellExecutor.execute(
+              command: config[:command],
+              input_json: input_json,
+              timeout: config[:timeout] || 60,
+              agent_name: context.agent_name,
+              swarm_name: swarm.name,
+              event: event,
+            )
+          end
+        end
+      end
+
+      def build_hook_input(context, event)
+        # Build JSON input for shell hooks (similar to HooksAdapter)
+        base = { event: event.to_s }
+
+        case event
+        when :pre_tool_use
+          base.merge(tool: context.tool_call.name, parameters: context.tool_call.parameters)
+        when :post_tool_use
+          base.merge(result: context.tool_result.content, success: context.tool_result.success?)
+        when :user_prompt
+          base.merge(prompt: context.metadata[:prompt])
+        when :swarm_start
+          base.merge(prompt: context.metadata[:prompt])
+        when :swarm_stop
+          base.merge(success: context.metadata[:success], duration: context.metadata[:duration])
+        else
+          base
+        end
+      end
+    end
+  end
+end

data/lib/swarm_sdk/swarm/mcp_configurator.rb

@@ -0,0 +1,151 @@
+# 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.with_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)
+        {
+          url: config[:url],
+          headers: config[:headers] || {},
+          version: config[:version]&.to_sym || :http2,
+          oauth: config[:oauth],
+          rate_limit: config[:rate_limit],
+        }
+      end
+    end
+  end
+end