swarm_sdk 2.7.13 → 3.0.0.alpha1

data/lib/swarm_sdk/v3/tools/glob.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module V3
+    module Tools
+      # Glob tool for fast file pattern matching
+      #
+      # Finds files and directories matching glob patterns, sorted by modification time.
+      class Glob < Base
+        class << self
+          # @return [Array<Symbol>] Constructor requirements
+          def creation_requirements
+            [:directory]
+          end
+        end
+
+        description <<~DESC
+          Fast file pattern matching tool.
+
+          Supports glob patterns like "**/*.js" or "src/**/*.ts".
+          Returns matching file paths sorted by modification time (most recent first).
+        DESC
+
+        param :pattern,
+          type: "string",
+          desc: "The glob pattern to match files against",
+          required: true
+
+        param :path,
+          type: "string",
+          desc: "Directory to search in. Defaults to working directory.",
+          required: false
+
+        # @param directory [String] Working directory for pattern matching
+        def initialize(directory:)
+          super()
+          @directory = File.expand_path(directory)
+        end
+
+        # Execute glob search
+        #
+        # @param pattern [String] Glob pattern
+        # @param path [String, nil] Search directory
+        # @return [String] Matching paths or error
+        def execute(pattern:, path: nil)
+          return validation_error("pattern is required") if pattern.nil? || pattern.to_s.strip.empty?
+
+          search_path = resolve_search_path(path)
+          return search_path if search_path.start_with?("<tool_use_error>")
+
+          full_pattern = pattern.start_with?("/") ? pattern : File.join(search_path, pattern)
+          matches = Dir.glob(full_pattern, File::FNM_DOTMATCH)
+
+          matches.reject! do |f|
+            basename = File.basename(f.chomp("/"))
+            basename == "." || basename == ".."
+          end
+
+          return "No matches found for pattern: #{pattern}" if matches.empty?
+
+          matches.sort_by! { |f| -File.mtime(f).to_i }
+
+          max_results = Configuration.instance.glob_result_limit
+          truncated = matches.count > max_results
+          matches = matches.take(max_results) if truncated
+
+          output = matches.join("\n")
+          output += "\n\n<system-reminder>Results limited to first #{max_results} matches.</system-reminder>" if truncated
+          output
+        rescue Errno::EACCES => e
+          error("Permission denied: #{e.message}")
+        rescue StandardError => e
+          error("Failed to execute glob: #{e.class.name} - #{e.message}")
+        end
+
+        private
+
+        # Resolve search path with validation
+        #
+        # @param path [String, nil] User-provided path
+        # @return [String] Resolved absolute path or validation error
+        def resolve_search_path(path)
+          if path && !path.to_s.strip.empty?
+            return validation_error("Invalid path value.") if ["undefined", "null"].include?(path.to_s.strip.downcase)
+            return validation_error("Path does not exist: #{path}") unless File.exist?(path)
+            return validation_error("Path is not a directory: #{path}") unless File.directory?(path)
+
+            resolve_path(path)
+          else
+            @directory
+          end
+        end
+      end
+    end
+  end
+end

data/lib/swarm_sdk/v3/tools/grep.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module V3
+    module Tools
+      # Grep tool for searching file contents using ripgrep
+      #
+      # Powerful search with regex support, context lines, and file filtering.
+      class Grep < Base
+        class << self
+          # @return [Array<Symbol>] Constructor requirements
+          def creation_requirements
+            [:directory]
+          end
+        end
+
+        description <<~DESC
+          Search file contents using ripgrep.
+
+          Supports regex patterns, file type filtering, and context lines.
+          Output modes: "content" (matching lines), "files_with_matches" (file paths, default), "count" (match counts).
+        DESC
+
+        param :pattern,
+          type: "string",
+          desc: "Regular expression pattern to search for",
+          required: true
+
+        param :path,
+          type: "string",
+          desc: "File or directory to search in. Defaults to working directory.",
+          required: false
+
+        param :glob,
+          type: "string",
+          desc: 'Glob pattern to filter files (e.g. "*.js", "*.{ts,tsx}")',
+          required: false
+
+        param :type,
+          type: "string",
+          desc: "File type to search (e.g. js, py, ruby, rust)",
+          required: false
+
+        param :output_mode,
+          type: "string",
+          desc: '"content", "files_with_matches" (default), or "count"',
+          required: false
+
+        param :case_insensitive,
+          type: "boolean",
+          desc: "Case insensitive search",
+          required: false
+
+        param :multiline,
+          type: "boolean",
+          desc: "Enable multiline matching",
+          required: false
+
+        param :context_before,
+          type: "integer",
+          desc: "Lines to show before each match (content mode only)",
+          required: false
+
+        param :context_after,
+          type: "integer",
+          desc: "Lines to show after each match (content mode only)",
+          required: false
+
+        param :context,
+          type: "integer",
+          desc: "Lines to show before and after each match (content mode only)",
+          required: false
+
+        param :show_line_numbers,
+          type: "boolean",
+          desc: "Show line numbers (content mode only)",
+          required: false
+
+        param :head_limit,
+          type: "integer",
+          desc: "Limit output to first N lines/entries",
+          required: false
+
+        # @param directory [String] Working directory for searches
+        def initialize(directory:)
+          super()
+          @directory = File.expand_path(directory)
+        end
+
+        # Execute content search
+        #
+        # @return [String] Search results or error
+        def execute(
+          pattern:,
+          path: nil,
+          glob: nil,
+          type: nil,
+          output_mode: "files_with_matches",
+          case_insensitive: false,
+          multiline: false,
+          context_before: nil,
+          context_after: nil,
+          context: nil,
+          show_line_numbers: false,
+          head_limit: nil
+        )
+          return validation_error("pattern is required") if pattern.nil? || pattern.empty?
+
+          search_path = resolve_search_path(path)
+
+          valid_modes = ["content", "files_with_matches", "count"]
+          return validation_error("output_mode must be one of: #{valid_modes.join(", ")}") unless valid_modes.include?(output_mode)
+
+          cmd = build_command(
+            pattern: pattern,
+            path: search_path,
+            glob: glob,
+            type: type,
+            output_mode: output_mode,
+            case_insensitive: case_insensitive,
+            multiline: multiline,
+            context_before: context_before,
+            context_after: context_after,
+            context: context,
+            show_line_numbers: show_line_numbers,
+          )
+
+          run_ripgrep(cmd, pattern, head_limit)
+        rescue StandardError => e
+          error("Unexpected error: #{e.class.name} - #{e.message}")
+        end
+
+        private
+
+        # Resolve the search path
+        #
+        # @param path [String, nil] User-provided path
+        # @return [String] Resolved absolute path
+        def resolve_search_path(path)
+          if path.nil? || path.to_s.strip.empty?
+            @directory
+          else
+            resolve_path(path)
+          end
+        end
+
+        # Build ripgrep command array
+        #
+        # @return [Array<String>] Command parts
+        def build_command(pattern:, path:, glob:, type:, output_mode:, case_insensitive:, multiline:, context_before:, context_after:, context:, show_line_numbers:)
+          cmd = ["rg"]
+
+          case output_mode
+          when "files_with_matches" then cmd << "-l"
+          when "count" then cmd << "-c"
+          when "content"
+            cmd << "-n" if show_line_numbers
+            cmd << "-B" << context_before.to_s if context_before
+            cmd << "-A" << context_after.to_s if context_after
+            cmd << "-C" << context.to_s if context
+          end
+
+          cmd << "-i" if case_insensitive
+          cmd.push("-U", "--multiline-dotall") if multiline
+          cmd.push("--type", type) if type && !type.to_s.strip.empty?
+          cmd.push("--glob", glob) if glob && !glob.to_s.strip.empty?
+          cmd.push("-e", pattern, path)
+
+          cmd
+        end
+
+        # Run ripgrep and format output
+        #
+        # @param cmd [Array<String>] Command parts
+        # @param pattern [String] Search pattern
+        # @param head_limit [Integer, nil] Output limit
+        # @return [String] Formatted results
+        def run_ripgrep(cmd, pattern, head_limit)
+          stdout, stderr, status = Open3.capture3(*cmd)
+
+          return "No matches found for pattern: #{pattern}" if status.exitstatus == 1 && stderr.empty?
+          return error("ripgrep error: #{stderr}") if status.exitstatus == 2 || !stderr.empty?
+
+          output = stdout
+          if head_limit && head_limit > 0
+            lines = output.lines
+            if lines.count > head_limit
+              output = lines.take(head_limit).join
+              output += "\n<system-reminder>Output limited to first #{head_limit} lines.</system-reminder>"
+            end
+          end
+
+          output.empty? ? "No matches found for pattern: #{pattern}" : output
+        rescue Errno::ENOENT
+          error("ripgrep (rg) is not installed or not in PATH.")
+        end
+      end
+    end
+  end
+end

data/lib/swarm_sdk/v3/tools/message_teammate.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module V3
+    module Tools
+      # Placeholder for inter-agent messaging (future hub integration)
+      #
+      # This tool will be implemented when the MessageHub primitive is built.
+      # For now it exists as a namespace placeholder.
+      class MessageTeammate < Base
+        # Not yet implemented — placeholder for hub integration
+      end
+    end
+  end
+end

data/lib/swarm_sdk/v3/tools/message_user.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module V3
+    module Tools
+      # Placeholder for user-facing messaging (future hub integration)
+      #
+      # This tool will be implemented when the MessageHub primitive is built.
+      # For now it exists as a namespace placeholder.
+      class MessageUser < Base
+        # Not yet implemented — placeholder for hub integration
+      end
+    end
+  end
+end

data/lib/swarm_sdk/v3/tools/read.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module V3
+    module Tools
+      # Read tool for reading file contents from the filesystem
+      #
+      # Supports reading entire files or specific line ranges with line numbers.
+      # Tracks reads per agent for enforcing read-before-write/edit rules.
+      class Read < Base
+        class << self
+          # @return [Array<Symbol>] Constructor requirements
+          def creation_requirements
+            [:agent_name, :directory, :read_tracker]
+          end
+        end
+
+        description <<~DESC
+          Reads a file from the local filesystem.
+
+          Supports text files with line numbers. Binary files (images) are returned as visual content.
+
+          Path handling:
+          - Relative paths resolve against your working directory
+          - Absolute paths (starting with /) are used as-is
+        DESC
+
+        param :file_path,
+          type: "string",
+          desc: "Path to the file to read",
+          required: true
+
+        param :offset,
+          type: "integer",
+          desc: "Line number to start reading from (1-indexed). Use for large files.",
+          required: false
+
+        param :limit,
+          type: "integer",
+          desc: "Number of lines to read. Use for large files.",
+          required: false
+
+        # @param agent_name [Symbol, String] Agent identifier for read tracking
+        # @param directory [String] Agent's working directory
+        # @param read_tracker [ReadTracker] Shared read tracker for cross-tool enforcement
+        def initialize(agent_name:, directory:, read_tracker:)
+          super()
+          @agent_name = agent_name.to_sym
+          @directory = File.expand_path(directory)
+          @read_tracker = read_tracker
+        end
+
+        # Check if a file has been read by this agent
+        #
+        # @param path [String] Resolved file path
+        # @return [Boolean]
+        def file_read?(path)
+          @read_tracker.file_read?(@agent_name, path)
+        end
+
+        # Execute file read
+        #
+        # @param file_path [String] Path to the file
+        # @param offset [Integer, nil] Starting line number (1-indexed)
+        # @param limit [Integer, nil] Number of lines to read
+        # @return [String, RubyLLM::Content] File contents or error message
+        def execute(file_path:, offset: nil, limit: nil)
+          return validation_error("file_path is required") if file_path.nil? || file_path.to_s.strip.empty?
+
+          resolved_path = resolve_path(file_path)
+
+          return validation_error("File does not exist: #{file_path}") unless File.exist?(resolved_path)
+          return validation_error("Path is a directory. Use Bash with ls to list directories.") if File.directory?(resolved_path)
+
+          content = read_file_content(resolved_path)
+
+          # Binary file — return as-is
+          return content if content.is_a?(RubyLLM::Content)
+          return content if content.start_with?("Error:")
+
+          @read_tracker.register_read(@agent_name, resolved_path)
+
+          return format_empty_file if content.empty?
+
+          format_text_content(content, file_path, offset, limit)
+        rescue StandardError => e
+          error("Unexpected error reading file: #{e.class.name} - #{e.message}")
+        end
+
+        private
+
+        # @return [String] Config accessor
+        def config
+          Configuration.instance
+        end
+
+        # Read file content, handling encoding
+        #
+        # @param file_path [String] Resolved absolute path
+        # @return [String, RubyLLM::Content] Text content or binary content object
+        def read_file_content(file_path)
+          content = File.read(file_path, encoding: "UTF-8")
+
+          unless content.valid_encoding?
+            return binary_or_unsupported(file_path)
+          end
+
+          content
+        rescue Encoding::InvalidByteSequenceError, Encoding::UndefinedConversionError
+          binary_or_unsupported(file_path)
+        rescue Errno::EACCES
+          error("Permission denied: Cannot read file '#{file_path}'")
+        end
+
+        # Handle binary files
+        #
+        # @param file_path [String] Path to binary file
+        # @return [RubyLLM::Content, String] Content object for images, error for others
+        def binary_or_unsupported(file_path)
+          ext = File.extname(file_path).downcase
+          image_formats = [".png", ".jpg", ".jpeg", ".gif", ".webp", ".bmp", ".tiff", ".tif", ".svg", ".ico"]
+
+          if image_formats.include?(ext)
+            RubyLLM::Content.new("File: #{File.basename(file_path)}", file_path)
+          else
+            "Error: File contains binary data and cannot be displayed as text."
+          end
+        end
+
+        # Format empty file output
+        #
+        # @return [String]
+        def format_empty_file
+          "<system-reminder>Warning: This file exists but has empty contents.</system-reminder>"
+        end
+
+        # Format text content with line numbers
+        #
+        # @param content [String] Raw file content
+        # @param file_path [String] Original file path for display
+        # @param offset [Integer, nil] Starting line (1-indexed)
+        # @param limit [Integer, nil] Lines to read
+        # @return [String] Formatted output with line numbers
+        def format_text_content(content, file_path, offset, limit)
+          lines = content.lines
+          total_lines = lines.count
+
+          start_line = offset ? [offset - 1, 0].max : 0
+          return validation_error("Offset #{offset} exceeds file length (#{total_lines} lines)") if start_line >= total_lines
+
+          lines = lines.drop(start_line)
+
+          default_limit = config.read_line_limit
+          effective_limit = limit || default_limit
+          lines = lines.take(effective_limit)
+          truncated = limit.nil? && total_lines > default_limit
+
+          max_line_length = config.line_character_limit
+          output_lines = lines.each_with_index.map do |line, idx|
+            line_number = start_line + idx + 1
+            display_line = line.chomp
+            display_line = "#{display_line[0...max_line_length]}... (line truncated)" if display_line.length > max_line_length
+            "#{line_number.to_s.rjust(6)}\t#{display_line}"
+          end
+
+          output = output_lines.join("\n")
+          output += truncation_notice(total_lines, default_limit) if truncated
+          output
+        end
+
+        # @param total_lines [Integer] Total lines in file
+        # @param limit [Integer] Applied limit
+        # @return [String] Truncation notice
+        def truncation_notice(total_lines, limit)
+          "\n\n<system-reminder>This file has #{total_lines} lines but only the first #{limit} are shown. " \
+            "Use offset and limit parameters to read more.</system-reminder>"
+        end
+      end
+    end
+  end
+end

data/lib/swarm_sdk/v3/tools/read_tracker.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module V3
+    module Tools
+      # Tracks which files have been read by each agent
+      #
+      # Shared across Read, Write, and Edit tool instances for the same agent.
+      # Enforces read-before-write/edit rules to prevent accidental overwrites.
+      #
+      # @example
+      #   tracker = ReadTracker.new
+      #   tracker.register_read(:backend, "/path/to/file.rb")
+      #   tracker.file_read?(:backend, "/path/to/file.rb")  #=> true
+      class ReadTracker
+        def initialize
+          @reads = Hash.new { |h, k| h[k] = Set.new }
+        end
+
+        # Register that an agent has read a file
+        #
+        # @param agent_name [Symbol] Agent identifier
+        # @param path [String] Absolute file path
+        # @return [void]
+        def register_read(agent_name, path)
+          @reads[agent_name].add(path)
+        end
+
+        # Check if an agent has read a file
+        #
+        # @param agent_name [Symbol] Agent identifier
+        # @param path [String] Absolute file path
+        # @return [Boolean]
+        def file_read?(agent_name, path)
+          @reads[agent_name].include?(path)
+        end
+      end
+    end
+  end
+end