swarm_sdk 2.7.14 → 3.0.0.alpha2

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,213 @@
+# 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.
+      # Supports document formats (PDF, DOCX, XLSX) if gems installed.
+      class Read < Base
+        # Document converters (optional gems)
+        CONVERTERS = [
+          DocumentConverters::PdfConverter,
+          DocumentConverters::DocxConverter,
+          DocumentConverters::XlsxConverter,
+        ].freeze
+
+        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.
+          Supports document formats (PDF, DOCX, XLSX) if gems installed.
+
+          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 text files. Ignored for documents.",
+          required: false
+
+        param :limit,
+          type: "integer",
+          desc: "Number of lines to read. Use for large text files. Ignored for documents.",
+          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)
+
+          # Try document converter first
+          converter_class = find_converter(resolved_path)
+          if converter_class
+            result = converter_class.new.convert(resolved_path)
+
+            # Register read for successful conversions
+            unless result.start_with?("<system-reminder>") || result.start_with?("Error:")
+              @read_tracker.register_read(@agent_name, resolved_path)
+            end
+
+            return result
+          end
+
+          # Standard text file handling
+          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
+
+        # Find appropriate document converter for file extension
+        #
+        # @param file_path [String] Resolved file path
+        # @return [Class, nil] Converter class or nil if no match
+        def find_converter(file_path)
+          ext = File.extname(file_path).downcase
+          CONVERTERS.find { |c| c.extensions.include?(ext) }
+        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

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

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module V3
+    module Tools
+      # Registry for V3 tools (built-in and custom)
+      #
+      # Maps tool names (symbols) to their V3 tool classes.
+      # Provides lookup, validation, factory, and custom tool registration.
+      #
+      # Tools fall into categories based on creation requirements:
+      # 1. **No params**: Simple tools (Think, Clock)
+      # 2. **Directory only**: Tools needing working directory (Bash, Grep, Glob)
+      # 3. **Agent context**: Tools needing agent name + directory (Read, Write, Edit)
+      #
+      # @example Look up a tool
+      #   klass = Registry.get(:Read)
+      #
+      # @example Create a tool instance
+      #   tool = Registry.create(:Read, agent_name: :backend, directory: "/app")
+      #
+      # @example Register a custom tool
+      #   Registry.register(:MyTool, MyCustomTool)
+      #
+      # @example List available tools
+      #   Registry.available_names  #=> [:Read, :Write, :Edit, ...]
+      class Registry
+        class << self
+          # Lazily-built tool mapping
+          #
+          # Uses lazy evaluation so tool classes are only resolved when first accessed,
+          # allowing Zeitwerk to load them on demand. Mutable to support custom registration.
+          #
+          # @return [Hash<Symbol, Class>] Tool name to class mapping
+          def builtin_tools
+            @builtin_tools ||= {
+              Read: SwarmSDK::V3::Tools::Read,
+              Write: SwarmSDK::V3::Tools::Write,
+              Edit: SwarmSDK::V3::Tools::Edit,
+              Bash: SwarmSDK::V3::Tools::Bash,
+              Grep: SwarmSDK::V3::Tools::Grep,
+              Glob: SwarmSDK::V3::Tools::Glob,
+              Think: SwarmSDK::V3::Tools::Think,
+              Clock: SwarmSDK::V3::Tools::Clock,
+              SubTask: SwarmSDK::V3::Tools::SubTask,
+            }
+          end
+
+          # Register a custom tool
+          #
+          # @param name [Symbol, String] Tool name
+          # @param klass [Class] Tool class (must inherit from Base or RubyLLM::Tool)
+          # @return [void]
+          # @raise [ConfigurationError] If name is already taken by a built-in tool
+          #
+          # @example
+          #   Registry.register(:WebSearch, MyWebSearchTool)
+          def register(name, klass)
+            name_sym = name.to_sym
+            builtin_tools[name_sym] = klass
+          end
+
+          # Reset registry to built-in tools only
+          #
+          # Removes all custom tool registrations. Useful for test cleanup.
+          #
+          # @return [void]
+          def reset!
+            @builtin_tools = nil
+          end
+
+          # Get tool class by name
+          #
+          # Respects the `registered_tools` configuration filter. If `registered_tools`
+          # is set, only those tools are visible.
+          #
+          # @param name [Symbol, String] Tool name
+          # @return [Class, nil] Tool class or nil if not found/filtered
+          #
+          # @example
+          #   Registry.get(:Read)  #=> SwarmSDK::V3::Tools::Read
+          def get(name)
+            name_sym = name.to_sym
+            allowed = Configuration.instance.registered_tools
+            return if allowed && !allowed.map(&:to_sym).include?(name_sym)
+
+            builtin_tools[name_sym]
+          end
+
+          # Create a tool instance with context
+          #
+          # Uses the tool's `creation_requirements` to determine constructor params.
+          #
+          # @param name [Symbol, String] Tool name
+          # @param context [Hash] Available context for tool creation
+          # @option context [Symbol] :agent_name Agent identifier
+          # @option context [String] :directory Agent's working directory
+          # @return [RubyLLM::Tool] Instantiated tool
+          # @raise [ConfigurationError] If tool unknown or requirements unmet
+          #
+          # @example
+          #   tool = Registry.create(:Read, agent_name: :backend, directory: "/app")
+          def create(name, **context)
+            name_sym = name.to_sym
+            tool_class = get(name_sym)
+
+            raise ConfigurationError, "Unknown tool: #{name}" unless tool_class
+
+            if tool_class.respond_to?(:creation_requirements) && tool_class.creation_requirements.any?
+              requirements = tool_class.creation_requirements
+              params = extract_params(requirements, context, name)
+              tool_class.new(**params)
+            else
+              tool_class.new
+            end
+          end
+
+          # Create all tools for an agent definition
+          #
+          # Merges the agent's tools with global `default_tools` from configuration.
+          # Filters against `registered_tools` if configured.
+          #
+          # @param definition [AgentDefinition] Agent definition with tool list
+          # @return [Array<RubyLLM::Tool>] Instantiated tools
+          # @raise [ConfigurationError] If any tool is unknown
+          #
+          # @example
+          #   tools = Registry.create_all(definition)
+          def create_all(definition, memory_store: nil, subtask_depth: 0)
+            # Create shared read tracker for cross-tool enforcement
+            read_tracker = ReadTracker.new
+
+            context = {
+              agent_name: definition.name,
+              directory: definition.directory,
+              read_tracker: read_tracker,
+              memory_store: memory_store,
+              agent_definition: definition,
+              subtask_depth: subtask_depth,
+            }
+
+            config = Configuration.instance
+
+            # Start with the agent's declared tools + global default_tools
+            tool_names = definition.tools.dup
+            config.default_tools.each do |name|
+              tool_names << name.to_sym unless tool_names.include?(name.to_sym)
+            end
+
+            # Filter against registered_tools if configured
+            if config.registered_tools
+              allowed = config.registered_tools.map(&:to_sym)
+              tool_names.select! { |name| allowed.include?(name) }
+            end
+
+            tool_names.uniq.map { |name| create(name, **context) }
+          end
+
+          # Check if a tool exists (respects registered_tools filter)
+          #
+          # @param name [Symbol, String] Tool name
+          # @return [Boolean]
+          def exists?(name)
+            !get(name.to_sym).nil?
+          end
+
+          # Get all available tool names (respects registered_tools filter)
+          #
+          # @return [Array<Symbol>]
+          def available_names
+            allowed = Configuration.instance.registered_tools
+            names = builtin_tools.keys
+            names.select! { |n| allowed.map(&:to_sym).include?(n) } if allowed
+            names
+          end
+
+          # Validate tool names
+          #
+          # @param names [Array<Symbol, String>] Tool names to validate
+          # @return [Array<Symbol>] Invalid tool names
+          def validate(names)
+            names.map(&:to_sym).reject { |name| exists?(name) }
+          end
+
+          private
+
+          # Extract parameters from context for tool construction
+          #
+          # Includes each declared requirement that exists in the context.
+          # Missing keys are skipped — the tool constructor's own defaults
+          # and Ruby's `missing keyword` error handle validation naturally.
+          #
+          # @param requirements [Array<Symbol>] Parameter names the tool accepts
+          # @param context [Hash] Available context
+          # @param _tool_name [Symbol] Tool name (unused, kept for interface stability)
+          # @return [Hash] Parameters for constructor
+          def extract_params(requirements, context, _tool_name)
+            params = {}
+            requirements.each do |req|
+              params[req] = context[req] if context.key?(req)
+            end
+            params
+          end
+        end
+      end
+    end
+  end
+end