swarm_memory 2.1.5 → 2.1.6

data/lib/swarm_sdk/tools/registry.rb

@@ -1,205 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  module Tools
-    # Registry for built-in SwarmSDK tools
-    #
-    # Maps tool names (symbols) to their RubyLLM::Tool classes.
-    # Provides validation, lookup, and factory functionality for tool registration.
-    #
-    # ## Tool Creation Pattern
-    #
-    # Tools register themselves with their creation requirements via the `tool_factory` method.
-    # This eliminates the need for a giant case statement in ToolConfigurator.
-    #
-    # Tools fall into three categories:
-    # 1. **No params**: Simple tools with no initialization requirements (Think, Clock)
-    # 2. **Directory only**: Tools needing working directory (Bash, Grep, Glob)
-    # 3. **Agent context**: Tools needing agent tracking (Read, Write, Edit, MultiEdit)
-    # 4. **Scratchpad**: Tools needing scratchpad storage instance
-    #
-    # @example Adding a new tool with creation requirements
-    #   # In the tool class:
-    #   class MyTool < RubyLLM::Tool
-    #     def self.creation_requirements
-    #       [:agent_name, :directory]
-    #     end
-    #   end
-    #
-    #   # In registry:
-    #   BUILTIN_TOOLS = {
-    #     MyTool: SwarmSDK::Tools::MyTool,
-    #   }
-    #
-    # Note: Plugin-provided tools (e.g., memory tools) are NOT in this registry.
-    # They are registered via SwarmSDK::PluginRegistry instead.
-    class Registry
-      # All available built-in tools
-      #
-      # Maps tool names to their classes. The class must respond to `creation_requirements`
-      # to specify what parameters are needed for instantiation.
-      BUILTIN_TOOLS = {
-        Read: SwarmSDK::Tools::Read,
-        Write: SwarmSDK::Tools::Write,
-        Edit: SwarmSDK::Tools::Edit,
-        MultiEdit: SwarmSDK::Tools::MultiEdit,
-        Bash: SwarmSDK::Tools::Bash,
-        Grep: SwarmSDK::Tools::Grep,
-        Glob: SwarmSDK::Tools::Glob,
-        TodoWrite: SwarmSDK::Tools::TodoWrite,
-        ScratchpadWrite: :scratchpad, # Requires scratchpad storage instance
-        ScratchpadRead: :scratchpad,  # Requires scratchpad storage instance
-        ScratchpadList: :scratchpad,  # Requires scratchpad storage instance
-        Think: SwarmSDK::Tools::Think,
-        WebFetch: SwarmSDK::Tools::WebFetch,
-        Clock: SwarmSDK::Tools::Clock,
-      }.freeze
-
-      class << self
-        # Get tool class by name
-        #
-        # Note: Plugin-provided tools are NOT returned by this method.
-        # They are managed by SwarmSDK::PluginRegistry instead.
-        #
-        # @param name [Symbol, String] Tool name
-        # @return [Class, Symbol, nil] Tool class, :scratchpad marker, or nil if not found
-        def get(name)
-          name_sym = name.to_sym
-          BUILTIN_TOOLS[name_sym]
-        end
-
-        # Create a tool instance using the Factory Pattern
-        #
-        # Uses the tool's `creation_requirements` class method to determine
-        # what parameters to pass to the constructor.
-        #
-        # @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
-        # @option context [Object] :scratchpad_storage Scratchpad storage instance
-        # @return [RubyLLM::Tool] Instantiated tool
-        # @raise [ConfigurationError] If tool is unknown or has unmet requirements
-        def create(name, context = {})
-          name_sym = name.to_sym
-          tool_entry = BUILTIN_TOOLS[name_sym]
-
-          raise ConfigurationError, "Unknown tool: #{name}" unless tool_entry
-
-          # Handle scratchpad tools specially (they use factory methods)
-          if tool_entry == :scratchpad
-            return create_scratchpad_tool(name_sym, context[:scratchpad_storage])
-          end
-
-          # Get the tool class and its requirements
-          tool_class = tool_entry
-
-          # Check if tool defines creation requirements
-          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
-        end
-
-        # Get multiple tool classes by names
-        #
-        # @param names [Array<Symbol, String>] Tool names
-        # @return [Array<Class>] Array of tool classes
-        # @raise [ConfigurationError] If any tool name is invalid
-        def get_many(names)
-          names.map do |name|
-            tool_class = get(name)
-            unless tool_class
-              raise ConfigurationError,
-                "Unknown tool: #{name}. Available tools: #{available_names.join(", ")}"
-            end
-
-            tool_class
-          end
-        end
-
-        # Check if a tool exists
-        #
-        # Note: Only checks built-in tools. Plugin-provided tools are checked
-        # via SwarmSDK::PluginRegistry.plugin_tool?() instead.
-        #
-        # @param name [Symbol, String] Tool name
-        # @return [Boolean]
-        def exists?(name)
-          name_sym = name.to_sym
-          BUILTIN_TOOLS.key?(name_sym)
-        end
-
-        # Get all available built-in tool names
-        #
-        # Note: Does NOT include plugin-provided tools. To get all available tools
-        # including plugins, combine with SwarmSDK::PluginRegistry.tools.
-        #
-        # @return [Array<Symbol>]
-        def available_names
-          BUILTIN_TOOLS.keys
-        end
-
-        # Validate tool names
-        #
-        # @param names [Array<Symbol, String>] Tool names to validate
-        # @return [Array<Symbol>] Invalid tool names
-        def validate(names)
-          names.reject { |name| exists?(name) }
-        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,
-                "Tool #{tool_name} requires #{req} but it was not provided in context"
-            end
-
-            params[req] = context[req]
-          end
-
-          params
-        end
-
-        # Create a scratchpad tool using its factory method
-        #
-        # @param name [Symbol] Scratchpad tool name
-        # @param storage [Object] Scratchpad storage instance
-        # @return [RubyLLM::Tool] Instantiated scratchpad tool
-        # @raise [ConfigurationError] If storage is not provided
-        def create_scratchpad_tool(name, storage)
-          unless storage
-            raise ConfigurationError,
-              "Scratchpad tool #{name} requires scratchpad_storage in context"
-          end
-
-          case name
-          when :ScratchpadWrite
-            Tools::Scratchpad::ScratchpadWrite.create_for_scratchpad(storage)
-          when :ScratchpadRead
-            Tools::Scratchpad::ScratchpadRead.create_for_scratchpad(storage)
-          when :ScratchpadList
-            Tools::Scratchpad::ScratchpadList.create_for_scratchpad(storage)
-          else
-            raise ConfigurationError, "Unknown scratchpad tool: #{name}"
-          end
-        end
-      end
-    end
-  end
-end

data/lib/swarm_sdk/tools/scratchpad/scratchpad_list.rb

@@ -1,117 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  module Tools
-    module Scratchpad
-      # Tool for listing scratchpad entries
-      #
-      # Shows all entries in the shared scratchpad with their metadata.
-      # All agents in the swarm share the same scratchpad.
-      class ScratchpadList < RubyLLM::Tool
-        define_method(:name) { "ScratchpadList" }
-
-        description <<~DESC
-          List all entries in scratchpad with their metadata.
-
-          ## When to Use ScratchpadList
-
-          Use ScratchpadList to:
-          - Discover what content is available in the scratchpad
-          - Check what other agents have stored
-          - Find relevant entries before reading them
-          - Review all stored outputs and analysis
-          - Check entry sizes and last update times
-
-          ## Best Practices
-
-          - Use this before ScratchpadRead if you don't know what's stored
-          - Filter by prefix to narrow down results (e.g., 'notes/' lists all notes)
-          - Shows path, title, size, and last updated time for each entry
-          - Any agent can see all scratchpad entries
-          - Helps coordinate multi-agent workflows
-
-          ## Examples
-
-          - List all entries: (no prefix parameter)
-          - List notes only: prefix='notes/'
-          - List analysis results: prefix='analysis/'
-        DESC
-
-        param :prefix,
-          desc: "Optional prefix to filter entries (e.g., 'notes/' to list all entries under notes/)",
-          required: false
-
-        class << self
-          # Create a ScratchpadList tool for a specific scratchpad storage instance
-          #
-          # @param scratchpad_storage [Stores::ScratchpadStorage] Shared scratchpad storage instance
-          # @return [ScratchpadList] Tool instance
-          def create_for_scratchpad(scratchpad_storage)
-            new(scratchpad_storage)
-          end
-        end
-
-        # Initialize with scratchpad storage instance
-        #
-        # @param scratchpad_storage [Stores::ScratchpadStorage] Shared scratchpad storage instance
-        def initialize(scratchpad_storage)
-          super() # Call RubyLLM::Tool's initialize
-          @scratchpad_storage = scratchpad_storage
-        end
-
-        # Execute the tool
-        #
-        # @param prefix [String, nil] Optional prefix to filter entries
-        # @return [String] Formatted list of entries
-        def execute(prefix: nil)
-          entries = scratchpad_storage.list(prefix: prefix)
-
-          if entries.empty?
-            prefix_msg = prefix ? " with prefix '#{prefix}'" : ""
-            return "No entries found in scratchpad#{prefix_msg}"
-          end
-
-          result = []
-          prefix_msg = prefix ? " with prefix '#{prefix}'" : ""
-          result << "Scratchpad entries#{prefix_msg} (#{entries.size} #{entries.size == 1 ? "entry" : "entries"}):"
-          result << ""
-
-          entries.each do |entry|
-            time_str = entry[:updated_at].strftime("%Y-%m-%d %H:%M:%S")
-            result << "  scratchpad://#{entry[:path]}"
-            result << "    Title: #{entry[:title]}"
-            result << "    Size: #{format_bytes(entry[:size])}"
-            result << "    Updated: #{time_str}"
-            result << ""
-          end
-
-          result.join("\n").rstrip
-        rescue ArgumentError => e
-          validation_error(e.message)
-        end
-
-        private
-
-        attr_reader :scratchpad_storage
-
-        def validation_error(message)
-          "<tool_use_error>InputValidationError: #{message}</tool_use_error>"
-        end
-
-        # Format bytes to human-readable size
-        #
-        # @param bytes [Integer] Number of bytes
-        # @return [String] Formatted size
-        def format_bytes(bytes)
-          if bytes >= 1_000_000
-            "#{(bytes.to_f / 1_000_000).round(1)}MB"
-          elsif bytes >= 1_000
-            "#{(bytes.to_f / 1_000).round(1)}KB"
-          else
-            "#{bytes}B"
-          end
-        end
-      end
-    end
-  end
-end

data/lib/swarm_sdk/tools/scratchpad/scratchpad_read.rb

@@ -1,97 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  module Tools
-    module Scratchpad
-      # Tool for reading content from scratchpad storage
-      #
-      # Retrieves content stored by any agent using scratchpad_write.
-      # All agents in the swarm share the same scratchpad.
-      class ScratchpadRead < RubyLLM::Tool
-        define_method(:name) { "ScratchpadRead" }
-
-        description <<~DESC
-          Read content from scratchpad.
-
-          ## When to Use ScratchpadRead
-
-          Use ScratchpadRead to:
-          - Retrieve previously stored content and outputs
-          - Access detailed analysis or results from earlier steps
-          - Read messages or notes left by other agents
-          - Access cached computed data
-          - Retrieve content that was too long for direct responses
-
-          ## Best Practices
-
-          - Any agent can read any scratchpad content
-          - Content is returned with line numbers for easy reference
-          - Use ScratchpadList first if you don't know what's stored
-          - Scratchpad data is temporary and lost when swarm ends
-          - For persistent data, use MemoryRead instead
-
-          ## Examples
-
-          - Read status: file_path='status'
-          - Read analysis: file_path='api_analysis'
-          - Read agent notes: file_path='notes/backend'
-        DESC
-
-        param :file_path,
-          desc: "Path to read from scratchpad (e.g., 'status', 'result', 'notes/agent_x')",
-          required: true
-
-        class << self
-          # Create a ScratchpadRead tool for a specific scratchpad storage instance
-          #
-          # @param scratchpad_storage [Stores::ScratchpadStorage] Shared scratchpad storage instance
-          # @return [ScratchpadRead] Tool instance
-          def create_for_scratchpad(scratchpad_storage)
-            new(scratchpad_storage)
-          end
-        end
-
-        # Initialize with scratchpad storage instance
-        #
-        # @param scratchpad_storage [Stores::ScratchpadStorage] Shared scratchpad storage instance
-        def initialize(scratchpad_storage)
-          super() # Call RubyLLM::Tool's initialize
-          @scratchpad_storage = scratchpad_storage
-        end
-
-        # Execute the tool
-        #
-        # @param file_path [String] Path to read from
-        # @return [String] Content at the path with line numbers, or error message
-        def execute(file_path:)
-          content = scratchpad_storage.read(file_path: file_path)
-          format_with_line_numbers(content)
-        rescue ArgumentError => e
-          validation_error(e.message)
-        end
-
-        private
-
-        attr_reader :scratchpad_storage
-
-        def validation_error(message)
-          "<tool_use_error>InputValidationError: #{message}</tool_use_error>"
-        end
-
-        # Format content with line numbers (same format as Read tool)
-        #
-        # @param content [String] Content to format
-        # @return [String] Content with line numbers
-        def format_with_line_numbers(content)
-          lines = content.lines
-          output_lines = lines.each_with_index.map do |line, idx|
-            line_number = idx + 1
-            display_line = line.chomp
-            "#{line_number.to_s.rjust(6)}→#{display_line}"
-          end
-          output_lines.join("\n")
-        end
-      end
-    end
-  end
-end

data/lib/swarm_sdk/tools/scratchpad/scratchpad_write.rb

@@ -1,108 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  module Tools
-    module Scratchpad
-      # Tool for writing content to scratchpad storage
-      #
-      # Stores content in volatile, shared storage for temporary communication.
-      # All agents in the swarm share the same scratchpad.
-      # Data is lost when the process ends (not persisted).
-      class ScratchpadWrite < RubyLLM::Tool
-        define_method(:name) { "ScratchpadWrite" }
-
-        description <<~DESC
-          Store content in scratchpad for temporary cross-agent communication.
-
-          ## When to Use Scratchpad
-
-          Use ScratchpadWrite to:
-          - Store detailed outputs, analysis, or results that are too long for direct responses
-          - Share information that would otherwise clutter your responses
-          - Store intermediate results during multi-step tasks
-          - Leave coordination messages for other agents
-          - Cache computed data for quick retrieval
-
-          ## Best Practices
-
-          - Choose simple, descriptive paths: 'status', 'result', 'notes/agent_x'
-          - Use hierarchical paths for organization: 'analysis/step1', 'analysis/step2'
-          - Keep entries focused - one piece of information per entry
-          - Any agent can read scratchpad content
-          - Data is lost when the swarm ends (use MemoryWrite for persistent storage)
-          - Maximum 1MB per entry
-
-          ## Examples
-
-          Good paths: 'status', 'api_analysis', 'test_results', 'notes/backend'
-          Bad paths: 'scratch/temp/file123.txt', 'output.log'
-        DESC
-
-        param :file_path,
-          desc: "Simple path for the content (e.g., 'status', 'result', 'notes/agent_x')",
-          required: true
-
-        param :content,
-          desc: "Content to store in scratchpad (max 1MB per entry)",
-          required: true
-
-        param :title,
-          desc: "Brief title describing the content",
-          required: true
-
-        class << self
-          # Create a ScratchpadWrite tool for a specific scratchpad storage instance
-          #
-          # @param scratchpad_storage [Stores::ScratchpadStorage] Shared scratchpad storage instance
-          # @return [ScratchpadWrite] Tool instance
-          def create_for_scratchpad(scratchpad_storage)
-            new(scratchpad_storage)
-          end
-        end
-
-        # Initialize with scratchpad storage instance
-        #
-        # @param scratchpad_storage [Stores::ScratchpadStorage] Shared scratchpad storage instance
-        def initialize(scratchpad_storage)
-          super() # Call RubyLLM::Tool's initialize
-          @scratchpad_storage = scratchpad_storage
-        end
-
-        # Execute the tool
-        #
-        # @param file_path [String] Path to store content
-        # @param content [String] Content to store
-        # @param title [String] Brief title
-        # @return [String] Success message with path and size
-        def execute(file_path:, content:, title:)
-          entry = scratchpad_storage.write(file_path: file_path, content: content, title: title)
-          "Stored at scratchpad://#{file_path} (#{format_bytes(entry.size)})"
-        rescue ArgumentError => e
-          validation_error(e.message)
-        end
-
-        private
-
-        attr_reader :scratchpad_storage
-
-        def validation_error(message)
-          "<tool_use_error>InputValidationError: #{message}</tool_use_error>"
-        end
-
-        # Format bytes to human-readable size
-        #
-        # @param bytes [Integer] Number of bytes
-        # @return [String] Formatted size
-        def format_bytes(bytes)
-          if bytes >= 1_000_000
-            "#{(bytes.to_f / 1_000_000).round(1)}MB"
-          elsif bytes >= 1_000
-            "#{(bytes.to_f / 1_000).round(1)}KB"
-          else
-            "#{bytes}B"
-          end
-        end
-      end
-    end
-  end
-end

data/lib/swarm_sdk/tools/stores/read_tracker.rb

@@ -1,96 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  module Tools
-    module Stores
-      # ReadTracker manages read-file tracking for all agents with content digest verification
-      #
-      # This module maintains a global registry of which files each agent has read
-      # during their conversation along with SHA256 digests of the content. This enables
-      # enforcement of the "read-before-write" and "read-before-edit" rules that ensure
-      # agents have context before modifying files, AND prevents editing files that have
-      # changed externally since being read.
-      #
-      # Each agent maintains an independent map of read files to content digests.
-      module ReadTracker
-        @read_files = {} # { agent_id => { file_path => sha256_digest } }
-        @mutex = Mutex.new
-
-        class << self
-          # Register that an agent has read a file with content digest
-          #
-          # @param agent_id [Symbol] The agent identifier
-          # @param file_path [String] The absolute path to the file
-          # @param content [String] File content (for digest calculation)
-          # @return [String] The calculated SHA256 digest
-          def register_read(agent_id, file_path, content)
-            @mutex.synchronize do
-              @read_files[agent_id] ||= {}
-              digest = Digest::SHA256.hexdigest(content)
-              @read_files[agent_id][File.expand_path(file_path)] = digest
-              digest
-            end
-          end
-
-          # Check if an agent has read a file AND content hasn't changed
-          #
-          # @param agent_id [Symbol] The agent identifier
-          # @param file_path [String] The absolute path to the file
-          # @return [Boolean] true if agent read file and content matches
-          def file_read?(agent_id, file_path)
-            @mutex.synchronize do
-              return false unless @read_files[agent_id]
-
-              expanded_path = File.expand_path(file_path)
-              stored_digest = @read_files[agent_id][expanded_path]
-              return false unless stored_digest
-
-              # Check if file still exists and matches stored digest
-              return false unless File.exist?(expanded_path)
-
-              current_digest = Digest::SHA256.hexdigest(File.read(expanded_path))
-              current_digest == stored_digest
-            end
-          end
-
-          # Get all read files with digests for snapshot
-          #
-          # @param agent_id [Symbol] The agent identifier
-          # @return [Hash] { file_path => digest }
-          def get_read_files(agent_id)
-            @mutex.synchronize do
-              @read_files[agent_id]&.dup || {}
-            end
-          end
-
-          # Restore read files with digests from snapshot
-          #
-          # @param agent_id [Symbol] The agent identifier
-          # @param files_with_digests [Hash] { file_path => digest }
-          # @return [void]
-          def restore_read_files(agent_id, files_with_digests)
-            @mutex.synchronize do
-              @read_files[agent_id] = files_with_digests.dup
-            end
-          end
-
-          # Clear read history for an agent (useful for testing)
-          #
-          # @param agent_id [Symbol] The agent identifier
-          def clear(agent_id)
-            @mutex.synchronize do
-              @read_files.delete(agent_id)
-            end
-          end
-
-          # Clear all read history (useful for testing)
-          def clear_all
-            @mutex.synchronize do
-              @read_files.clear
-            end
-          end
-        end
-      end
-    end
-  end
-end