claude_swarm 1.0.9 → 1.0.11

data/lib/swarm_sdk/custom_tool_registry.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+require "delegate"
+
+module SwarmSDK
+  # Registry for user-defined custom tools
+  #
+  # Provides a simple way to register custom tools without creating a full plugin.
+  # Custom tools are registered globally and available to all agents that request them.
+  #
+  # ## When to Use Custom Tools vs Plugins
+  #
+  # **Use Custom Tools when:**
+  # - You have simple, stateless tools
+  # - Tools don't need persistent storage
+  # - Tools don't need lifecycle hooks
+  # - Tools don't need system prompt contributions
+  #
+  # **Use Plugins when:**
+  # - Tools need persistent storage per agent
+  # - Tools need lifecycle hooks (on_agent_initialized, on_user_message, etc.)
+  # - Tools need to contribute to system prompts
+  # - You have a suite of related tools that share configuration
+  #
+  # @example Register a simple tool
+  #   class WeatherTool < RubyLLM::Tool
+  #     description "Get weather for a city"
+  #     param :city, type: "string", required: true
+  #
+  #     def execute(city:)
+  #       "Weather in #{city}: Sunny"
+  #     end
+  #   end
+  #
+  #   SwarmSDK.register_tool(WeatherTool)
+  #
+  # @example Register with explicit name
+  #   SwarmSDK.register_tool(:Weather, WeatherTool)
+  #
+  # @example Tool with creation requirements
+  #   class AgentAwareTool < RubyLLM::Tool
+  #     def self.creation_requirements
+  #       [:agent_name, :directory]
+  #     end
+  #
+  #     def initialize(agent_name:, directory:)
+  #       super()
+  #       @agent_name = agent_name
+  #       @directory = directory
+  #     end
+  #
+  #     def execute
+  #       "Agent: #{@agent_name}, Dir: #{@directory}"
+  #     end
+  #   end
+  #
+  #   SwarmSDK.register_tool(AgentAwareTool)
+  #
+  module CustomToolRegistry
+    # Wrapper that overrides the tool's name to match the registered name
+    #
+    # This ensures that when a user registers a tool with a specific name,
+    # that name is what gets used for tool lookup (has_tool?) and LLM tool calls.
+    class NamedToolWrapper < SimpleDelegator
+      def initialize(tool, registered_name)
+        super(tool)
+        @registered_name = registered_name.to_s
+      end
+
+      # Override name to return the registered name
+      def name
+        @registered_name
+      end
+    end
+
+    @tools = {}
+
+    class << self
+      # Register a custom tool
+      #
+      # @param name [Symbol] Tool name
+      # @param tool_class [Class] Tool class (must be a RubyLLM::Tool subclass)
+      # @raise [ArgumentError] If tool_class is not a RubyLLM::Tool subclass
+      # @raise [ArgumentError] If a tool with the same name is already registered
+      # @return [void]
+      def register(name, tool_class)
+        name = name.to_sym
+
+        unless tool_class.is_a?(Class) && tool_class < RubyLLM::Tool
+          raise ArgumentError, "Tool class must inherit from RubyLLM::Tool"
+        end
+
+        if @tools.key?(name)
+          raise ArgumentError, "Custom tool '#{name}' is already registered"
+        end
+
+        if PluginRegistry.plugin_tool?(name)
+          raise ArgumentError, "Tool '#{name}' is already provided by a plugin"
+        end
+
+        if Tools::Registry.exists?(name)
+          raise ArgumentError, "Tool '#{name}' is a built-in tool and cannot be overridden"
+        end
+
+        @tools[name] = tool_class
+      end
+
+      # Check if a custom tool is registered
+      #
+      # @param name [Symbol, String] Tool name
+      # @return [Boolean]
+      def registered?(name)
+        @tools.key?(name.to_sym)
+      end
+
+      # Get a registered tool class
+      #
+      # @param name [Symbol, String] Tool name
+      # @return [Class, nil] Tool class or nil if not found
+      def get(name)
+        @tools[name.to_sym]
+      end
+
+      # Get all registered custom tool names
+      #
+      # @return [Array<Symbol>]
+      def tool_names
+        @tools.keys
+      end
+
+      # Create a tool instance
+      #
+      # Uses the tool's `creation_requirements` class method (if defined) to determine
+      # what parameters to pass to the constructor. The created tool is wrapped with
+      # NamedToolWrapper to ensure the registered name is used for tool lookup.
+      #
+      # @param name [Symbol, String] Tool name
+      # @param context [Hash] Available context for tool creation
+      # @option context [Symbol] :agent_name Agent identifier
+      # @option context [String] :directory Agent's working directory
+      # @return [RubyLLM::Tool] Instantiated tool (wrapped with registered name)
+      # @raise [ConfigurationError] If tool is unknown or has unmet requirements
+      def create(name, context = {})
+        name_sym = name.to_sym
+        tool_class = @tools[name_sym]
+
+        raise ConfigurationError, "Unknown custom tool: #{name}" unless tool_class
+
+        # Create the tool instance
+        tool = if tool_class.respond_to?(:creation_requirements)
+          requirements = tool_class.creation_requirements
+          params = extract_params(requirements, context, name)
+          tool_class.new(**params)
+        else
+          # No requirements - simple instantiation
+          tool_class.new
+        end
+
+        # Wrap with NamedToolWrapper to ensure registered name is used
+        NamedToolWrapper.new(tool, name_sym)
+      end
+
+      # Unregister a custom tool
+      #
+      # @param name [Symbol, String] Tool name
+      # @return [Class, nil] The unregistered tool class, or nil if not found
+      def unregister(name)
+        @tools.delete(name.to_sym)
+      end
+
+      # Clear all registered custom tools
+      #
+      # Primarily useful for testing.
+      #
+      # @return [void]
+      def clear
+        @tools.clear
+      end
+
+      # Infer tool name from class name
+      #
+      # @param tool_class [Class] Tool class
+      # @return [Symbol] Inferred tool name
+      #
+      # @example
+      #   infer_name(WeatherTool) #=> :Weather
+      #   infer_name(MyApp::Tools::StockPrice) #=> :StockPrice
+      #   infer_name(MyApp::Tools::StockPriceTool) #=> :StockPrice
+      def infer_name(tool_class)
+        # Get the class name without module prefix
+        class_name = tool_class.name.split("::").last
+
+        # Remove "Tool" suffix if present
+        name = class_name.sub(/Tool\z/, "")
+
+        name.to_sym
+      end
+
+      private
+
+      # Extract required parameters from context
+      #
+      # @param requirements [Array<Symbol>] Required parameter names
+      # @param context [Hash] Available context
+      # @param tool_name [Symbol] Tool name for error messages
+      # @return [Hash] Parameters to pass to tool constructor
+      # @raise [ConfigurationError] If required parameter is missing
+      def extract_params(requirements, context, tool_name)
+        params = {}
+
+        requirements.each do |req|
+          unless context.key?(req)
+            raise ConfigurationError,
+              "Custom tool '#{tool_name}' requires '#{req}' but it was not provided. " \
+                "Ensure the tool's `creation_requirements` only includes supported keys: " \
+                ":agent_name, :directory"
+          end
+
+          params[req] = context[req]
+        end
+
+        params
+      end
+    end
+  end
+end

data/lib/swarm_sdk/defaults.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  # Centralized configuration defaults for SwarmSDK
+  #
+  # This module provides well-documented default values for all configurable
+  # aspects of the SDK. Values are organized by category and include explanations
+  # for their purpose and rationale.
+  #
+  # @example Accessing defaults
+  #   SwarmSDK::Defaults::Timeouts::AGENT_REQUEST_SECONDS
+  #   SwarmSDK::Defaults::Concurrency::GLOBAL_LIMIT
+  #   SwarmSDK::Defaults::Limits::OUTPUT_CHARACTERS
+  module Defaults
+    # Concurrency limits for parallel execution
+    #
+    # These limits prevent overwhelming external services and ensure
+    # fair resource usage across the system.
+    module Concurrency
+      # Maximum concurrent API calls across entire swarm
+      #
+      # This limits total parallel LLM API requests to prevent rate limiting
+      # and excessive resource consumption. 50 is a balanced value that allows
+      # good parallelism while respecting API rate limits.
+      GLOBAL_LIMIT = 50
+
+      # Maximum parallel tool executions per agent
+      #
+      # Limits concurrent tool calls within a single agent. 10 allows
+      # meaningful parallelism (e.g., reading multiple files) without
+      # overwhelming the system.
+      LOCAL_LIMIT = 10
+    end
+
+    # Timeout values for various operations
+    #
+    # All timeouts are in seconds unless explicitly marked as milliseconds.
+    # Timeouts balance responsiveness with allowing enough time for operations
+    # to complete successfully.
+    module Timeouts
+      # LLM API request timeout (seconds)
+      #
+      # Default timeout for Claude/GPT API calls. 5 minutes accommodates
+      # reasoning models (o1, Claude with extended thinking) which can take
+      # longer to process complex queries.
+      AGENT_REQUEST_SECONDS = 300
+
+      # Bash command execution timeout (milliseconds)
+      #
+      # Default timeout for shell commands. 2 minutes balances allowing
+      # build/test commands while preventing runaway processes.
+      BASH_COMMAND_MS = 120_000
+
+      # Maximum Bash command timeout (milliseconds)
+      #
+      # Hard upper limit for bash commands. 10 minutes prevents indefinitely
+      # running commands while allowing long builds/tests.
+      BASH_COMMAND_MAX_MS = 600_000
+
+      # Web fetch timeout (seconds)
+      #
+      # Timeout for HTTP requests in WebFetch tool. 30 seconds is standard
+      # for web requests, allowing slow servers while timing out unresponsive ones.
+      WEB_FETCH_SECONDS = 30
+
+      # Shell hook executor timeout (seconds)
+      #
+      # Default timeout for hook shell commands. 60 seconds allows complex
+      # pre/post hooks while preventing indefinite blocking.
+      HOOK_SHELL_SECONDS = 60
+
+      # Workflow transformer command timeout (seconds)
+      #
+      # Timeout for input/output transformer bash commands. 60 seconds allows
+      # data transformation operations while preventing stalls.
+      TRANSFORMER_COMMAND_SECONDS = 60
+
+      # OpenAI responses API ID TTL (seconds)
+      #
+      # Time-to-live for cached response IDs. 5 minutes allows conversation
+      # continuity while preventing stale cache issues.
+      RESPONSES_API_TTL_SECONDS = 300
+    end
+
+    # Output and content size limits
+    #
+    # These limits prevent overwhelming context windows and ensure
+    # reasonable memory usage.
+    module Limits
+      # Maximum Bash output characters
+      #
+      # Truncates command output to prevent overwhelming agent context.
+      # 30,000 characters balances useful information with context constraints.
+      OUTPUT_CHARACTERS = 30_000
+
+      # Default lines to read from files
+      #
+      # When no explicit limit is set, Read tool returns first 2000 lines.
+      # This provides substantial file content while preventing huge files
+      # from overwhelming context.
+      READ_LINES = 2000
+
+      # Maximum characters per line in Read output
+      #
+      # Truncates very long lines to prevent single lines from consuming
+      # excessive context. 2000 characters per line is generous while
+      # protecting against minified files.
+      LINE_CHARACTERS = 2000
+
+      # Maximum WebFetch content length
+      #
+      # Limits web content fetched from URLs. 100,000 characters provides
+      # substantial page content while preventing huge pages from overwhelming context.
+      WEB_FETCH_CHARACTERS = 100_000
+
+      # Maximum Glob search results
+      #
+      # Limits number of file paths returned by Glob tool. 1000 results
+      # provides comprehensive search while preventing overwhelming output.
+      GLOB_RESULTS = 1000
+    end
+
+    # Storage limits for persistent data
+    module Storage
+      # Maximum size for single scratchpad entry (bytes)
+      #
+      # 3MB per entry prevents individual entries from consuming excessive storage
+      # while allowing substantial content (code, large texts).
+      ENTRY_SIZE_BYTES = 3_000_000
+
+      # Maximum total scratchpad storage (bytes)
+      #
+      # 100GB total storage provides ample room for extensive projects
+      # while preventing unbounded growth.
+      TOTAL_SIZE_BYTES = 100_000_000_000
+    end
+
+    # Context management settings
+    module Context
+      # Context usage percentage triggering compression warning
+      #
+      # When context usage reaches 60%, agents should consider compaction.
+      # This threshold provides buffer before hitting limits.
+      COMPRESSION_THRESHOLD_PERCENT = 60
+
+      # Message count between TodoWrite reminders
+      #
+      # After 8 messages without using TodoWrite, a gentle reminder is injected.
+      # Balances helpfulness without being annoying.
+      TODOWRITE_REMINDER_INTERVAL = 8
+    end
+
+    # Token estimation factors
+    #
+    # Used for approximate token counting when precise counts aren't available.
+    module TokenEstimation
+      # Characters per token for prose text
+      #
+      # Average of ~4 characters per token for natural language text.
+      # Based on empirical analysis of tokenization patterns.
+      CHARS_PER_TOKEN_PROSE = 4.0
+
+      # Characters per token for code
+      #
+      # Code tends to have shorter tokens due to symbols and operators.
+      # ~3.5 characters per token accounts for this density.
+      CHARS_PER_TOKEN_CODE = 3.5
+    end
+
+    # Logging configuration
+    module Logging
+      # Default MCP client log level
+      #
+      # WARN level suppresses verbose MCP client logs while still
+      # reporting important issues.
+      MCP_LOG_LEVEL = Logger::WARN
+    end
+
+    # Agent configuration defaults
+    #
+    # Default values for agent configuration when not explicitly specified.
+    module Agent
+      # Default LLM model identifier
+      #
+      # OpenAI's GPT-5 is used as the default model. This can be overridden
+      # per-agent or globally via all_agents configuration.
+      MODEL = "gpt-5"
+
+      # Default LLM provider
+      #
+      # OpenAI is the default provider. Supported providers include:
+      # openai, anthropic, gemini, deepseek, openrouter, bedrock, etc.
+      PROVIDER = "openai"
+    end
+  end
+end

data/lib/swarm_sdk/events_to_messages.rb

@@ -44,6 +44,7 @@ module SwarmSDK
   # - `agent_step`: Reconstructs assistant message with tool calls
   # - `agent_stop`: Reconstructs final assistant message
   # - `tool_result`: Reconstructs tool result message
+  # - `delegation_result`: Reconstructs tool result message from delegation
   class EventsToMessages
     class << self
       # Reconstruct messages for an agent from event stream
@@ -90,6 +91,8 @@ module SwarmSDK
           reconstruct_assistant_message(event)
         when "tool_result"
           reconstruct_tool_result_message(event)
+        when "delegation_result"
+          reconstruct_delegation_result_message(event)
         end
 
         messages << message if message
@@ -158,6 +161,21 @@ module SwarmSDK
       )
     end
 
+    # Reconstruct tool result message from delegation_result event
+    #
+    # delegation_result events are emitted when a delegation completes,
+    # and they should be converted to tool result messages in the conversation.
+    #
+    # @param event [Hash] delegation_result event
+    # @return [RubyLLM::Message] Tool result message
+    def reconstruct_delegation_result_message(event)
+      RubyLLM::Message.new(
+        role: :tool,
+        content: event[:result].to_s,
+        tool_call_id: event[:tool_call_id],
+      )
+    end
+
     # Parse timestamp string to Time object
     #
     # @param timestamp [String, nil] ISO 8601 timestamp

data/lib/swarm_sdk/hooks/adapter.rb

@@ -167,7 +167,7 @@ module SwarmSDK
         def create_hook_callback(hook_def, event_symbol, agent_name, swarm_name)
           # Support both string and symbol keys (YAML may be symbolized)
           command = hook_def[:command] || hook_def["command"]
-          timeout = hook_def[:timeout] || hook_def["timeout"] || ShellExecutor::DEFAULT_TIMEOUT
+          timeout = hook_def[:timeout] || hook_def["timeout"] || SwarmSDK.config.hook_shell_timeout
 
           lambda do |context|
             input_json = build_input_json(context, event_symbol, agent_name)
@@ -191,7 +191,7 @@ module SwarmSDK
         def create_all_agents_hook_callback(hook_def, event_symbol, swarm_name)
           # Support both string and symbol keys (YAML may be symbolized)
           command = hook_def[:command] || hook_def["command"]
-          timeout = hook_def[:timeout] || hook_def["timeout"] || ShellExecutor::DEFAULT_TIMEOUT
+          timeout = hook_def[:timeout] || hook_def["timeout"] || SwarmSDK.config.hook_shell_timeout
 
           lambda do |context|
             # Agent name comes from context
@@ -217,7 +217,7 @@ module SwarmSDK
         def create_swarm_hook_callback(hook_def, event_symbol, swarm_name)
           # Support both string and symbol keys (YAML may be symbolized)
           command = hook_def[:command] || hook_def["command"]
-          timeout = hook_def[:timeout] || hook_def["timeout"] || ShellExecutor::DEFAULT_TIMEOUT
+          timeout = hook_def[:timeout] || hook_def["timeout"] || SwarmSDK.config.hook_shell_timeout
 
           lambda do |context|
             input_json = build_swarm_input_json(context, event_symbol, swarm_name)

data/lib/swarm_sdk/hooks/shell_executor.rb

@@ -47,7 +47,7 @@ module SwarmSDK
     #   )
     #   # => Result (continue or halt based on exit code)
     class ShellExecutor
-      DEFAULT_TIMEOUT = 60
+      # NOTE: Timeout now accessed via SwarmSDK.config.hook_shell_timeout
 
       class << self
         # Execute a shell command hook
@@ -59,7 +59,9 @@ module SwarmSDK
         # @param swarm_name [String, nil] Swarm name for environment variables
         # @param event [Symbol] Event type for context-aware behavior
         # @return [Result] Result based on exit code (continue or halt)
-        def execute(command:, input_json:, timeout: DEFAULT_TIMEOUT, agent_name: nil, swarm_name: nil, event: nil)
+        def execute(command:, input_json:, timeout: nil, agent_name: nil, swarm_name: nil, event: nil)
+          timeout ||= SwarmSDK.config.hook_shell_timeout
+
           # Build environment variables
           env = build_environment(agent_name: agent_name, swarm_name: swarm_name)