swarm_sdk 2.6.2 → 2.7.0

data/lib/swarm_sdk/agent/tool_registry.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Agent
+    # Per-agent tool registry managing available and active tools
+    #
+    # ## Architecture
+    #
+    # - **Available tools**: All tool instances the agent CAN use (registry)
+    # - **Active tools**: Subset sent to LLM based on skill state
+    #
+    # ## Thread Safety
+    #
+    # Registry access is protected by Async::Semaphore for fiber-safe operations.
+    #
+    # @example Registering tools
+    #   registry = ToolRegistry.new
+    #   registry.register(Read.new, source: :builtin)
+    #   registry.register(delegate_tool, source: :delegation, metadata: { delegate_name: :backend })
+    #
+    # @example Getting active tools (no skill)
+    #   active = registry.active_tools(skill_state: nil)
+    #   # Returns ALL available tools
+    #
+    # @example Getting active tools (with skill)
+    #   skill_state = SkillState.new(  # From SwarmMemory plugin
+    #     file_path: "skill/audit.md",
+    #     tools: ["Read", "Grep"],
+    #     permissions: { "Bash" => { deny_commands: ["rm"] } }
+    #   )
+    #   active = registry.active_tools(skill_state: skill_state)
+    #   # Returns: skill's tools + non-removable tools
+    class ToolRegistry
+      # Tool metadata stored in registry
+      #
+      # @!attribute instance [r] Tool instance (possibly wrapped with permissions)
+      # @!attribute base_instance [r] Unwrapped tool instance (for skill permission override)
+      # @!attribute removable [r] Can be deactivated by skills
+      # @!attribute source [r] Tool source (:builtin, :delegation, :mcp, :plugin, :custom)
+      # @!attribute metadata [r] Source-specific metadata
+      ToolEntry = Data.define(:instance, :base_instance, :removable, :source, :metadata)
+
+      def initialize
+        @available_tools = {} # String name => ToolEntry
+        @mutex = Async::Semaphore.new(1) # Fiber-safe mutex
+      end
+
+      # Register a tool in the available tools registry
+      #
+      # @param tool [RubyLLM::Tool] Tool instance (possibly wrapped)
+      # @param base_tool [RubyLLM::Tool, nil] Unwrapped instance (for permission override)
+      # @param source [Symbol] Tool source (:builtin, :delegation, :mcp, :plugin, :custom)
+      # @param metadata [Hash] Source-specific metadata (server_name, plugin_name, etc.)
+      # @return [void]
+      #
+      # @example Register builtin tool
+      #   registry.register(Read.new, source: :builtin)
+      #
+      # @example Register delegation tool
+      #   registry.register(delegate_tool, source: :delegation, metadata: { delegate_name: :backend })
+      #
+      # @example Register MCP tool
+      #   registry.register(mcp_tool, source: :mcp, metadata: { server_name: "codebase" })
+      #
+      # @example Register with permission wrapper
+      #   wrapped_tool = PermissionWrapper.new(base_tool, permissions)
+      #   registry.register(wrapped_tool, base_tool: base_tool, source: :builtin)
+      def register(tool, base_tool: nil, source:, metadata: {})
+        @mutex.acquire do
+          # Infer removability from tool class
+          removable = tool.respond_to?(:removable?) ? tool.removable? : true
+
+          @available_tools[tool.name] = ToolEntry.new(
+            instance: tool,
+            base_instance: base_tool || tool, # If no base, use same instance
+            removable: removable,
+            source: source,
+            metadata: metadata,
+          )
+        end
+      end
+
+      # Unregister a tool (for testing/cleanup)
+      #
+      # @param name [String, Symbol] Tool name
+      # @return [ToolEntry, nil] Removed entry
+      def unregister(name)
+        @mutex.acquire do
+          @available_tools.delete(name.to_s)
+        end
+      end
+
+      # Get active tools based on skill state
+      #
+      # Returns Hash of tool instances ready for RubyLLM::Chat.
+      #
+      # Logic:
+      # - If skill_state is nil: Return ALL available tools
+      # - If skill_state restricts tools: Return skill's tools + non-removable tools
+      # - Skill permissions are applied during activation (wrapping base_instance)
+      #
+      # @param skill_state [Object, nil] Skill state object (from plugin), or nil for all
+      # @param tool_configurator [ToolConfigurator, nil] For permission wrapping
+      # @param agent_definition [Agent::Definition, nil] For permission wrapping
+      # @return [Hash{String => RubyLLM::Tool}] name => instance mapping
+      #
+      # @example No skill loaded - all tools
+      #   registry.active_tools(skill_state: nil)
+      #   # => { "Read" => <Read>, "WorkWithBackend" => <Delegate>, ... }
+      #
+      # @example Skill loaded with focused toolset
+      #   registry.active_tools(skill_state: skill_state)
+      #   # => { "Read" => <Read>, "WorkWithBackend" => <Delegate>, "Think" => <Think>, "MemoryRead" => <MemoryRead> }
+      #   # Includes: requested tools + non-removable tools
+      def active_tools(skill_state: nil, tool_configurator: nil, agent_definition: nil)
+        @mutex.acquire do
+          result = if skill_state&.restricts_tools?
+            # Skill loaded with tool restriction - only skill's tools + non-removable
+            filtered = {}
+
+            # Always include non-removable tools (use wrapped instance)
+            @available_tools.each do |name, entry|
+              filtered[name] = entry.instance unless entry.removable
+            end
+
+            # Add requested tools from skill
+            skill_state.tools.each do |name|
+              entry = @available_tools[name.to_s]
+              next unless entry
+
+              # Check if skill has custom permissions for this tool
+              skill_permissions = skill_state.permissions_for(name)
+
+              if skill_permissions && tool_configurator && agent_definition
+                # Skill overrides permissions - wrap the BASE instance
+                wrapped = tool_configurator.wrap_tool_with_permissions(
+                  entry.base_instance,
+                  skill_permissions,
+                  agent_definition,
+                )
+                filtered[name.to_s] = wrapped
+              else
+                # No skill permission override - use registered instance
+                filtered[name.to_s] = entry.instance
+              end
+            end
+
+            filtered
+          else
+            # No skill OR skill doesn't restrict tools - all available tools
+            @available_tools.transform_values(&:instance)
+          end
+
+          result
+        end
+      end
+
+      # Check if tool exists in registry
+      #
+      # @param name [String, Symbol] Tool name
+      # @return [Boolean]
+      def has_tool?(name)
+        @available_tools.key?(name.to_s)
+      end
+
+      # Get all available tool names
+      #
+      # @return [Array<String>]
+      def tool_names
+        @available_tools.keys
+      end
+
+      # Get tool entry with metadata
+      #
+      # @param name [String, Symbol] Tool name
+      # @return [ToolEntry, nil]
+      def get(name)
+        @available_tools[name.to_s]
+      end
+
+      # Get all non-removable tool names
+      #
+      # @return [Array<String>]
+      def non_removable_tool_names
+        @available_tools.select { |_name, entry| !entry.removable }.keys
+      end
+    end
+  end
+end

data/lib/swarm_sdk/builders/base_builder.rb

@@ -446,6 +446,10 @@ module SwarmSDK
         if !all_agents_hash[:coding_agent].nil? && !agent_builder.coding_agent_set?
           agent_builder.coding_agent(all_agents_hash[:coding_agent])
         end
+
+        if !all_agents_hash[:streaming].nil? && !agent_builder.streaming_set?
+          agent_builder.streaming(all_agents_hash[:streaming])
+        end
       end
 
       # Validate all_agents filesystem tools

data/lib/swarm_sdk/config.rb

@@ -94,6 +94,7 @@ module SwarmSDK
       webfetch_max_tokens: ["SWARM_SDK_WEBFETCH_MAX_TOKENS", 4096],
       allow_filesystem_tools: ["SWARM_SDK_ALLOW_FILESYSTEM_TOOLS", true],
       env_interpolation: ["SWARM_SDK_ENV_INTERPOLATION", true],
+      streaming: ["SWARM_SDK_STREAMING", true],
     }.freeze
 
     class << self
@@ -282,7 +283,7 @@ module SwarmSDK
     # @return [Integer, Float, Boolean, String] The parsed value
     def parse_env_value(value, key)
       case key
-      when :allow_filesystem_tools, :env_interpolation
+      when :allow_filesystem_tools, :env_interpolation, :streaming
         # Convert string to boolean
         case value.to_s.downcase
         when "true", "yes", "1", "on", "enabled"

data/lib/swarm_sdk/configuration/translator.rb

@@ -99,6 +99,7 @@ module SwarmSDK
           headers(all_agents_cfg[:headers]) if all_agents_cfg[:headers]
           coding_agent(all_agents_cfg[:coding_agent]) unless all_agents_cfg[:coding_agent].nil?
           disable_default_tools(all_agents_cfg[:disable_default_tools]) unless all_agents_cfg[:disable_default_tools].nil?
+          streaming(all_agents_cfg[:streaming]) unless all_agents_cfg[:streaming].nil?
 
           if all_agents_hks.any?
             all_agents_hks.each do |event, hook_specs|
@@ -162,6 +163,7 @@ module SwarmSDK
           bypass_permissions(config[:bypass_permissions]) if config[:bypass_permissions]
           disable_default_tools(config[:disable_default_tools]) unless config[:disable_default_tools].nil?
           shared_across_delegations(config[:shared_across_delegations]) unless config[:shared_across_delegations].nil?
+          streaming(config[:streaming]) unless config[:streaming].nil?
 
           if config[:tools]&.any?
             tool_names = config[:tools].map { |t| t.is_a?(Hash) ? t[:name] : t }

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