ruby_llm-toolbox 0.1.0

data/lib/ruby_llm/toolbox/tools/grep_files.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+require "find"
+require "pathname"
+require "ruby_llm/toolbox/base"
+require "ruby_llm/toolbox/safety/path_jail"
+
+module RubyLLM
+  module Toolbox
+    module Tools
+      # SAFE. Searches file contents for a regular expression within fs_root and
+      # returns "path:line: text" hits.
+      #
+      # The pattern comes from the model, so two abuse vectors are guarded:
+      #   - ReDoS: the regex is compiled with a per-match timeout (Ruby 3.2+),
+      #     so catastrophic backtracking can't hang the process.
+      #   - Traversal: the walk starts at the jailed root, prunes noisy/VCS
+      #     directories, and skips symlinks so it can't be led outside.
+      class GrepFiles < Base
+        description "Search file contents for a regular expression within fs_root. Returns " \
+                    "'path:line: text' for each match. Optionally restrict to files whose name " \
+                    "matches a glob, and/or match case-insensitively. Results are capped, " \
+                    "ReDoS-guarded, and token-budgeted."
+
+        param :pattern, type: "string",
+                        desc: "Regular expression to search for.",
+                        required: true
+        param :path, type: "string",
+                     desc: "Directory to search, relative to fs_root. Defaults to fs_root.",
+                     required: false
+        param :glob, type: "string",
+                     desc: "Only search files whose basename matches this glob, e.g. '*.rb'. Optional.",
+                     required: false
+        param :ignore_case, type: "boolean",
+                           desc: "Case-insensitive match. Default false.",
+                           required: false
+        param :context, type: "integer",
+                        desc: "Lines of context to show before AND after each match (like grep -C). Optional.",
+                        required: false
+        param :before, type: "integer",
+                       desc: "Lines of context before each match (like grep -B). Overrides context. Optional.",
+                       required: false
+        param :after, type: "integer",
+                      desc: "Lines of context after each match (like grep -A). Overrides context. Optional.",
+                      required: false
+
+        MAX_FILE_BYTES = 5 * 1024 * 1024
+        MAX_CONTEXT = 50
+
+        def execute(pattern:, path: ".", glob: nil, ignore_case: false, context: nil, before: nil, after: nil)
+          regex = build_regex(pattern, ignore_case)
+          jail  = Safety::PathJail.new(config.fs_root)
+          root  = jail.resolve(path)
+          return error("not a directory: #{path}", code: :not_a_directory) unless File.directory?(root)
+
+          ctx_before = clamp_context(before.nil? ? context : before)
+          ctx_after  = clamp_context(after.nil? ? context : after)
+
+          if ctx_before.zero? && ctx_after.zero?
+            matches, capped = gather(root, regex, glob)
+            return "no matches for #{pattern.inspect}" if matches.empty?
+
+            body = +"#{matches.size}#{capped ? '+' : ''} match#{matches.size == 1 ? '' : 'es'} " \
+                    "for #{pattern.inspect}:\n"
+            body << matches.join("\n")
+            truncate(body)
+          else
+            blocks, total, capped = gather_with_context(root, regex, glob, ctx_before, ctx_after)
+            return "no matches for #{pattern.inspect}" if total.zero?
+
+            body = +"#{total}#{capped ? '+' : ''} match#{total == 1 ? '' : 'es'} " \
+                    "for #{pattern.inspect}:\n"
+            body << blocks.join("\n--\n")
+            truncate(body)
+          end
+        rescue Safety::PathJail::Jailbreak => e
+          error(e.message, code: :path_denied)
+        rescue Regexp::TimeoutError
+          error("regex timed out (possible catastrophic backtracking); simplify the pattern",
+                code: :regex_timeout)
+        rescue RegexpError => e
+          error("invalid regex: #{e.message}", code: :bad_pattern)
+        end
+
+        private
+
+        def clamp_context(value)
+          n = value.to_i
+          return 0 if n <= 0
+
+          [n, MAX_CONTEXT].min
+        end
+
+        def build_regex(pattern, ignore_case)
+          options = ignore_case ? Regexp::IGNORECASE : 0
+          Regexp.new(pattern.to_s, options, timeout: config.regex_timeout)
+        end
+
+        def gather(root, regex, glob)
+          base    = Pathname.new(root)
+          matches = []
+          capped  = false
+
+          catch(:done) do
+            walk(root, glob) do |file|
+              scan(file, regex) do |lineno, text|
+                rel = Pathname.new(file).relative_path_from(base).to_s
+                matches << "#{rel}:#{lineno}: #{text.strip}"
+                if matches.size >= config.max_grep_matches
+                  capped = true
+                  throw :done
+                end
+              end
+            end
+          end
+
+          [matches, capped]
+        end
+
+        # Like gather, but expands each match with before/after context lines,
+        # merges overlapping/adjacent ranges per file, and returns formatted
+        # blocks (joined later with grep-style "--" separators). Match lines use
+        # "path:line: text"; context lines use "path-line- text".
+        def gather_with_context(root, regex, glob, ctx_before, ctx_after)
+          base   = Pathname.new(root)
+          blocks = []
+          total  = 0
+          capped = false
+          cap    = config.max_grep_matches
+
+          catch(:done) do
+            walk(root, glob) do |file|
+              next if binary?(file)
+
+              lines = read_lines(file)
+              next if lines.nil?
+
+              match_idxs = []
+              lines.each_with_index { |line, i| match_idxs << i if regex.match?(line) }
+              next if match_idxs.empty?
+
+              taken = match_idxs.first(cap - total)
+              capped = true if taken.size < match_idxs.size
+              match_set = {}
+              taken.each { |i| match_set[i] = true }
+
+              rel = Pathname.new(file).relative_path_from(base).to_s
+              ranges = taken.map { |i| [[i - ctx_before, 0].max, [i + ctx_after, lines.size - 1].min] }
+              merge_ranges(ranges).each do |lo, hi|
+                block = (lo..hi).map do |i|
+                  sep = match_set[i] ? ":" : "-"
+                  "#{rel}#{sep}#{i + 1}#{sep} #{lines[i].to_s.strip}"
+                end
+                blocks << block.join("\n")
+              end
+
+              total += taken.size
+              throw :done if total >= cap
+            end
+          end
+
+          [blocks, total, capped]
+        end
+
+        def read_lines(file)
+          File.readlines(file).map(&:scrub)
+        rescue ArgumentError, SystemCallError
+          nil
+        end
+
+        def merge_ranges(ranges)
+          merged = []
+          ranges.sort_by(&:first).each do |lo, hi|
+            if !merged.empty? && lo <= merged.last[1] + 1
+              merged.last[1] = [merged.last[1], hi].max
+            else
+              merged << [lo, hi]
+            end
+          end
+          merged
+        end
+
+        def walk(root, glob)
+          Find.find(root) do |entry|
+            basename = File.basename(entry)
+
+            if File.directory?(entry)
+              Find.prune if config.ignored_dirs.include?(basename)
+              next
+            end
+
+            next if File.symlink?(entry)
+            next if glob && !File.fnmatch?(glob, basename, File::FNM_PATHNAME)
+            next unless File.file?(entry)
+            next if File.size(entry) > MAX_FILE_BYTES
+
+            yield entry
+          end
+        end
+
+        def scan(file, regex)
+          return if binary?(file)
+
+          File.foreach(file).with_index(1) do |line, lineno|
+            safe = line.scrub
+            yield(lineno, safe) if regex.match?(safe)
+          end
+        rescue ArgumentError
+          # Unreadable as text (encoding) — skip the file rather than fail.
+          nil
+        end
+
+        def binary?(file)
+          File.binread(file, 1024).to_s.include?("\u0000".b)
+        rescue StandardError
+          false
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/toolbox/tools/http_helpers.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "ruby_llm/toolbox/safety/url_guard"
+
+module RubyLLM
+  module Toolbox
+    module Tools
+      # Shared guarded-HTTP behavior for web_fetch and http_request. With the
+      # guard on (the default), every request URL and every redirect hop passes
+      # through UrlGuard, and the socket is pinned to the vetted IP so a second
+      # DNS lookup can't redirect us to an internal address. With guard: false
+      # (only reachable via an operator-permitted unsafe override), the URL is
+      # fetched directly with no SSRF checks.
+      module HttpHelpers
+        Response = Struct.new(:status, :headers, :body, :final_url, keyword_init: true)
+
+        class FetchError < StandardError; end
+
+        def url_guard
+          Safety::UrlGuard.new(allowlist: config.web_allowlist, denylist: config.web_denylist)
+        end
+
+        # GET with redirect following and a body-size cap. Each hop is re-guarded
+        # and re-pinned when guard is true.
+        def guarded_get(url, guard: true)
+          checker = url_guard if guard
+          current = url
+          seen = 0
+
+          loop do
+            uri, pin = resolve_hop(checker, current, guard)
+            response, body = perform(uri, "GET", nil, nil, pin)
+
+            if redirect?(response)
+              location = response["location"]
+              raise FetchError, "redirect with no Location header (status #{response.code})" unless location
+              raise FetchError, "too many redirects (max #{config.max_redirects})" if seen >= config.max_redirects
+
+              seen += 1
+              current = URI.join(uri.to_s, location).to_s
+              next
+            end
+
+            return Response.new(status: response.code.to_i, headers: response.to_hash,
+                                body: body, final_url: uri.to_s)
+          end
+        rescue Safety::UrlGuard::Blocked
+          raise
+        rescue StandardError => e
+          raise FetchError, e.message
+        end
+
+        # A single request with an explicit method/headers/body (no redirect
+        # following). Used by http_request.
+        def guarded_request(method, url, headers: {}, body: nil, guard: true)
+          uri, pin = resolve_hop(url_guard, url, guard)
+          response, raw = perform(uri, method.to_s.upcase, headers, body, pin)
+          Response.new(status: response.code.to_i, headers: response.to_hash, body: raw, final_url: uri.to_s)
+        rescue Safety::UrlGuard::Blocked
+          raise
+        rescue StandardError => e
+          raise FetchError, e.message
+        end
+
+        private
+
+        # Returns [uri, pinned_ip_or_nil]. When guarded, UrlGuard vets the host
+        # and supplies the IP to pin; when not, we only enforce http/https.
+        def resolve_hop(checker, url, guard)
+          if guard
+            resolution = checker.resolve!(url)
+            [resolution.uri, resolution.address]
+          else
+            uri = URI.parse(url.to_s)
+            raise FetchError, "only http/https URLs are allowed" unless %w[http https].include?(uri.scheme)
+
+            [uri, nil]
+          end
+        end
+
+        def redirect?(response)
+          response.is_a?(Net::HTTPRedirection)
+        end
+
+        def perform(uri, method, headers, body, pin = nil)
+          request = build_request(uri, method, headers, body)
+
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.use_ssl = uri.scheme == "https"
+          http.ipaddr = pin if pin # pin to the vetted address (closes DNS rebinding)
+          http.open_timeout = config.http_timeout
+          http.read_timeout = config.http_timeout
+
+          captured = +""
+          response = http.start do |conn|
+            conn.request(request) do |res|
+              unless res.is_a?(Net::HTTPRedirection)
+                res.read_body do |chunk|
+                  captured << chunk
+                  break if captured.bytesize >= config.max_fetch_bytes
+                end
+              end
+              res
+            end
+          end
+
+          [response, captured]
+        end
+
+        def build_request(uri, method, headers, body)
+          klass = begin
+            Net::HTTP.const_get(method.capitalize)
+          rescue NameError
+            nil
+          end
+          raise FetchError, "unsupported HTTP method: #{method}" unless klass && klass <= Net::HTTPRequest
+
+          request = klass.new(uri)
+          request["User-Agent"] = config.user_agent
+          request["Accept"] ||= "*/*"
+          Array(headers).each { |k, v| request[k.to_s] = v.to_s } if headers
+          request.body = body.to_s if body && !body.to_s.empty?
+          request
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/toolbox/tools/http_request.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "ruby_llm/toolbox/base"
+require "ruby_llm/toolbox/tools/http_helpers"
+
+module RubyLLM
+  module Toolbox
+    module Tools
+      # A general HTTP client, UrlGuard-protected. Read methods (GET/HEAD) work
+      # by default; mutating methods (POST/PUT/PATCH/DELETE) require
+      # enable_exec_tools, so the safe default can't change remote state. Returns
+      # status, key headers, and the (token-budgeted) body.
+      class HttpRequest < Base
+        include HttpHelpers
+
+        description "Make an HTTP request to an http/https URL and return the status, headers, and " \
+                    "body. GET and HEAD are available by default; POST/PUT/PATCH/DELETE require exec " \
+                    "tools to be enabled. Cannot reach private, loopback, or cloud-metadata addresses."
+
+        READ_METHODS     = %w[GET HEAD].freeze
+        MUTATING_METHODS = %w[POST PUT PATCH DELETE].freeze
+        SHOWN_HEADERS    = %w[content-type content-length location etag last-modified].freeze
+
+        param :url, type: "string",
+                    desc: "The http/https URL to request.",
+                    required: true
+        param :method, type: "string",
+                      desc: "HTTP method: GET (default), HEAD, POST, PUT, PATCH, DELETE.",
+                      required: false
+        param :headers, type: "object",
+                       desc: "Optional request headers as a JSON object of name/value strings.",
+                       required: false
+        param :body, type: "string",
+                     desc: "Optional request body (for POST/PUT/PATCH).",
+                     required: false
+        param :unsafe, type: "boolean",
+                       desc: "Request bypassing SSRF protection (UrlGuard). Only takes effect if an " \
+                             "operator enabled allow_unsafe; otherwise the call is refused. Default false.",
+                       required: false
+
+        def execute(url:, method: "GET", headers: nil, body: nil, unsafe: false)
+          verb = method.to_s.strip.upcase
+          verb = "GET" if verb.empty?
+          return error("unsupported method: #{verb}", code: :bad_method) unless (READ_METHODS + MUTATING_METHODS).include?(verb)
+          if MUTATING_METHODS.include?(verb) && !config.enable_exec_tools
+            return error("#{verb} requires enable_exec_tools = true (mutating request)", code: :exec_disabled)
+          end
+
+          bypass = permit_unsafe!(unsafe, url)
+          response = guarded_request(verb, url, headers: headers, body: body, guard: !bypass)
+          return error("HTTP #{response.status} from #{response.final_url}", code: :http_error) if response.status >= 400
+
+          truncate(format_response(verb, response))
+        rescue Safety::UrlGuard::Blocked => e
+          error(e.message, code: :url_blocked)
+        rescue HttpHelpers::FetchError => e
+          error("request failed: #{e.message}", code: :request_failed)
+        end
+
+        private
+
+        def format_response(verb, response)
+          lines = ["#{verb} #{response.final_url} -> #{response.status}"]
+          SHOWN_HEADERS.each do |name|
+            value = Array(response.headers[name]).first
+            lines << "#{name}: #{value}" if value
+          end
+          body = response.body.to_s.scrub
+          lines << "\n--- body ---\n#{body}" unless body.empty?
+          lines.join("\n")
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/toolbox/tools/json_query.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "json"
+require "ruby_llm/toolbox/base"
+require "ruby_llm/toolbox/data_path"
+require "ruby_llm/toolbox/safety/path_jail"
+
+module RubyLLM
+  module Toolbox
+    module Tools
+      # SAFE. Parses JSON (from a file in fs_root or an inline string) and either
+      # pretty-prints it or extracts a value with a dot/bracket path. In-process,
+      # read-only.
+      #
+      # Path syntax: dot-separated keys, [n] for array indices, and [] to map a
+      # field across an array. Examples:
+      #   users[0].name        users[].email        config.server.port
+      class JsonQuery < Base
+        description "Query JSON with a path expression, or pretty-print it. Provide either a file " \
+                    "path (within fs_root) or an inline json string. Path syntax: keys separated by " \
+                    "dots, [n] for array index, [] to map over an array (e.g. users[].name)."
+
+        MAX_BYTES = 5 * 1024 * 1024
+
+        param :path, type: "string",
+                     desc: "JSON file to read, relative to fs_root. Provide this or json.",
+                     required: false
+        param :json, type: "string",
+                     desc: "Inline JSON string. Provide this or path.",
+                     required: false
+        param :query, type: "string",
+                      desc: "Path expression to extract, e.g. 'users[0].name'. Omit to pretty-print. Optional.",
+                      required: false
+
+        def execute(path: nil, json: nil, query: nil)
+          source = load_source(path, json)
+          return source if source.is_a?(Hash) # error
+
+          data = JSON.parse(source)
+          result = query.to_s.strip.empty? ? data : DataPath.query(data, query)
+          truncate(JSON.pretty_generate(result))
+        rescue Safety::PathJail::Jailbreak => e
+          error(e.message, code: :path_denied)
+        rescue JSON::ParserError => e
+          error("invalid JSON: #{e.message}", code: :bad_json)
+        rescue DataPath::Error => e
+          error(e.message, code: :bad_query)
+        end
+
+        private
+
+        def load_source(path, json)
+          if path && !path.to_s.empty?
+            jail = Safety::PathJail.new(config.fs_root)
+            real = jail.resolve(path)
+            return error("not a file: #{path}", code: :not_a_file) unless File.file?(real)
+            return error("file too large (> #{MAX_BYTES} bytes)", code: :too_large) if File.size(real) > MAX_BYTES
+
+            File.read(real).scrub
+          elsif json && !json.to_s.empty?
+            json.to_s
+          else
+            error("provide either path or json", code: :no_input)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/toolbox/tools/lint.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "ruby_llm/toolbox/base"
+require "ruby_llm/toolbox/tools/toolchain_helpers"
+
+module RubyLLM
+  module Toolbox
+    module Tools
+      # EXEC. Runs RuboCop or Standard over the project at fs_root. Offenses are
+      # a normal result, not a tool error. With autocorrect, the linter rewrites
+      # files in place (a write effect — hence exec-gated).
+      class Lint < Base
+        include ToolchainHelpers
+        exec_tool!
+
+        description "Lint the project at fs_root with RuboCop or Standard. Auto-detects (Standard if " \
+                    ".standard.yml is present, else RuboCop) or set linter explicitly. Optionally scope " \
+                    "to a path and apply safe autocorrections. Uses `bundle exec` when a Gemfile exists."
+
+        LINTERS = %w[rubocop standard].freeze
+
+        param :path, type: "string",
+                     desc: "Limit linting to this path, relative to fs_root. Optional.",
+                     required: false
+        param :linter, type: "string",
+                      desc: "Force the linter: rubocop or standard. Default: auto-detect.",
+                      required: false
+        param :autocorrect, type: "boolean",
+                           desc: "Apply safe autocorrections, rewriting files in place. Default false.",
+                           required: false
+
+        def execute(path: nil, linter: nil, autocorrect: false)
+          tool = (linter || detect_linter).to_s
+          return error("unknown linter: #{tool} (use #{LINTERS.join(', ')})", code: :bad_linter) unless LINTERS.include?(tool)
+
+          rel = jail_relative(path)
+          out, err, status = run_in_project(build_args(tool, rel, autocorrect), use_bundle: true)
+          toolchain_output(out, err, status,
+                           pass_label: "LINT CLEAN",
+                           fail_label: autocorrect ? "LINT: offenses found (autocorrected where possible)" : "LINT: offenses found")
+        rescue Safety::PathJail::Jailbreak => e
+          error(e.message, code: :path_denied)
+        rescue CommandMissing => e
+          error("#{e.message} is not available (is it in the bundle / installed?)", code: :unavailable)
+        end
+
+        private
+
+        def detect_linter
+          File.exist?(File.join(config.fs_root, ".standard.yml")) ? "standard" : "rubocop"
+        end
+
+        def build_args(tool, rel, autocorrect)
+          if tool == "standard"
+            args = ["standardrb"]
+            args << "--fix" if autocorrect
+          else
+            args = ["rubocop", "--no-color"]
+            args << "--autocorrect" if autocorrect
+          end
+          args << rel if rel
+          args
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/toolbox/tools/list_directory.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "ruby_llm/toolbox/base"
+require "ruby_llm/toolbox/safety/path_jail"
+
+module RubyLLM
+  module Toolbox
+    module Tools
+      # SAFE. Lists the entries of a directory within fs_root, with type and
+      # size. Symlinked directories are listed but not traversed, so a link
+      # can't be used to walk out of the jail.
+      class ListDirectory < Base
+        description "List the entries of a directory within fs_root, with each entry's " \
+                    "type (dir/file/symlink) and size. Set recursive to walk subdirectories " \
+                    "(results are capped and token-budgeted)."
+
+        param :path, type: "string",
+                     desc: "Directory path relative to fs_root. Defaults to fs_root itself.",
+                     required: false
+        param :recursive, type: "boolean",
+                          desc: "Walk subdirectories. Default false.",
+                          required: false
+        param :include_hidden, type: "boolean",
+                              desc: "Include dotfiles and dot-directories. Default false.",
+                              required: false
+
+        MAX_ENTRIES = 1_000
+
+        def execute(path: ".", recursive: false, include_hidden: false)
+          jail = Safety::PathJail.new(config.fs_root)
+          root = jail.resolve(path)
+          return error("not a directory: #{path}", code: :not_a_directory) unless File.directory?(root)
+
+          entries = collect(root, recursive: recursive, include_hidden: include_hidden)
+          capped  = entries.first(MAX_ENTRIES)
+
+          body = +"#{entries.size} entr#{entries.size == 1 ? 'y' : 'ies'}"
+          body << " (showing first #{MAX_ENTRIES}; narrow the path)" if entries.size > MAX_ENTRIES
+          body << " in #{display(path)}:\n"
+          capped.each { |line| body << line << "\n" }
+          truncate(body)
+        rescue Safety::PathJail::Jailbreak => e
+          error(e.message, code: :path_denied)
+        end
+
+        private
+
+        def display(path)
+          path.nil? || path.empty? || path == "." ? "fs_root" : path
+        end
+
+        def collect(root, recursive:, include_hidden:)
+          base    = Pathname.new(root)
+          pattern = recursive ? File.join(root, "**", "*") : File.join(root, "*")
+          flags   = include_hidden ? File::FNM_DOTMATCH : 0
+
+          Dir.glob(pattern, flags).sort.filter_map do |entry|
+            basename = File.basename(entry)
+            next if basename == "." || basename == ".."
+
+            rel = base_relative(base, entry)
+            next if !include_hidden && rel.split(File::SEPARATOR).any? { |seg| seg.start_with?(".") }
+
+            describe(entry, rel)
+          end
+        end
+
+        def base_relative(base, entry)
+          Pathname.new(entry).relative_path_from(base).to_s
+        end
+
+        def describe(entry, rel)
+          if File.symlink?(entry)
+            "#{rel} -> (symlink)"
+          elsif File.directory?(entry)
+            "#{rel}/"
+          else
+            "#{rel} (#{File.size(entry)} B)"
+          end
+        rescue SystemCallError
+          nil
+        end
+      end
+    end
+  end
+end