swarm_sdk 2.6.2 → 2.7.0

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.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: swarm_sdk
 version: !ruby/object:Gem::Version
-  version: 2.6.2
+  version: 2.7.0
 platform: ruby
 authors:
 - Paulo Arruda
@@ -139,6 +139,7 @@ files:
 - lib/swarm_sdk/agent/definition.rb
 - lib/swarm_sdk/agent/llm_instrumentation_middleware.rb
 - lib/swarm_sdk/agent/system_prompt_builder.rb
+- lib/swarm_sdk/agent/tool_registry.rb
 - lib/swarm_sdk/agent_registry.rb
 - lib/swarm_sdk/builders/base_builder.rb
 - lib/swarm_sdk/claude_code_agent_adapter.rb
@@ -205,6 +206,7 @@ files:
 - lib/swarm_sdk/swarm/tool_configurator.rb
 - lib/swarm_sdk/swarm_loader.rb
 - lib/swarm_sdk/swarm_registry.rb
+- lib/swarm_sdk/tools/base.rb
 - lib/swarm_sdk/tools/bash.rb
 - lib/swarm_sdk/tools/clock.rb
 - lib/swarm_sdk/tools/delegate.rb
@@ -219,6 +221,7 @@ files:
 - lib/swarm_sdk/tools/image_extractors/docx_image_extractor.rb
 - lib/swarm_sdk/tools/image_extractors/pdf_image_extractor.rb
 - lib/swarm_sdk/tools/image_formats/tiff_builder.rb
+- lib/swarm_sdk/tools/mcp_tool_stub.rb
 - lib/swarm_sdk/tools/multi_edit.rb
 - lib/swarm_sdk/tools/path_resolver.rb
 - lib/swarm_sdk/tools/read.rb