ruby_llm-toolbox 0.1.0

data/lib/ruby_llm/toolbox/sandbox/base.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+
+module RubyLLM
+  module Toolbox
+    # Pluggable sandboxes for the code-execution tools (run_ruby/run_python/
+    # run_rust). Each backend exposes the same contract:
+    #
+    #   available?                       -> true if it can run here
+    #   run(argv, stdin:, image: nil)    -> [stdout, stderr, status]
+    #   command(argv, image: nil)        -> the fully wrapped argv (for tests)
+    #
+    # `image` is only meaningful for Docker; the host-process sandboxes
+    # (Bubblewrap, sandbox-exec) ignore it and run the host's interpreters.
+    #
+    # Sandbox.build(config) returns the active backend based on
+    # config.sandbox_runtime (:auto by default): on Linux it prefers bubblewrap,
+    # on macOS sandbox-exec, falling back to Docker, then to a Null backend that
+    # reports unavailability cleanly.
+    module Sandbox
+      class Unavailable < StandardError; end
+
+      module_function
+
+      def host_os
+        RbConfig::CONFIG["host_os"].to_s
+      end
+
+      def linux?
+        host_os.include?("linux")
+      end
+
+      def macos?
+        host_os =~ /darwin|mac os/ ? true : false
+      end
+
+      def build(config)
+        case config.sandbox_runtime
+        when :docker       then Docker.new(config)
+        when :bubblewrap   then Bubblewrap.new(config)
+        when :sandbox_exec then SandboxExec.new(config)
+        when :none         then Null.new(config)
+        else detect(config)
+        end
+      end
+
+      # :auto — first available backend, preferring the native lightweight
+      # sandbox for the platform, then Docker.
+      def detect(config)
+        candidates =
+          if macos?
+            [SandboxExec, Docker]
+          elsif linux?
+            [Bubblewrap, Docker]
+          else
+            [Docker]
+          end
+
+        candidates.each do |klass|
+          backend = klass.new(config)
+          return backend if backend.available?
+        end
+        Null.new(config)
+      end
+
+      # Shared behavior for every backend.
+      class Base
+        def initialize(config)
+          @config = config
+        end
+
+        attr_reader :config
+
+        def name
+          self.class.name.split("::").last.downcase
+        end
+
+        def available?
+          false
+        end
+
+        def run(_argv, stdin: nil, image: nil)
+          raise NotImplementedError
+        end
+
+        def command(_argv, image: nil)
+          raise NotImplementedError
+        end
+
+        private
+
+        # A minimal, non-secret environment for host-process sandboxes: enough
+        # for interpreters to resolve and behave, without leaking the operator's
+        # whole environment to model-generated code.
+        def sandbox_env
+          {
+            "PATH" => ENV["PATH"],
+            "HOME" => "/tmp",
+            "TMPDIR" => "/tmp",
+            "LANG" => ENV["LANG"],
+            "LC_ALL" => ENV["LC_ALL"]
+          }.compact
+        end
+
+        # Resource caps applied via Process.spawn rlimits (inherited by the
+        # sandboxed child). Used by the host-process backends, since they can't
+        # rely on Docker's --memory/--cpus. Address space from sandbox_memory,
+        # CPU seconds from the command timeout plus a small grace.
+        def spawn_rlimits
+          limits = {}
+          bytes = parse_memory_bytes(config.sandbox_memory)
+          limits[:rlimit_as] = bytes if bytes
+          limits[:rlimit_cpu] = config.command_timeout.to_i + 2 if config.command_timeout
+          limits
+        end
+
+        def parse_memory_bytes(value)
+          str = value.to_s.strip.downcase
+          return nil if str.empty?
+
+          if (m = str.match(/\A(\d+)\s*([kmg])?b?\z/))
+            n = m[1].to_i
+            case m[2]
+            when "k" then n * 1024
+            when "m" then n * 1024 * 1024
+            when "g" then n * 1024 * 1024 * 1024
+            else n
+            end
+          end
+        end
+      end
+
+      # Used when no sandbox runtime is available; keeps the error path uniform.
+      class Null < Base
+        def available?
+          false
+        end
+
+        def run(_argv, stdin: nil, image: nil)
+          raise Unavailable,
+                "no sandbox runtime available (need docker, or bubblewrap on Linux / sandbox-exec on macOS)"
+        end
+
+        def command(argv, image: nil)
+          Array(argv)
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/toolbox/sandbox/bubblewrap.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "ruby_llm/toolbox/process_runner"
+require "ruby_llm/toolbox/sandbox/base"
+
+module RubyLLM
+  module Toolbox
+    module Sandbox
+      # Linux host-process sandbox via bubblewrap (bwrap). No daemon, no image:
+      # it runs the host's interpreters inside fresh namespaces. Isolation:
+      #
+      #   --unshare-all     new PID/IPC/UTS/cgroup/user/NET namespaces -> no network
+      #   --die-with-parent dies if the toolbox process is killed (enforces timeout)
+      #   --ro-bind / /     the host filesystem, read-only (so any interpreter
+      #                     path resolves) — nothing on the host can be written
+      #   --proc/--dev      fresh /proc and a minimal /dev
+      #   --tmpfs /tmp ...  the only writable space, in memory
+      #
+      # Memory/CPU caps are applied as rlimits (inherited by the child), since
+      # bwrap doesn't do cgroup limits itself.
+      #
+      # Note: unlike Docker, the host filesystem is *readable* (read-only) inside
+      # the sandbox. For read-confidentiality on a host with secrets, prefer
+      # Docker, or add masks (e.g. "--tmpfs", "/home") via config.sandbox_bwrap_extra.
+      class Bubblewrap < Base
+        def available?
+          return false unless Sandbox.linux?
+
+          system("bwrap", "--version", out: File::NULL, err: File::NULL)
+        rescue StandardError
+          false
+        end
+
+        def run(command_argv, stdin: nil, image: nil)
+          raise Unavailable, "bubblewrap (bwrap) is not available on this Linux host" unless available?
+
+          ProcessRunner.capture(
+            command(command_argv, image: image),
+            env: sandbox_env,
+            stdin: stdin,
+            timeout: config.command_timeout,
+            unsetenv_others: true,
+            rlimits: spawn_rlimits
+          )
+        end
+
+        def command(command_argv, image: nil)
+          [
+            "bwrap",
+            "--unshare-all",
+            "--die-with-parent",
+            "--new-session",
+            "--ro-bind", "/", "/",
+            "--proc", "/proc",
+            "--dev", "/dev",
+            "--tmpfs", "/tmp",
+            "--tmpfs", "/run",
+            "--tmpfs", "/dev/shm",
+            "--chdir", "/tmp",
+            *Array(config.sandbox_bwrap_extra),
+            "--",
+            *command_argv
+          ]
+        end
+
+        Unavailable = Sandbox::Unavailable
+      end
+    end
+  end
+end

data/lib/ruby_llm/toolbox/sandbox/docker.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "ruby_llm/toolbox/process_runner"
+require "ruby_llm/toolbox/sandbox/base"
+
+module RubyLLM
+  module Toolbox
+    module Sandbox
+      # Runs a command inside a hardened, ephemeral Docker container. The host
+      # docker client runs with the normal environment (so DOCKER_HOST etc. are
+      # honored); all isolation is applied to the container:
+      #
+      #   --rm                      ephemeral, removed on exit
+      #   --network none            no network by default
+      #   --read-only + tmpfs /tmp  immutable root, scratch space only in tmpfs
+      #   --cap-drop ALL            no Linux capabilities
+      #   --security-opt no-new-privileges
+      #   --user <uid:gid>          non-root
+      #   --memory/--cpus/--pids-limit   resource caps
+      #
+      # The program is array-form (no shell). Source is fed on stdin, so nothing
+      # from the host filesystem is mounted into the container. Unlike the
+      # host-process backends, the container only sees its image — not the host.
+      class Docker < Base
+        # Kept for backwards compatibility; the canonical error is
+        # Sandbox::Unavailable.
+        Unavailable = Sandbox::Unavailable
+
+        def available?
+          system("docker", "version", out: File::NULL, err: File::NULL)
+        rescue StandardError
+          false
+        end
+
+        def run(command_argv, stdin: nil, image: nil)
+          raise Unavailable, "docker was not found or is not running on the host" unless available?
+
+          ProcessRunner.capture(
+            command(command_argv, image: image),
+            stdin: stdin,
+            timeout: config.command_timeout,
+            unsetenv_others: false # the docker *client* needs the host env
+          )
+        end
+
+        # Exposed so the exact isolation flags can be asserted in tests.
+        def command(command_argv, image: nil)
+          [
+            "docker", "run", "--rm", "-i",
+            "--network", config.sandbox_network,
+            "--memory", config.sandbox_memory,
+            "--cpus", config.sandbox_cpus.to_s,
+            "--pids-limit", config.sandbox_pids.to_s,
+            "--read-only",
+            "--tmpfs", "/tmp:rw,size=64m",
+            "--cap-drop", "ALL",
+            "--security-opt", "no-new-privileges",
+            "--user", config.sandbox_user,
+            image || config.docker_image,
+            *command_argv
+          ]
+        end
+
+        # Backwards-compatible alias.
+        alias docker_argv command
+      end
+    end
+  end
+end

data/lib/ruby_llm/toolbox/sandbox/sandbox_exec.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "ruby_llm/toolbox/process_runner"
+require "ruby_llm/toolbox/sandbox/base"
+
+module RubyLLM
+  module Toolbox
+    module Sandbox
+      # macOS host-process sandbox via sandbox-exec (Seatbelt). No daemon, no
+      # image: it runs the host's interpreters under a Seatbelt profile that
+      # denies by default, blocks all network, allows reading the system, and
+      # permits writes only to temp directories. Memory/CPU caps are applied as
+      # rlimits.
+      #
+      # sandbox-exec is deprecated by Apple but remains present and functional on
+      # current macOS. As with bubblewrap, the filesystem is readable (read-only
+      # for writes) inside the sandbox; use Docker for full read-confidentiality.
+      class SandboxExec < Base
+        BINARY = "/usr/bin/sandbox-exec"
+
+        DEFAULT_PROFILE = <<~SBPL
+          (version 1)
+          (deny default)
+          (allow process-fork)
+          (allow process-exec)
+          (allow signal (target self))
+          (allow sysctl-read)
+          (allow mach-lookup)
+          (allow file-read*)
+          (allow file-write*
+            (subpath "/tmp")
+            (subpath "/private/tmp")
+            (subpath "/private/var/tmp")
+            (subpath "/private/var/folders")
+            (literal "/dev/null")
+            (literal "/dev/zero")
+            (literal "/dev/random")
+            (literal "/dev/urandom")
+            (literal "/dev/dtracehelper"))
+          (deny network*)
+        SBPL
+
+        def available?
+          return false unless Sandbox.macos?
+
+          File.executable?(BINARY)
+        end
+
+        def run(command_argv, stdin: nil, image: nil)
+          raise Unavailable, "sandbox-exec is not available on this host" unless available?
+
+          ProcessRunner.capture(
+            command(command_argv, image: image),
+            env: sandbox_env,
+            stdin: stdin,
+            timeout: config.command_timeout,
+            unsetenv_others: true,
+            rlimits: spawn_rlimits
+          )
+        end
+
+        def command(command_argv, image: nil)
+          ["sandbox-exec", "-p", profile, *command_argv]
+        end
+
+        def profile
+          prof = config.sandbox_seatbelt_profile
+          prof && !prof.to_s.strip.empty? ? prof.to_s : DEFAULT_PROFILE
+        end
+
+        Unavailable = Sandbox::Unavailable
+      end
+    end
+  end
+end

data/lib/ruby_llm/toolbox/search/brave.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+require "ruby_llm/toolbox/search/tavily"
+
+module RubyLLM
+  module Toolbox
+    module Search
+      # Brave Search API adapter — a commercial drop-in alternative to Tavily.
+      # Auth is a subscription token sent in the X-Subscribe-Token header. The
+      # basic plan has no synthesized answer, so #search returns answer: nil and
+      # a list of web results.
+      #
+      # Select it with config.search_adapter = :brave and config.brave_api_key.
+      class Brave
+        ENDPOINT = "https://api.search.brave.com/res/v1/web/search"
+
+        def initialize(api_key:, user_agent: nil, timeout: 10)
+          @api_key = api_key
+          @user_agent = user_agent
+          @timeout = timeout
+        end
+
+        def search(query, max_results: 5)
+          raise Error, "missing Brave API key" if @api_key.nil? || @api_key.to_s.empty?
+
+          # Brave caps count at 20; keep within the tool's own 1..10 range anyway.
+          count = max_results.clamp(1, 20)
+          data = get_json(ENDPOINT, q: query, count: count)
+
+          results = Array(data.dig("web", "results")).map do |r|
+            { title: r["title"], url: r["url"], content: r["description"] }
+          end
+          { answer: nil, results: results }
+        end
+
+        # Seam for tests.
+        def get_json(url, params)
+          uri = URI.parse(url)
+          uri.query = URI.encode_www_form(params)
+          request = Net::HTTP::Get.new(uri)
+          request["Accept"] = "application/json"
+          request["X-Subscribe-Token"] = @api_key
+          request["User-Agent"] = @user_agent if @user_agent
+
+          response = Net::HTTP.start(uri.host, uri.port, use_ssl: true,
+                                     open_timeout: @timeout, read_timeout: @timeout) do |http|
+            http.request(request)
+          end
+
+          raise Error, "Brave returned HTTP #{response.code}" unless response.is_a?(Net::HTTPSuccess)
+
+          JSON.parse(response.body)
+        rescue JSON::ParserError => e
+          raise Error, "invalid JSON from Brave (#{e.message})"
+        rescue SocketError, Net::OpenTimeout, Net::ReadTimeout => e
+          raise Error, e.message
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/toolbox/search/searxng.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+require "ruby_llm/toolbox/search/tavily"
+
+module RubyLLM
+  module Toolbox
+    module Search
+      # SearXNG adapter — a self-hosted, keyless metasearch alternative. Point it
+      # at your own instance with config.searxng_url; no API key or third-party
+      # account is involved, which is the whole appeal. SearXNG's JSON response
+      # often carries instant "answers", which are surfaced as the answer field.
+      #
+      # Select it with config.search_adapter = :searxng and config.searxng_url.
+      #
+      # The base URL is operator-configured infrastructure (frequently on a
+      # private network), so it is deliberately NOT run through the SSRF guard:
+      # reaching an internal SearXNG host is the intended behavior, not an attack.
+      class SearXNG
+        def initialize(base_url:, user_agent: nil, timeout: 10)
+          @base_url = base_url.to_s.sub(%r{/+\z}, "")
+          @user_agent = user_agent
+          @timeout = timeout
+        end
+
+        def search(query, max_results: 5)
+          raise Error, "missing SearXNG URL (set config.searxng_url)" if @base_url.empty?
+
+          data = get_json("#{@base_url}/search", q: query, format: "json")
+
+          results = Array(data["results"]).first(max_results).map do |r|
+            { title: r["title"], url: r["url"], content: r["content"] }
+          end
+          answer = Array(data["answers"]).map(&:to_s).reject(&:empty?).join(" ")
+          { answer: (answer.empty? ? nil : answer), results: results }
+        end
+
+        # Seam for tests.
+        def get_json(url, params)
+          uri = URI.parse(url)
+          uri.query = URI.encode_www_form(params)
+          request = Net::HTTP::Get.new(uri)
+          request["Accept"] = "application/json"
+          request["User-Agent"] = @user_agent if @user_agent
+
+          response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https",
+                                     open_timeout: @timeout, read_timeout: @timeout) do |http|
+            http.request(request)
+          end
+
+          raise Error, "SearXNG returned HTTP #{response.code}" unless response.is_a?(Net::HTTPSuccess)
+
+          JSON.parse(response.body)
+        rescue JSON::ParserError => e
+          raise Error, "invalid JSON from SearXNG (#{e.message}) — is format=json enabled on the instance?"
+        rescue SocketError, Net::OpenTimeout, Net::ReadTimeout => e
+          raise Error, e.message
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/toolbox/search/tavily.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module RubyLLM
+  module Toolbox
+    module Search
+      # Base error for any search adapter, so the web_search tool can rescue one
+      # type regardless of backend.
+      class Error < StandardError; end
+
+      # Default web_search backend. Tavily is built for agent use: one call
+      # returns cleaned result content and an optional synthesized answer. Swap
+      # in another adapter via config.search_adapter (anything responding to
+      # #search(query, max_results:) and returning { answer:, results: }).
+      class Tavily
+        ENDPOINT = "https://api.tavily.com/search"
+
+        def initialize(api_key:, user_agent: nil, timeout: 10)
+          @api_key = api_key
+          @user_agent = user_agent
+          @timeout = timeout
+        end
+
+        def search(query, max_results: 5)
+          raise Error, "missing Tavily API key" if @api_key.nil? || @api_key.to_s.empty?
+
+          data = post_json(ENDPOINT, {
+                             api_key: @api_key,
+                             query: query,
+                             max_results: max_results,
+                             include_answer: true
+                           })
+
+          {
+            answer: data["answer"],
+            results: Array(data["results"]).map do |r|
+              { title: r["title"], url: r["url"], content: r["content"] }
+            end
+          }
+        end
+
+        # Seam for tests.
+        def post_json(url, payload)
+          uri = URI.parse(url)
+          request = Net::HTTP::Post.new(uri)
+          request["Content-Type"] = "application/json"
+          request["Accept"] = "application/json"
+          request["User-Agent"] = @user_agent if @user_agent
+          request.body = JSON.generate(payload)
+
+          response = Net::HTTP.start(uri.host, uri.port, use_ssl: true,
+                                     open_timeout: @timeout, read_timeout: @timeout) do |http|
+            http.request(request)
+          end
+
+          raise Error, "Tavily returned HTTP #{response.code}" unless response.is_a?(Net::HTTPSuccess)
+
+          JSON.parse(response.body)
+        rescue JSON::ParserError => e
+          raise Error, "invalid JSON from Tavily (#{e.message})"
+        rescue SocketError, Net::OpenTimeout, Net::ReadTimeout => e
+          raise Error, e.message
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/toolbox/text_diff.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Toolbox
+    # Line-based diff via longest-common-subsequence. Produces a readable diff
+    # ('-'/'+'/' ' prefixes) with long unchanged runs elided. Pure stdlib.
+    module TextDiff
+      module_function
+
+      def unified(old_text, new_text, old_label: "old", new_label: "new", context: 3)
+        a = old_text.to_s.lines
+        b = new_text.to_s.lines
+        ops = diff_ops(a, b)
+        return "(no differences)" if ops.all? { |type, _| type == :eq }
+
+        render(ops, old_label, new_label, context)
+      end
+
+      def diff_ops(a, b)
+        n = a.size
+        m = b.size
+        lcs = Array.new(n + 1) { Array.new(m + 1, 0) }
+        (n - 1).downto(0) do |i|
+          (m - 1).downto(0) do |j|
+            lcs[i][j] = a[i] == b[j] ? lcs[i + 1][j + 1] + 1 : [lcs[i + 1][j], lcs[i][j + 1]].max
+          end
+        end
+
+        ops = []
+        i = 0
+        j = 0
+        while i < n && j < m
+          if a[i] == b[j]
+            ops << [:eq, a[i]]
+            i += 1
+            j += 1
+          elsif lcs[i + 1][j] >= lcs[i][j + 1]
+            ops << [:del, a[i]]
+            i += 1
+          else
+            ops << [:add, b[j]]
+            j += 1
+          end
+        end
+        ops.concat(a[i..].map { |line| [:del, line] }) if i < n
+        ops.concat(b[j..].map { |line| [:add, line] }) if j < m
+        ops
+      end
+
+      def render(ops, old_label, new_label, context)
+        out = ["--- #{old_label}", "+++ #{new_label}"]
+        i = 0
+        while i < ops.size
+          type, line = ops[i]
+          if type == :eq
+            run = []
+            while i < ops.size && ops[i][0] == :eq
+              run << ops[i][1]
+              i += 1
+            end
+            emit_context(out, run, context)
+          else
+            out << "#{type == :del ? '-' : '+'} #{line.chomp}"
+            i += 1
+          end
+        end
+        out.join("\n")
+      end
+
+      def emit_context(out, run, context)
+        if run.size > (context * 2) + 1
+          run.first(context).each { |line| out << "  #{line.chomp}" }
+          out << "  ⋮ (#{run.size - (context * 2)} unchanged lines)"
+          run.last(context).each { |line| out << "  #{line.chomp}" }
+        else
+          run.each { |line| out << "  #{line.chomp}" }
+        end
+      end
+    end
+  end
+end