swarm_sdk 2.0.6 → 2.0.7

data/lib/swarm_sdk/tools/memory/memory_edit.rb

@@ -1,145 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  module Tools
-    module Memory
-      # Tool for editing memory entries with exact string replacement
-      #
-      # Performs exact string replacements in memory content.
-      # Each agent has its own isolated memory storage.
-      class MemoryEdit < RubyLLM::Tool
-        define_method(:name) { "MemoryEdit" }
-
-        description <<~DESC
-          Performs exact string replacements in memory entries.
-          Works like the Edit tool but operates on memory content instead of files.
-          You must use MemoryRead on the entry before editing it.
-          When editing text from MemoryRead output, ensure you preserve the exact indentation as it appears AFTER the line number prefix.
-          The line number prefix format is: spaces + line number + tab. Everything after that tab is the actual content to match.
-          Never include any part of the line number prefix in the old_string or new_string.
-          The edit will FAIL if old_string is not unique in the entry. Either provide a larger string with more surrounding context to make it unique or use replace_all to change every instance of old_string.
-          Use replace_all for replacing and renaming strings across the entry.
-        DESC
-
-        param :file_path,
-          desc: "Path to the memory entry (e.g., 'analysis/report', 'parallel/batch1/task_0')",
-          required: true
-
-        param :old_string,
-          desc: "The exact text to replace (must match exactly including whitespace)",
-          required: true
-
-        param :new_string,
-          desc: "The text to replace it with (must be different from old_string)",
-          required: true
-
-        param :replace_all,
-          desc: "Replace all occurrences of old_string (default false)",
-          required: false
-
-        class << self
-          # Create a MemoryEdit tool for a specific memory storage instance
-          #
-          # @param memory_storage [Stores::MemoryStorage] Per-agent memory storage instance
-          # @param agent_name [Symbol, String] Agent identifier for tracking reads
-          # @return [MemoryEdit] Tool instance
-          def create_for_memory(memory_storage, agent_name)
-            new(memory_storage, agent_name)
-          end
-        end
-
-        # Initialize with memory storage instance and agent name
-        #
-        # @param memory_storage [Stores::MemoryStorage] Per-agent memory storage instance
-        # @param agent_name [Symbol, String] Agent identifier
-        def initialize(memory_storage, agent_name)
-          super() # Call RubyLLM::Tool's initialize
-          @memory_storage = memory_storage
-          @agent_name = agent_name.to_sym
-        end
-
-        # Execute the tool
-        #
-        # @param file_path [String] Path to memory entry
-        # @param old_string [String] Text to replace
-        # @param new_string [String] Replacement text
-        # @param replace_all [Boolean] Replace all occurrences
-        # @return [String] Success message or error
-        def execute(file_path:, old_string:, new_string:, replace_all: false)
-          # Validate inputs
-          return validation_error("file_path is required") if file_path.nil? || file_path.to_s.strip.empty?
-          return validation_error("old_string is required") if old_string.nil? || old_string.empty?
-          return validation_error("new_string is required") if new_string.nil?
-
-          # old_string and new_string must be different
-          if old_string == new_string
-            return validation_error("old_string and new_string must be different. They are currently identical.")
-          end
-
-          # Read current content (this will raise ArgumentError if entry doesn't exist)
-          content = memory_storage.read(file_path: file_path)
-
-          # Enforce read-before-edit
-          unless Stores::StorageReadTracker.entry_read?(@agent_name, file_path)
-            return validation_error(
-              "Cannot edit memory entry without reading it first. " \
-                "You must use MemoryRead on 'memory://#{file_path}' before editing it. " \
-                "This ensures you have the current content to match against.",
-            )
-          end
-
-          # Check if old_string exists in content
-          unless content.include?(old_string)
-            return validation_error(<<~ERROR.chomp)
-              old_string not found in memory entry. Make sure it matches exactly, including all whitespace and indentation.
-              Do not include line number prefixes from MemoryRead tool output.
-            ERROR
-          end
-
-          # Count occurrences
-          occurrences = content.scan(old_string).count
-
-          # If not replace_all and multiple occurrences, error
-          if !replace_all && occurrences > 1
-            return validation_error(<<~ERROR.chomp)
-              Found #{occurrences} occurrences of old_string.
-              Either provide more surrounding context to make the match unique, or use replace_all: true to replace all occurrences.
-            ERROR
-          end
-
-          # Perform replacement
-          new_content = if replace_all
-            content.gsub(old_string, new_string)
-          else
-            content.sub(old_string, new_string)
-          end
-
-          # Get existing entry metadata
-          entries = memory_storage.list
-          existing_entry = entries.find { |e| e[:path] == file_path }
-
-          # Write updated content back (preserving the title)
-          memory_storage.write(
-            file_path: file_path,
-            content: new_content,
-            title: existing_entry[:title],
-          )
-
-          # Build success message
-          replaced_count = replace_all ? occurrences : 1
-          "Successfully replaced #{replaced_count} occurrence(s) in memory://#{file_path}"
-        rescue ArgumentError => e
-          validation_error(e.message)
-        end
-
-        private
-
-        attr_reader :memory_storage
-
-        def validation_error(message)
-          "<tool_use_error>InputValidationError: #{message}</tool_use_error>"
-        end
-      end
-    end
-  end
-end

data/lib/swarm_sdk/tools/memory/memory_glob.rb

@@ -1,94 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  module Tools
-    module Memory
-      # Tool for searching memory entries by glob pattern
-      #
-      # Finds memory entries matching a glob pattern (like filesystem glob).
-      # Each agent has its own isolated memory storage.
-      class MemoryGlob < RubyLLM::Tool
-        define_method(:name) { "MemoryGlob" }
-
-        description <<~DESC
-          Search your memory entries by glob pattern.
-          Works like filesystem glob - use * for wildcards, ** for recursive matching.
-          Use this to discover entries matching specific patterns.
-
-          Examples:
-          - "parallel/*" - all entries directly under parallel/
-          - "parallel/**" - all entries under parallel/ (recursive)
-          - "*/report" - all entries named "report" in any top-level directory
-          - "analysis/*/result_*" - entries like "analysis/foo/result_1"
-        DESC
-
-        param :pattern,
-          desc: "Glob pattern to match (e.g., '**/*.txt', 'parallel/*/task_*')",
-          required: true
-
-        class << self
-          # Create a MemoryGlob tool for a specific memory storage instance
-          #
-          # @param memory_storage [Stores::MemoryStorage] Per-agent memory storage instance
-          # @return [MemoryGlob] Tool instance
-          def create_for_memory(memory_storage)
-            new(memory_storage)
-          end
-        end
-
-        # Initialize with memory storage instance
-        #
-        # @param memory_storage [Stores::MemoryStorage] Per-agent memory storage instance
-        def initialize(memory_storage)
-          super() # Call RubyLLM::Tool's initialize
-          @memory_storage = memory_storage
-        end
-
-        # Execute the tool
-        #
-        # @param pattern [String] Glob pattern to match
-        # @return [String] Formatted list of matching entries
-        def execute(pattern:)
-          entries = memory_storage.glob(pattern: pattern)
-
-          if entries.empty?
-            return "No entries found matching pattern '#{pattern}'"
-          end
-
-          result = []
-          result << "Memory entries matching '#{pattern}' (#{entries.size} #{entries.size == 1 ? "entry" : "entries"}):"
-
-          entries.each do |entry|
-            result << "  memory://#{entry[:path]} - \"#{entry[:title]}\" (#{format_bytes(entry[:size])})"
-          end
-
-          result.join("\n")
-        rescue ArgumentError => e
-          validation_error(e.message)
-        end
-
-        private
-
-        attr_reader :memory_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/memory/memory_grep.rb

@@ -1,147 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  module Tools
-    module Memory
-      # Tool for searching memory content by pattern
-      #
-      # Searches content stored in memory entries using regex patterns.
-      # Each agent has its own isolated memory storage.
-      class MemoryGrep < RubyLLM::Tool
-        define_method(:name) { "MemoryGrep" }
-
-        description <<~DESC
-          Search your memory content by pattern (like grep).
-          Use regex patterns to search content within memory entries.
-          Returns matching entries and optionally line numbers and content.
-
-          Output modes:
-          - files_with_matches: Only list paths containing matches (default)
-          - content: Show matching lines with line numbers
-          - count: Show number of matches per file
-        DESC
-
-        param :pattern,
-          desc: "Regular expression pattern to search for",
-          required: true
-
-        param :case_insensitive,
-          desc: "Perform case-insensitive search (default: false)",
-          required: false
-
-        param :output_mode,
-          desc: "Output mode: 'files_with_matches' (default), 'content', or 'count'",
-          required: false
-
-        class << self
-          # Create a MemoryGrep tool for a specific memory storage instance
-          #
-          # @param memory_storage [Stores::MemoryStorage] Per-agent memory storage instance
-          # @return [MemoryGrep] Tool instance
-          def create_for_memory(memory_storage)
-            new(memory_storage)
-          end
-        end
-
-        # Initialize with memory storage instance
-        #
-        # @param memory_storage [Stores::MemoryStorage] Per-agent memory storage instance
-        def initialize(memory_storage)
-          super() # Call RubyLLM::Tool's initialize
-          @memory_storage = memory_storage
-        end
-
-        # Execute the tool
-        #
-        # @param pattern [String] Regex pattern to search for
-        # @param case_insensitive [Boolean] Whether to perform case-insensitive search
-        # @param output_mode [String] Output mode
-        # @return [String] Formatted search results
-        def execute(pattern:, case_insensitive: false, output_mode: "files_with_matches")
-          results = memory_storage.grep(
-            pattern: pattern,
-            case_insensitive: case_insensitive,
-            output_mode: output_mode,
-          )
-
-          format_results(results, pattern, output_mode)
-        rescue ArgumentError => e
-          validation_error(e.message)
-        rescue RegexpError => e
-          validation_error("Invalid regex pattern: #{e.message}")
-        end
-
-        private
-
-        attr_reader :memory_storage
-
-        def validation_error(message)
-          "<tool_use_error>InputValidationError: #{message}</tool_use_error>"
-        end
-
-        def format_results(results, pattern, output_mode)
-          case output_mode
-          when "files_with_matches"
-            format_files_with_matches(results, pattern)
-          when "content"
-            format_content(results, pattern)
-          when "count"
-            format_count(results, pattern)
-          else
-            validation_error("Invalid output_mode: #{output_mode}")
-          end
-        end
-
-        def format_files_with_matches(paths, pattern)
-          if paths.empty?
-            return "No matches found for pattern '#{pattern}'"
-          end
-
-          result = []
-          result << "Memory entries matching '#{pattern}' (#{paths.size} #{paths.size == 1 ? "entry" : "entries"}):"
-          paths.each do |path|
-            result << "  memory://#{path}"
-          end
-          result.join("\n")
-        end
-
-        def format_content(results, pattern)
-          if results.empty?
-            return "No matches found for pattern '#{pattern}'"
-          end
-
-          total_matches = results.sum { |r| r[:matches].size }
-          output = []
-          output << "Memory entries matching '#{pattern}' (#{results.size} #{results.size == 1 ? "entry" : "entries"}, #{total_matches} #{total_matches == 1 ? "match" : "matches"}):"
-          output << ""
-
-          results.each do |result|
-            output << "memory://#{result[:path]}:"
-            result[:matches].each do |match|
-              output << "  #{match[:line_number]}: #{match[:content]}"
-            end
-            output << ""
-          end
-
-          output.join("\n").rstrip
-        end
-
-        def format_count(results, pattern)
-          if results.empty?
-            return "No matches found for pattern '#{pattern}'"
-          end
-
-          total_matches = results.sum { |r| r[:count] }
-          output = []
-          output << "Memory entries matching '#{pattern}' (#{results.size} #{results.size == 1 ? "entry" : "entries"}, #{total_matches} total #{total_matches == 1 ? "match" : "matches"}):"
-
-          results.each do |result|
-            output << "  memory://#{result[:path]}: #{result[:count]} #{result[:count] == 1 ? "match" : "matches"}"
-          end
-
-          output.join("\n")
-        end
-      end
-    end
-  end
-end

data/lib/swarm_sdk/tools/memory/memory_multi_edit.rb

@@ -1,228 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  module Tools
-    module Memory
-      # Tool for performing multiple edits to a memory entry
-      #
-      # Applies multiple edit operations sequentially to a single memory entry.
-      # Each edit sees the result of all previous edits, allowing for
-      # coordinated multi-step transformations.
-      # Each agent has its own isolated memory storage.
-      class MemoryMultiEdit < RubyLLM::Tool
-        define_method(:name) { "MemoryMultiEdit" }
-
-        description <<~DESC
-          Performs multiple exact string replacements in a single memory entry.
-          Edits are applied sequentially, so later edits see the results of earlier ones.
-          You must use MemoryRead on the entry before editing it.
-          When editing text from MemoryRead output, ensure you preserve the exact indentation as it appears AFTER the line number prefix.
-          The line number prefix format is: spaces + line number + tab. Everything after that tab is the actual content to match.
-          Never include any part of the line number prefix in the old_string or new_string.
-          Each edit will FAIL if old_string is not unique in the entry. Either provide a larger string with more surrounding context to make it unique or use replace_all to change every instance of old_string.
-          Use replace_all for replacing and renaming strings across the entry.
-        DESC
-
-        param :file_path,
-          desc: "Path to the memory entry (e.g., 'analysis/report', 'parallel/batch1/task_0')",
-          required: true
-
-        param :edits_json,
-          type: "string",
-          desc: <<~DESC.chomp,
-            JSON array of edit operations. Each edit must have:
-            old_string (exact text to replace),
-            new_string (replacement text),
-            and optionally replace_all (boolean, default false).
-            Example: [{"old_string":"foo","new_string":"bar","replace_all":false}]
-          DESC
-          required: true
-
-        class << self
-          # Create a MemoryMultiEdit tool for a specific memory storage instance
-          #
-          # @param memory_storage [Stores::MemoryStorage] Per-agent memory storage instance
-          # @param agent_name [Symbol, String] Agent identifier for tracking reads
-          # @return [MemoryMultiEdit] Tool instance
-          def create_for_memory(memory_storage, agent_name)
-            new(memory_storage, agent_name)
-          end
-        end
-
-        # Initialize with memory storage instance and agent name
-        #
-        # @param memory_storage [Stores::MemoryStorage] Per-agent memory storage instance
-        # @param agent_name [Symbol, String] Agent identifier
-        def initialize(memory_storage, agent_name)
-          super() # Call RubyLLM::Tool's initialize
-          @memory_storage = memory_storage
-          @agent_name = agent_name.to_sym
-        end
-
-        # Execute the tool
-        #
-        # @param file_path [String] Path to memory entry
-        # @param edits_json [String] JSON array of edit operations
-        # @return [String] Success message or error
-        def execute(file_path:, edits_json:)
-          # Validate inputs
-          return validation_error("file_path is required") if file_path.nil? || file_path.to_s.strip.empty?
-
-          # Parse JSON
-          edits = begin
-            JSON.parse(edits_json)
-          rescue JSON::ParserError
-            nil
-          end
-
-          return validation_error("Invalid JSON format. Please provide a valid JSON array of edit operations.") if edits.nil?
-
-          return validation_error("edits must be an array") unless edits.is_a?(Array)
-          return validation_error("edits array cannot be empty") if edits.empty?
-
-          # Read current content (this will raise ArgumentError if entry doesn't exist)
-          content = memory_storage.read(file_path: file_path)
-
-          # Enforce read-before-edit
-          unless Stores::StorageReadTracker.entry_read?(@agent_name, file_path)
-            return validation_error(
-              "Cannot edit memory entry without reading it first. " \
-                "You must use MemoryRead on 'memory://#{file_path}' before editing it. " \
-                "This ensures you have the current content to match against.",
-            )
-          end
-
-          # Validate edit operations
-          validated_edits = []
-          edits.each_with_index do |edit, index|
-            unless edit.is_a?(Hash)
-              return validation_error("Edit at index #{index} must be a hash/object with old_string and new_string")
-            end
-
-            # Convert string keys to symbols for consistency
-            edit = edit.transform_keys(&:to_sym)
-
-            unless edit[:old_string]
-              return validation_error("Edit at index #{index} missing required field 'old_string'")
-            end
-
-            unless edit[:new_string]
-              return validation_error("Edit at index #{index} missing required field 'new_string'")
-            end
-
-            # old_string and new_string must be different
-            if edit[:old_string] == edit[:new_string]
-              return validation_error("Edit at index #{index}: old_string and new_string must be different")
-            end
-
-            validated_edits << {
-              old_string: edit[:old_string].to_s,
-              new_string: edit[:new_string].to_s,
-              replace_all: edit[:replace_all] == true,
-              index: index,
-            }
-          end
-
-          # Apply edits sequentially
-          results = []
-          current_content = content
-
-          validated_edits.each do |edit|
-            # Check if old_string exists in current content
-            unless current_content.include?(edit[:old_string])
-              return error_with_results(
-                <<~ERROR.chomp,
-                  Edit #{edit[:index]}: old_string not found in memory entry.
-                  Make sure it matches exactly, including all whitespace and indentation.
-                  Do not include line number prefixes from MemoryRead tool output.
-                  Note: This edit follows #{edit[:index]} previous edit(s) which may have changed the content.
-                ERROR
-                results,
-              )
-            end
-
-            # Count occurrences
-            occurrences = current_content.scan(edit[:old_string]).count
-
-            # If not replace_all and multiple occurrences, error
-            if !edit[:replace_all] && occurrences > 1
-              return error_with_results(
-                <<~ERROR.chomp,
-                  Edit #{edit[:index]}: Found #{occurrences} occurrences of old_string.
-                  Either provide more surrounding context to make the match unique, or set replace_all: true to replace all occurrences.
-                ERROR
-                results,
-              )
-            end
-
-            # Perform replacement
-            new_content = if edit[:replace_all]
-              current_content.gsub(edit[:old_string], edit[:new_string])
-            else
-              current_content.sub(edit[:old_string], edit[:new_string])
-            end
-
-            # Record result
-            replaced_count = edit[:replace_all] ? occurrences : 1
-            results << {
-              index: edit[:index],
-              status: "success",
-              occurrences: replaced_count,
-              message: "Replaced #{replaced_count} occurrence(s)",
-            }
-
-            # Update content for next edit
-            current_content = new_content
-          end
-
-          # Get existing entry metadata
-          entries = memory_storage.list
-          existing_entry = entries.find { |e| e[:path] == file_path }
-
-          # Write updated content back (preserving the title)
-          memory_storage.write(
-            file_path: file_path,
-            content: current_content,
-            title: existing_entry[:title],
-          )
-
-          # Build success message
-          total_replacements = results.sum { |r| r[:occurrences] }
-          message = "Successfully applied #{validated_edits.size} edit(s) to memory://#{file_path}\n"
-          message += "Total replacements: #{total_replacements}\n\n"
-          message += "Details:\n"
-          results.each do |result|
-            message += "  Edit #{result[:index]}: #{result[:message]}\n"
-          end
-
-          message
-        rescue ArgumentError => e
-          validation_error(e.message)
-        end
-
-        private
-
-        attr_reader :memory_storage
-
-        def validation_error(message)
-          "<tool_use_error>InputValidationError: #{message}</tool_use_error>"
-        end
-
-        def error_with_results(message, results)
-          output = "<tool_use_error>InputValidationError: #{message}\n\n"
-
-          if results.any?
-            output += "Previous successful edits before error:\n"
-            results.each do |result|
-              output += "  Edit #{result[:index]}: #{result[:message]}\n"
-            end
-            output += "\n"
-          end
-
-          output += "Note: The memory entry has NOT been modified. All or nothing approach - if any edit fails, no changes are saved.</tool_use_error>"
-          output
-        end
-      end
-    end
-  end
-end

data/lib/swarm_sdk/tools/memory/memory_read.rb

@@ -1,82 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  module Tools
-    module Memory
-      # Tool for reading content from memory storage
-      #
-      # Retrieves content stored by this agent using memory_write.
-      # Each agent has its own isolated memory storage.
-      class MemoryRead < RubyLLM::Tool
-        define_method(:name) { "MemoryRead" }
-
-        description <<~DESC
-          Read content from your memory storage.
-          Use this to retrieve detailed outputs, analysis, or results that were
-          stored using memory_write. Only you (this agent) can access your memory.
-        DESC
-
-        param :file_path,
-          desc: "Path to read from memory (e.g., 'analysis/report', 'parallel/batch1/task_0')",
-          required: true
-
-        class << self
-          # Create a MemoryRead tool for a specific memory storage instance
-          #
-          # @param memory_storage [Stores::MemoryStorage] Per-agent memory storage instance
-          # @param agent_name [Symbol, String] Agent identifier for tracking reads
-          # @return [MemoryRead] Tool instance
-          def create_for_memory(memory_storage, agent_name)
-            new(memory_storage, agent_name)
-          end
-        end
-
-        # Initialize with memory storage instance and agent name
-        #
-        # @param memory_storage [Stores::MemoryStorage] Per-agent memory storage instance
-        # @param agent_name [Symbol, String] Agent identifier
-        def initialize(memory_storage, agent_name)
-          super() # Call RubyLLM::Tool's initialize
-          @memory_storage = memory_storage
-          @agent_name = agent_name.to_sym
-        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:)
-          # Register this read in the tracker
-          Stores::StorageReadTracker.register_read(@agent_name, file_path)
-
-          content = memory_storage.read(file_path: file_path)
-          format_with_line_numbers(content)
-        rescue ArgumentError => e
-          validation_error(e.message)
-        end
-
-        private
-
-        attr_reader :memory_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