ruby_llm-toolbox 0.1.0

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

@@ -0,0 +1,54 @@
+# 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. Moves or renames a file or directory within fs_root. BOTH the
+      # source and destination are confined to the jail, so nothing can be moved
+      # in from or out to outside the root. Refuses to clobber an existing
+      # destination unless overwrite is set.
+      class MoveFile < Base
+        exec_tool!
+
+        description "Move or rename a file or directory within fs_root. Both source and destination " \
+                    "must be inside the jail. Missing parent directories of the destination are " \
+                    "created. Will not overwrite an existing destination unless overwrite is true."
+
+        param :source, type: "string",
+                       desc: "Existing path to move, relative to fs_root.",
+                       required: true
+        param :destination, type: "string",
+                            desc: "Target path, relative to fs_root.",
+                            required: true
+        param :overwrite, type: "boolean",
+                         desc: "Replace the destination if it already exists. Default false.",
+                         required: false
+
+        def execute(source:, destination:, overwrite: false)
+          jail = Safety::PathJail.new(config.fs_root)
+          from = jail.resolve(source)
+          to   = jail.resolve(destination)
+
+          return error("source does not exist: #{source}", code: :not_found) unless File.exist?(from)
+          if File.directory?(to) && !File.directory?(from)
+            return error("destination is a directory: #{destination}", code: :is_a_directory)
+          end
+          if File.exist?(to) && !overwrite
+            return error("destination already exists: #{destination} (set overwrite to replace)",
+                         code: :exists)
+          end
+
+          FileUtils.mkdir_p(File.dirname(to))
+          FileUtils.mv(from, to, force: overwrite)
+          "Moved #{source} -> #{destination}"
+        rescue Safety::PathJail::Jailbreak => e
+          error(e.message, code: :path_denied)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require "ruby_llm/toolbox/base"
+require "ruby_llm/toolbox/safety/path_jail"
+
+module RubyLLM
+  module Toolbox
+    module Tools
+      # EXEC. Applies several string replacements to one file in a single,
+      # atomic operation. Edits are applied in order (a later edit sees the
+      # result of earlier ones), each following edit_file's rules: old_string
+      # must match exactly once unless replace_all is set. If any edit can't be
+      # applied, nothing is written and the failing edit is reported — so the
+      # file is never left half-edited.
+      class MultiEdit < Base
+        class BadEdit < StandardError; end
+
+        exec_tool!
+
+        description "Apply multiple find/replace edits to a single file atomically. Provide edits as an " \
+                    "array of objects with old_string, new_string, and optional replace_all. Edits run " \
+                    "in order; if any fails to apply cleanly, no changes are written."
+
+        MAX_BYTES = 10 * 1024 * 1024
+
+        param :path, type: "string",
+                     desc: "File to edit, relative to fs_root.",
+                     required: true
+        param :edits, type: "array",
+                      desc: "Array of edits, each an object: { old_string, new_string, replace_all? }. " \
+                            "Applied in order.",
+                      required: true
+
+        def execute(path:, edits:)
+          return error("edits must be a non-empty array", code: :bad_edits) unless edits.is_a?(Array) && !edits.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
+
+          original = File.read(real).scrub
+          content = original
+          total = 0
+
+          edits.each_with_index do |edit, i|
+            content, n = apply_edit(content, edit, i + 1, path)
+            total += n
+          end
+
+          File.write(real, content)
+          "Applied #{edits.size} edit#{edits.size == 1 ? '' : 's'} to #{path} " \
+            "(#{total} replacement#{total == 1 ? '' : 's'}, #{original.bytesize} -> #{content.bytesize} bytes)"
+        rescue Safety::PathJail::Jailbreak => e
+          error(e.message, code: :path_denied)
+        rescue BadEdit => e
+          error(e.message, code: :edit_failed)
+        end
+
+        private
+
+        def apply_edit(content, edit, index, path)
+          old_s = fetch(edit, "old_string").to_s
+          raise BadEdit, "edit #{index}: new_string is required" unless has_key?(edit, "new_string")
+
+          new_s = fetch(edit, "new_string").to_s
+          replace_all = [true, "true"].include?(fetch(edit, "replace_all"))
+
+          raise BadEdit, "edit #{index}: old_string must not be empty" if old_s.empty?
+          raise BadEdit, "edit #{index}: old_string and new_string are identical" if old_s == new_s
+
+          if replace_all
+            count = 0
+            updated = content.gsub(old_s) { count += 1; new_s }
+            raise BadEdit, "edit #{index}: old_string not found in #{path}" if count.zero?
+
+            [updated, count]
+          else
+            count = content.scan(Regexp.new(Regexp.escape(old_s))).size
+            raise BadEdit, "edit #{index}: old_string not found in #{path}" if count.zero?
+            if count > 1
+              raise BadEdit, "edit #{index}: old_string is ambiguous (#{count} matches in #{path}); " \
+                             "add surrounding context or set replace_all"
+            end
+
+            [content.sub(old_s) { new_s }, 1]
+          end
+        end
+
+        def indifferent_key(edit, key)
+          return nil unless edit.is_a?(Hash)
+          return key if edit.key?(key)
+          return key.to_sym if edit.key?(key.to_sym)
+        end
+
+        def fetch(edit, key)
+          k = indifferent_key(edit, key)
+          k ? edit[k] : nil
+        end
+
+        def has_key?(edit, key)
+          !indifferent_key(edit, key).nil?
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require "ruby_llm/toolbox/base"
+require "ruby_llm/toolbox/ruby_outline"
+require "ruby_llm/toolbox/safety/path_jail"
+
+module RubyLLM
+  module Toolbox
+    module Tools
+      # SAFE. Produces a structural outline of a Ruby file (classes, modules,
+      # methods, constants) with line numbers, or finds where a name is defined.
+      # In-process via Ripper — it parses, never executes, the code.
+      class ParseRuby < Base
+        description "Outline a Ruby file's structure (classes, modules, methods, constants with line " \
+                    "numbers), or locate definitions. Give a query to find definitions whose name " \
+                    "matches, and/or a kind to filter. Parses in-process; does not run the code."
+
+        KINDS = %w[class module method constant].freeze
+        MAX_BYTES = 5 * 1024 * 1024
+
+        param :path, type: "string",
+                     desc: "Ruby file to outline, relative to fs_root.",
+                     required: true
+        param :query, type: "string",
+                      desc: "Only show definitions whose (qualified) name matches this, case-insensitive. Optional.",
+                      required: false
+        param :kind, type: "string",
+                     desc: "Filter to a kind: class, module, method, or constant. Optional.",
+                     required: false
+
+        def execute(path:, query: nil, kind: nil)
+          kind = kind.to_s.strip.downcase
+          kind = nil if kind.empty?
+          return error("unknown kind: #{kind} (use #{KINDS.join(', ')})", code: :bad_kind) if kind && !KINDS.include?(kind)
+
+          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
+
+          entries = RubyOutline.extract(File.read(real).scrub)
+          return "no definitions found in #{path}" if entries.empty?
+
+          truncate(render(entries, path, query, kind))
+        rescue Safety::PathJail::Jailbreak => e
+          error(e.message, code: :path_denied)
+        rescue RubyOutline::ParseError => e
+          error("#{e.message} in #{path}", code: :parse_error)
+        end
+
+        private
+
+        def render(entries, path, query, kind)
+          if query || kind
+            flat_list(entries, path, query, kind)
+          else
+            "Outline of #{path}:\n#{tree(entries)}"
+          end
+        end
+
+        def tree(entries)
+          entries.map { |e| "#{'  ' * e.depth}#{label(e)} (L#{e.line})" }.join("\n")
+        end
+
+        def flat_list(entries, path, query, kind)
+          pairs = qualify(entries)
+          pairs = pairs.select { |e, _| e.kind.to_s == kind } if kind
+          if query
+            q = query.downcase
+            pairs = pairs.select { |e, qn| qn.downcase.include?(q) || e.name.downcase.include?(q) }
+          end
+          return "no matching definitions in #{path}" if pairs.empty?
+
+          desc = ["definitions", ("matching #{query.inspect}" if query), ("of kind #{kind}" if kind)].compact.join(" ")
+          header = "#{pairs.size} #{desc} in #{path}:"
+          "#{header}\n#{pairs.map { |e, qn| "#{qn} (L#{e.line}) [#{e.kind}]" }.join("\n")}"
+        end
+
+        # Pair each entry with its fully-qualified name using the depth stack.
+        def qualify(entries)
+          namespace = []
+          entries.map do |entry|
+            namespace = namespace.first(entry.depth)
+            ns = namespace.compact
+            qualified =
+              case entry.kind
+              when :class, :module, :singleton_class
+                full = (ns + [entry.name]).join("::")
+                namespace[entry.depth] = entry.name
+                full
+              when :method
+                ns.empty? ? entry.name : "#{ns.join('::')}##{entry.name}"
+              else # constant
+                ns.empty? ? entry.name : "#{ns.join('::')}::#{entry.name}"
+              end
+            [entry, qualified]
+          end
+        end
+
+        def label(entry)
+          case entry.kind
+          when :class, :singleton_class then "class #{entry.name}"
+          when :module then "module #{entry.name}"
+          when :method then "def #{entry.name}"
+          else entry.name
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "ruby_llm/toolbox/base"
+require "ruby_llm/toolbox/process_registry"
+
+module RubyLLM
+  module Toolbox
+    module Tools
+      # SAFE. Stops a background process: SIGTERM to its process group, escalating
+      # to SIGKILL if it doesn't exit, then returns any final output. Always
+      # available (even if exec tools are later disabled) so a runaway can always
+      # be stopped. Removes the process from the registry.
+      class ProcessKill < Base
+        description "Stop a background process (started with process_start) and return any final output. " \
+                    "Terminates the whole process group, escalating to SIGKILL if needed."
+
+        param :id, type: "string",
+                   desc: "The process id to kill (e.g. 'proc_1').",
+                   required: true
+
+        def execute(id:)
+          proc = ProcessRegistry.get(id)
+          return error("no such process: #{id}", code: :not_found) unless proc
+
+          was_running = proc.running?
+          proc.kill
+          final = proc.read_new
+          ProcessRegistry.delete(id)
+
+          body = +"#{id} #{was_running ? 'terminated' : 'was already exited'}"
+          body << " (exit #{proc.exit_code})" if proc.exit_code
+          unless final[:out].empty? && final[:err].empty?
+            body << "\n--- final stdout ---\n#{final[:out]}" unless final[:out].empty?
+            body << "\n--- final stderr ---\n#{final[:err]}" unless final[:err].empty?
+          end
+          truncate(body)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "ruby_llm/toolbox/base"
+require "ruby_llm/toolbox/process_registry"
+
+module RubyLLM
+  module Toolbox
+    module Tools
+      # SAFE. Lists the background processes started this session, with their id,
+      # status, pid, age, and command — so an agent can rediscover ids and see
+      # what's still running.
+      class ProcessList < Base
+        description "List background processes (started with process_start): id, status, pid, age, and " \
+                    "command. Read-only."
+
+        def execute
+          procs = ProcessRegistry.all
+          return "no background processes" if procs.empty?
+
+          lines = procs.map do |proc|
+            status = proc.status == :exited ? "exited(#{proc.exit_code})" : "running"
+            "#{proc.id}  #{status.ljust(12)}  pid=#{proc.pid}  age=#{proc.age.round}s  #{proc.name}  #{proc.argv.inspect}"
+          end
+          truncate(([+"#{procs.size} process#{procs.size == 1 ? '' : 'es'}:"] + lines).join("\n"))
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "ruby_llm/toolbox/base"
+require "ruby_llm/toolbox/process_registry"
+
+module RubyLLM
+  module Toolbox
+    module Tools
+      # SAFE. Returns the output a background process has produced since the last
+      # read, plus its current status (running, or exited with a code). Reads are
+      # incremental, so polling in a loop streams the process's output without
+      # repeats.
+      class ProcessOutput < Base
+        description "Read new stdout/stderr from a background process (started with process_start) since " \
+                    "the last read, along with its status and exit code if it has finished. Poll this to " \
+                    "follow a process's output."
+
+        param :id, type: "string",
+                   desc: "The process id returned by process_start (e.g. 'proc_1').",
+                   required: true
+
+        def execute(id:)
+          proc = ProcessRegistry.get(id)
+          return error("no such process: #{id}", code: :not_found) unless proc
+
+          data = proc.read_new
+          truncate(format_output(proc, data))
+        end
+
+        private
+
+        def format_output(proc, data)
+          body = +"#{proc.id} (#{proc.name}): #{proc.status}"
+          body << " (exit #{proc.exit_code})" if proc.status == :exited && proc.exit_code
+          body << "\n"
+
+          if data[:out].empty? && data[:err].empty?
+            body << "(no new output)"
+            return body
+          end
+
+          unless data[:out].empty?
+            body << "\n--- stdout#{data[:out_dropped] ? ' (earlier output dropped)' : ''} ---\n"
+            body << data[:out]
+          end
+          unless data[:err].empty?
+            body << "\n--- stderr#{data[:err_dropped] ? ' (earlier output dropped)' : ''} ---\n"
+            body << data[:err]
+          end
+          body
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "ruby_llm/toolbox/base"
+require "ruby_llm/toolbox/process_registry"
+require "ruby_llm/toolbox/safety/command_guard"
+
+module RubyLLM
+  module Toolbox
+    module Tools
+      # EXEC. Starts a long-running background process (a dev server, a file
+      # watcher, a log tail) and returns its id immediately instead of blocking.
+      # Read its output later with process_output, see everything running with
+      # process_list, and stop it with process_kill.
+      #
+      # Same safety model as bash: one allowlisted executable, argv only (no
+      # shell), the minimal env_passthrough environment, run in fs_root, in its
+      # own process group with an address-space cap. Concurrency is bounded by
+      # config.max_processes.
+      class ProcessStart < Base
+        exec_tool!
+
+        description "Start a long-running command as a background process and return its id (does not " \
+                    "block). Use for dev servers, watchers, or log tails. The executable must be on the " \
+                    "allowlist; no shell is involved. Manage it with process_output / process_list / " \
+                    "process_kill."
+
+        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 :name, type: "string",
+                     desc: "A short label for this process, shown in listings. Optional.",
+                     required: false
+        param :unsafe, type: "boolean",
+                       desc: "Request bypassing the command allowlist (still argv only, no shell). Only " \
+                             "takes effect if an operator enabled allow_unsafe; otherwise refused. Default false.",
+                       required: false
+
+        def execute(command:, args: nil, name: nil, unsafe: false)
+          exe = resolve_command(command, unsafe)
+          argv = [exe, *sanitize_args(args)]
+
+          id = ProcessRegistry.start(
+            argv: argv,
+            env: clean_env,
+            chdir: config.fs_root,
+            name: (name.to_s.empty? ? exe : name.to_s),
+            rlimits: memory_rlimits,
+            max: config.max_processes
+          )
+          proc = ProcessRegistry.get(id)
+          "Started #{id} (pid #{proc.pid}): #{argv.inspect}\nUse process_output id:#{id.inspect} to read its output."
+        rescue Safety::CommandGuard::Blocked => e
+          error(e.message, code: :command_denied)
+        rescue ProcessRegistry::LimitError => e
+          error(e.message, code: :too_many_processes)
+        end
+
+        private
+
+        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
+            raise Safety::CommandGuard::Blocked, "argument contains a NUL byte" if str.include?("\u0000")
+
+            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
+
+        # An address-space cap so a runaway can't exhaust host memory. No CPU
+        # cap — background processes are expected to run indefinitely.
+        def memory_rlimits
+          return {} unless /linux/i.match?(RUBY_PLATFORM)
+
+          bytes = parse_memory_bytes(config.sandbox_memory)
+          bytes ? { rlimit_as: bytes } : {}
+        end
+
+        def parse_memory_bytes(value)
+          str = value.to_s.strip.downcase
+          return nil if str.empty?
+          return nil unless (m = str.match(/\A(\d+)\s*([kmg])?b?\z/))
+
+          n = m[1].to_i
+          { "k" => 1024, "m" => 1024**2, "g" => 1024**3 }.fetch(m[2], 1) * n
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "ruby_llm/toolbox/base"
+require "ruby_llm/toolbox/tools/toolchain_helpers"
+
+module RubyLLM
+  module Toolbox
+    module Tools
+      # EXEC. Runs the project's Python tests (pytest or unittest) from fs_root
+      # and returns the output with a pass/fail headline. A failing suite is a
+      # normal result, not a tool error. Runs in the project environment, so a
+      # virtualenv/installed deps resolve as they would in a shell.
+      class PythonTests < Base
+        include ToolchainHelpers
+        exec_tool!
+
+        description "Run the project's Python test suite from fs_root and report results. Uses pytest " \
+                    "by default, or unittest (python -m unittest discover) when framework is unittest. " \
+                    "Optionally scope to a path."
+
+        FRAMEWORKS = %w[pytest unittest].freeze
+
+        param :path, type: "string",
+                     desc: "Limit the run to this test file or directory, relative to fs_root. Optional.",
+                     required: false
+        param :framework, type: "string",
+                          desc: "pytest (default) or unittest.",
+                          required: false
+
+        def execute(path: nil, framework: "pytest")
+          fw = framework.to_s.strip.downcase
+          fw = "pytest" if fw.empty?
+          return error("unknown framework: #{fw} (use #{FRAMEWORKS.join(', ')})", code: :bad_framework) unless FRAMEWORKS.include?(fw)
+
+          rel = jail_relative(path)
+          out, err, status = run_in_project(args_for(fw, rel), use_bundle: false)
+          toolchain_output(out, err, status,
+                           pass_label: summarize(out, err, "TESTS PASSED"),
+                           fail_label: summarize(out, err, "TESTS FAILED"))
+        rescue Safety::PathJail::Jailbreak => e
+          error(e.message, code: :path_denied)
+        rescue CommandMissing => e
+          error("#{e.message} is not available (is it installed in the project env?)", code: :unavailable)
+        end
+
+        private
+
+        def args_for(framework, rel)
+          if framework == "unittest"
+            args = ["python3", "-m", "unittest", "discover"]
+            args += ["-s", rel] if rel
+          else
+            args = ["pytest"]
+            args << rel if rel
+          end
+          args
+        end
+
+        # Surface pytest's or unittest's summary in the headline.
+        def summarize(out, err, label)
+          text = "#{out}\n#{err}"
+          counts = %w[passed failed error skipped].filter_map do |word|
+            m = text.match(/(\d+) #{word}/)
+            "#{m[1]} #{word}" if m
+          end
+          return "#{label} (#{counts.join(', ')})" unless counts.empty?
+
+          if (m = text.match(/Ran (\d+) tests?.*?(OK|FAILED)/m))
+            return "#{label} (ran #{m[1]}, #{m[2]})"
+          end
+
+          label
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "ruby_llm/toolbox/base"
+require "ruby_llm/toolbox/safety/path_jail"
+
+module RubyLLM
+  module Toolbox
+    module Tools
+      # SAFE reference tool. Read-only, confined to fs_root, output budgeted.
+      # Loaded and usable by default.
+      class ReadFile < Base
+        description "Read a UTF-8 text file from within the configured fs_root. " \
+                    "Optionally restrict to a 1-based line range, or return only the last N lines with tail. " \
+                    "Large output is automatically truncated to fit a token budget."
+
+        param :path, type: "string",
+                     desc: "File path, relative to fs_root (or an absolute path inside it).",
+                     required: true
+        param :start_line, type: "integer",
+                           desc: "1-based first line to include. Optional.",
+                           required: false
+        param :end_line, type: "integer",
+                         desc: "1-based last line to include, inclusive. Optional.",
+                         required: false
+        param :tail, type: "integer",
+                     desc: "Return only the last N lines (like `tail -n N`). Takes precedence over " \
+                           "start_line/end_line. Optional.",
+                     required: false
+        param :unsafe, type: "boolean",
+                       desc: "Bypass the fs_root jail (read anywhere). Only honored if the operator " \
+                             "enabled allow_unsafe; otherwise the call is refused. Default false.",
+                       required: false
+
+        MAX_BYTES = 5 * 1024 * 1024 # refuse to slurp anything enormous
+
+        def execute(path:, start_line: nil, end_line: nil, tail: nil, unsafe: false)
+          jail = path_jail(unsafe: unsafe, detail: path)
+          real = jail.resolve(path)
+
+          return error("not a file: #{path}", code: :not_a_file) unless File.file?(real)
+          if File.size(real) > MAX_BYTES
+            return error("file too large (> #{MAX_BYTES} bytes)", code: :too_large)
+          end
+
+          lines = File.readlines(real)
+          selected = if tail && tail.to_i.positive?
+                       lines.last(tail.to_i)
+                     else
+                       slice_lines(lines, start_line, end_line)
+                     end
+          return error("no lines in the given range", code: :empty_range) if selected.nil?
+
+          truncate(selected.join.scrub)
+        rescue Safety::PathJail::Jailbreak => e
+          error(e.message, code: :path_denied)
+        end
+
+        private
+
+        def slice_lines(lines, start_line, end_line)
+          return lines if start_line.nil? && end_line.nil?
+
+          first = (start_line || 1).to_i
+          last  = (end_line || lines.length).to_i
+          return nil if first < 1 || first > lines.length
+
+          last = lines.length if last > lines.length
+          return nil if last < first
+
+          lines[(first - 1)..(last - 1)]
+        end
+      end
+    end
+  end
+end