swarm_memory 2.1.2 → 2.1.4

data/lib/swarm_sdk/swarm_loader.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  # Loader for creating swarm instances from multiple sources
+  #
+  # SwarmLoader loads swarm configurations from:
+  # - Files: .rb (DSL) or .yml (YAML)
+  # - YAML strings: Direct YAML content
+  # - DSL blocks: Inline Ruby blocks
+  #
+  # All loaded swarms get hierarchical swarm_id and parent_swarm_id.
+  #
+  # ## Features
+  # - Supports Ruby DSL (.rb files or blocks)
+  # - Supports YAML (.yml/.yaml files or strings)
+  # - Sets hierarchical swarm_id based on parent + registration name
+  # - Isolates loading in separate context
+  # - Proper error handling for missing/invalid sources
+  #
+  # ## Examples
+  #
+  #   # From file
+  #   swarm = SwarmLoader.load_from_file(
+  #     "./swarms/code_review.rb",
+  #     swarm_id: "main/code_review",
+  #     parent_swarm_id: "main"
+  #   )
+  #
+  #   # From YAML string
+  #   swarm = SwarmLoader.load_from_yaml_string(
+  #     "version: 2\nswarm:\n  name: Test\n...",
+  #     swarm_id: "main/testing",
+  #     parent_swarm_id: "main"
+  #   )
+  #
+  #   # From block
+  #   swarm = SwarmLoader.load_from_block(
+  #     proc { id "team"; name "Team"; agent :dev { ... } },
+  #     swarm_id: "main/team",
+  #     parent_swarm_id: "main"
+  #   )
+  #
+  class SwarmLoader
+    class << self
+      # Load a swarm from a file (.rb or .yml)
+      #
+      # @param file_path [String] Path to swarm file
+      # @param swarm_id [String] Hierarchical swarm ID to assign
+      # @param parent_swarm_id [String] Parent swarm ID
+      # @return [Swarm] Loaded swarm instance with overridden IDs
+      # @raise [ConfigurationError] If file not found or unsupported type
+      def load_from_file(file_path, swarm_id:, parent_swarm_id:)
+        path = Pathname.new(file_path).expand_path
+
+        raise ConfigurationError, "Swarm file not found: #{path}" unless path.exist?
+
+        # Determine file type and load
+        case path.extname
+        when ".rb"
+          load_from_ruby_file(path, swarm_id, parent_swarm_id)
+        when ".yml", ".yaml"
+          load_from_yaml_file(path, swarm_id, parent_swarm_id)
+        else
+          raise ConfigurationError, "Unsupported swarm file type: #{path.extname}. Use .rb, .yml, or .yaml"
+        end
+      end
+
+      # Load a swarm from YAML string
+      #
+      # @param yaml_content [String] YAML configuration content
+      # @param swarm_id [String] Hierarchical swarm ID to assign
+      # @param parent_swarm_id [String] Parent swarm ID
+      # @return [Swarm] Loaded swarm instance with overridden IDs
+      # @raise [ConfigurationError] If YAML is invalid
+      def load_from_yaml_string(yaml_content, swarm_id:, parent_swarm_id:)
+        # Use Configuration to parse YAML string
+        config = Configuration.new(yaml_content, base_dir: Dir.pwd)
+        config.load_and_validate
+        swarm = config.to_swarm
+
+        # Override swarm_id and parent_swarm_id
+        swarm.override_swarm_ids(swarm_id: swarm_id, parent_swarm_id: parent_swarm_id)
+
+        swarm
+      end
+
+      # Load a swarm from DSL block
+      #
+      # @param block [Proc] Block containing SwarmSDK DSL
+      # @param swarm_id [String] Hierarchical swarm ID to assign
+      # @param parent_swarm_id [String] Parent swarm ID
+      # @return [Swarm] Loaded swarm instance with overridden IDs
+      def load_from_block(block, swarm_id:, parent_swarm_id:)
+        # Execute block in Builder context
+        builder = Swarm::Builder.new
+        builder.instance_eval(&block)
+        swarm = builder.build_swarm
+
+        # Override swarm_id and parent_swarm_id
+        swarm.override_swarm_ids(swarm_id: swarm_id, parent_swarm_id: parent_swarm_id)
+
+        swarm
+      end
+
+      private
+
+      # Load swarm from Ruby DSL file
+      #
+      # @param path [Pathname] Path to .rb file
+      # @param swarm_id [String] Swarm ID to assign
+      # @param parent_swarm_id [String] Parent swarm ID
+      # @return [Swarm] Loaded swarm with overridden IDs
+      def load_from_ruby_file(path, swarm_id, parent_swarm_id)
+        content = File.read(path)
+
+        # Execute DSL in isolated context
+        # The DSL should return a swarm via SwarmSDK.build { ... }
+        swarm = eval(content, binding, path.to_s) # rubocop:disable Security/Eval
+
+        # Override swarm_id and parent_swarm_id
+        # These must be set after build to ensure hierarchical structure
+        swarm.override_swarm_ids(swarm_id: swarm_id, parent_swarm_id: parent_swarm_id)
+
+        swarm
+      end
+
+      # Load swarm from YAML file
+      #
+      # @param path [Pathname] Path to .yml file
+      # @param swarm_id [String] Swarm ID to assign
+      # @param parent_swarm_id [String] Parent swarm ID
+      # @return [Swarm] Loaded swarm with overridden IDs
+      def load_from_yaml_file(path, swarm_id, parent_swarm_id)
+        # Use Configuration to load and convert YAML to swarm
+        config = Configuration.load_file(path.to_s)
+        swarm = config.to_swarm
+
+        # Override swarm_id and parent_swarm_id
+        swarm.override_swarm_ids(swarm_id: swarm_id, parent_swarm_id: parent_swarm_id)
+
+        swarm
+      end
+    end
+  end
+end

data/lib/swarm_sdk/swarm_registry.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  # Registry for managing sub-swarms in composable swarms
+  #
+  # SwarmRegistry handles lazy loading, caching, and lifecycle management
+  # of child swarms registered via the `swarms` DSL block.
+  #
+  # ## Features
+  # - Lazy loading: Sub-swarms are only loaded when first accessed
+  # - Caching: Loaded swarms are cached for reuse
+  # - Hierarchical IDs: Sub-swarms get IDs based on parent + registration name
+  # - Context control: keep_context determines if swarm state persists
+  # - Lifecycle management: Cleanup cascades through all sub-swarms
+  #
+  # ## Example
+  #
+  #   registry = SwarmRegistry.new(parent_swarm_id: "main_app")
+  #   registry.register("code_review", file: "./swarms/code_review.rb", keep_context: true)
+  #
+  #   # Lazy load on first access
+  #   swarm = registry.load_swarm("code_review")
+  #   # => Swarm with swarm_id = "main_app/code_review"
+  #
+  #   # Reset if keep_context: false
+  #   registry.reset_if_needed("code_review")
+  #
+  class SwarmRegistry
+    # Initialize a new swarm registry
+    #
+    # @param parent_swarm_id [String] ID of the parent swarm
+    def initialize(parent_swarm_id:)
+      @parent_swarm_id = parent_swarm_id
+      @registered_swarms = {}
+      # Format: { "code_review" => { file: "...", keep_context: true, instance: nil } }
+    end
+
+    # Register a sub-swarm for lazy loading
+    #
+    # @param name [String] Registration name for the swarm
+    # @param source [Hash] Source specification with :type and :value
+    #   - { type: :file, value: "./path/to/swarm.rb" }
+    #   - { type: :yaml, value: "version: 2\n..." }
+    #   - { type: :block, value: Proc }
+    # @param keep_context [Boolean] Whether to preserve conversation state between calls (default: true)
+    # @return [void]
+    # @raise [ArgumentError] If swarm with same name already registered
+    def register(name, source:, keep_context: true)
+      raise ArgumentError, "Swarm '#{name}' already registered" if @registered_swarms.key?(name)
+
+      @registered_swarms[name] = {
+        source: source,
+        keep_context: keep_context,
+        instance: nil, # Lazy load
+      }
+    end
+
+    # Check if a swarm is registered
+    #
+    # @param name [String] Swarm registration name
+    # @return [Boolean] True if swarm is registered
+    def registered?(name)
+      @registered_swarms.key?(name)
+    end
+
+    # Load a registered swarm (lazy load + cache)
+    #
+    # Loads the swarm from its source (file, yaml, or block) on first access, then caches it.
+    # Sets hierarchical swarm_id based on parent_swarm_id + registration name.
+    #
+    # @param name [String] Swarm registration name
+    # @return [Swarm] Loaded swarm instance
+    # @raise [ConfigurationError] If swarm not registered
+    def load_swarm(name)
+      entry = @registered_swarms[name]
+      raise ConfigurationError, "Swarm '#{name}' not registered" unless entry
+
+      # Return cached instance if exists
+      return entry[:instance] if entry[:instance]
+
+      # Load from appropriate source
+      swarm_id = "#{@parent_swarm_id}/#{name}" # Hierarchical
+      source = entry[:source]
+
+      swarm = case source[:type]
+      when :file
+        SwarmLoader.load_from_file(
+          source[:value],
+          swarm_id: swarm_id,
+          parent_swarm_id: @parent_swarm_id,
+        )
+      when :yaml
+        SwarmLoader.load_from_yaml_string(
+          source[:value],
+          swarm_id: swarm_id,
+          parent_swarm_id: @parent_swarm_id,
+        )
+      when :block
+        SwarmLoader.load_from_block(
+          source[:value],
+          swarm_id: swarm_id,
+          parent_swarm_id: @parent_swarm_id,
+        )
+      else
+        raise ConfigurationError, "Unknown source type: #{source[:type]}"
+      end
+
+      entry[:instance] = swarm
+      swarm
+    end
+
+    # Reset swarm context if keep_context: false
+    #
+    # @param name [String] Swarm registration name
+    # @return [void]
+    def reset_if_needed(name)
+      entry = @registered_swarms[name]
+      return if entry[:keep_context]
+
+      entry[:instance]&.reset_context!
+    end
+
+    # Cleanup all registered swarms
+    #
+    # Stops all loaded swarm instances and clears the registry.
+    # Should be called when parent swarm is done.
+    #
+    # @return [void]
+    def shutdown_all
+      @registered_swarms.each_value do |entry|
+        entry[:instance]&.cleanup
+      end
+      @registered_swarms.clear
+    end
+  end
+end

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,10 @@ 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
+      # Backward compatibility aliases - use Defaults module for new code
+      DEFAULT_TIMEOUT_MS = Defaults::Timeouts::BASH_COMMAND_MS
+      MAX_TIMEOUT_MS = Defaults::Timeouts::BASH_COMMAND_MAX_MS
+      MAX_OUTPUT_LENGTH = Defaults::Limits::OUTPUT_CHARACTERS
 
       # Commands that are ALWAYS blocked for safety reasons
       # These cannot be overridden by permissions configuration

data/lib/swarm_sdk/tools/delegate.rb

@@ -2,22 +2,39 @@
 
 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
       #
       # @param delegate_name [String] Name of the delegate agent (e.g., "backend")
       # @param delegate_description [String] Description of the delegate agent
-      # @param delegate_chat [AgentChat] The chat instance for 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 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:,
@@ -25,7 +42,6 @@ module SwarmSDK
         delegate_chat:,
         agent_name:,
         swarm:,
-        hook_registry:,
         delegating_chat: nil
       )
         super()
@@ -35,22 +51,21 @@ module SwarmSDK
         @delegate_chat = delegate_chat
         @agent_name = agent_name
         @swarm = swarm
-        @hook_registry = hook_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
@@ -60,9 +75,21 @@ 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(call_stack)
+          return "Error: Circular delegation detected: #{call_stack.join(" -> ")} -> #{@delegate_target}. " \
+            "Please restructure your delegation to avoid infinite loops."
+        end
+
         # Get agent-specific hooks from the delegating chat instance
         agent_hooks = if @delegating_chat&.respond_to?(:hook_agent_hooks)
           @delegating_chat.hook_agent_hooks || {}
@@ -78,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)
 
@@ -94,9 +121,16 @@ module SwarmSDK
           return result.value
         end
 
-        # Proceed with delegation
-        response = @delegate_chat.ask(task)
-        delegation_result = response.content
+        # Determine delegation type and proceed
+        delegation_result = if @delegate_chat
+          # Delegate to agent
+          delegate_to_agent(message, call_stack)
+        elsif swarm_registry&.registered?(@delegate_target)
+          # Delegate to registered swarm
+          delegate_to_swarm(message, call_stack, swarm_registry)
+        else
+          raise ConfigurationError, "Unknown delegation target: #{@delegate_target}"
+        end
 
         # Trigger post_delegation callback
         post_context = Hooks::Context.new(
@@ -107,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,
           },
@@ -127,10 +161,12 @@ module SwarmSDK
         LogStream.emit(
           type: "delegation_error",
           agent: @agent_name,
+          swarm_id: @swarm.swarm_id,
+          parent_swarm_id: @swarm.parent_swarm_id,
           delegate_to: @tool_name,
           error_class: e.class.name,
           error_message: "Request timed out",
-          backtrace: e.backtrace&.first(5) || [],
+          error_backtrace: e.backtrace&.first(5) || [],
         )
         "Error: Request to #{@tool_name} timed out. The agent may be overloaded or the LLM service is not responding. Please try again or simplify the task."
       rescue Faraday::Error => e
@@ -138,10 +174,12 @@ module SwarmSDK
         LogStream.emit(
           type: "delegation_error",
           agent: @agent_name,
+          swarm_id: @swarm.swarm_id,
+          parent_swarm_id: @swarm.parent_swarm_id,
           delegate_to: @tool_name,
           error_class: e.class.name,
           error_message: e.message,
-          backtrace: e.backtrace&.first(5) || [],
+          error_backtrace: e.backtrace&.first(5) || [],
         )
         "Error: Network error communicating with #{@tool_name}: #{e.class.name}. Please check connectivity and try again."
       rescue StandardError => e
@@ -150,15 +188,80 @@ module SwarmSDK
         LogStream.emit(
           type: "delegation_error",
           agent: @agent_name,
+          swarm_id: @swarm.swarm_id,
+          parent_swarm_id: @swarm.parent_swarm_id,
           delegate_to: @tool_name,
           error_class: e.class.name,
           error_message: e.message,
-          backtrace: backtrace_array,
+          error_backtrace: backtrace_array,
         )
         # Return error string for LLM
         backtrace_str = backtrace_array.join("\n  ")
         "Error: #{@tool_name} encountered an error: #{e.class.name}: #{e.message}\nBacktrace:\n  #{backtrace_str}"
       end
+
+      private
+
+      # Delegate to an agent
+      #
+      # @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(message, call_stack)
+        # Push delegate target onto call stack to track delegation chain
+        call_stack.push(@delegate_target)
+        begin
+          response = @delegate_chat.ask(message, source: "delegation")
+          response.content
+        ensure
+          # Always pop from stack, even if delegation fails
+          call_stack.pop
+        end
+      end
+
+      # Delegate to a registered swarm
+      #
+      # @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(message, call_stack, swarm_registry)
+        # Load sub-swarm (lazy load + cache)
+        subswarm = swarm_registry.load_swarm(@delegate_target)
+
+        # Push delegate target onto call stack to track delegation chain
+        call_stack.push(@delegate_target)
+        begin
+          # Execute sub-swarm's lead agent
+          lead_agent = subswarm.agents[subswarm.lead_agent]
+          response = lead_agent.ask(message, source: "delegation")
+          result = response.content
+
+          # Reset if keep_context: false
+          swarm_registry.reset_if_needed(@delegate_target)
+
+          result
+        ensure
+          # Always pop from stack, even if delegation fails
+          call_stack.pop
+        end
+      end
+
+      # Emit circular dependency warning event
+      #
+      # @param call_stack [Array] Current delegation call stack
+      # @return [void]
+      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,
+          timestamp: Time.now.utc.iso8601,
+        )
+      end
     end
   end
 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,8 @@ 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
+      # Backward compatibility alias - use Defaults module for new code
+      MAX_RESULTS = Defaults::Limits::GLOB_RESULTS
 
       def execute(pattern:, path: nil)
         # Validate inputs

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)