swarm_sdk 2.2.0 → 2.4.0

data/lib/swarm_sdk/tools/bash.rb

@@ -7,6 +7,13 @@ module SwarmSDK
     # Executes commands in a persistent shell session with timeout support.
     # Provides comprehensive guidance on proper usage patterns.
     class Bash < RubyLLM::Tool
+      # Factory pattern: declare what parameters this tool needs for instantiation
+      class << self
+        def creation_requirements
+          [:directory]
+        end
+      end
+
       def initialize(directory:)
         super()
         @directory = File.expand_path(directory)
@@ -78,9 +85,7 @@ module SwarmSDK
         desc: "Optional timeout in milliseconds (max 600000)",
         required: false
 
-      DEFAULT_TIMEOUT_MS = 120_000 # 2 minutes
-      MAX_TIMEOUT_MS = 600_000 # 10 minutes
-      MAX_OUTPUT_LENGTH = 30_000 # characters
+      # NOTE: Timeout and output limits now accessed via SwarmSDK.config
 
       # Commands that are ALWAYS blocked for safety reasons
       # These cannot be overridden by permissions configuration
@@ -99,8 +104,8 @@ module SwarmSDK
         end
 
         # Validate and set timeout
-        timeout_ms = timeout || DEFAULT_TIMEOUT_MS
-        timeout_ms = [timeout_ms, MAX_TIMEOUT_MS].min
+        timeout_ms = timeout || SwarmSDK.config.bash_command_timeout
+        timeout_ms = [timeout_ms, SwarmSDK.config.bash_command_max_timeout].min
         timeout_seconds = timeout_ms / 1000.0
 
         # Execute command with timeout
@@ -141,9 +146,10 @@ module SwarmSDK
         output = format_command_output(command, description, stdout, stderr, exit_status)
 
         # Truncate if too long
-        if output.length > MAX_OUTPUT_LENGTH
-          truncated = output[0...MAX_OUTPUT_LENGTH]
-          truncated += "\n\n<system-reminder>Output truncated at #{MAX_OUTPUT_LENGTH} characters. The full output was #{output.length} characters.</system-reminder>"
+        max_output = SwarmSDK.config.output_character_limit
+        if output.length > max_output
+          truncated = output[0...max_output]
+          truncated += "\n\n<system-reminder>Output truncated at #{max_output} characters. The full output was #{output.length} characters.</system-reminder>"
           output = truncated
         end
 

data/lib/swarm_sdk/tools/delegate.rb

@@ -2,12 +2,30 @@
 
 module SwarmSDK
   module Tools
-    # Delegate tool for delegating tasks to other agents in the swarm
+    # Delegate tool for working with other agents in the swarm
     #
-    # Creates agent-specific delegation tools (e.g., DelegateTaskToBackend)
-    # that allow one agent to delegate work to another agent.
+    # 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
+      # Tool name prefix for delegation tools
+      # Change this to customize the tool naming pattern (e.g., "DelegateTaskTo", "AskAgent", etc.)
+      TOOL_NAME_PREFIX = "WorkWith"
+
+      class << self
+        # Generate tool name for a delegate agent
+        #
+        # This is the single source of truth for delegation tool naming.
+        # Used both when creating Delegate instances and when predicting tool names
+        # for agent context setup.
+        #
+        # @param delegate_name [String, Symbol] Name of the delegate agent
+        # @return [String] Tool name (e.g., "WorkWithBackend")
+        def tool_name_for(delegate_name)
+          "#{TOOL_NAME_PREFIX}#{delegate_name.to_s.capitalize}"
+        end
+      end
+
       attr_reader :delegate_name, :delegate_target, :tool_name
 
       # Initialize a delegation tool
@@ -16,10 +34,7 @@ module SwarmSDK
       # @param delegate_description [String] Description of the delegate agent
       # @param delegate_chat [AgentChat, nil] The chat instance for the delegate agent (nil if delegating to swarm)
       # @param agent_name [Symbol, String] Name of the agent using this tool
-      # @param swarm [Swarm] The swarm instance
-      # @param hook_registry [Hooks::Registry] Registry for callbacks
-      # @param call_stack [Array] Delegation call stack for circular dependency detection
-      # @param swarm_registry [SwarmRegistry, nil] Registry for sub-swarms (nil if not using composable swarms)
+      # @param swarm [Swarm] The swarm instance (provides hook_registry, delegation_call_stack, swarm_registry)
       # @param delegating_chat [Agent::Chat, nil] The chat instance of the agent doing the delegating (for accessing hooks)
       def initialize(
         delegate_name:,
@@ -27,9 +42,6 @@ module SwarmSDK
         delegate_chat:,
         agent_name:,
         swarm:,
-        hook_registry:,
-        call_stack:,
-        swarm_registry: nil,
         delegating_chat: nil
       )
         super()
@@ -39,24 +51,21 @@ module SwarmSDK
         @delegate_chat = delegate_chat
         @agent_name = agent_name
         @swarm = swarm
-        @hook_registry = hook_registry
-        @call_stack = call_stack
-        @swarm_registry = swarm_registry
         @delegating_chat = delegating_chat
 
-        # Generate tool name in the expected format: DelegateTaskTo[AgentName]
-        @tool_name = "DelegateTaskTo#{delegate_name.to_s.capitalize}"
+        # Generate tool name using canonical method
+        @tool_name = self.class.tool_name_for(delegate_name)
         @delegate_target = delegate_name.to_s
       end
 
       # Override description to return dynamic string based on delegate
       def description
-        "Delegate tasks to #{@delegate_name}. #{@delegate_description}"
+        "Work with #{@delegate_name} to delegate work, ask questions, or collaborate. #{@delegate_description}"
       end
 
-      param :task,
+      param :message,
         type: "string",
-        desc: "Task description for the agent",
+        desc: "Message to send to the agent - can be a work request, question, or collaboration message",
         required: true
 
       # Override name to return custom delegation tool name
@@ -66,13 +75,18 @@ module SwarmSDK
 
       # Execute delegation with pre/post hooks
       #
-      # @param task [String] Task to delegate
+      # @param message [String] Message to send to the agent
       # @return [String] Result from delegate agent or error message
-      def execute(task:)
+      def execute(message:)
+        # Access swarm infrastructure
+        call_stack = @swarm.delegation_call_stack
+        hook_registry = @swarm.hook_registry
+        swarm_registry = @swarm.swarm_registry
+
         # Check for circular dependency
-        if @call_stack.include?(@delegate_target)
-          emit_circular_warning
-          return "Error: Circular delegation detected: #{@call_stack.join(" -> ")} -> #{@delegate_target}. " \
+        if call_stack.include?(@delegate_target)
+          emit_circular_warning(call_stack)
+          return "Error: Circular delegation detected: #{call_stack.join(" -> ")} -> #{@delegate_target}. " \
             "Please restructure your delegation to avoid infinite loops."
         end
 
@@ -91,12 +105,12 @@ module SwarmSDK
           delegation_target: @delegate_target,
           metadata: {
             tool_name: @tool_name,
-            task: task,
+            message: message,
             timestamp: Time.now.utc.iso8601,
           },
         )
 
-        executor = Hooks::Executor.new(@hook_registry, logger: RubyLLM.logger)
+        executor = Hooks::Executor.new(hook_registry, logger: RubyLLM.logger)
         pre_agent_hooks = agent_hooks[:pre_delegation] || []
         result = executor.execute_safe(event: :pre_delegation, context: context, callbacks: pre_agent_hooks)
 
@@ -110,10 +124,10 @@ module SwarmSDK
         # Determine delegation type and proceed
         delegation_result = if @delegate_chat
           # Delegate to agent
-          delegate_to_agent(task)
-        elsif @swarm_registry&.registered?(@delegate_target)
+          delegate_to_agent(message, call_stack)
+        elsif swarm_registry&.registered?(@delegate_target)
           # Delegate to registered swarm
-          delegate_to_swarm(task)
+          delegate_to_swarm(message, call_stack, swarm_registry)
         else
           raise ConfigurationError, "Unknown delegation target: #{@delegate_target}"
         end
@@ -127,7 +141,7 @@ module SwarmSDK
           delegation_result: delegation_result,
           metadata: {
             tool_name: @tool_name,
-            task: task,
+            message: message,
             result: delegation_result,
             timestamp: Time.now.utc.iso8601,
           },
@@ -190,57 +204,61 @@ module SwarmSDK
 
       # Delegate to an agent
       #
-      # @param task [String] Task to delegate
+      # @param message [String] Message to send to the agent
+      # @param call_stack [Array] Delegation call stack for circular dependency detection
       # @return [String] Result from agent
-      def delegate_to_agent(task)
+      def delegate_to_agent(message, call_stack)
         # Push delegate target onto call stack to track delegation chain
-        @call_stack.push(@delegate_target)
+        call_stack.push(@delegate_target)
         begin
-          response = @delegate_chat.ask(task)
+          response = @delegate_chat.ask(message, source: "delegation")
           response.content
         ensure
           # Always pop from stack, even if delegation fails
-          @call_stack.pop
+          call_stack.pop
         end
       end
 
       # Delegate to a registered swarm
       #
-      # @param task [String] Task to delegate
+      # @param message [String] Message to send to the swarm
+      # @param call_stack [Array] Delegation call stack for circular dependency detection
+      # @param swarm_registry [SwarmRegistry] Registry for sub-swarms
       # @return [String] Result from swarm's lead agent
-      def delegate_to_swarm(task)
+      def delegate_to_swarm(message, call_stack, swarm_registry)
         # Load sub-swarm (lazy load + cache)
-        subswarm = @swarm_registry.load_swarm(@delegate_target)
+        subswarm = swarm_registry.load_swarm(@delegate_target)
 
         # Push delegate target onto call stack to track delegation chain
-        @call_stack.push(@delegate_target)
+        call_stack.push(@delegate_target)
         begin
           # Execute sub-swarm's lead agent
           lead_agent = subswarm.agents[subswarm.lead_agent]
-          response = lead_agent.ask(task)
+          response = lead_agent.ask(message, source: "delegation")
           result = response.content
 
           # Reset if keep_context: false
-          @swarm_registry.reset_if_needed(@delegate_target)
+          swarm_registry.reset_if_needed(@delegate_target)
 
           result
         ensure
           # Always pop from stack, even if delegation fails
-          @call_stack.pop
+          call_stack.pop
         end
       end
 
       # Emit circular dependency warning event
       #
+      # @param call_stack [Array] Current delegation call stack
       # @return [void]
-      def emit_circular_warning
+      def emit_circular_warning(call_stack)
         LogStream.emit(
           type: "delegation_circular_dependency",
           agent: @agent_name,
           swarm_id: @swarm.swarm_id,
           parent_swarm_id: @swarm.parent_swarm_id,
           target: @delegate_target,
-          call_stack: @call_stack,
+          call_stack: call_stack,
           timestamp: Time.now.utc.iso8601,
         )
       end

data/lib/swarm_sdk/tools/edit.rb

@@ -10,6 +10,13 @@ module SwarmSDK
     class Edit < RubyLLM::Tool
       include PathResolver
 
+      # Factory pattern: declare what parameters this tool needs for instantiation
+      class << self
+        def creation_requirements
+          [:agent_name, :directory]
+        end
+      end
+
       description <<~DESC
         Performs exact string replacements in files.
         You must use your Read tool at least once in the conversation before editing.
@@ -55,8 +62,7 @@ module SwarmSDK
       # @param directory [String] Agent's working directory
       def initialize(agent_name:, directory:)
         super()
-        @agent_name = agent_name.to_sym
-        @directory = File.expand_path(directory)
+        initialize_agent_context(agent_name: agent_name, directory: directory)
       end
 
       # Override name to return simple "Edit" instead of full class path
@@ -134,17 +140,6 @@ module SwarmSDK
       rescue StandardError => e
         error("Unexpected error editing file: #{e.class.name} - #{e.message}")
       end
-
-      private
-
-      # Helper methods
-      def validation_error(message)
-        "<tool_use_error>InputValidationError: #{message}</tool_use_error>"
-      end
-
-      def error(message)
-        "Error: #{message}"
-      end
     end
   end
 end

data/lib/swarm_sdk/tools/glob.rb

@@ -9,6 +9,13 @@ module SwarmSDK
     class Glob < RubyLLM::Tool
       include PathResolver
 
+      # Factory pattern: declare what parameters this tool needs for instantiation
+      class << self
+        def creation_requirements
+          [:directory]
+        end
+      end
+
       def initialize(directory:)
         super()
         @directory = File.expand_path(directory)
@@ -43,7 +50,7 @@ module SwarmSDK
         desc: "The directory to search in. If not specified, the current working directory will be used. IMPORTANT: Omit this field to use the default directory. DO NOT enter \"undefined\" or \"null\" - simply omit it for the default behavior. Must be a valid directory path if provided.",
         required: false
 
-      MAX_RESULTS = 1000 # Limit results to prevent overwhelming output
+      # NOTE: Result limit now accessed via SwarmSDK.config.glob_result_limit
 
       def execute(pattern:, path: nil)
         # Validate inputs
@@ -100,8 +107,9 @@ module SwarmSDK
           matches.sort_by! { |f| -File.mtime(f).to_i }
 
           # Limit results
-          if matches.count > MAX_RESULTS
-            matches = matches.take(MAX_RESULTS)
+          max_results = SwarmSDK.config.glob_result_limit
+          if matches.count > max_results
+            matches = matches.take(max_results)
             truncated = true
           else
             truncated = false
@@ -115,7 +123,7 @@ module SwarmSDK
             output += <<~REMINDER
 
               <system-reminder>
-              Results limited to first #{MAX_RESULTS} matches (sorted by most recently modified).
+              Results limited to first #{max_results} matches (sorted by most recently modified).
               Consider using a more specific pattern to narrow your search.
               </system-reminder>
             REMINDER

data/lib/swarm_sdk/tools/grep.rb

@@ -9,6 +9,13 @@ module SwarmSDK
     class Grep < RubyLLM::Tool
       include PathResolver
 
+      # Factory pattern: declare what parameters this tool needs for instantiation
+      class << self
+        def creation_requirements
+          [:directory]
+        end
+      end
+
       def initialize(directory:)
         super()
         @directory = File.expand_path(directory)

data/lib/swarm_sdk/tools/multi_edit.rb

@@ -11,6 +11,13 @@ module SwarmSDK
     class MultiEdit < RubyLLM::Tool
       include PathResolver
 
+      # Factory pattern: declare what parameters this tool needs for instantiation
+      class << self
+        def creation_requirements
+          [:agent_name, :directory]
+        end
+      end
+
       description <<~DESC
         Performs multiple exact string replacements in a single file.
         Edits are applied sequentially, so later edits see the results of earlier ones.
@@ -53,8 +60,7 @@ module SwarmSDK
       # @param directory [String] Agent's working directory
       def initialize(agent_name:, directory:)
         super()
-        @agent_name = agent_name.to_sym
-        @directory = File.expand_path(directory)
+        initialize_agent_context(agent_name: agent_name, directory: directory)
       end
 
       # Override name to return simple "MultiEdit" instead of full class path
@@ -204,15 +210,13 @@ module SwarmSDK
 
       private
 
-      # Helper methods
-      def validation_error(message)
-        "<tool_use_error>InputValidationError: #{message}</tool_use_error>"
-      end
-
-      def error(message)
-        "Error: #{message}"
-      end
-
+      # Format an error that includes partial results
+      #
+      # Shows what edits succeeded before the error occurred.
+      #
+      # @param message [String] Error description
+      # @param results [Array<Hash>] Successful edit results before failure
+      # @return [String] Formatted error message with results summary
       def error_with_results(message, results)
         output = "<tool_use_error>InputValidationError: #{message}\n\n"
 

data/lib/swarm_sdk/tools/path_resolver.rb

@@ -2,7 +2,12 @@
 
 module SwarmSDK
   module Tools
-    # Shared path resolution logic for all file tools
+    # Shared path resolution and agent context logic for file tools
+    #
+    # This module provides:
+    # - Path resolution (relative to agent's working directory)
+    # - Agent context initialization (agent_name, directory expansion)
+    # - Standard error message formatting
     #
     # Tools resolve relative paths against the agent's directory.
     # Absolute paths are used as-is.
@@ -12,17 +17,41 @@ module SwarmSDK
     #     include PathResolver
     #
     #     def initialize(agent_name:, directory:)
-    #       @directory = File.expand_path(directory)
+    #       super()
+    #       initialize_agent_context(agent_name: agent_name, directory: directory)
     #     end
     #
     #     def execute(file_path:)
     #       resolved_path = resolve_path(file_path)
     #       File.read(resolved_path)
+    #     rescue StandardError => e
+    #       error("Failed to read: #{e.message}")
     #     end
     #   end
     module PathResolver
+      # Agent context attributes
+      # @return [Symbol] The agent identifier
+      attr_reader :agent_name
+
+      # @return [String] Absolute path to agent's working directory
+      attr_reader :directory
+
       private
 
+      # Initialize agent context for file tools
+      #
+      # Sets up the common agent context needed by file tools:
+      # - Normalizes agent_name to symbol
+      # - Expands directory to absolute path
+      #
+      # @param agent_name [Symbol, String] The agent identifier
+      # @param directory [String] Agent's working directory (will be expanded)
+      # @return [void]
+      def initialize_agent_context(agent_name:, directory:)
+        @agent_name = agent_name.to_sym
+        @directory = File.expand_path(directory)
+      end
+
       # Resolve a path relative to the agent's directory
       #
       # - Absolute paths (starting with /) are returned as-is
@@ -38,6 +67,26 @@ module SwarmSDK
 
         File.expand_path(path, @directory)
       end
+
+      # Format a validation error response
+      #
+      # Used for input validation failures (missing required params, invalid formats, etc.)
+      #
+      # @param message [String] Error description
+      # @return [String] Formatted error message wrapped in tool_use_error tags
+      def validation_error(message)
+        "<tool_use_error>InputValidationError: #{message}</tool_use_error>"
+      end
+
+      # Format a general error response
+      #
+      # Used for runtime errors (permission denied, file not found, etc.)
+      #
+      # @param message [String] Error description
+      # @return [String] Formatted error message prefixed with "Error:"
+      def error(message)
+        "Error: #{message}"
+      end
     end
   end
 end

data/lib/swarm_sdk/tools/read.rb

@@ -10,8 +10,7 @@ module SwarmSDK
     class Read < RubyLLM::Tool
       include PathResolver
 
-      MAX_LINE_LENGTH = 2000
-      DEFAULT_LIMIT = 2000
+      # NOTE: Line length and limit now accessed via SwarmSDK.config
 
       # List of available document converters
       CONVERTERS = [
@@ -28,6 +27,13 @@ module SwarmSDK
         ""
       end
 
+      # Factory pattern: declare what parameters this tool needs for instantiation
+      class << self
+        def creation_requirements
+          [:agent_name, :directory]
+        end
+      end
+
       description <<~DESC
         Reads a file from the local filesystem. You can access any file directly by using this tool.
         Assume this tool is able to read all files on the machine. If the User provides a path to a file assume that path is valid.
@@ -67,8 +73,7 @@ module SwarmSDK
       # @param directory [String] Agent's working directory
       def initialize(agent_name:, directory:)
         super()
-        @agent_name = agent_name.to_sym
-        @directory = File.expand_path(directory)
+        initialize_agent_context(agent_name: agent_name, directory: directory)
       end
 
       # Override name to return simple "Read" instead of full class path
@@ -146,18 +151,20 @@ module SwarmSDK
         lines = lines.drop(start_line)
 
         # Apply limit if specified, otherwise use default
-        effective_limit = limit || DEFAULT_LIMIT
+        default_limit = SwarmSDK.config.read_line_limit
+        effective_limit = limit || default_limit
         lines = lines.take(effective_limit)
-        truncated = limit.nil? && total_lines > DEFAULT_LIMIT
+        truncated = limit.nil? && total_lines > default_limit
 
         # Format with line numbers (cat -n style)
+        max_line_length = SwarmSDK.config.line_character_limit
         output_lines = lines.each_with_index.map do |line, idx|
           line_number = start_line + idx + 1
           display_line = line.chomp
 
           # Truncate long lines
-          if display_line.length > MAX_LINE_LENGTH
-            display_line = display_line[0...MAX_LINE_LENGTH]
+          if display_line.length > max_line_length
+            display_line = display_line[0...max_line_length]
             display_line += "... (line truncated)"
           end
 
@@ -182,15 +189,6 @@ module SwarmSDK
         CONVERTERS.find { |converter| converter.extensions.include?(ext) }
       end
 
-      # Helper methods
-      def validation_error(message)
-        "<tool_use_error>InputValidationError: #{message}</tool_use_error>"
-      end
-
-      def error(message)
-        "Error: #{message}"
-      end
-
       def format_with_reminder(content, reminder)
         return content if reminder.nil? || reminder.empty?
 
@@ -205,7 +203,7 @@ module SwarmSDK
 
         if truncated
           reminders << ""
-          reminders << "Note: This file has #{total_lines} lines but only the first #{DEFAULT_LIMIT} lines are shown. Use the offset and limit parameters to read additional sections if needed."
+          reminders << "Note: This file has #{total_lines} lines but only the first #{SwarmSDK.config.read_line_limit} lines are shown. Use the offset and limit parameters to read additional sections if needed."
         end
 
         reminders << "</system-reminder>"