swarm_sdk 2.7.14 → 3.0.0.alpha1

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 < Base
-      include PathResolver
-
-      # NOTE: Line length and limit now accessed via SwarmSDK.config
-
-      # 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
-        default_limit = SwarmSDK.config.read_line_limit
-        effective_limit = limit || default_limit
-        lines = lines.take(effective_limit)
-        truncated = limit.nil? && total_lines > default_limit
-
-        # Format with line numbers (cat -n style)
-        max_line_length = SwarmSDK.config.line_character_limit
-        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 #{SwarmSDK.config.read_line_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

@@ -1,205 +0,0 @@
-# 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, lookup, and factory functionality for tool registration.
-    #
-    # ## Tool Creation Pattern
-    #
-    # Tools register themselves with their creation requirements via the `tool_factory` method.
-    # This eliminates the need for a giant case statement in ToolConfigurator.
-    #
-    # Tools fall into three categories:
-    # 1. **No params**: Simple tools with no initialization requirements (Think, Clock)
-    # 2. **Directory only**: Tools needing working directory (Bash, Grep, Glob)
-    # 3. **Agent context**: Tools needing agent tracking (Read, Write, Edit, MultiEdit)
-    # 4. **Scratchpad**: Tools needing scratchpad storage instance
-    #
-    # @example Adding a new tool with creation requirements
-    #   # In the tool class:
-    #   class MyTool < RubyLLM::Tool
-    #     def self.creation_requirements
-    #       [:agent_name, :directory]
-    #     end
-    #   end
-    #
-    #   # In registry:
-    #   BUILTIN_TOOLS = {
-    #     MyTool: SwarmSDK::Tools::MyTool,
-    #   }
-    #
-    # Note: Plugin-provided tools (e.g., memory tools) are NOT in this registry.
-    # They are registered via SwarmSDK::PluginRegistry instead.
-    class Registry
-      # All available built-in tools
-      #
-      # Maps tool names to their classes. The class must respond to `creation_requirements`
-      # to specify what parameters are needed for instantiation.
-      BUILTIN_TOOLS = {
-        Read: SwarmSDK::Tools::Read,
-        Write: SwarmSDK::Tools::Write,
-        Edit: SwarmSDK::Tools::Edit,
-        MultiEdit: SwarmSDK::Tools::MultiEdit,
-        Bash: SwarmSDK::Tools::Bash,
-        Grep: SwarmSDK::Tools::Grep,
-        Glob: SwarmSDK::Tools::Glob,
-        TodoWrite: SwarmSDK::Tools::TodoWrite,
-        ScratchpadWrite: :scratchpad, # Requires scratchpad storage instance
-        ScratchpadRead: :scratchpad,  # Requires scratchpad storage instance
-        ScratchpadList: :scratchpad,  # Requires scratchpad storage instance
-        Think: SwarmSDK::Tools::Think,
-        WebFetch: SwarmSDK::Tools::WebFetch,
-        Clock: SwarmSDK::Tools::Clock,
-      }.freeze
-
-      class << self
-        # Get tool class by name
-        #
-        # Note: Plugin-provided tools are NOT returned by this method.
-        # They are managed by SwarmSDK::PluginRegistry instead.
-        #
-        # @param name [Symbol, String] Tool name
-        # @return [Class, Symbol, nil] Tool class, :scratchpad marker, or nil if not found
-        def get(name)
-          name_sym = name.to_sym
-          BUILTIN_TOOLS[name_sym]
-        end
-
-        # Create a tool instance using the Factory Pattern
-        #
-        # Uses the tool's `creation_requirements` class method to determine
-        # what parameters to pass to the constructor.
-        #
-        # @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
-        # @option context [Object] :scratchpad_storage Scratchpad storage instance
-        # @return [RubyLLM::Tool] Instantiated tool
-        # @raise [ConfigurationError] If tool is unknown or has unmet requirements
-        def create(name, context = {})
-          name_sym = name.to_sym
-          tool_entry = BUILTIN_TOOLS[name_sym]
-
-          raise ConfigurationError, "Unknown tool: #{name}" unless tool_entry
-
-          # Handle scratchpad tools specially (they use factory methods)
-          if tool_entry == :scratchpad
-            return create_scratchpad_tool(name_sym, context[:scratchpad_storage])
-          end
-
-          # Get the tool class and its requirements
-          tool_class = tool_entry
-
-          # Check if tool defines creation requirements
-          if tool_class.respond_to?(:creation_requirements)
-            requirements = tool_class.creation_requirements
-            params = extract_params(requirements, context, name)
-            tool_class.new(**params)
-          else
-            # No requirements - simple instantiation
-            tool_class.new
-          end
-        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)
-            unless tool_class
-              raise ConfigurationError,
-                "Unknown tool: #{name}. Available tools: #{available_names.join(", ")}"
-            end
-
-            tool_class
-          end
-        end
-
-        # Check if a tool exists
-        #
-        # Note: Only checks built-in tools. Plugin-provided tools are checked
-        # via SwarmSDK::PluginRegistry.plugin_tool?() instead.
-        #
-        # @param name [Symbol, String] Tool name
-        # @return [Boolean]
-        def exists?(name)
-          name_sym = name.to_sym
-          BUILTIN_TOOLS.key?(name_sym)
-        end
-
-        # Get all available built-in tool names
-        #
-        # Note: Does NOT include plugin-provided tools. To get all available tools
-        # including plugins, combine with SwarmSDK::PluginRegistry.tools.
-        #
-        # @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
-
-        private
-
-        # Extract required parameters from context
-        #
-        # @param requirements [Array<Symbol>] Required parameter names
-        # @param context [Hash] Available context
-        # @param tool_name [Symbol] Tool name for error messages
-        # @return [Hash] Parameters to pass to tool constructor
-        # @raise [ConfigurationError] If required parameter is missing
-        def extract_params(requirements, context, tool_name)
-          params = {}
-
-          requirements.each do |req|
-            unless context.key?(req)
-              raise ConfigurationError,
-                "Tool #{tool_name} requires #{req} but it was not provided in context"
-            end
-
-            params[req] = context[req]
-          end
-
-          params
-        end
-
-        # Create a scratchpad tool using its factory method
-        #
-        # @param name [Symbol] Scratchpad tool name
-        # @param storage [Object] Scratchpad storage instance
-        # @return [RubyLLM::Tool] Instantiated scratchpad tool
-        # @raise [ConfigurationError] If storage is not provided
-        def create_scratchpad_tool(name, storage)
-          unless storage
-            raise ConfigurationError,
-              "Scratchpad tool #{name} requires scratchpad_storage in context"
-          end
-
-          case name
-          when :ScratchpadWrite
-            Tools::Scratchpad::ScratchpadWrite.create_for_scratchpad(storage)
-          when :ScratchpadRead
-            Tools::Scratchpad::ScratchpadRead.create_for_scratchpad(storage)
-          when :ScratchpadList
-            Tools::Scratchpad::ScratchpadList.create_for_scratchpad(storage)
-          else
-            raise ConfigurationError, "Unknown scratchpad tool: #{name}"
-          end
-        end
-      end
-    end
-  end
-end

data/lib/swarm_sdk/tools/scratchpad/scratchpad_list.rb

@@ -1,117 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  module Tools
-    module Scratchpad
-      # Tool for listing scratchpad entries
-      #
-      # Shows all entries in the shared scratchpad with their metadata.
-      # All agents in the swarm share the same scratchpad.
-      class ScratchpadList < Base
-        define_method(:name) { "ScratchpadList" }
-
-        description <<~DESC
-          List all entries in scratchpad with their metadata.
-
-          ## When to Use ScratchpadList
-
-          Use ScratchpadList to:
-          - Discover what content is available in the scratchpad
-          - Check what other agents have stored
-          - Find relevant entries before reading them
-          - Review all stored outputs and analysis
-          - Check entry sizes and last update times
-
-          ## Best Practices
-
-          - Use this before ScratchpadRead if you don't know what's stored
-          - Filter by prefix to narrow down results (e.g., 'notes/' lists all notes)
-          - Shows path, title, size, and last updated time for each entry
-          - Any agent can see all scratchpad entries
-          - Helps coordinate multi-agent workflows
-
-          ## Examples
-
-          - List all entries: (no prefix parameter)
-          - List notes only: prefix='notes/'
-          - List analysis results: prefix='analysis/'
-        DESC
-
-        param :prefix,
-          desc: "Optional prefix to filter entries (e.g., 'notes/' to list all entries under notes/)",
-          required: false
-
-        class << self
-          # Create a ScratchpadList tool for a specific scratchpad storage instance
-          #
-          # @param scratchpad_storage [Stores::ScratchpadStorage] Shared scratchpad storage instance
-          # @return [ScratchpadList] Tool instance
-          def create_for_scratchpad(scratchpad_storage)
-            new(scratchpad_storage)
-          end
-        end
-
-        # Initialize with scratchpad storage instance
-        #
-        # @param scratchpad_storage [Stores::ScratchpadStorage] Shared scratchpad storage instance
-        def initialize(scratchpad_storage)
-          super() # Call RubyLLM::Tool's initialize
-          @scratchpad_storage = scratchpad_storage
-        end
-
-        # Execute the tool
-        #
-        # @param prefix [String, nil] Optional prefix to filter entries
-        # @return [String] Formatted list of entries
-        def execute(prefix: nil)
-          entries = scratchpad_storage.list(prefix: prefix)
-
-          if entries.empty?
-            prefix_msg = prefix ? " with prefix '#{prefix}'" : ""
-            return "No entries found in scratchpad#{prefix_msg}"
-          end
-
-          result = []
-          prefix_msg = prefix ? " with prefix '#{prefix}'" : ""
-          result << "Scratchpad entries#{prefix_msg} (#{entries.size} #{entries.size == 1 ? "entry" : "entries"}):"
-          result << ""
-
-          entries.each do |entry|
-            time_str = entry[:updated_at].strftime("%Y-%m-%d %H:%M:%S")
-            result << "  scratchpad://#{entry[:path]}"
-            result << "    Title: #{entry[:title]}"
-            result << "    Size: #{format_bytes(entry[:size])}"
-            result << "    Updated: #{time_str}"
-            result << ""
-          end
-
-          result.join("\n").rstrip
-        rescue ArgumentError => e
-          validation_error(e.message)
-        end
-
-        private
-
-        attr_reader :scratchpad_storage
-
-        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
-end

data/lib/swarm_sdk/tools/scratchpad/scratchpad_read.rb

@@ -1,97 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  module Tools
-    module Scratchpad
-      # Tool for reading content from scratchpad storage
-      #
-      # Retrieves content stored by any agent using scratchpad_write.
-      # All agents in the swarm share the same scratchpad.
-      class ScratchpadRead < Base
-        define_method(:name) { "ScratchpadRead" }
-
-        description <<~DESC
-          Read content from scratchpad.
-
-          ## When to Use ScratchpadRead
-
-          Use ScratchpadRead to:
-          - Retrieve previously stored content and outputs
-          - Access detailed analysis or results from earlier steps
-          - Read messages or notes left by other agents
-          - Access cached computed data
-          - Retrieve content that was too long for direct responses
-
-          ## Best Practices
-
-          - Any agent can read any scratchpad content
-          - Content is returned with line numbers for easy reference
-          - Use ScratchpadList first if you don't know what's stored
-          - Scratchpad data is temporary and lost when swarm ends
-          - For persistent data, use MemoryRead instead
-
-          ## Examples
-
-          - Read status: file_path='status'
-          - Read analysis: file_path='api_analysis'
-          - Read agent notes: file_path='notes/backend'
-        DESC
-
-        param :file_path,
-          desc: "Path to read from scratchpad (e.g., 'status', 'result', 'notes/agent_x')",
-          required: true
-
-        class << self
-          # Create a ScratchpadRead tool for a specific scratchpad storage instance
-          #
-          # @param scratchpad_storage [Stores::ScratchpadStorage] Shared scratchpad storage instance
-          # @return [ScratchpadRead] Tool instance
-          def create_for_scratchpad(scratchpad_storage)
-            new(scratchpad_storage)
-          end
-        end
-
-        # Initialize with scratchpad storage instance
-        #
-        # @param scratchpad_storage [Stores::ScratchpadStorage] Shared scratchpad storage instance
-        def initialize(scratchpad_storage)
-          super() # Call RubyLLM::Tool's initialize
-          @scratchpad_storage = scratchpad_storage
-        end
-
-        # Execute the tool
-        #
-        # @param file_path [String] Path to read from
-        # @return [String] Content at the path with line numbers, or error message
-        def execute(file_path:)
-          content = scratchpad_storage.read(file_path: file_path)
-          format_with_line_numbers(content)
-        rescue ArgumentError => e
-          validation_error(e.message)
-        end
-
-        private
-
-        attr_reader :scratchpad_storage
-
-        def validation_error(message)
-          "<tool_use_error>InputValidationError: #{message}</tool_use_error>"
-        end
-
-        # Format content with line numbers (same format as Read tool)
-        #
-        # @param content [String] Content to format
-        # @return [String] Content with line numbers
-        def format_with_line_numbers(content)
-          lines = content.lines
-          output_lines = lines.each_with_index.map do |line, idx|
-            line_number = idx + 1
-            display_line = line.chomp
-            "#{line_number.to_s.rjust(6)}→#{display_line}"
-          end
-          output_lines.join("\n")
-        end
-      end
-    end
-  end
-end