swarm_sdk 2.0.4 → 2.0.5

data/lib/swarm_sdk/tools/scratchpad_grep.rb

@@ -1,145 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  module Tools
-    # Tool for searching scratchpad content by pattern
-    #
-    # Searches content stored in scratchpad entries using regex patterns.
-    # All agents in the swarm share the same scratchpad.
-    class ScratchpadGrep < RubyLLM::Tool
-      define_method(:name) { "ScratchpadGrep" }
-
-      description <<~DESC
-        Search scratchpad content by pattern (like grep).
-        Use regex patterns to search content within scratchpad 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 ScratchpadGrep tool for a specific scratchpad instance
-        #
-        # @param scratchpad [Stores::Scratchpad] Shared scratchpad instance
-        # @return [ScratchpadGrep] Tool instance
-        def create_for_scratchpad(scratchpad)
-          new(scratchpad)
-        end
-      end
-
-      # Initialize with scratchpad instance
-      #
-      # @param scratchpad [Stores::Scratchpad] Shared scratchpad instance
-      def initialize(scratchpad)
-        super() # Call RubyLLM::Tool's initialize
-        @scratchpad = scratchpad
-      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 = scratchpad.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 :scratchpad
-
-      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 << "Scratchpad entries matching '#{pattern}' (#{paths.size} #{paths.size == 1 ? "entry" : "entries"}):"
-        paths.each do |path|
-          result << "  scratchpad://#{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 << "Scratchpad entries matching '#{pattern}' (#{results.size} #{results.size == 1 ? "entry" : "entries"}, #{total_matches} #{total_matches == 1 ? "match" : "matches"}):"
-        output << ""
-
-        results.each do |result|
-          output << "scratchpad://#{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 << "Scratchpad entries matching '#{pattern}' (#{results.size} #{results.size == 1 ? "entry" : "entries"}, #{total_matches} total #{total_matches == 1 ? "match" : "matches"}):"
-
-        results.each do |result|
-          output << "  scratchpad://#{result[:path]}: #{result[:count]} #{result[:count] == 1 ? "match" : "matches"}"
-        end
-
-        output.join("\n")
-      end
-    end
-  end
-end

data/lib/swarm_sdk/tools/scratchpad_multi_edit.rb

@@ -1,226 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  module Tools
-    # Tool for performing multiple edits to a scratchpad entry
-    #
-    # Applies multiple edit operations sequentially to a single scratchpad entry.
-    # Each edit sees the result of all previous edits, allowing for
-    # coordinated multi-step transformations.
-    # All agents in the swarm share the same scratchpad.
-    class ScratchpadMultiEdit < RubyLLM::Tool
-      define_method(:name) { "ScratchpadMultiEdit" }
-
-      description <<~DESC
-        Performs multiple exact string replacements in a single scratchpad entry.
-        Edits are applied sequentially, so later edits see the results of earlier ones.
-        You must use ScratchpadRead on the entry before editing it.
-        When editing text from ScratchpadRead 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 scratchpad 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 ScratchpadMultiEdit tool for a specific scratchpad instance
-        #
-        # @param scratchpad [Stores::Scratchpad] Shared scratchpad instance
-        # @param agent_name [Symbol, String] Agent identifier for tracking reads
-        # @return [ScratchpadMultiEdit] Tool instance
-        def create_for_scratchpad(scratchpad, agent_name)
-          new(scratchpad, agent_name)
-        end
-      end
-
-      # Initialize with scratchpad instance and agent name
-      #
-      # @param scratchpad [Stores::Scratchpad] Shared scratchpad instance
-      # @param agent_name [Symbol, String] Agent identifier
-      def initialize(scratchpad, agent_name)
-        super() # Call RubyLLM::Tool's initialize
-        @scratchpad = scratchpad
-        @agent_name = agent_name.to_sym
-      end
-
-      # Execute the tool
-      #
-      # @param file_path [String] Path to scratchpad 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 = scratchpad.read(file_path: file_path)
-
-        # Enforce read-before-edit
-        unless Stores::ScratchpadReadTracker.entry_read?(@agent_name, file_path)
-          return validation_error(
-            "Cannot edit scratchpad entry without reading it first. " \
-              "You must use ScratchpadRead on 'scratchpad://#{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 scratchpad entry.
-                Make sure it matches exactly, including all whitespace and indentation.
-                Do not include line number prefixes from ScratchpadRead 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 = scratchpad.list
-        existing_entry = entries.find { |e| e[:path] == file_path }
-
-        # Write updated content back (preserving the title)
-        scratchpad.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 scratchpad://#{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 :scratchpad
-
-      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 scratchpad 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

data/lib/swarm_sdk/tools/scratchpad_read.rb

@@ -1,80 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  module Tools
-    # Tool for reading content from scratchpad memory
-    #
-    # 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 detailed outputs, analysis, or results that were
-        stored using scratchpad_write. Any agent can read any scratchpad content.
-      DESC
-
-      param :file_path,
-        desc: "Path to read from scratchpad (e.g., 'analysis/report', 'parallel/batch1/task_0')",
-        required: true
-
-      class << self
-        # Create a ScratchpadRead tool for a specific scratchpad instance
-        #
-        # @param scratchpad [Stores::Scratchpad] Shared scratchpad instance
-        # @param agent_name [Symbol, String] Agent identifier for tracking reads
-        # @return [ScratchpadRead] Tool instance
-        def create_for_scratchpad(scratchpad, agent_name)
-          new(scratchpad, agent_name)
-        end
-      end
-
-      # Initialize with scratchpad instance and agent name
-      #
-      # @param scratchpad [Stores::Scratchpad] Shared scratchpad instance
-      # @param agent_name [Symbol, String] Agent identifier
-      def initialize(scratchpad, agent_name)
-        super() # Call RubyLLM::Tool's initialize
-        @scratchpad = scratchpad
-        @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::ScratchpadReadTracker.register_read(@agent_name, file_path)
-
-        content = scratchpad.read(file_path: file_path)
-        format_with_line_numbers(content)
-      rescue ArgumentError => e
-        validation_error(e.message)
-      end
-
-      private
-
-      attr_reader :scratchpad
-
-      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

data/lib/swarm_sdk/tools/scratchpad_write.rb

@@ -1,88 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  module Tools
-    # Tool for writing content to scratchpad memory
-    #
-    # Stores content in session-scoped, in-memory storage with metadata.
-    # All agents in the swarm share the same scratchpad.
-    class ScratchpadWrite < RubyLLM::Tool
-      define_method(:name) { "ScratchpadWrite" }
-
-      description <<~DESC
-        Store content in scratchpad for later retrieval.
-        Use this to save detailed outputs, analysis, or results that would
-        otherwise bloat tool responses. Any agent can read this content using scratchpad_read.
-
-        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 scratchpad (max 1MB per entry)",
-        required: true
-
-      param :title,
-        desc: "Brief title describing the content (shown in listings)",
-        required: true
-
-      class << self
-        # Create a ScratchpadWrite tool for a specific scratchpad instance
-        #
-        # @param scratchpad [Stores::Scratchpad] Shared scratchpad instance
-        # @return [ScratchpadWrite] Tool instance
-        def create_for_scratchpad(scratchpad)
-          new(scratchpad)
-        end
-      end
-
-      # Initialize with scratchpad instance
-      #
-      # @param scratchpad [Stores::Scratchpad] Shared scratchpad instance
-      def initialize(scratchpad)
-        super() # Call RubyLLM::Tool's initialize
-        @scratchpad = scratchpad
-      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.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
-
-      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