swarm_memory 2.1.5 → 2.1.6

data/lib/swarm_sdk/tools/multi_edit.rb

@@ -1,236 +0,0 @@
-# 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
-
-      # Factory pattern: declare what parameters this tool needs for instantiation
-      class << self
-        def creation_requirements
-          [:agent_name, :directory]
-        end
-      end
-
-      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()
-        initialize_agent_context(agent_name: agent_name, directory: 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
-
-      # Format an error that includes partial results
-      #
-      # Shows what edits succeeded before the error occurred.
-      #
-      # @param message [String] Error description
-      # @param results [Array<Hash>] Successful edit results before failure
-      # @return [String] Formatted error message with results summary
-      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

@@ -1,92 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  module Tools
-    # Shared path resolution and agent context logic for file tools
-    #
-    # This module provides:
-    # - Path resolution (relative to agent's working directory)
-    # - Agent context initialization (agent_name, directory expansion)
-    # - Standard error message formatting
-    #
-    # 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:)
-    #       super()
-    #       initialize_agent_context(agent_name: agent_name, directory: directory)
-    #     end
-    #
-    #     def execute(file_path:)
-    #       resolved_path = resolve_path(file_path)
-    #       File.read(resolved_path)
-    #     rescue StandardError => e
-    #       error("Failed to read: #{e.message}")
-    #     end
-    #   end
-    module PathResolver
-      # Agent context attributes
-      # @return [Symbol] The agent identifier
-      attr_reader :agent_name
-
-      # @return [String] Absolute path to agent's working directory
-      attr_reader :directory
-
-      private
-
-      # Initialize agent context for file tools
-      #
-      # Sets up the common agent context needed by file tools:
-      # - Normalizes agent_name to symbol
-      # - Expands directory to absolute path
-      #
-      # @param agent_name [Symbol, String] The agent identifier
-      # @param directory [String] Agent's working directory (will be expanded)
-      # @return [void]
-      def initialize_agent_context(agent_name:, directory:)
-        @agent_name = agent_name.to_sym
-        @directory = File.expand_path(directory)
-      end
-
-      # 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
-
-      # Format a validation error response
-      #
-      # Used for input validation failures (missing required params, invalid formats, etc.)
-      #
-      # @param message [String] Error description
-      # @return [String] Formatted error message wrapped in tool_use_error tags
-      def validation_error(message)
-        "<tool_use_error>InputValidationError: #{message}</tool_use_error>"
-      end
-
-      # Format a general error response
-      #
-      # Used for runtime errors (permission denied, file not found, etc.)
-      #
-      # @param message [String] Error description
-      # @return [String] Formatted error message prefixed with "Error:"
-      def error(message)
-        "Error: #{message}"
-      end
-    end
-  end
-end

data/lib/swarm_sdk/tools/read.rb

@@ -1,261 +0,0 @@
-# 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
-
-      # Backward compatibility aliases - use Defaults module for new code
-      MAX_LINE_LENGTH = Defaults::Limits::LINE_CHARACTERS
-      DEFAULT_LIMIT = Defaults::Limits::READ_LINES
-
-      # 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
-
-      # Factory pattern: declare what parameters this tool needs for instantiation
-      class << self
-        def creation_requirements
-          [:agent_name, :directory]
-        end
-      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()
-        initialize_agent_context(agent_name: agent_name, directory: 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
-
-        # 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)
-          # For document files, register the converted text content
-          # Extract text from result (may be wrapped in system-reminder tags)
-          if result.is_a?(String)
-            # Remove system-reminder wrapper if present to get clean text for digest
-            text_content = result.gsub(%r{<system-reminder>.*?</system-reminder>}m, "").strip
-            Stores::ReadTracker.register_read(@agent_name, resolved_path, text_content)
-          end
-          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), track with binary digest and return
-        if content.is_a?(RubyLLM::Content)
-          # For binary files, read raw bytes for digest
-          binary_content = File.binread(resolved_path)
-          Stores::ReadTracker.register_read(@agent_name, resolved_path, binary_content)
-          return content
-        end
-
-        # 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>"))
-
-        # At this point, we have valid text content - register the read with digest
-        Stores::ReadTracker.register_read(@agent_name, resolved_path, content)
-
-        # 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
-
-      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