swarm_sdk 2.6.2 → 2.7.1

data/lib/swarm_sdk/swarm/agent_initializer.rb

@@ -25,12 +25,13 @@ module SwarmSDK
 
       # Initialize all agents with their chat instances and tools
       #
-      # This implements a 5-pass algorithm:
+      # This implements a 6-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)
+      # 6. Activate tools (Plan 025: populate @llm_chat.tools from registry after plugins)
       #
       # @return [Hash] agents hash { agent_name => Agent::Chat }
       def initialize_all
@@ -39,6 +40,7 @@ module SwarmSDK
         pass_3_setup_contexts
         pass_4_configure_hooks
         pass_5_apply_yaml_hooks
+        pass_6_activate_tools # Plan 025: Activate tools after all plugins registered
 
         @agents
       end
@@ -261,7 +263,12 @@ module SwarmSDK
           custom_tool_name: custom_tool_name,
         )
 
-        delegator_chat.add_tool(tool)
+        # Register in tool registry (Plan 025)
+        delegator_chat.tool_registry.register(
+          tool,
+          source: :delegation,
+          metadata: { delegate_name: swarm_name, delegation_type: :swarm },
+        )
       end
 
       # Wire delegation to a local agent
@@ -311,7 +318,15 @@ module SwarmSDK
           custom_tool_name: custom_tool_name,
         )
 
-        delegator_chat.add_tool(tool)
+        # Register in tool registry (Plan 025)
+        delegator_chat.tool_registry.register(
+          tool,
+          source: :delegation,
+          metadata: {
+            delegate_name: delegate_name_sym,
+            delegation_mode: delegate_definition.shared_across_delegations ? :shared : :isolated,
+          },
+        )
       end
 
       # Pass 3: Setup agent contexts
@@ -447,6 +462,22 @@ module SwarmSDK
         Hooks::Adapter.apply_agent_hooks(chat, agent_name, hooks, @swarm.name)
       end
 
+      # Pass 6: Activate tools after all plugins have registered (Plan 025)
+      #
+      # This must be the LAST pass because:
+      # - Plugins register tools in on_agent_initialized (e.g., LoadSkill from memory plugin)
+      # - Tools must be activated AFTER all registration is complete
+      # - This populates @llm_chat.tools from the registry
+      #
+      # @return [void]
+      def pass_6_activate_tools
+        # Activate tools for PRIMARY agents
+        @agents.each_value(&:activate_tools_for_prompt)
+
+        # Activate tools for DELEGATION instances
+        @swarm.delegation_instances.each_value(&:activate_tools_for_prompt)
+      end
+
       # Create Agent::Chat instance with rate limiting
       #
       # @param agent_name [Symbol] Agent name
@@ -476,6 +507,15 @@ module SwarmSDK
           mcp_configurator.register_mcp_servers(chat, agent_definition.mcp_servers, agent_name: agent_name)
         end
 
+        # Setup tool activation dependencies (Plan 025)
+        chat.setup_tool_activation(
+          tool_configurator: tool_configurator,
+          agent_definition: agent_definition,
+        )
+
+        # NOTE: activate_tools_for_prompt is called in Pass 5 after all plugins
+        # have registered their tools (e.g., LoadSkill from memory plugin)
+
         chat
       end
 
@@ -517,9 +557,17 @@ module SwarmSDK
           )
         end
 
+        # Setup tool activation dependencies (Plan 025)
+        chat.setup_tool_activation(
+          tool_configurator: tool_configurator,
+          agent_definition: agent_definition,
+        )
+
         # Notify plugins (use instance_name, plugins extract base_name if needed)
         notify_plugins_agent_initialized(instance_name.to_sym, chat, agent_definition, tool_configurator)
 
+        # NOTE: activate_tools_for_prompt is called in Pass 6 after all plugins
+
         chat
       end
 

data/lib/swarm_sdk/swarm/all_agents_builder.rb

@@ -35,6 +35,7 @@ module SwarmSDK
         @headers = nil
         @coding_agent = nil
         @disable_default_tools = nil
+        @streaming = nil
       end
 
       # Set model for all agents
@@ -91,6 +92,13 @@ module SwarmSDK
         @disable_default_tools = value
       end
 
+      # Enable or disable streaming for all agents
+      #
+      # @param value [Boolean] If true, enables streaming; if false, disables it
+      def streaming(value)
+        @streaming = value
+      end
+
       # Add tools that all agents will have
       def tools(*tool_names)
         @tools_list.concat(tool_names)
@@ -165,6 +173,7 @@ module SwarmSDK
           headers: @headers,
           coding_agent: @coding_agent,
           disable_default_tools: @disable_default_tools,
+          streaming: @streaming,
           tools: @tools_list,
           permissions: @permissions_config,
         }.compact

data/lib/swarm_sdk/swarm/mcp_configurator.rb

@@ -22,9 +22,22 @@ module SwarmSDK
       # 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?
 
@@ -37,14 +50,39 @@ module SwarmSDK
           # 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}")
+          tools_config = server_config[:tools]
+
+          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
+            all_tools.each do |tool|
+              chat.tool_registry.register(
+                tool,
+                source: :mcp,
+                metadata: { server_name: server_config[:name] },
+              )
+            end
+            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)
+            tools_config.each do |tool_name|
+              stub = Tools::McpToolStub.new(
+                client: client,
+                name: tool_name.to_s,
+              )
+              chat.tool_registry.register(
+                stub,
+                source: :mcp,
+                metadata: { server_name: server_config[:name] },
+              )
+            end
+            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.message}")
+          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

data/lib/swarm_sdk/swarm/tool_configurator.rb

@@ -219,9 +219,17 @@ module SwarmSDK
       # @param permissions_config [Hash, nil] Permissions configuration
       # @param agent_definition [Agent::Definition] Agent definition
       # @return [void]
-      def wrap_and_add_tool(chat, tool_instance, permissions_config, agent_definition)
-        tool_instance = wrap_tool_with_permissions(tool_instance, permissions_config, agent_definition)
-        chat.add_tool(tool_instance)
+      def wrap_and_add_tool(chat, tool_instance, permissions_config, agent_definition, source: :builtin, metadata: {})
+        base_tool = tool_instance # Keep reference to unwrapped tool
+        wrapped_tool = wrap_tool_with_permissions(tool_instance, permissions_config, agent_definition)
+
+        # Register in tool registry (Plan 025)
+        chat.tool_registry.register(
+          wrapped_tool,
+          base_tool: base_tool,
+          source: source,
+          metadata: metadata.merge(permissions: permissions_config),
+        )
       end
 
       # Resolve permissions for a default/plugin tool
@@ -301,7 +309,14 @@ module SwarmSDK
 
             permissions_config = resolve_default_permissions(tool_name, agent_definition)
 
-            wrap_and_add_tool(chat, tool_instance, permissions_config, agent_definition)
+            wrap_and_add_tool(
+              chat,
+              tool_instance,
+              permissions_config,
+              agent_definition,
+              source: :plugin,
+              metadata: { plugin_name: plugin.class.name },
+            )
           end
         end
       end
@@ -364,7 +379,12 @@ module SwarmSDK
             delegating_chat: chat,
           )
 
-          chat.add_tool(tool)
+          # Register in tool registry (Plan 025)
+          chat.tool_registry.register(
+            tool,
+            source: :delegation,
+            metadata: { delegate_name: delegate_name },
+          )
         end
       end
     end

data/lib/swarm_sdk/tools/base.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Tools
+    # Base class for all SwarmSDK tools
+    #
+    # Provides:
+    # - Declarative removability control
+    # - Common tool functionality
+    # - Standard initialization patterns
+    #
+    # ## Removability
+    #
+    # Tools can be marked as non-removable to ensure they're always available:
+    #
+    #   class Think < Base
+    #     removable false
+    #   end
+    #
+    # Non-removable tools are included even when skills specify a limited toolset.
+    #
+    # @example Removable tool (default)
+    #   class Read < Base
+    #     # removable true  # Default, can omit
+    #   end
+    #
+    # @example Non-removable tool
+    #   class Think < Base
+    #     removable false  # Always available
+    #   end
+    class Base < RubyLLM::Tool
+      class << self
+        # Whether this tool can be deactivated by LoadSkill
+        #
+        # Non-removable tools are ALWAYS active regardless of skill toolset.
+        # Use for essential tools that agents should never lose.
+        #
+        # @return [Boolean] True if removable (default: true)
+        def removable?
+          @removable.nil? ? true : @removable
+        end
+
+        # Mark tool as removable or non-removable
+        #
+        # @param value [Boolean] Whether tool can be removed
+        # @return [void]
+        #
+        # @example Make tool always available
+        #   removable false
+        def removable(value)
+          @removable = value
+        end
+      end
+
+      # Instance method for checking removability
+      #
+      # @return [Boolean]
+      def removable?
+        self.class.removable?
+      end
+    end
+  end
+end

data/lib/swarm_sdk/tools/bash.rb

@@ -6,7 +6,7 @@ module SwarmSDK
     #
     # Executes commands in a persistent shell session with timeout support.
     # Provides comprehensive guidance on proper usage patterns.
-    class Bash < RubyLLM::Tool
+    class Bash < Base
       # Factory pattern: declare what parameters this tool needs for instantiation
       class << self
         def creation_requirements

data/lib/swarm_sdk/tools/clock.rb

@@ -6,7 +6,9 @@ module SwarmSDK
     #
     # Returns current temporal information in a consistent format.
     # Agents use this when they need to know what day/time it is.
-    class Clock < RubyLLM::Tool
+    class Clock < Base
+      removable false # Clock is always available
+
       description <<~DESC
         Get current date and time.
 

data/lib/swarm_sdk/tools/delegate.rb

@@ -7,7 +7,8 @@ module SwarmSDK
     # Creates agent-specific collaboration tools (e.g., WorkWithBackend)
     # that allow one agent to work with another agent.
     # Supports pre/post delegation hooks for customization.
-    class Delegate < RubyLLM::Tool
+    class Delegate < Base
+      removable true # Delegate tools can be controlled by skills
       # Tool name prefix for delegation tools
       # Change this to customize the tool naming pattern (e.g., "DelegateTaskTo", "AskAgent", etc.)
       TOOL_NAME_PREFIX = "WorkWith"
@@ -19,10 +20,20 @@ module SwarmSDK
         # Used both when creating Delegate instances and when predicting tool names
         # for agent context setup.
         #
+        # Converts names to PascalCase: backend → Backend, slack_agent → SlackAgent
+        #
         # @param delegate_name [String, Symbol] Name of the delegate agent
-        # @return [String] Tool name (e.g., "WorkWithBackend")
+        # @return [String] Tool name (e.g., "WorkWithBackend", "WorkWithSlackAgent")
+        #
+        # @example Simple name
+        #   tool_name_for(:backend) # => "WorkWithBackend"
+        #
+        # @example Name with underscore
+        #   tool_name_for(:slack_agent) # => "WorkWithSlackAgent"
         def tool_name_for(delegate_name)
-          "#{TOOL_NAME_PREFIX}#{delegate_name.to_s.capitalize}"
+          # Convert to PascalCase: split on underscore, capitalize each part, join
+          pascal_case = delegate_name.to_s.split("_").map(&:capitalize).join
+          "#{TOOL_NAME_PREFIX}#{pascal_case}"
         end
       end
 

data/lib/swarm_sdk/tools/edit.rb

@@ -7,7 +7,7 @@ module SwarmSDK
     # Uses exact string matching to find and replace content.
     # Requires unique matches and proper Read tool usage beforehand.
     # Enforces read-before-edit rule.
-    class Edit < RubyLLM::Tool
+    class Edit < Base
       include PathResolver
 
       # Factory pattern: declare what parameters this tool needs for instantiation

data/lib/swarm_sdk/tools/glob.rb

@@ -6,7 +6,7 @@ module SwarmSDK
     #
     # Finds files and directories matching glob patterns, sorted by modification time.
     # Works efficiently with any codebase size.
-    class Glob < RubyLLM::Tool
+    class Glob < Base
       include PathResolver
 
       # Factory pattern: declare what parameters this tool needs for instantiation

data/lib/swarm_sdk/tools/grep.rb

@@ -6,7 +6,7 @@ module SwarmSDK
     #
     # Powerful search capabilities with regex support, context lines, and filtering.
     # Built on ripgrep (rg) for fast, efficient searching.
-    class Grep < RubyLLM::Tool
+    class Grep < Base
       include PathResolver
 
       # Factory pattern: declare what parameters this tool needs for instantiation

data/lib/swarm_sdk/tools/mcp_tool_stub.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Tools
+    # Lazy-loading wrapper for MCP tools
+    #
+    # Creates minimal tool stub without calling tools/list.
+    # Schema is fetched on-demand when LLM needs it.
+    #
+    # ## Boot Optimization
+    #
+    # When MCP server tools are pre-specified in configuration:
+    # - Boot time: Create stubs instantly (no RPC)
+    # - First LLM request: Fetch schema lazily (~100ms one-time cost)
+    # - Subsequent requests: Use cached schema (instant)
+    #
+    # ## Thread Safety
+    #
+    # Schema loading is protected by Async::Semaphore with double-check pattern
+    # to ensure only one fiber fetches the schema even under concurrent access.
+    #
+    # @example Creating a stub
+    #   coordinator = RubyLLM::MCP::Coordinator.new(client)
+    #   stub = McpToolStub.new(
+    #     coordinator: coordinator,
+    #     name: "search_code",
+    #     description: "Search code in repository"
+    #   )
+    #
+    # @example Schema is fetched lazily
+    #   stub.params_schema  # First access triggers tools/list RPC
+    #   stub.params_schema  # Cached, instant
+    class McpToolStub < Base
+      removable true # MCP tools can be controlled by skills
+
+      attr_reader :name, :client
+
+      # Create a new MCP tool stub
+      #
+      # @param client [RubyLLM::MCP::Client] MCP client instance
+      # @param name [String] Tool name
+      # @param description [String, nil] Tool description (optional, fetched if nil)
+      # @param schema [Hash, nil] Tool input schema (optional, fetched if nil)
+      #
+      # @example Minimal stub (lazy description + schema)
+      #   McpToolStub.new(client: client, name: "search")
+      #
+      # @example With description (lazy schema only)
+      #   McpToolStub.new(
+      #     client: client,
+      #     name: "search",
+      #     description: "Search the codebase"
+      #   )
+      #
+      # @example Fully specified (no lazy loading)
+      #   McpToolStub.new(
+      #     client: client,
+      #     name: "search",
+      #     description: "Search the codebase",
+      #     schema: { type: "object", properties: {...} }
+      #   )
+      def initialize(client:, name:, description: nil, schema: nil)
+        super()
+        @client = client
+        @name = name
+        @mcp_name = name
+        @description = description || "MCP tool: #{name}"
+        @input_schema = schema
+        @schema_loaded = !schema.nil?
+        @schema_mutex = Async::Semaphore.new(1) # Thread-safe schema loading
+      end
+
+      # Get tool description
+      #
+      # @return [String]
+      attr_reader :description
+
+      # Get parameter schema (lazy-loaded on first access)
+      #
+      # This method is called by RubyLLM when building tool schemas for LLM requests.
+      # On first access, it triggers a tools/list RPC to fetch the schema.
+      #
+      # @return [Hash, nil] JSON Schema for tool parameters
+      def params_schema
+        ensure_schema_loaded!
+        @input_schema
+      end
+
+      # Execute the MCP tool
+      #
+      # Calls the MCP server's tools/call endpoint with the provided parameters.
+      # Schema is NOT required for execution - the server validates parameters.
+      #
+      # @param params [Hash] Tool parameters
+      # @return [String, Hash] Tool result content or error hash
+      def execute(**params)
+        # Use client.call_tool (client has internal coordinator)
+        result = @client.call_tool(
+          name: @mcp_name,
+          arguments: params,
+        )
+
+        # client.call_tool returns the result content directly
+        result
+      end
+
+      private
+
+      # Lazy-load schema on first access (when LLM needs it)
+      #
+      # Thread-safe via semaphore with double-check pattern.
+      # Multiple concurrent fibers will only trigger one fetch.
+      #
+      # @return [void]
+      def ensure_schema_loaded!
+        return if @schema_loaded
+
+        @schema_mutex.acquire do
+          return if @schema_loaded # Double-check after acquiring lock
+
+          # Fetch tool info from client (calls tools/list if not cached)
+          tool_info = @client.tool_info(@mcp_name)
+
+          if tool_info
+            @description = tool_info["description"] || @description
+            @input_schema = tool_info["inputSchema"]
+          else
+            # Tool doesn't exist on server - schema remains nil
+            RubyLLM.logger.warn("SwarmSDK: MCP tool '#{@mcp_name}' not found on server during schema fetch")
+          end
+
+          @schema_loaded = true
+        end
+      end
+    end
+  end
+end

data/lib/swarm_sdk/tools/multi_edit.rb

@@ -8,7 +8,7 @@ module SwarmSDK
     # Each edit sees the result of all previous edits, allowing for
     # coordinated multi-step transformations.
     # Enforces read-before-edit rule.
-    class MultiEdit < RubyLLM::Tool
+    class MultiEdit < Base
       include PathResolver
 
       # Factory pattern: declare what parameters this tool needs for instantiation

data/lib/swarm_sdk/tools/read.rb

@@ -7,7 +7,7 @@ module SwarmSDK
     # Supports reading entire files or specific line ranges with line numbers.
     # Provides system reminders to guide proper usage.
     # Tracks reads per agent for enforcing read-before-write/edit rules.
-    class Read < RubyLLM::Tool
+    class Read < Base
       include PathResolver
 
       # NOTE: Line length and limit now accessed via SwarmSDK.config

data/lib/swarm_sdk/tools/scratchpad/scratchpad_list.rb

@@ -7,7 +7,7 @@ module SwarmSDK
       #
       # Shows all entries in the shared scratchpad with their metadata.
       # All agents in the swarm share the same scratchpad.
-      class ScratchpadList < RubyLLM::Tool
+      class ScratchpadList < Base
         define_method(:name) { "ScratchpadList" }
 
         description <<~DESC

data/lib/swarm_sdk/tools/scratchpad/scratchpad_read.rb

@@ -7,7 +7,7 @@ module SwarmSDK
       #
       # Retrieves content stored by any agent using scratchpad_write.
       # All agents in the swarm share the same scratchpad.
-      class ScratchpadRead < RubyLLM::Tool
+      class ScratchpadRead < Base
         define_method(:name) { "ScratchpadRead" }
 
         description <<~DESC

data/lib/swarm_sdk/tools/scratchpad/scratchpad_write.rb

@@ -8,7 +8,7 @@ module SwarmSDK
       # Stores content in volatile, shared storage for temporary communication.
       # All agents in the swarm share the same scratchpad.
       # Data is lost when the process ends (not persisted).
-      class ScratchpadWrite < RubyLLM::Tool
+      class ScratchpadWrite < Base
         define_method(:name) { "ScratchpadWrite" }
 
         description <<~DESC

data/lib/swarm_sdk/tools/think.rb

@@ -11,7 +11,9 @@ module SwarmSDK
     # This is inspired by research showing that explicitly articulating reasoning steps
     # (chain-of-thought prompting) leads to significantly better outcomes, especially
     # for complex tasks requiring multi-step reasoning or arithmetic.
-    class Think < RubyLLM::Tool
+    class Think < Base
+      removable false # Think is always available
+
       def name
         "Think"
       end

data/lib/swarm_sdk/tools/todo_write.rb

@@ -6,7 +6,9 @@ module SwarmSDK
     #
     # This tool helps agents track progress on complex multi-step tasks.
     # Each agent maintains its own independent todo list.
-    class TodoWrite < RubyLLM::Tool
+    class TodoWrite < Base
+      removable false # TodoWrite is always available
+
       # Factory pattern: declare what parameters this tool needs for instantiation
       class << self
         def creation_requirements

data/lib/swarm_sdk/tools/web_fetch.rb

@@ -6,7 +6,7 @@ module SwarmSDK
     #
     # Fetches content from URLs, converts HTML to markdown, and processes it
     # using an AI model to extract information based on a provided prompt.
-    class WebFetch < RubyLLM::Tool
+    class WebFetch < Base
       def initialize
         super()
         @cache = {}

data/lib/swarm_sdk/tools/write.rb

@@ -7,7 +7,7 @@ module SwarmSDK
     # Creates new files or overwrites existing files.
     # Enforces read-before-write rule for existing files.
     # Includes validation and usage guidelines via system reminders.
-    class Write < RubyLLM::Tool
+    class Write < Base
       include PathResolver
 
       # Factory pattern: declare what parameters this tool needs for instantiation

data/lib/swarm_sdk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SwarmSDK
-  VERSION = "2.6.2"
+  VERSION = "2.7.1"
 end