swarm_sdk 2.0.3 → 2.0.5

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

@@ -0,0 +1,228 @@
+# 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

@@ -0,0 +1,82 @@
+# 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

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

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Tools
+    module Memory
+      # Tool for writing content to memory storage
+      #
+      # Stores content in persistent, per-agent memory storage with metadata.
+      # Each agent has its own isolated memory storage that persists across sessions.
+      class MemoryWrite < RubyLLM::Tool
+        define_method(:name) { "MemoryWrite" }
+
+        description <<~DESC
+          Store content in memory for later retrieval.
+          Use this to save detailed outputs, analysis, or results that would
+          otherwise bloat tool responses. Only you (this agent) can access your memory.
+
+          IMPORTANT: You must determine the appropriate file_path based on the task you're performing.
+          Choose a logical, descriptive path that reflects the content type and purpose.
+          Examples: 'analysis/code_review', 'research/findings', 'parallel/batch_1/results', 'logs/debug_trace'
+        DESC
+
+        param :file_path,
+          desc: "File-path-like address you determine based on the task (e.g., 'analysis/report', 'parallel/batch1/task_0')",
+          required: true
+
+        param :content,
+          desc: "Content to store in memory (max 1MB per entry)",
+          required: true
+
+        param :title,
+          desc: "Brief title describing the content (shown in listings)",
+          required: true
+
+        class << self
+          # Create a MemoryWrite tool for a specific memory storage instance
+          #
+          # @param memory_storage [Stores::MemoryStorage] Per-agent memory storage instance
+          # @return [MemoryWrite] 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 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 = memory_storage.write(file_path: file_path, content: content, title: title)
+          "Stored at memory://#{file_path} (#{format_bytes(entry.size)})"
+        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/registry.rb

@@ -17,10 +17,18 @@ module SwarmSDK
         Glob: SwarmSDK::Tools::Glob,
         MultiEdit: :special, # Requires agent context for read-before-edit enforcement
         TodoWrite: :special, # Requires agent context for todo tracking
-        ScratchpadWrite: :special, # Requires scratchpad instance
-        ScratchpadRead: :special, # Requires scratchpad instance
-        ScratchpadList: :special, # Requires scratchpad instance
+        ScratchpadWrite: :special, # Requires scratchpad storage instance
+        ScratchpadRead: :special, # Requires scratchpad storage instance
+        ScratchpadList: :special, # Requires scratchpad storage instance
+        MemoryWrite: :special, # Requires memory storage instance
+        MemoryRead: :special, # Requires memory storage instance
+        MemoryEdit: :special, # Requires memory storage instance
+        MemoryMultiEdit: :special, # Requires memory storage instance
+        MemoryDelete: :special, # Requires memory storage instance
+        MemoryGlob: :special, # Requires memory storage instance
+        MemoryGrep: :special, # Requires memory storage instance
         Think: SwarmSDK::Tools::Think,
+        WebFetch: SwarmSDK::Tools::WebFetch,
       }.freeze
 
       class << self

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

@@ -0,0 +1,96 @@
+# 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.
+          Shows path, title, size, and last updated time for each entry.
+          Use this to discover what's stored in the scratchpad.
+        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

@@ -0,0 +1,76 @@
+# 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.
+          Use this to retrieve temporary notes, results, or messages stored by any agent.
+          Any agent can read any scratchpad content.
+        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

@@ -0,0 +1,91 @@
+# 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.
+          Use this for quick notes, intermediate results, or coordination messages.
+          Any agent can read this content. Data is lost when the swarm ends.
+
+          For persistent storage that survives across sessions, use MemoryWrite instead.
+
+          Choose a simple, descriptive path. Examples: 'status', 'result', 'notes/agent_x'
+        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