ruby_llm-toolbox 0.1.0

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

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "ruby_llm/toolbox/base"
+require "ruby_llm/toolbox/tools/http_helpers"
+
+module RubyLLM
+  module Toolbox
+    module Tools
+      # SAFE. Fetches a URL over http/https and returns its readable text (HTML
+      # is stripped to text). Every request and redirect hop passes through
+      # UrlGuard, so it can't be pointed at internal/loopback/metadata addresses.
+      # Output is token-budgeted.
+      class WebFetch < Base
+        include HttpHelpers
+
+        description "Fetch a web page or text/JSON resource over http/https and return its readable " \
+                    "content (HTML is converted to text). Follows redirects safely. Cannot reach " \
+                    "private, loopback, or cloud-metadata addresses."
+
+        param :url, type: "string",
+                    desc: "The http/https URL to fetch.",
+                    required: true
+        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:, unsafe: false)
+          bypass = permit_unsafe!(unsafe, url)
+          response = guarded_get(url, guard: !bypass)
+
+          if response.status >= 400
+            return error("HTTP #{response.status} from #{response.final_url}", code: :http_error)
+          end
+
+          content_type = content_type_of(response)
+          text = extract_text(response.body, content_type)
+
+          header = "GET #{response.final_url} -> #{response.status} (#{content_type})"
+          truncate("#{header}\n\n#{text}".strip)
+        rescue Safety::UrlGuard::Blocked => e
+          error(e.message, code: :url_blocked)
+        rescue HttpHelpers::FetchError => e
+          error("fetch failed: #{e.message}", code: :fetch_failed)
+        end
+
+        private
+
+        def content_type_of(response)
+          Array(response.headers["content-type"]).first.to_s.split(";").first.to_s.strip
+        end
+
+        def extract_text(body, content_type)
+          text = body.to_s.scrub
+          return collapse(text) unless content_type =~ /html|xml/i
+
+          text = text.dup
+          text.gsub!(%r{<script\b[^>]*>.*?</script>}mi, " ")
+          text.gsub!(%r{<style\b[^>]*>.*?</style>}mi, " ")
+          text.gsub!(/<!--.*?-->/m, " ")
+          text.gsub!(%r{</(?:p|div|br|li|h[1-6]|tr|section|article)\s*/?>}i, "\n")
+          text.gsub!(/<[^>]+>/, " ")
+          collapse(decode_entities(text))
+        end
+
+        def decode_entities(str)
+          str.gsub("&amp;", "&").gsub("&lt;", "<").gsub("&gt;", ">")
+             .gsub("&quot;", '"').gsub("&#39;", "'").gsub("&nbsp;", " ")
+        end
+
+        def collapse(str)
+          str.gsub(/[ \t]+/, " ").gsub(/\n[ \t]*/, "\n").gsub(/\n{3,}/, "\n\n").strip
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "ruby_llm/toolbox/base"
+require "ruby_llm/toolbox/search/tavily"
+require "ruby_llm/toolbox/search/brave"
+require "ruby_llm/toolbox/search/searxng"
+
+module RubyLLM
+  module Toolbox
+    module Tools
+      # SAFE. Searches the web through the configured adapter (Tavily by
+      # default) and returns ranked results plus an optional synthesized answer.
+      # Requires an API key for the default Tavily adapter (config.tavily_api_key).
+      class WebSearch < Base
+        description "Search the web and return ranked results (title, URL, snippet) with an optional " \
+                    "synthesized answer. Uses Tavily by default (needs config.tavily_api_key); switch " \
+                    "providers with config.search_adapter set to :brave, :searxng, or a custom adapter."
+
+        param :query, type: "string",
+                      desc: "The search query.",
+                      required: true
+        param :max_results, type: "integer",
+                           desc: "Number of results to return (1-10, default 5).",
+                           required: false
+
+        def execute(query:, max_results: 5)
+          q = query.to_s.strip
+          return error("query must not be empty", code: :bad_query) if q.empty?
+
+          n = max_results.to_i
+          n = 5 if n <= 0
+          n = 10 if n > 10
+
+          result = adapter.search(q, max_results: n)
+          truncate(format_results(q, result))
+        rescue Search::Error => e
+          code = e.message.match?(/missing .*(api key|url)/i) ? :no_api_key : :search_failed
+          error(e.message, code: code)
+        end
+
+        private
+
+        # config.search_adapter may be: nil (→ Tavily), a Symbol naming a built-in
+        # adapter, or any object that responds to #search(query, max_results:).
+        def adapter
+          case config.search_adapter
+          when nil, :tavily
+            Search::Tavily.new(api_key: config.tavily_api_key, user_agent: config.user_agent,
+                               timeout: config.http_timeout)
+          when :brave
+            Search::Brave.new(api_key: config.brave_api_key, user_agent: config.user_agent,
+                              timeout: config.http_timeout)
+          when :searxng
+            Search::SearXNG.new(base_url: config.searxng_url, user_agent: config.user_agent,
+                                timeout: config.http_timeout)
+          when Symbol
+            raise Search::Error, "unknown search adapter #{config.search_adapter.inspect} " \
+                                 "(expected :tavily, :brave, :searxng, or an adapter object)"
+          else
+            config.search_adapter
+          end
+        end
+
+        def format_results(query, result)
+          results = Array(result[:results])
+          return "no results for #{query.inspect}" if results.empty?
+
+          body = +"Results for #{query.inspect}:\n"
+          results.each_with_index do |r, i|
+            body << "\n#{i + 1}. #{r[:title]}\n   #{r[:url]}\n"
+            snippet = r[:content].to_s.strip
+            body << "   #{snippet}\n" unless snippet.empty?
+          end
+          answer = result[:answer].to_s.strip
+          body << "\nAnswer: #{answer}\n" unless answer.empty?
+          body
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,52 @@
+# 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 or overwrites a text file within fs_root. Missing parent
+      # directories are created (inside the jail). Path traversal and symlink
+      # escapes are rejected by PathJail.
+      class WriteFile < Base
+        exec_tool!
+
+        description "Create or overwrite a text file within fs_root. Missing parent directories " \
+                    "are created automatically. Overwrites an existing file at the path."
+
+        param :path, type: "string",
+                     desc: "File path relative to fs_root (or an absolute path inside it).",
+                     required: true
+        param :content, type: "string",
+                        desc: "Full contents to write. Replaces the file entirely.",
+                        required: true
+        param :unsafe, type: "boolean",
+                       desc: "Request writing outside fs_root (bypass the path jail). Only takes effect " \
+                             "if an operator enabled allow_unsafe; otherwise the call is refused. Default false.",
+                       required: false
+
+        MAX_BYTES = 10 * 1024 * 1024
+
+        def execute(path:, content:, unsafe: false)
+          body = content.to_s
+          return error("content too large (> #{MAX_BYTES} bytes)", code: :too_large) if body.bytesize > MAX_BYTES
+
+          jail = path_jail(unsafe: unsafe, detail: path)
+          real = jail.resolve(path)
+          return error("path is a directory: #{path}", code: :is_a_directory) if File.directory?(real)
+
+          existed = File.exist?(real)
+          FileUtils.mkdir_p(File.dirname(real))
+          File.write(real, body)
+
+          verb = existed ? "Overwrote" : "Created"
+          "#{verb} #{path} (#{body.bytesize} bytes)"
+        rescue Safety::PathJail::Jailbreak => e
+          error(e.message, code: :path_denied)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "json"
+require "date"
+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 YAML (from a file in fs_root or an inline string) and either
+      # pretty-prints it (as JSON, for readability) or extracts a value with a
+      # dot/bracket path. Uses safe_load — no arbitrary Ruby objects are
+      # instantiated from the document.
+      #
+      # Path syntax matches json_query: users[0].name, users[].email, config.port
+      class YamlQuery < Base
+        description "Query YAML with a path expression, or pretty-print it. Provide either a file path " \
+                    "(within fs_root) or an inline yaml string. Loaded safely (no object deserialization). " \
+                    "Path syntax: keys separated by dots, [n] for array index, [] to map over an array."
+
+        MAX_BYTES = 5 * 1024 * 1024
+        PERMITTED = [Date, Time, Symbol].freeze
+
+        param :path, type: "string",
+                     desc: "YAML file to read, relative to fs_root. Provide this or yaml.",
+                     required: false
+        param :yaml, type: "string",
+                     desc: "Inline YAML string. Provide this or path.",
+                     required: false
+        param :query, type: "string",
+                      desc: "Path expression to extract, e.g. 'services[0].image'. Omit to pretty-print. Optional.",
+                      required: false
+
+        def execute(path: nil, yaml: nil, query: nil)
+          source = load_source(path, yaml)
+          return source if source.is_a?(Hash) # error
+
+          data = YAML.safe_load(source, permitted_classes: PERMITTED, aliases: true)
+          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 Psych::DisallowedClass => e
+          error("YAML contains a disallowed type: #{e.message}", code: :unsafe_yaml)
+        rescue Psych::SyntaxError => e
+          error("invalid YAML: #{e.message}", code: :bad_yaml)
+        rescue DataPath::Error => e
+          error(e.message, code: :bad_query)
+        end
+
+        private
+
+        def load_source(path, yaml)
+          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 yaml && !yaml.to_s.empty?
+            yaml.to_s
+          else
+            error("provide either path or yaml", code: :no_input)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/toolbox/truncator.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "ruby_llm/tokenizer"
+
+module RubyLLM
+  module Toolbox
+    # Token-budgets a string so a single tool result can never blow up the
+    # context window. Keeps the head and the tail (the two ends an agent most
+    # often needs) and elides the middle. Counting goes through
+    # ruby_llm-tokenizer; if no tokenizer backend is available for the model,
+    # it falls back to a ~4-chars-per-token heuristic so a tool never crashes
+    # just because a tokenizer gem isn't installed.
+    class Truncator
+      MARKER_RESERVE = 16 # tokens held back for the elision marker
+
+      def initialize(model:, max_tokens:)
+        @model = model
+        @max_tokens = [max_tokens.to_i, 1].max
+      end
+
+      def call(text)
+        text = text.to_s
+        total = count(text)
+        return text if total <= @max_tokens
+
+        budget      = [@max_tokens - MARKER_RESERVE, 2].max
+        head_budget = (budget * 0.6).floor
+        tail_budget = budget - head_budget
+
+        head = take(text, head_budget, from: :head)
+        tail = take(text, tail_budget, from: :tail)
+        cut  = total - count(head) - count(tail)
+
+        "#{head}\n\n…[truncated ~#{cut} tokens]…\n\n#{tail}"
+      end
+
+      private
+
+      def count(text)
+        RubyLLM::Tokenizer.count(text, model: @model)
+      rescue StandardError
+        (text.to_s.length / 4.0).ceil
+      end
+
+      # Longest prefix (or suffix) of `text` whose token count fits `max_tokens`.
+      # Binary search keeps this O(log n) tokenizer calls instead of O(n).
+      def take(text, max_tokens, from:)
+        return +"" if max_tokens <= 0
+        return text if count(text) <= max_tokens
+
+        lo = 0
+        hi = text.length
+        best = +""
+        while lo <= hi
+          mid = (lo + hi) / 2
+          slice = (from == :head ? text[0, mid] : text[text.length - mid, mid]).to_s
+          if count(slice) <= max_tokens
+            best = slice
+            lo = mid + 1
+          else
+            hi = mid - 1
+          end
+        end
+        best
+      end
+    end
+  end
+end

data/lib/ruby_llm/toolbox/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Toolbox
+    VERSION = "0.1.0"
+  end
+end

data/lib/ruby_llm/toolbox.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require "ruby_llm"
+
+require_relative "toolbox/version"
+require_relative "toolbox/configuration"
+require_relative "toolbox/truncator"
+require_relative "toolbox/base"
+require_relative "toolbox/process_runner"
+require_relative "toolbox/process_registry"
+require_relative "toolbox/ruby_outline"
+require_relative "toolbox/safety/path_jail"
+require_relative "toolbox/safety/command_guard"
+require_relative "toolbox/safety/url_guard"
+require_relative "toolbox/sandbox/base"
+require_relative "toolbox/sandbox/docker"
+require_relative "toolbox/sandbox/bubblewrap"
+require_relative "toolbox/sandbox/sandbox_exec"
+require_relative "toolbox/tools/read_file"
+require_relative "toolbox/tools/list_directory"
+require_relative "toolbox/tools/tree"
+require_relative "toolbox/tools/glob"
+require_relative "toolbox/tools/grep_files"
+require_relative "toolbox/tools/gem_tool"
+require_relative "toolbox/tools/parse_ruby"
+require_relative "toolbox/tools/web_fetch"
+require_relative "toolbox/tools/web_search"
+require_relative "toolbox/tools/http_request"
+require_relative "toolbox/tools/json_query"
+require_relative "toolbox/tools/yaml_query"
+require_relative "toolbox/tools/toml_query"
+require_relative "toolbox/tools/csv_read"
+require_relative "toolbox/tools/calculator"
+require_relative "toolbox/tools/date_time"
+require_relative "toolbox/tools/diff"
+require_relative "toolbox/tools/todo_write"
+require_relative "toolbox/tools/process_output"
+require_relative "toolbox/tools/process_list"
+require_relative "toolbox/tools/process_kill"
+require_relative "toolbox/tools/git_helpers"
+require_relative "toolbox/tools/git_status"
+require_relative "toolbox/tools/git_diff"
+require_relative "toolbox/tools/git_log"
+require_relative "toolbox/tools/git_show"
+require_relative "toolbox/tools/git_blame"
+require_relative "toolbox/tools/git_grep"
+require_relative "toolbox/tools/git_branch"
+require_relative "toolbox/tools/write_file"
+require_relative "toolbox/tools/edit_file"
+require_relative "toolbox/tools/multi_edit"
+require_relative "toolbox/tools/create_directory"
+require_relative "toolbox/tools/move_file"
+require_relative "toolbox/tools/delete_file"
+require_relative "toolbox/tools/git_add"
+require_relative "toolbox/tools/git_commit"
+require_relative "toolbox/tools/git_checkout"
+require_relative "toolbox/tools/apply_patch"
+require_relative "toolbox/tools/csv_write"
+require_relative "toolbox/tools/replace_in_files"
+require_relative "toolbox/tools/download_file"
+require_relative "toolbox/tools/toolchain_helpers"
+require_relative "toolbox/tools/run_tests"
+require_relative "toolbox/tools/python_tests"
+require_relative "toolbox/tools/lint"
+require_relative "toolbox/tools/bundle"
+require_relative "toolbox/tools/sandbox_run"
+require_relative "toolbox/tools/bash_tool"
+require_relative "toolbox/tools/process_start"
+require_relative "toolbox/tools/run_ruby"
+require_relative "toolbox/tools/run_python"
+require_relative "toolbox/tools/run_rust"
+
+module RubyLLM
+  # A safe-by-default bundle of RubyLLM::Tool classes covering the skills common
+  # to most LLM harnesses. One require loads everything; the dangerous tools are
+  # inert until you flip config.enable_exec_tools.
+  module Toolbox
+    class << self
+      def config
+        @config ||= Configuration.new
+      end
+
+      def configure
+        yield config
+      end
+
+      # Resets global config. Primarily for tests.
+      def reset!
+        @config = nil
+      end
+
+      # Always-on, read-only tools.
+      def safe_tools(**overrides)
+        [
+          Tools::ReadFile.new(**overrides),
+          Tools::ListDirectory.new(**overrides),
+          Tools::Tree.new(**overrides),
+          Tools::Glob.new(**overrides),
+          Tools::GrepFiles.new(**overrides),
+          Tools::GemTool.new(**overrides),
+          Tools::ParseRuby.new(**overrides),
+          Tools::WebFetch.new(**overrides),
+          Tools::WebSearch.new(**overrides),
+          Tools::HttpRequest.new(**overrides),
+          Tools::GitStatus.new(**overrides),
+          Tools::GitDiff.new(**overrides),
+          Tools::GitLog.new(**overrides),
+          Tools::GitShow.new(**overrides),
+          Tools::GitBlame.new(**overrides),
+          Tools::GitGrep.new(**overrides),
+          Tools::GitBranch.new(**overrides),
+          Tools::JsonQuery.new(**overrides),
+          Tools::YamlQuery.new(**overrides),
+          Tools::TomlQuery.new(**overrides),
+          Tools::CsvRead.new(**overrides),
+          Tools::Calculator.new(**overrides),
+          Tools::DateTime.new(**overrides),
+          Tools::Diff.new(**overrides),
+          Tools::TodoWrite.new(**overrides),
+          Tools::ProcessOutput.new(**overrides),
+          Tools::ProcessList.new(**overrides),
+          Tools::ProcessKill.new(**overrides)
+        ]
+      end
+
+      # Tools whose effects are gated behind enable_exec_tools.
+      def exec_tools(**overrides)
+        [
+          Tools::WriteFile.new(**overrides),
+          Tools::EditFile.new(**overrides),
+          Tools::MultiEdit.new(**overrides),
+          Tools::CreateDirectory.new(**overrides),
+          Tools::MoveFile.new(**overrides),
+          Tools::DeleteFile.new(**overrides),
+          Tools::GitAdd.new(**overrides),
+          Tools::GitCommit.new(**overrides),
+          Tools::GitCheckout.new(**overrides),
+          Tools::ApplyPatch.new(**overrides),
+          Tools::CsvWrite.new(**overrides),
+          Tools::ReplaceInFiles.new(**overrides),
+          Tools::DownloadFile.new(**overrides),
+          Tools::RunTests.new(**overrides),
+          Tools::PythonTests.new(**overrides),
+          Tools::Lint.new(**overrides),
+          Tools::Bundle.new(**overrides),
+          Tools::BashTool.new(**overrides),
+          Tools::ProcessStart.new(**overrides),
+          Tools::RunRuby.new(**overrides),
+          Tools::RunPython.new(**overrides),
+          Tools::RunRust.new(**overrides)
+        ]
+      end
+
+      # Everything. Exec tools still honor the gate at call time, so handing the
+      # full set to a chat is safe by default.
+      def all_tools(**overrides)
+        safe_tools(**overrides) + exec_tools(**overrides)
+      end
+    end
+  end
+end