ruby_llm-toolbox 0.1.0

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

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "ruby_llm/toolbox/base"
+require "ruby_llm/toolbox/safe_math"
+
+module RubyLLM
+  module Toolbox
+    module Tools
+      # SAFE. Evaluates an arithmetic expression without eval, so it can't
+      # execute code. Supports + - * / % **, parentheses, unary minus, the
+      # functions sqrt/abs/sin/cos/tan/ln/log10/exp/floor/ceil/round, and the
+      # constants pi and e.
+      class Calculator < Base
+        description "Evaluate an arithmetic expression and return the result. Supports + - * / % **, " \
+                    "parentheses, sqrt/abs/sin/cos/tan/ln/log10/exp/floor/ceil/round, and pi/e. " \
+                    "Does not execute code."
+
+        param :expression, type: "string",
+                          desc: "The arithmetic expression, e.g. '(1 + 2) * 3' or 'sqrt(2) * pi'.",
+                          required: true
+
+        def execute(expression:)
+          return error("expression must not be empty", code: :empty) if expression.to_s.strip.empty?
+
+          value = SafeMath.evaluate(expression)
+          "#{expression.strip} = #{format_number(value)}"
+        rescue SafeMath::Error => e
+          error(e.message, code: :bad_expression)
+        end
+
+        private
+
+        def format_number(value)
+          return value.to_s unless value.is_a?(Float)
+          return value.to_i.to_s if value.finite? && value == value.to_i
+
+          value.to_s
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "ruby_llm/toolbox/base"
+require "ruby_llm/toolbox/safety/path_jail"
+
+module RubyLLM
+  module Toolbox
+    module Tools
+      # EXEC. Creates a directory (and any missing parents) within fs_root.
+      class CreateDirectory < Base
+        exec_tool!
+
+        description "Create a directory within fs_root, including any missing parent directories. " \
+                    "Succeeds quietly if it already exists."
+
+        param :path, type: "string",
+                     desc: "Directory path relative to fs_root.",
+                     required: true
+
+        def execute(path:)
+          jail = Safety::PathJail.new(config.fs_root)
+          real = jail.resolve(path)
+          return error("a file already exists at #{path}", code: :is_a_file) if File.file?(real)
+
+          existed = File.directory?(real)
+          FileUtils.mkdir_p(real)
+          existed ? "Directory already exists: #{path}" : "Created directory #{path}"
+        rescue Safety::PathJail::Jailbreak => e
+          error(e.message, code: :path_denied)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "csv"
+require "ruby_llm/toolbox/base"
+require "ruby_llm/toolbox/safety/path_jail"
+
+module RubyLLM
+  module Toolbox
+    module Tools
+      # SAFE. Reads a CSV file within fs_root and returns its rows in a compact
+      # readable form. Read-only.
+      class CsvRead < Base
+        description "Read a CSV file within fs_root and return its rows. By default the first row is " \
+                    "treated as a header. Use limit to cap the number of data rows returned."
+
+        MAX_BYTES = 10 * 1024 * 1024
+        DEFAULT_LIMIT = 100
+
+        param :path, type: "string",
+                     desc: "CSV file to read, relative to fs_root.",
+                     required: true
+        param :headers, type: "boolean",
+                       desc: "Treat the first row as column headers. Default true.",
+                       required: false
+        param :limit, type: "integer",
+                      desc: "Maximum number of data rows to return (default 100).",
+                      required: false
+
+        def execute(path:, headers: true, limit: DEFAULT_LIMIT)
+          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
+
+          rows = CSV.read(real)
+          return "empty CSV" if rows.empty?
+
+          max = limit.to_i
+          max = DEFAULT_LIMIT if max <= 0
+          truncate(render(rows, headers, max))
+        rescue Safety::PathJail::Jailbreak => e
+          error(e.message, code: :path_denied)
+        rescue CSV::MalformedCSVError => e
+          error("malformed CSV: #{e.message}", code: :bad_csv)
+        end
+
+        private
+
+        def render(rows, headers, max)
+          header = headers ? rows.first : nil
+          data = headers ? rows[1..] : rows
+          shown = data.first(max)
+
+          lines = []
+          lines << "columns: #{header.join(' | ')}" if header
+          lines << "#{data.size} row#{data.size == 1 ? '' : 's'}#{data.size > max ? " (showing #{max})" : ''}"
+          shown.each_with_index do |row, i|
+            lines << if header
+                       "#{i + 1}. " + header.zip(row).map { |k, v| "#{k}=#{v}" }.join(", ")
+                     else
+                       "#{i + 1}. " + row.join(" | ")
+                     end
+          end
+          lines.join("\n")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "csv"
+require "fileutils"
+require "ruby_llm/toolbox/base"
+require "ruby_llm/toolbox/safety/path_jail"
+
+module RubyLLM
+  module Toolbox
+    module Tools
+      # EXEC. Writes rows to a CSV file within fs_root. Optional header row.
+      # Missing parent directories are created.
+      class CsvWrite < Base
+        exec_tool!
+
+        description "Write rows to a CSV file within fs_root. Provide rows as an array of arrays " \
+                    "(each inner array is a row of cell values), with an optional headers array " \
+                    "written as the first line. Overwrites an existing file."
+
+        param :path, type: "string",
+                     desc: "Destination CSV path, relative to fs_root.",
+                     required: true
+        param :rows, type: "array",
+                     desc: "Array of rows; each row is an array of cell values.",
+                     required: true
+        param :headers, type: "array",
+                       desc: "Optional column header row, written first.",
+                       required: false
+
+        def execute(path:, rows:, headers: nil)
+          return error("rows must be an array of arrays", code: :bad_rows) unless rows.is_a?(Array)
+
+          jail = Safety::PathJail.new(config.fs_root)
+          real = jail.resolve(path)
+          return error("path is a directory: #{path}", code: :is_a_directory) if File.directory?(real)
+
+          all = []
+          all << Array(headers) if headers && !Array(headers).empty?
+          rows.each { |row| all << Array(row) }
+
+          FileUtils.mkdir_p(File.dirname(real))
+          CSV.open(real, "w") { |csv| all.each { |row| csv << row } }
+
+          "Wrote #{rows.size} row#{rows.size == 1 ? '' : 's'} to #{path}"
+        rescue Safety::PathJail::Jailbreak => e
+          error(e.message, code: :path_denied)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "time"
+require "ruby_llm/toolbox/base"
+
+module RubyLLM
+  module Toolbox
+    module Tools
+      # SAFE. Reports the current date/time (or converts a given unix timestamp),
+      # with optional strftime formatting.
+      class DateTime < Base
+        description "Get the current date and time, or convert a unix timestamp. Optionally format " \
+                    "with a strftime pattern. Returns ISO 8601, unix time, weekday, and timezone."
+
+        param :format, type: "string",
+                      desc: "Optional strftime pattern, e.g. '%Y-%m-%d %H:%M'. If given, returns just that.",
+                      required: false
+        param :unix, type: "integer",
+                     desc: "Optional unix timestamp to convert instead of using the current time.",
+                     required: false
+
+        def execute(format: nil, unix: nil)
+          time = unix.nil? ? Time.now : Time.at(unix.to_i).utc
+
+          if format && !format.to_s.strip.empty?
+            return time.strftime(format.to_s)
+          end
+
+          [
+            "iso8601: #{time.iso8601}",
+            "unix: #{time.to_i}",
+            "date: #{time.strftime('%A, %B %-d, %Y')}",
+            "time: #{time.strftime('%H:%M:%S')}",
+            "timezone: #{time.strftime('%Z (%z)')}"
+          ].join("\n")
+        rescue StandardError => e
+          error("could not format time: #{e.message}", code: :bad_format)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "ruby_llm/toolbox/base"
+require "ruby_llm/toolbox/safety/path_jail"
+
+module RubyLLM
+  module Toolbox
+    module Tools
+      # EXEC. Deletes a file or directory within fs_root. Deleting a non-empty
+      # directory requires recursive: true, so a single mistaken call can't wipe
+      # a tree by accident. Confinement to the jail bounds the blast radius to
+      # fs_root regardless.
+      class DeleteFile < Base
+        exec_tool!
+
+        description "Delete a file or directory within fs_root. A non-empty directory is only " \
+                    "removed when recursive is true. Refuses to delete fs_root itself."
+
+        param :path, type: "string",
+                     desc: "Path to delete, relative to fs_root.",
+                     required: true
+        param :recursive, type: "boolean",
+                         desc: "Allow deleting a non-empty directory and its contents. Default false.",
+                         required: false
+
+        def execute(path:, recursive: false)
+          jail = Safety::PathJail.new(config.fs_root)
+          real = jail.resolve(path)
+
+          return error("refusing to delete fs_root itself", code: :refused) if real == jail.root
+          return error("path does not exist: #{path}", code: :not_found) unless File.exist?(real)
+
+          if File.directory?(real)
+            delete_directory(real, path, recursive)
+          else
+            File.delete(real)
+            "Deleted file #{path}"
+          end
+        rescue Safety::PathJail::Jailbreak => e
+          error(e.message, code: :path_denied)
+        end
+
+        private
+
+        def delete_directory(real, path, recursive)
+          empty = Dir.empty?(real)
+          if empty
+            Dir.rmdir(real)
+            "Deleted empty directory #{path}"
+          elsif recursive
+            count = Dir.glob(File.join(real, "**", "*"), File::FNM_DOTMATCH)
+                       .reject { |p| %w[. ..].include?(File.basename(p)) }.size
+            FileUtils.rm_rf(real)
+            "Deleted directory #{path} and #{count} item#{count == 1 ? '' : 's'} inside it"
+          else
+            error("directory is not empty: #{path} (set recursive to delete its contents)",
+                  code: :not_empty)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "ruby_llm/toolbox/base"
+require "ruby_llm/toolbox/text_diff"
+
+module RubyLLM
+  module Toolbox
+    module Tools
+      # SAFE. Compares two blocks of text and returns a readable line diff.
+      class Diff < Base
+        description "Compare two blocks of text and return a readable line-by-line diff " \
+                    "(removed lines prefixed -, added lines prefixed +). In-process."
+
+        param :old, type: "string",
+                    desc: "The original text.",
+                    required: true
+        param :new, type: "string",
+                    desc: "The changed text.",
+                    required: true
+        param :old_label, type: "string",
+                         desc: "Label for the original side. Default 'old'.",
+                         required: false
+        param :new_label, type: "string",
+                         desc: "Label for the changed side. Default 'new'.",
+                         required: false
+
+        def execute(old:, new:, old_label: "old", new_label: "new")
+          diff = TextDiff.unified(old.to_s, new.to_s,
+                                  old_label: old_label.to_s, new_label: new_label.to_s)
+          truncate(diff)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "ruby_llm/toolbox/base"
+require "ruby_llm/toolbox/tools/http_helpers"
+require "ruby_llm/toolbox/safety/path_jail"
+
+module RubyLLM
+  module Toolbox
+    module Tools
+      # EXEC. Downloads a URL to a file within fs_root. The request goes through
+      # UrlGuard (so it can't be pointed at internal/loopback/metadata
+      # addresses), follows redirects safely, and is capped at
+      # config.max_fetch_bytes. The destination path is jailed to fs_root.
+      class DownloadFile < Base
+        include HttpHelpers
+        exec_tool!
+
+        description "Download an http/https URL to a file within fs_root. SSRF-protected and " \
+                    "size-capped. Use for fetching an asset or release to disk (web_fetch returns text " \
+                    "instead). Overwrites an existing file."
+
+        param :url, type: "string",
+                    desc: "The http/https URL to download.",
+                    required: true
+        param :path, type: "string",
+                     desc: "Destination path, relative to fs_root.",
+                     required: true
+
+        def execute(url:, path:)
+          jail = Safety::PathJail.new(config.fs_root)
+          real = jail.resolve(path)
+          return error("path is a directory: #{path}", code: :is_a_directory) if File.directory?(real)
+
+          response = guarded_get(url)
+          if response.status >= 400
+            return error("server returned HTTP #{response.status} for #{response.final_url}", code: :http_error)
+          end
+
+          body = response.body.to_s
+          FileUtils.mkdir_p(File.dirname(real))
+          File.binwrite(real, body)
+
+          "Downloaded #{body.bytesize} bytes from #{response.final_url} to #{path}"
+        rescue Safety::PathJail::Jailbreak => e
+          error(e.message, code: :path_denied)
+        rescue Safety::UrlGuard::Blocked => e
+          error(e.message, code: :url_blocked)
+        rescue HttpHelpers::FetchError => e
+          error("download failed: #{e.message}", code: :fetch_failed)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "ruby_llm/toolbox/base"
+require "ruby_llm/toolbox/safety/path_jail"
+
+module RubyLLM
+  module Toolbox
+    module Tools
+      # EXEC. The core editing primitive: replace an exact substring in a file.
+      #
+      # By default old_string must match EXACTLY ONCE — if it's missing the edit
+      # fails, and if it's ambiguous (appears more than once) the edit also fails
+      # rather than guessing. Set replace_all to change every occurrence. This is
+      # the same contract coding agents rely on from a str_replace tool: it makes
+      # edits deterministic and refuses to silently do the wrong thing.
+      class EditFile < Base
+        exec_tool!
+
+        description "Replace an exact substring in a text file within fs_root. old_string must " \
+                    "match exactly once (include enough surrounding context to be unique), or set " \
+                    "replace_all to change every occurrence. Fails clearly if old_string is missing " \
+                    "or ambiguous, so edits never land in the wrong place."
+
+        param :path, type: "string",
+                     desc: "File path relative to fs_root.",
+                     required: true
+        param :old_string, type: "string",
+                          desc: "Exact text to replace. Include surrounding lines so it's unique.",
+                          required: true
+        param :new_string, type: "string",
+                          desc: "Replacement text.",
+                          required: true
+        param :replace_all, type: "boolean",
+                           desc: "Replace every occurrence instead of requiring a unique match. Default false.",
+                           required: false
+
+        MAX_BYTES = 10 * 1024 * 1024
+
+        def execute(path:, old_string:, new_string:, replace_all: false)
+          old_s = old_string.to_s
+          new_s = new_string.to_s
+          return error("old_string must not be empty", code: :empty_match) if old_s.empty?
+          return error("old_string and new_string are identical; nothing to do", code: :no_change) if old_s == new_s
+
+          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
+
+          original = File.read(real).scrub
+          count = original.scan(old_string_regexp(old_s)).size
+          return error("old_string not found in #{path}", code: :not_found) if count.zero?
+          if count > 1 && !replace_all
+            return error("old_string is ambiguous: #{count} matches in #{path}. " \
+                         "Add surrounding context to make it unique, or set replace_all.",
+                         code: :ambiguous)
+          end
+
+          updated = if replace_all
+                      original.gsub(old_s) { new_s }
+                    else
+                      original.sub(old_s) { new_s }
+                    end
+          File.write(real, updated)
+
+          line = original[0...original.index(old_s)].count("\n") + 1
+          "Edited #{path} (#{count} replacement#{count == 1 ? '' : 's'}, " \
+            "#{original.bytesize} -> #{updated.bytesize} bytes, first change at line #{line})"
+        rescue Safety::PathJail::Jailbreak => e
+          error(e.message, code: :path_denied)
+        end
+
+        private
+
+        # Count occurrences by literal text, not as a pattern.
+        def old_string_regexp(old_s)
+          Regexp.new(Regexp.escape(old_s))
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+require "ruby_llm/toolbox/base"
+
+module RubyLLM
+  module Toolbox
+    module Tools
+      # SAFE. Read-only RubyGems.org metadata lookup. The host is fixed and all
+      # user input is URL-encoded into the path/query (and gem names are
+      # validated), so there is no arbitrary-URL / SSRF surface here.
+      #
+      # Tool name: "gem".
+      class GemTool < Base
+        class NotFound < StandardError; end
+        class HttpError < StandardError; end
+
+        description "Look up RubyGems.org metadata for a gem (read-only). Actions: info (summary), " \
+                    "version (latest version), dependencies (runtime deps), search (find gems by " \
+                    "query). For 'search', pass the query as name. Returns concise, token-budgeted text."
+
+        ACTIONS = %w[info version dependencies search].freeze
+        NAME_RE = /\A[A-Za-z0-9_.-]+\z/
+        HOST    = "https://rubygems.org"
+
+        param :name, type: "string",
+                     desc: "Gem name, or — for action 'search' — the search query.",
+                     required: true
+        param :action, type: "string",
+                       desc: "One of: info, version, dependencies, search. Default info.",
+                       required: false
+
+        def execute(name:, action: "info")
+          action = normalize_action(action)
+          return error("unknown action: #{action} (use #{ACTIONS.join(', ')})", code: :bad_action) unless ACTIONS.include?(action)
+          return search(name) if action == "search"
+
+          gem = name.to_s.strip
+          return error("invalid gem name: #{gem.inspect}", code: :bad_name) unless gem.match?(NAME_RE)
+
+          case action
+          when "version"      then version(gem)
+          when "dependencies" then dependencies(gem)
+          else                     info(gem)
+          end
+        rescue NotFound
+          error("gem not found: #{name}", code: :not_found)
+        rescue HttpError => e
+          error("rubygems.org request failed: #{e.message}", code: :http_error)
+        end
+
+        private
+
+        def normalize_action(action)
+          a = action.to_s.strip.downcase
+          a.empty? ? "info" : a
+        end
+
+        def info(gem)
+          data = get_json("#{HOST}/api/v1/gems/#{enc(gem)}.json")
+          lines = ["#{data['name']} #{data['version']}"]
+          lines << data["info"].to_s.strip unless data["info"].to_s.strip.empty?
+          lines << "homepage: #{data['homepage_uri']}" if data["homepage_uri"]
+          lines << "licenses: #{Array(data['licenses']).join(', ')}" if data["licenses"]
+          lines << "downloads: #{data['downloads']}" if data["downloads"]
+          runtime = data.dig("dependencies", "runtime") || []
+          unless runtime.empty?
+            lines << "runtime deps: #{runtime.map { |d| "#{d['name']} #{d['requirements']}" }.join('; ')}"
+          end
+          truncate(lines.join("\n"))
+        end
+
+        def version(gem)
+          data = get_json("#{HOST}/api/v1/versions/#{enc(gem)}/latest.json")
+          v = data["version"]
+          return error("gem not found: #{gem}", code: :not_found) if v.nil? || v == "unknown"
+
+          "#{gem} #{v}"
+        end
+
+        def dependencies(gem)
+          data    = get_json("#{HOST}/api/v1/gems/#{enc(gem)}.json")
+          runtime = data.dig("dependencies", "runtime") || []
+          dev     = data.dig("dependencies", "development") || []
+          return "#{gem} #{data['version']} has no runtime dependencies" if runtime.empty?
+
+          body = +"#{gem} #{data['version']} runtime dependencies:\n"
+          runtime.each { |d| body << "  #{d['name']} #{d['requirements']}\n" }
+          body << "(+#{dev.size} development deps)" unless dev.empty?
+          truncate(body)
+        end
+
+        def search(query)
+          q = query.to_s.strip
+          return error("empty search query", code: :bad_name) if q.empty?
+
+          results = get_json("#{HOST}/api/v1/search.json?query=#{enc(q)}")
+          return "no gems found for #{q.inspect}" unless results.is_a?(Array) && results.any?
+
+          body = +"#{results.size} result#{results.size == 1 ? '' : 's'} for #{q.inspect}:\n"
+          results.first(20).each do |g|
+            summary = g["info"].to_s.split("\n").first
+            body << "  #{g['name']} #{g['version']} — #{summary}\n"
+          end
+          truncate(body)
+        end
+
+        def enc(str)
+          URI.encode_www_form_component(str)
+        end
+
+        # Seam for tests. Performs a GET and parses JSON, mapping transport and
+        # not-found conditions onto the tool's error classes.
+        def get_json(url)
+          uri = URI.parse(url)
+          req = Net::HTTP::Get.new(uri)
+          req["User-Agent"] = config.user_agent
+          req["Accept"]     = "application/json"
+
+          res = Net::HTTP.start(uri.host, uri.port,
+                                use_ssl: uri.scheme == "https",
+                                open_timeout: config.http_timeout,
+                                read_timeout: config.http_timeout) { |http| http.request(req) }
+
+          case res
+          when Net::HTTPSuccess  then JSON.parse(res.body)
+          when Net::HTTPNotFound then raise NotFound
+          else raise HttpError, "HTTP #{res.code}"
+          end
+        rescue JSON::ParserError => e
+          raise HttpError, "invalid JSON (#{e.message})"
+        rescue SocketError, Net::OpenTimeout, Net::ReadTimeout => e
+          raise HttpError, e.message
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "ruby_llm/toolbox/base"
+require "ruby_llm/toolbox/tools/git_helpers"
+
+module RubyLLM
+  module Toolbox
+    module Tools
+      # EXEC. Stages changes in the repo at fs_root.
+      class GitAdd < Base
+        include GitHelpers
+        exec_tool!
+
+        description "Stage changes in the repository at fs_root. Pass specific paths, or set all to " \
+                    "stage every change (git add -A)."
+
+        param :paths, type: "array",
+                     desc: "Paths to stage, relative to fs_root. Each is confined to the repo.",
+                     required: false
+        param :all, type: "boolean",
+                    desc: "Stage all changes (git add -A) instead of specific paths. Default false.",
+                    required: false
+
+        def execute(paths: nil, all: false)
+          rels = Array(paths).filter_map { |p| repo_relative(p) }
+
+          if all
+            args = ["add", "-A"]
+          elsif rels.empty?
+            return error("provide paths or set all: true", code: :nothing_to_add)
+          else
+            args = ["add", "--", *rels]
+          end
+
+          out, err, status = run_git(*args)
+          result = git_result(out, err, status)
+          return result if result.is_a?(Hash)
+
+          all ? "Staged all changes" : "Staged: #{rels.join(', ')}"
+        rescue Safety::PathJail::Jailbreak => e
+          error(e.message, code: :path_denied)
+        end
+      end
+    end
+  end
+end