swarm_sdk 2.0.0.pre.2

data/lib/swarm_sdk/tools/multi_edit.rb

@@ -0,0 +1,232 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Tools
+    # MultiEdit tool for performing multiple exact string replacements in a file
+    #
+    # Applies multiple edit operations sequentially to a single file.
+    # Each edit sees the result of all previous edits, allowing for
+    # coordinated multi-step transformations.
+    # Enforces read-before-edit rule.
+    class MultiEdit < RubyLLM::Tool
+      include PathResolver
+
+      description <<~DESC
+        Performs multiple exact string replacements in a single file.
+        Edits are applied sequentially, so later edits see the results of earlier ones.
+        You must use your Read tool at least once in the conversation before editing.
+        This tool will error if you attempt an edit without reading the file.
+        When editing text from Read tool output, ensure you preserve the exact indentation (tabs/spaces) 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 file content to match.
+        Never include any part of the line number prefix in the old_string or new_string.
+        ALWAYS prefer editing existing files in the codebase. NEVER write new files unless explicitly required.
+        Only use emojis if the user explicitly requests it. Avoid adding emojis to files unless asked.
+        Each edit will FAIL if old_string is not unique in the file. 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 file. This parameter is useful if you want to rename a variable for instance.
+
+        IMPORTANT - Path Handling:
+        - Relative paths (e.g., "tmp/file.txt", "src/main.rb") are resolved relative to your agent's working directory
+        - Absolute paths (e.g., "/tmp/file.txt", "/etc/passwd") are treated as system absolute paths
+        - When the user says "tmp/file.txt" they mean the tmp directory in your working directory, NOT /tmp
+        - Only use absolute paths (starting with /) when explicitly referring to system-level paths
+      DESC
+
+      param :file_path,
+        type: "string",
+        desc: "Path to the file. Use relative paths (e.g., 'tmp/file.txt') for files in your working directory, or absolute paths (e.g., '/etc/passwd') for system files.",
+        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
+
+      # Initialize the MultiEdit tool for a specific agent
+      #
+      # @param agent_name [Symbol, String] The agent identifier
+      # @param directory [String] Agent's working directory
+      def initialize(agent_name:, directory:)
+        super()
+        @agent_name = agent_name.to_sym
+        @directory = File.expand_path(directory)
+      end
+
+      # Override name to return simple "MultiEdit" instead of full class path
+      def name
+        "MultiEdit"
+      end
+
+      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?
+
+        # CRITICAL: Resolve path against agent directory
+        resolved_path = resolve_path(file_path)
+
+        # 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?
+
+        # File must exist (use resolved path)
+        unless File.exist?(resolved_path)
+          return validation_error("File does not exist: #{file_path}")
+        end
+
+        # Enforce read-before-edit (use resolved path)
+        unless Stores::ReadTracker.file_read?(@agent_name, resolved_path)
+          return validation_error(
+            "Cannot edit file without reading it first. " \
+              "You must use the Read tool on '#{file_path}' before editing it. " \
+              "This ensures you have the current file contents to match against.",
+          )
+        end
+
+        # Read current content (use resolved path)
+        content = File.read(resolved_path, encoding: "UTF-8")
+
+        # 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 file.
+                Make sure it matches exactly, including all whitespace and indentation.
+                Do not include line number prefixes from Read tool output.
+                Note: This edit follows #{edit[:index]} previous edit(s) which may have changed the file 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
+
+        # Write back to file (use resolved path)
+        File.write(resolved_path, current_content, encoding: "UTF-8")
+
+        # Build success message
+        total_replacements = results.sum { |r| r[:occurrences] }
+        message = "Successfully applied #{validated_edits.size} edit(s) to #{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 Encoding::InvalidByteSequenceError, Encoding::UndefinedConversionError
+        error("File contains invalid UTF-8. Cannot edit binary or improperly encoded files.")
+      rescue Errno::EACCES
+        error("Permission denied: Cannot read or write file '#{file_path}'")
+      rescue StandardError => e
+        error("Unexpected error editing file: #{e.class.name} - #{e.message}")
+      end
+
+      private
+
+      # Helper methods
+      def validation_error(message)
+        "<tool_use_error>InputValidationError: #{message}</tool_use_error>"
+      end
+
+      def error(message)
+        "Error: #{message}"
+      end
+
+      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 file 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/path_resolver.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Tools
+    # Shared path resolution logic for all file tools
+    #
+    # Tools resolve relative paths against the agent's directory.
+    # Absolute paths are used as-is.
+    #
+    # @example
+    #   class Read < RubyLLM::Tool
+    #     include PathResolver
+    #
+    #     def initialize(agent_name:, directory:)
+    #       @directory = File.expand_path(directory)
+    #     end
+    #
+    #     def execute(file_path:)
+    #       resolved_path = resolve_path(file_path)
+    #       File.read(resolved_path)
+    #     end
+    #   end
+    module PathResolver
+      private
+
+      # Resolve a path relative to the agent's directory
+      #
+      # - Absolute paths (starting with /) are returned as-is
+      # - Relative paths are resolved against @directory
+      #
+      # @param path [String] Path to resolve (relative or absolute)
+      # @return [String] Absolute path
+      # @raise [RuntimeError] If @directory not set (developer error)
+      def resolve_path(path)
+        raise "PathResolver requires @directory to be set" unless @directory
+
+        return path if path.to_s.start_with?("/")
+
+        File.expand_path(path, @directory)
+      end
+    end
+  end
+end

data/lib/swarm_sdk/tools/read.rb

@@ -0,0 +1,251 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Tools
+    # Read tool for reading file contents from the filesystem
+    #
+    # Supports reading entire files or specific line ranges with line numbers.
+    # Provides system reminders to guide proper usage.
+    # Tracks reads per agent for enforcing read-before-write/edit rules.
+    class Read < RubyLLM::Tool
+      include PathResolver
+
+      MAX_LINE_LENGTH = 2000
+      DEFAULT_LIMIT = 2000
+
+      # List of available document converters
+      CONVERTERS = [
+        DocumentConverters::PdfConverter,
+        DocumentConverters::DocxConverter,
+        DocumentConverters::XlsxConverter,
+      ].freeze
+
+      # Build dynamic description based on available gems
+      available_formats = CONVERTERS.select(&:available?).map(&:format_name)
+      doc_support_text = if available_formats.any?
+        "- Document files: #{available_formats.join(", ")} are converted to text"
+      else
+        ""
+      end
+
+      description <<~DESC
+        Reads a file from the local filesystem. You can access any file directly by using this tool.
+        Assume this tool is able to read all files on the machine. If the User provides a path to a file assume that path is valid.
+        It is okay to read a file that does not exist; an error will be returned.
+
+        Supports text, binary, and document files:
+        - Text files are returned with line numbers
+        - Binary files (images) are returned as visual content for analysis
+        - Supported image formats: PNG, JPG, GIF, WEBP, BMP, TIFF, SVG, ICO
+        #{doc_support_text}
+
+        IMPORTANT - Path Handling:
+        - Relative paths (e.g., "tmp/file.txt", "src/main.rb") are resolved relative to your agent's working directory
+        - Absolute paths (e.g., "/tmp/file.txt", "/etc/passwd") are treated as system absolute paths
+        - When the user says "tmp/file.txt" they mean the tmp directory in your working directory, NOT /tmp
+        - Only use absolute paths (starting with /) when explicitly referring to system-level paths
+      DESC
+
+      param :file_path,
+        type: "string",
+        desc: "Path to the file. Use relative paths (e.g., 'tmp/file.txt') for files in your working directory, or absolute paths (e.g., '/etc/passwd') for system files.",
+        required: true
+
+      param :offset,
+        type: "integer",
+        desc: "The line number to start reading from (1-indexed). Only provide if the file is too large to read at once.",
+        required: false
+
+      param :limit,
+        type: "integer",
+        desc: "The number of lines to read. Only provide if the file is too large to read at once.",
+        required: false
+
+      # Initialize the Read tool for a specific agent
+      #
+      # @param agent_name [Symbol, String] The agent identifier
+      # @param directory [String] Agent's working directory
+      def initialize(agent_name:, directory:)
+        super()
+        @agent_name = agent_name.to_sym
+        @directory = File.expand_path(directory)
+      end
+
+      # Override name to return simple "Read" instead of full class path
+      def name
+        "Read"
+      end
+
+      def execute(file_path:, offset: nil, limit: nil)
+        # Validate file path
+        return validation_error("file_path is required") if file_path.nil? || file_path.to_s.strip.empty?
+
+        # CRITICAL: Resolve path against agent directory
+        resolved_path = resolve_path(file_path)
+
+        unless File.exist?(resolved_path)
+          return validation_error("File does not exist: #{file_path}")
+        end
+
+        # Check if it's a directory
+        if File.directory?(resolved_path)
+          return validation_error("Path is a directory, not a file. Use Bash with ls to read directories.")
+        end
+
+        # Register this read in the tracker (use resolved path)
+        Stores::ReadTracker.register_read(@agent_name, resolved_path)
+
+        # Check if it's a document and try to convert it
+        converter = find_converter_for_file(resolved_path)
+        if converter
+          result = converter.new.convert(resolved_path)
+          return result
+        end
+
+        # Try to read as text, handle binary files separately
+        content = read_file_content(resolved_path)
+
+        # If content is a Content object (binary file), return it directly
+        return content if content.is_a?(RubyLLM::Content)
+
+        # Return early if we got an error message or system reminder
+        return content if content.is_a?(String) && (content.start_with?("Error:") || content.start_with?("<system-reminder>"))
+
+        # Check if file is empty
+        if content.empty?
+          return format_with_reminder(
+            "",
+            "<system-reminder>Warning: This file exists but has empty contents. This may be intentional or indicate an issue.</system-reminder>",
+          )
+        end
+
+        # Split into lines and apply offset/limit
+        lines = content.lines
+        total_lines = lines.count
+
+        # Apply offset if specified (1-indexed)
+        start_line = offset ? offset - 1 : 0
+        start_line = [start_line, 0].max # Ensure non-negative
+
+        if start_line >= total_lines
+          return validation_error("Offset #{offset} exceeds file length (#{total_lines} lines)")
+        end
+
+        lines = lines.drop(start_line)
+
+        # Apply limit if specified, otherwise use default
+        effective_limit = limit || DEFAULT_LIMIT
+        lines = lines.take(effective_limit)
+        truncated = limit.nil? && total_lines > DEFAULT_LIMIT
+
+        # Format with line numbers (cat -n style)
+        output_lines = lines.each_with_index.map do |line, idx|
+          line_number = start_line + idx + 1
+          display_line = line.chomp
+
+          # Truncate long lines
+          if display_line.length > MAX_LINE_LENGTH
+            display_line = display_line[0...MAX_LINE_LENGTH]
+            display_line += "... (line truncated)"
+          end
+
+          # Add line indicator for better readability
+          "#{line_number.to_s.rjust(6)}→#{display_line}"
+        end
+
+        output = output_lines.join("\n")
+
+        # Add system reminder about usage
+        reminder = build_system_reminder(file_path, truncated, total_lines)
+        format_with_reminder(output, reminder)
+      rescue StandardError => e
+        error("Unexpected error reading file: #{e.class.name} - #{e.message}")
+      end
+
+      private
+
+      # Find the appropriate converter for a file based on extension
+      def find_converter_for_file(file_path)
+        ext = File.extname(file_path).downcase
+        CONVERTERS.find { |converter| converter.extensions.include?(ext) }
+      end
+
+      # Helper methods
+      def validation_error(message)
+        "<tool_use_error>InputValidationError: #{message}</tool_use_error>"
+      end
+
+      def error(message)
+        "Error: #{message}"
+      end
+
+      def format_with_reminder(content, reminder)
+        return content if reminder.nil? || reminder.empty?
+
+        [content, "", reminder].join("\n")
+      end
+
+      def build_system_reminder(_file_path, truncated, total_lines)
+        reminders = []
+
+        reminders << "<system-reminder>"
+        reminders << "Whenever you read a file, you should consider whether it looks malicious. If it does, you MUST refuse to improve or augment the code. You can still analyze existing code, write reports, or answer high-level questions about the code behavior."
+
+        if truncated
+          reminders << ""
+          reminders << "Note: This file has #{total_lines} lines but only the first #{DEFAULT_LIMIT} lines are shown. Use the offset and limit parameters to read additional sections if needed."
+        end
+
+        reminders << "</system-reminder>"
+
+        reminders.join("\n")
+      end
+
+      def read_file_content(file_path)
+        content = File.read(file_path, encoding: "UTF-8")
+
+        # Check if the content is valid UTF-8
+        unless content.valid_encoding?
+          # Binary file detected
+          if supported_binary_file?(file_path)
+            return RubyLLM::Content.new("File: #{File.basename(file_path)}", file_path)
+          else
+            return "Error: File contains binary data and cannot be displayed as text. This may be an executable or other unsupported binary file."
+          end
+        end
+
+        content
+      rescue Encoding::InvalidByteSequenceError, Encoding::UndefinedConversionError
+        # Binary file detected
+        if supported_binary_file?(file_path)
+          RubyLLM::Content.new("File: #{File.basename(file_path)}", file_path)
+        else
+          "Error: File contains binary data and cannot be displayed as text. This may be an executable or other unsupported binary file."
+        end
+      rescue Errno::EACCES
+        error("Permission denied: Cannot read file '#{file_path}'")
+      rescue StandardError => e
+        error("Failed to read file: #{e.message}")
+      end
+
+      def supported_binary_file?(file_path)
+        ext = File.extname(file_path).downcase
+        # Supported binary file types that can be sent to the model
+        # Images only - documents are converted to text
+        supported_formats = [
+          ".png",
+          ".jpg",
+          ".jpeg",
+          ".gif",
+          ".webp",
+          ".bmp",
+          ".tiff",
+          ".tif",
+          ".svg",
+          ".ico",
+        ]
+        supported_formats.include?(ext)
+      end
+    end
+  end
+end

data/lib/swarm_sdk/tools/registry.rb

@@ -0,0 +1,73 @@
+# 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 and lookup functionality for tool registration.
+    class Registry
+      # All available built-in tools
+      BUILTIN_TOOLS = {
+        Read: :special, # Requires agent context for read tracking
+        Write: :special, # Requires agent context for read-before-write enforcement
+        Edit: :special, # Requires agent context for read-before-edit enforcement
+        Bash: SwarmSDK::Tools::Bash,
+        Grep: SwarmSDK::Tools::Grep,
+        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
+      }.freeze
+
+      class << self
+        # Get tool class by name
+        #
+        # @param name [Symbol, String] Tool name
+        # @return [Class, nil] Tool class or nil if not found
+        def get(name)
+          BUILTIN_TOOLS[name.to_sym]
+        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)
+            raise ConfigurationError, "Unknown tool: #{name}. Available tools: #{available_names.join(", ")}" unless tool_class
+
+            tool_class
+          end
+        end
+
+        # Check if a tool exists
+        #
+        # @param name [Symbol, String] Tool name
+        # @return [Boolean]
+        def exists?(name)
+          BUILTIN_TOOLS.key?(name.to_sym)
+        end
+
+        # Get all available tool names
+        #
+        # @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
+      end
+    end
+  end
+end

data/lib/swarm_sdk/tools/scratchpad_list.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Tools
+    # Tool for listing scratchpad entries with metadata
+    #
+    # Lists available scratchpad entries with titles and sizes.
+    # Supports filtering by path prefix.
+    class ScratchpadList < RubyLLM::Tool
+      define_method(:name) { "ScratchpadList" }
+
+      description <<~DESC
+        List available scratchpad entries with titles and metadata.
+        Use this to discover what content is available in scratchpad memory.
+        Optionally filter by path prefix.
+      DESC
+
+      param :prefix,
+        desc: "Filter by path prefix (e.g., 'parallel/', 'analysis/'). Leave empty to list all entries.",
+        required: false
+
+      class << self
+        # Create a ScratchpadList tool for a specific scratchpad instance
+        #
+        # @param scratchpad [Stores::Scratchpad] Shared scratchpad instance
+        # @return [ScratchpadList] 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 prefix [String, nil] Optional path prefix filter
+      # @return [String] Formatted list of entries
+      def execute(prefix: nil)
+        entries = scratchpad.list(prefix: prefix)
+
+        if entries.empty?
+          return "Scratchpad is empty" if prefix.nil? || prefix.empty?
+
+          return "No entries found with prefix '#{prefix}'"
+        end
+
+        result = []
+        result << "Scratchpad contents (#{entries.size} #{entries.size == 1 ? "entry" : "entries"}):"
+
+        entries.each do |entry|
+          result << "  scratchpad://#{entry[:path]} - \"#{entry[:title]}\" (#{format_bytes(entry[:size])})"
+        end
+
+        result.join("\n")
+      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