swarm_sdk 2.0.0.pre.2

data/lib/swarm_sdk/tools/document_converters/xlsx_converter.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Tools
+    module DocumentConverters
+      # Converts XLSX/XLS spreadsheets to text with image extraction
+      class XlsxConverter < BaseConverter
+        class << self
+          def gem_name
+            "roo"
+          end
+
+          def format_name
+            "XLSX/XLS"
+          end
+
+          def extensions
+            [".xlsx", ".xls"]
+          end
+
+          # XLS files require an additional gem
+          def xls_gem_available?
+            gem_available?("roo-xls")
+          end
+        end
+
+        # Convert a spreadsheet to text/content
+        # @param file_path [String] Path to the spreadsheet file
+        # @return [String, RubyLLM::Content] Converted content or error message
+        def convert(file_path)
+          unless self.class.available?
+            return unsupported_format_reminder(self.class.format_name, self.class.gem_name)
+          end
+
+          # Check for legacy XLS files
+          extension = File.extname(file_path).downcase
+          if extension == ".xls" && !self.class.xls_gem_available?
+            return error("Legacy .xls files require the 'roo-xls' gem. Install with: gem install roo-xls")
+          end
+
+          spreadsheet = nil
+
+          begin
+            require "roo"
+            require "csv"
+            require "tmpdir"
+
+            spreadsheet = Roo::Spreadsheet.open(file_path)
+
+            # Extract images from all sheets
+            image_paths = extract_images(spreadsheet, file_path)
+
+            output = []
+            output << "Spreadsheet: #{File.basename(file_path)}"
+            output << "Sheets: #{spreadsheet.sheets.size}"
+            output << "=" * 60
+            output << ""
+
+            spreadsheet.sheets.each_with_index do |sheet_name, sheet_idx|
+              sheet = spreadsheet.sheet(sheet_name)
+
+              output << "Sheet #{sheet_idx + 1}: #{sheet_name}"
+              output << "-" * 60
+
+              # Add sheet dimensions
+              first_row = sheet.first_row
+              last_row = sheet.last_row
+              first_col = sheet.first_column
+              last_col = sheet.last_column
+
+              if first_row && last_row && first_col && last_col
+                row_count = last_row - first_row + 1
+                col_count = last_col - first_col + 1
+                output << "Dimensions: #{row_count} rows × #{col_count} columns"
+                output << ""
+              else
+                output << "(Empty sheet)"
+                output << ""
+                next
+              end
+
+              # Extract data rows
+              sheet.each_row_streaming(pad_cells: true) do |row|
+                row_values = row.map do |cell|
+                  format_cell_value(cell)
+                end
+
+                # Skip completely empty rows
+                next if row_values.all? { |v| v.nil? || v.empty? }
+
+                # Format as CSV with proper escaping
+                output << CSV.generate_line(row_values).chomp
+              end
+
+              output << ""
+            end
+
+            text_content = output.join("\n")
+
+            # If there are images, return Content with attachments
+            if image_paths.any?
+              content = RubyLLM::Content.new(text_content)
+              image_paths.each do |image_path|
+                content.add_attachment(image_path)
+              end
+              content
+            else
+              # No images, return just text
+              text_content
+            end
+          rescue ArgumentError => e
+            error("Failed to open spreadsheet: #{e.message}")
+          rescue RangeError => e
+            error("Sheet access error: #{e.message}")
+          rescue Zip::Error => e
+            error("Corrupted or invalid XLSX file: #{e.message}")
+          rescue IOError => e
+            error("File reading error: #{e.message}")
+          rescue StandardError => e
+            error("Failed to parse spreadsheet: #{e.message}")
+          ensure
+            # Always clean up resources
+            spreadsheet.close if spreadsheet&.respond_to?(:close)
+          end
+        end
+
+        private
+
+        # Format cell value based on type
+        # @param cell [Roo::Cell] The cell to format
+        # @return [String] Formatted cell value
+        def format_cell_value(cell)
+          return "" if cell.nil? || cell.empty?
+
+          case cell.type
+          when :string
+            cell.value.to_s
+          when :float, :number
+            cell.value.to_s
+          when :date
+            cell.value.strftime("%Y-%m-%d")
+          when :datetime
+            cell.value.strftime("%Y-%m-%d %H:%M:%S")
+          when :time
+            hours = (cell.value / 3600).to_i
+            minutes = ((cell.value % 3600) / 60).to_i
+            seconds = (cell.value % 60).to_i
+            format("%02d:%02d:%02d", hours, minutes, seconds)
+          when :boolean
+            cell.value ? "TRUE" : "FALSE"
+          when :formula
+            # Returns calculated value, not the formula itself
+            cell.value.to_s
+          when :link
+            cell.value.to_s
+          when :percentage
+            (cell.value * 100).to_s + "%"
+          else
+            cell.value.to_s
+          end
+        rescue StandardError
+          "[ERROR]"
+        end
+
+        # Extract images from spreadsheet
+        # @param spreadsheet [Roo::Spreadsheet] The spreadsheet
+        # @param _xlsx_path [String] Path to the XLSX file (unused but kept for consistency)
+        # @return [Array<String>] Array of temporary file paths containing extracted images
+        def extract_images(spreadsheet, _xlsx_path)
+          image_paths = []
+
+          spreadsheet.sheets.each do |sheet_name|
+            # Check if the spreadsheet supports image extraction
+            next unless spreadsheet.respond_to?(:images)
+
+            images = spreadsheet.images(sheet_name)
+            next unless images && !images.empty?
+
+            images.each do |img_path|
+              if img_path && File.exist?(img_path)
+                image_paths << img_path
+              end
+            end
+          end
+
+          image_paths
+        rescue StandardError
+          # If image extraction fails, don't fail the entire spreadsheet read
+          []
+        end
+      end
+    end
+  end
+end

data/lib/swarm_sdk/tools/edit.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Tools
+    # Edit tool for performing exact string replacements in files
+    #
+    # Uses exact string matching to find and replace content.
+    # Requires unique matches and proper Read tool usage beforehand.
+    # Enforces read-before-edit rule.
+    class Edit < RubyLLM::Tool
+      include PathResolver
+
+      description <<~DESC
+        Performs exact string replacements in files.
+        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.
+        The 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 :old_string,
+        type: "string",
+        desc: "The exact text to replace (must match exactly including whitespace)",
+        required: true
+
+      param :new_string,
+        type: "string",
+        desc: "The text to replace it with (must be different from old_string)",
+        required: true
+
+      param :replace_all,
+        type: "boolean",
+        desc: "Replace all occurrences of old_string (default false)",
+        required: false
+
+      # Initialize the Edit 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 "Edit" instead of full class path
+      def name
+        "Edit"
+      end
+
+      def execute(file_path:, old_string:, new_string:, replace_all: false)
+        # Validate inputs
+        return validation_error("file_path is required") if file_path.nil? || file_path.to_s.strip.empty?
+        return validation_error("old_string is required") if old_string.nil? || old_string.empty?
+        return validation_error("new_string is required") if new_string.nil?
+
+        # old_string and new_string must be different
+        if old_string == new_string
+          return validation_error("old_string and new_string must be different. They are currently identical.")
+        end
+
+        # CRITICAL: Resolve path against agent directory
+        resolved_path = resolve_path(file_path)
+
+        # 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")
+
+        # Check if old_string exists in file
+        unless content.include?(old_string)
+          return validation_error(<<~ERROR.chomp)
+            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.
+          ERROR
+        end
+
+        # Count occurrences
+        occurrences = content.scan(old_string).count
+
+        # If not replace_all and multiple occurrences, error
+        if !replace_all && occurrences > 1
+          return validation_error(<<~ERROR.chomp)
+            Found #{occurrences} occurrences of old_string.
+            Either provide more surrounding context to make the match unique, or use replace_all: true to replace all occurrences.
+          ERROR
+        end
+
+        # Perform replacement
+        new_content = if replace_all
+          content.gsub(old_string, new_string)
+        else
+          content.sub(old_string, new_string)
+        end
+
+        # Write back to file (use resolved path)
+        File.write(resolved_path, new_content, encoding: "UTF-8")
+
+        # Build success message
+        replaced_count = replace_all ? occurrences : 1
+        "Successfully replaced #{replaced_count} occurrence(s) in #{file_path}"
+      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
+    end
+  end
+end

data/lib/swarm_sdk/tools/glob.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Tools
+    # Glob tool for fast file and directory pattern matching
+    #
+    # Finds files and directories matching glob patterns, sorted by modification time.
+    # Works efficiently with any codebase size.
+    class Glob < RubyLLM::Tool
+      include PathResolver
+
+      def initialize(directory:)
+        super()
+        @directory = File.expand_path(directory)
+      end
+
+      define_method(:name) { "Glob" }
+
+      description <<~DESC
+        - Fast file pattern matching tool that works with any directory size
+
+        - Supports glob patterns like "**/*.js" or "src/**/*.ts"
+
+        - Returns matching file paths sorted by modification time
+
+        - Use this tool when you need to find files by name patterns
+
+        - When you are doing an open ended search that may require multiple rounds of
+        globbing and grepping, use the Agent tool instead
+
+        - You have the capability to call multiple tools in a single response. It is
+        always better to speculatively perform multiple searches as a batch that are
+        potentially useful.
+      DESC
+
+      param :pattern,
+        type: "string",
+        desc: "The glob pattern to match files against",
+        required: true
+
+      param :path,
+        type: "string",
+        desc: "The directory to search in. If not specified, the current working directory will be used. IMPORTANT: Omit this field to use the default directory. DO NOT enter \"undefined\" or \"null\" - simply omit it for the default behavior. Must be a valid directory path if provided.",
+        required: false
+
+      MAX_RESULTS = 1000 # Limit results to prevent overwhelming output
+
+      def execute(pattern:, path: nil)
+        # Validate inputs
+        return validation_error("pattern is required") if pattern.nil? || pattern.to_s.strip.empty?
+
+        # Validate path if provided
+        if path && !path.to_s.strip.empty?
+          # Check for literal "undefined" or "null" strings
+          if path.to_s.strip.downcase == "undefined" || path.to_s.strip.downcase == "null"
+            return validation_error("Invalid path value. Omit the path parameter entirely to use the current working directory.")
+          end
+
+          unless File.exist?(path)
+            return validation_error("Path does not exist: #{path}")
+          end
+
+          unless File.directory?(path)
+            return validation_error("Path is not a directory: #{path}")
+          end
+
+          # CRITICAL: Resolve relative paths against agent directory
+          search_path = resolve_path(path)
+        else
+          # CRITICAL: Use agent's directory as default (NOT Dir.pwd)
+          search_path = @directory
+        end
+
+        # Execute glob from specified path
+        begin
+          # Build full pattern by joining search path with pattern
+          # If pattern is already absolute, File.join will use it as-is
+          full_pattern = if pattern.start_with?("/")
+            # Pattern is absolute, use it directly
+            pattern
+          else
+            # Pattern is relative, join with search path
+            File.join(search_path, pattern)
+          end
+
+          matches = Dir.glob(full_pattern, File::FNM_DOTMATCH)
+
+          # Remove . and .. entries (handle both with and without trailing slashes)
+          matches.reject! do |f|
+            basename = File.basename(f.chomp("/"))
+            basename == "." || basename == ".."
+          end
+
+          # Handle no matches
+          if matches.empty?
+            return "No matches found for pattern: #{pattern}"
+          end
+
+          # Sort by modification time (most recent first)
+          matches.sort_by! { |f| -File.mtime(f).to_i }
+
+          # Limit results
+          if matches.count > MAX_RESULTS
+            matches = matches.take(MAX_RESULTS)
+            truncated = true
+          else
+            truncated = false
+          end
+
+          # Format output
+          output = matches.join("\n")
+
+          # Add system reminder if truncated
+          if truncated
+            output += <<~REMINDER
+
+              <system-reminder>
+              Results limited to first #{MAX_RESULTS} matches (sorted by most recently modified).
+              Consider using a more specific pattern to narrow your search.
+              </system-reminder>
+            REMINDER
+          end
+
+          # Add usage reminder
+          output += "\n\n" + build_usage_reminder(matches.count, pattern)
+
+          output
+        rescue Errno::EACCES => e
+          error("Permission denied: #{e.message}")
+        rescue StandardError => e
+          error("Failed to execute glob: #{e.class.name} - #{e.message}")
+        end
+      rescue StandardError => e
+        error("Unexpected error during glob: #{e.class.name} - #{e.message}")
+      end
+
+      private
+
+      def validation_error(message)
+        "<tool_use_error>InputValidationError: #{message}</tool_use_error>"
+      end
+
+      def error(message)
+        "Error: #{message}"
+      end
+
+      def build_usage_reminder(count, pattern)
+        <<~REMINDER
+          <system-reminder>
+          Found #{count} match#{"es" if count != 1} for '#{pattern}' (files and directories).
+          These paths are sorted by modification time (most recent first).
+          You can now use the Read tool to examine specific files, or use Grep to search within these files.
+          </system-reminder>
+        REMINDER
+      end
+    end
+  end
+end