ruby_llm-toolbox 0.1.0

data/lib/ruby_llm/toolbox/toml.rb

@@ -0,0 +1,409 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Toolbox
+    # A small, dependency-free TOML parser. Covers the common surface of TOML
+    # 1.0 used by real config files: comments; bare/quoted/dotted keys;
+    # [tables] and [[arrays of tables]]; basic/literal strings and their
+    # multiline forms; integers (with underscores and 0x/0o/0b), floats
+    # (exponents, inf, nan), booleans; offset/local date-times, dates and times
+    # (kept as strings); arrays (multiline, nested, heterogeneous); and inline
+    # tables. Returns nested Hashes/Arrays with string keys, ready for JSON
+    # output or DataPath navigation.
+    module Toml
+      class ParseError < StandardError; end
+
+      module_function
+
+      def parse(text)
+        Parser.new(text).parse
+      end
+
+      # Recursive-descent parser over a character cursor.
+      class Parser
+        DATETIME = /\A(\d{4}-\d{2}-\d{2}([Tt ]\d{2}:\d{2}:\d{2}(\.\d+)?([Zz]|[+-]\d{2}:\d{2})?)?|\d{2}:\d{2}:\d{2}(\.\d+)?)/
+
+        def initialize(source)
+          @s = source.to_s
+          @i = 0
+          @len = @s.length
+          @root = {}
+        end
+
+        def parse
+          @current = @root
+          loop do
+            skip_blank
+            break if eof?
+
+            if peek == "["
+              parse_table_header
+            else
+              key = parse_key
+              skip_inline_ws
+              expect("=")
+              value = parse_value
+              assign(@current, key, value)
+              expect_line_end
+            end
+          end
+          @root
+        end
+
+        private
+
+        # --- table headers ------------------------------------------------
+        def parse_table_header
+          advance # [
+          array = false
+          if peek == "["
+            advance
+            array = true
+          end
+          skip_inline_ws
+          keys = parse_key
+          skip_inline_ws
+          expect("]")
+          expect("]") if array
+          expect_line_end
+
+          @current = array ? open_array_table(keys) : open_table(keys)
+        end
+
+        def open_table(keys)
+          node = @root
+          keys.each do |k|
+            node[k] = {} unless node.key?(k)
+            raise ParseError, "cannot redefine #{k.inspect} as a table" unless node[k].is_a?(Hash) || node[k].is_a?(Array)
+            node = node[k].is_a?(Array) ? node[k].last : node[k]
+          end
+          node
+        end
+
+        def open_array_table(keys)
+          node = @root
+          keys[0..-2].each do |k|
+            node[k] = {} unless node.key?(k)
+            raise ParseError, "cannot redefine #{k.inspect} as a table" unless node[k].is_a?(Hash) || node[k].is_a?(Array)
+            node = node[k].is_a?(Array) ? node[k].last : node[k]
+          end
+          last = keys[-1]
+          node[last] ||= []
+          raise ParseError, "key #{last.inspect} is not an array of tables" unless node[last].is_a?(Array)
+
+          fresh = {}
+          node[last] << fresh
+          fresh
+        end
+
+        # --- keys ---------------------------------------------------------
+        def parse_key
+          parts = []
+          loop do
+            skip_inline_ws
+            parts << parse_key_segment
+            skip_inline_ws
+            break unless peek == "."
+
+            advance
+          end
+          parts
+        end
+
+        def parse_key_segment
+          case peek
+          when '"' then parse_basic_string
+          when "'" then parse_literal_string
+          else
+            start = @i
+            advance while !eof? && peek.match?(/[A-Za-z0-9_-]/)
+            raise ParseError, "empty key near position #{@i}" if @i == start
+
+            @s[start...@i]
+          end
+        end
+
+        def assign(table, keys, value)
+          node = table
+          keys[0..-2].each do |k|
+            node[k] = {} unless node.key?(k)
+            raise ParseError, "cannot redefine #{k.inspect} as a table" unless node[k].is_a?(Hash)
+            node = node[k]
+          end
+          node[keys[-1]] = value
+        end
+
+        # --- values -------------------------------------------------------
+        def parse_value
+          skip_inline_ws
+          case peek
+          when '"', "'" then parse_string
+          when "[" then parse_array
+          when "{" then parse_inline_table
+          else parse_atom
+          end
+        end
+
+        def parse_atom
+          rest = @s[@i..]
+          if (m = rest.match(DATETIME))
+            @i += m[0].length
+            return m[0]
+          end
+          if rest.start_with?("true")
+            @i += 4
+            return true
+          end
+          if rest.start_with?("false")
+            @i += 5
+            return false
+          end
+          parse_number
+        end
+
+        def parse_number
+          start = @i
+          advance while !eof? && !peek.match?(/[\s,\]}#]/)
+          token = @s[start...@i]
+          raise ParseError, "expected a value near position #{start}" if token.empty?
+
+          classify_number(token)
+        end
+
+        def classify_number(token)
+          t = token.gsub("_", "")
+          return Float::INFINITY if %w[inf +inf].include?(t)
+          return -Float::INFINITY if t == "-inf"
+          return Float::NAN if %w[nan +nan -nan].include?(t)
+
+          if (m = t.match(/\A[+-]?0(x|o|b)(.+)\z/))
+            base = { "x" => 16, "o" => 8, "b" => 2 }[m[1]]
+            return Integer(m[2], base)
+          end
+          return Float(t) if t.match?(/[.eE]/) && !t.match?(/\A[+-]?0x/i)
+
+          Integer(t, 10)
+        rescue ArgumentError
+          raise ParseError, "invalid number: #{token.inspect}"
+        end
+
+        # --- strings ------------------------------------------------------
+        def parse_string
+          if @s[@i, 3] == '"""'
+            parse_multiline_basic
+          elsif @s[@i, 3] == "'''"
+            parse_multiline_literal
+          elsif peek == '"'
+            parse_basic_string
+          else
+            parse_literal_string
+          end
+        end
+
+        def parse_basic_string
+          advance # opening "
+          out = +""
+          until eof?
+            c = peek
+            raise ParseError, "unterminated string" if c == "\n"
+
+            if c == '"'
+              advance
+              return out
+            elsif c == "\\"
+              advance
+              out << read_escape
+            else
+              out << c
+              advance
+            end
+          end
+          raise ParseError, "unterminated string"
+        end
+
+        def parse_literal_string
+          advance # opening '
+          start = @i
+          advance while !eof? && peek != "'" && peek != "\n"
+          raise ParseError, "unterminated literal string" if eof? || peek == "\n"
+
+          str = @s[start...@i]
+          advance # closing '
+          str
+        end
+
+        def parse_multiline_basic
+          @i += 3
+          @i += 1 if peek == "\n"
+          out = +""
+          until eof?
+            if @s[@i, 3] == '"""'
+              @i += 3
+              return out
+            elsif peek == "\\" && @s[@i + 1..].match?(/\A[ \t]*\r?\n/)
+              @i += 1
+              @i += 1 while !eof? && peek.match?(/[\s]/)
+            elsif peek == "\\"
+              advance
+              out << read_escape
+            else
+              out << peek
+              advance
+            end
+          end
+          raise ParseError, "unterminated multiline string"
+        end
+
+        def parse_multiline_literal
+          @i += 3
+          @i += 1 if peek == "\n"
+          start = @i
+          until eof?
+            if @s[@i, 3] == "'''"
+              str = @s[start...@i]
+              @i += 3
+              return str
+            end
+            advance
+          end
+          raise ParseError, "unterminated multiline literal string"
+        end
+
+        def read_escape
+          c = peek
+          advance
+          case c
+          when "n" then "\n"
+          when "t" then "\t"
+          when "r" then "\r"
+          when "b" then "\b"
+          when "f" then "\f"
+          when '"' then '"'
+          when "\\" then "\\"
+          when "u" then read_unicode(4)
+          when "U" then read_unicode(8)
+          else raise ParseError, "invalid escape: \\#{c}"
+          end
+        end
+
+        def read_unicode(width)
+          hex = @s[@i, width]
+          raise ParseError, "invalid unicode escape" unless hex && hex.match?(/\A[0-9A-Fa-f]{#{width}}\z/)
+
+          @i += width
+          [hex.to_i(16)].pack("U")
+        end
+
+        # --- arrays & inline tables --------------------------------------
+        def parse_array
+          advance # [
+          arr = []
+          loop do
+            skip_ws_comments
+            break if eof?
+
+            if peek == "]"
+              advance
+              return arr
+            end
+            arr << parse_value
+            skip_ws_comments
+            if peek == ","
+              advance
+            elsif peek == "]"
+              advance
+              return arr
+            else
+              raise ParseError, "expected ',' or ']' in array near position #{@i}"
+            end
+          end
+          raise ParseError, "unterminated array"
+        end
+
+        def parse_inline_table
+          advance # {
+          table = {}
+          skip_ws_comments
+          if peek == "}"
+            advance
+            return table
+          end
+          loop do
+            skip_ws_comments
+            key = parse_key
+            skip_inline_ws
+            expect("=")
+            assign(table, key, parse_value)
+            skip_ws_comments
+            if peek == ","
+              advance
+            elsif peek == "}"
+              advance
+              return table
+            else
+              raise ParseError, "expected ',' or '}' in inline table near position #{@i}"
+            end
+          end
+        end
+
+        # --- cursor helpers ----------------------------------------------
+        def peek
+          @s[@i]
+        end
+
+        def advance
+          @i += 1
+        end
+
+        def eof?
+          @i >= @len
+        end
+
+        def expect(char)
+          raise ParseError, "expected #{char.inspect} near position #{@i}, got #{peek.inspect}" unless peek == char
+
+          advance
+        end
+
+        def skip_inline_ws
+          advance while !eof? && (peek == " " || peek == "\t")
+        end
+
+        # Between top-level statements: whitespace, newlines and comment lines.
+        def skip_blank
+          loop do
+            if !eof? && peek.match?(/[ \t\r\n]/)
+              advance
+            elsif peek == "#"
+              advance while !eof? && peek != "\n"
+            else
+              break
+            end
+          end
+        end
+
+        # Inside arrays/inline tables: whitespace, newlines and comments.
+        def skip_ws_comments
+          skip_blank
+        end
+
+        # After a key/value or header: optional comment, then newline or EOF.
+        def expect_line_end
+          skip_inline_ws
+          if peek == "#"
+            advance while !eof? && peek != "\n"
+          end
+          return if eof?
+          if peek == "\r"
+            advance
+          end
+          if peek == "\n"
+            advance
+          elsif !eof?
+            raise ParseError, "expected end of line near position #{@i}, got #{peek.inspect}"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require "ruby_llm/toolbox/base"
+require "ruby_llm/toolbox/tools/git_helpers"
+
+module RubyLLM
+  module Toolbox
+    module Tools
+      # EXEC. Applies a unified diff to files in fs_root using `git apply`.
+      # Complements edit_file when a model wants to emit a whole multi-hunk
+      # patch. The patch is validated with `git apply --check` before anything
+      # is written. Patch paths are also checked against PathJail so a patch
+      # cannot escape fs_root even when fs_root is a subdirectory of a git repo.
+      # Works with or without a git repository.
+      class ApplyPatch < Base
+        include GitHelpers
+        exec_tool!
+
+        description "Apply a unified diff to files in fs_root (as produced by `git diff` / `diff -u`). " \
+                    "Validates the patch first and reports the affected files; nothing is written if it " \
+                    "would not apply cleanly. Set check: true for a dry run only."
+
+        param :patch, type: "string",
+                      desc: "The unified diff text to apply.",
+                      required: true
+        param :check, type: "boolean",
+                     desc: "Validate only (dry run); do not write changes. Default false.",
+                     required: false
+
+        def execute(patch:, check: false)
+          diff = patch.to_s
+          diff += "\n" unless diff.end_with?("\n")
+          return error("patch is empty", code: :empty_patch) if diff.strip.empty?
+
+          validate_patch_paths!(diff)
+
+          verify = run_git("apply", "--check", stdin: diff)
+          unless succeeded?(verify)
+            return error("patch does not apply cleanly: #{message(verify)}", code: :patch_failed)
+          end
+
+          files = changed_files(diff)
+          return "Patch applies cleanly (dry run). Affected files: #{files.join(', ')}" if check
+
+          result = run_git("apply", stdin: diff)
+          return error("apply failed: #{message(result)}", code: :patch_failed) unless succeeded?(result)
+
+          "Applied patch to #{files.size} file#{files.size == 1 ? '' : 's'}: #{files.join(', ')}"
+        rescue Safety::PathJail::Jailbreak => e
+          error("patch path escapes fs_root: #{e.message}", code: :patch_failed)
+        rescue Errno::ENOENT
+          error("git is not available on the host", code: :unavailable)
+        end
+
+        private
+
+        def succeeded?((_out, _err, status))
+          status != :timeout && status.exitstatus&.zero?
+        end
+
+        def validate_patch_paths!(diff)
+          jail = path_jail
+          diff.each_line do |line|
+            if line.start_with?("+++ ")
+              path = line[4..].chomp.sub(/\Ab\//, "")
+              next if path.empty? || path == "/dev/null"
+              jail.resolve(path)
+            elsif line.start_with?("--- ")
+              path = line[4..].chomp.sub(/\Aa\//, "")
+              next if path.empty? || path == "/dev/null"
+              jail.resolve(path)
+            end
+          end
+        end
+
+        def message((out, err, status))
+          return "timed out after #{config.command_timeout}s" if status == :timeout
+
+          (err.to_s.empty? ? out.to_s : err.to_s).strip
+        end
+
+        def changed_files(diff)
+          out, = run_git("apply", "--numstat", stdin: diff)
+          out.to_s.each_line.filter_map do |line|
+            parts = line.strip.split("\t")
+            parts.last if parts.size >= 3
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "ruby_llm/toolbox/base"
+require "ruby_llm/toolbox/process_runner"
+require "ruby_llm/toolbox/safety/command_guard"
+
+module RubyLLM
+  module Toolbox
+    module Tools
+      # EXEC reference tool. Runs ONE allowlisted executable with arguments.
+      #
+      # Deliberately NOT a shell: there are no pipes, redirects, globs, quoting,
+      # or variable expansion. The program goes in `command`; each argument is a
+      # separate element of `args` and is passed verbatim as argv. This is the
+      # safe primitive that the OS-command-injection class of bug cannot touch,
+      # because no shell ever parses the input.
+      #
+      # Gated: refuses to run unless config.enable_exec_tools is true AND the
+      # executable is on config.allowed_commands.
+      class BashTool < Base
+        exec_tool!
+
+        description "Run a single ALLOWLISTED executable with arguments. " \
+                    "No shell is involved: no pipes, redirects, globs, or variable expansion. " \
+                    "Put the program name in `command` and each argument as its own element of `args`."
+
+        param :command, type: "string",
+                        desc: "Executable name (must be on the allowlist). No path, no shell characters.",
+                        required: true
+        param :args, type: "array",
+                     desc: "Arguments passed verbatim to the program, one per element. Optional.",
+                     required: false
+        param :unsafe, type: "boolean",
+                       desc: "Request bypassing the command allowlist (still no shell; argv only). " \
+                             "Only takes effect if an operator enabled allow_unsafe; otherwise refused. " \
+                             "Default false.",
+                       required: false
+
+        def execute(command:, args: nil, unsafe: false)
+          exe  = resolve_command(command, unsafe)
+          argv = sanitize_args(args)
+
+          out, err, status = ProcessRunner.capture(
+            [exe, *argv],
+            env: clean_env,
+            timeout: config.command_timeout,
+            unsetenv_others: true
+          )
+          truncate(format_result(exe, argv, out, err, status))
+        rescue Safety::CommandGuard::Blocked => e
+          error(e.message, code: :command_denied)
+        end
+
+        private
+
+        # With an operator-permitted unsafe override, skip the allowlist (the
+        # program may even be an absolute path) but keep the invariants that make
+        # this not-a-shell: no NUL bytes, argv form only, never a shell string.
+        def resolve_command(command, unsafe)
+          return Safety::CommandGuard.new(config.allowed_commands).check!(command) unless permit_unsafe!(unsafe, command)
+
+          cmd = command.to_s
+          raise Safety::CommandGuard::Blocked, "command is empty" if cmd.strip.empty?
+          raise Safety::CommandGuard::Blocked, "command contains a NUL byte" if cmd.include?("\u0000")
+
+          cmd
+        end
+
+        def sanitize_args(args)
+          Array(args).map do |arg|
+            str = arg.to_s
+            if str.include?("\u0000")
+              raise Safety::CommandGuard::Blocked, "argument contains a NUL byte"
+            end
+
+            str
+          end
+        end
+
+        def clean_env
+          config.env_passthrough.each_with_object({}) do |key, env|
+            value = ENV[key]
+            env[key] = value unless value.nil?
+          end
+        end
+
+        def format_result(exe, argv, out, err, status)
+          body = +"argv: #{([exe] + argv).inspect}\n"
+          body << if status == :timeout
+                    "result: timed out after #{config.command_timeout}s (killed)\n"
+                  else
+                    "exit: #{status.exitstatus}\n"
+                  end
+          body << "\n--- stdout ---\n#{out}" unless out.empty?
+          body << "\n--- stderr ---\n#{err}" unless err.empty?
+          body
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "ruby_llm/toolbox/base"
+require "ruby_llm/toolbox/tools/toolchain_helpers"
+
+module RubyLLM
+  module Toolbox
+    module Tools
+      # EXEC. Runs Bundler operations in the project at fs_root. The mutating
+      # sibling of the read-only `gem` tool. install/update/add reach the network
+      # and change the project's gems, so this is exec-gated.
+      class Bundle < Base
+        include ToolchainHelpers
+        exec_tool!
+
+        description "Run Bundler in the project at fs_root. Actions: install, update, outdated, check, " \
+                    "lock, add. For 'add' provide a gem name; for 'update' a gem name is optional " \
+                    "(omit to update all). Requires a Gemfile."
+
+        ACTIONS = %w[install update outdated check lock add].freeze
+        NAME_RE = /\A[A-Za-z0-9_.-]+\z/
+
+        param :action, type: "string",
+                       desc: "One of: install, update, outdated, check, lock, add.",
+                       required: true
+        param :gem, type: "string",
+                    desc: "Gem name — required for 'add', optional for 'update'.",
+                    required: false
+
+        def execute(action:, gem: nil)
+          act = action.to_s.strip.downcase
+          return error("unknown action: #{act} (use #{ACTIONS.join(', ')})", code: :bad_action) unless ACTIONS.include?(act)
+          return error("a Gemfile is required (none at fs_root)", code: :no_gemfile) unless gemfile?
+
+          args = build_args(act, gem)
+          return args if args.is_a?(Hash) # validation error
+
+          out, err, status = run_in_project(args, use_bundle: false)
+          toolchain_output(out, err, status,
+                           pass_label: "bundle #{act}: ok",
+                           fail_label: "bundle #{act}: failed")
+        rescue CommandMissing
+          error("bundler is not available (gem install bundler)", code: :unavailable)
+        end
+
+        private
+
+        def build_args(act, gem_name)
+          case act
+          when "add"
+            name = gem_name.to_s.strip
+            return error("'add' requires a valid gem name", code: :bad_name) unless name.match?(NAME_RE)
+
+            ["bundle", "add", name]
+          when "update"
+            name = gem_name.to_s.strip
+            if name.empty?
+              ["bundle", "update"]
+            else
+              return error("invalid gem name: #{name.inspect}", code: :bad_name) unless name.match?(NAME_RE)
+
+              ["bundle", "update", name]
+            end
+          else
+            ["bundle", act]
+          end
+        end
+      end
+    end
+  end
+end