rubino-agent 0.3.0

data/lib/rubino/tools/base.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+module Rubino
+  module Tools
+    # Abstract base class for all tools.
+    # Each tool must implement: name, description, input_schema, risk_level, call.
+    class Base
+      # Set by ToolExecutor before each call so long-running tools (shell,
+      # http, watchers) can poll for user cancellation. Default is nil — the
+      # tool should treat that as "no cancellation possible" and not crash.
+      attr_accessor :cancel_token
+
+      # Session-scoped ReadTracker injected by ToolExecutor. ReadTool
+      # registers successful reads; EditTool / MultiEditTool consult it
+      # before writing so they can refuse to edit a file the model never
+      # opened in this session. Nil-tolerant: tools that don't care just
+      # ignore it.
+      attr_accessor :read_tracker
+
+      # Optional Proc, injected by ToolExecutor, that the tool can call with
+      # incremental output chunks during a long-running call. ShellTool uses
+      # this to stream stdout/stderr lines as the subprocess writes them
+      # instead of dumping everything at end-of-command. Nil-tolerant: a
+      # tool with no streamable output (read, edit, glob) just ignores it.
+      attr_accessor :stream_chunk
+
+      # Convenience guard so tools don't sprinkle nil-checks at every emit.
+      def emit_chunk(text)
+        return if text.nil? || text.to_s.empty?
+
+        @stream_chunk&.call(text.to_s)
+      end
+
+      # True when the user has requested cancellation. Cheap, lock-protected.
+      # Use in tight loops; on true, terminate gracefully and either return
+      # an "interrupted" string or raise Rubino::Interrupted.
+      def cancellation_requested?
+        @cancel_token&.cancelled?
+      end
+
+      # Returns the tool name (used in LLM tool definitions)
+      def name
+        raise NotImplementedError, "#{self.class}#name not implemented"
+      end
+
+      # The `tools.<key>` config gate that enables/disables this tool. Single
+      # source of truth shared with Registry#tool_enabled_in_config? and the
+      # `tools` CLI command, so the displayed state always matches the state
+      # the registry actually enforces. Defaults to the tool's own name;
+      # tools whose config key differs (webfetch/websearch both gate on
+      # `tools.web`) override this. Returning a key absent from config means
+      # the tool is enabled (opt-out model).
+      def config_key
+        name
+      end
+
+      # Returns a description for the LLM
+      def description
+        raise NotImplementedError, "#{self.class}#description not implemented"
+      end
+
+      # Returns the JSON schema for input parameters
+      def input_schema
+        raise NotImplementedError, "#{self.class}#input_schema not implemented"
+      end
+
+      # Returns the risk level: :low, :medium, :high
+      def risk_level
+        :low
+      end
+
+      # Executes the tool with given arguments, returns output string
+      def call(arguments)
+        raise NotImplementedError, "#{self.class}#call not implemented"
+      end
+
+      # Returns true if this tool requires user confirmation
+      def risky?
+        %i[medium high].include?(risk_level)
+      end
+
+      # Returns the tool definition for LLM registration
+      def to_tool_definition
+        {
+          name: name,
+          description: description,
+          parameters: input_schema
+        }
+      end
+
+      protected
+
+      # Filesystem sandbox for write/edit/delete operations.
+      #
+      # Defaults to Dir.pwd, overridable via terminal.cwd in config. Mutating
+      # tools must call within_workspace? before touching the disk so a prompt
+      # injection that asks for `file_path: "/etc/passwd"` is refused at the
+      # tool boundary, before the approval prompt even sees the path.
+      #
+      # The check resolves every symlink with File.realpath before comparing
+      # against the workspace root: dropping a `link → /etc` inside the
+      # workspace and writing through it used to bypass the boundary because
+      # expand_path alone never crosses the symlink. realpath walks the
+      # filesystem and gives us the canonical destination, so an in-workspace
+      # path that ultimately points outside is rejected like any other escape.
+      # For non-existent targets (write-creates-new-file) we resolve the
+      # deepest existing ancestor and re-attach the remainder — the new file
+      # will land at that ancestor, so the ancestor is what we sandbox.
+      #
+      # Set tools.workspace_strict=false in config.yml to disable globally
+      # (the agent then trusts the model + the approval flow alone).
+      # The directory tools sandbox to. Exposed as a class method so the
+      # File API operations can root their Workspace at the SAME place
+      # (otherwise produced artifacts under this root look like traversal
+      # escapes relative to paths_home and the download 422s).
+      # The PRIMARY root — terminal.cwd or the launch cwd. Kept as the single
+      # source of truth for "the" directory: the @-picker, shell/test cwd, the
+      # File API workspace and the attachment downloader all root here so they
+      # agree. The write/edit SANDBOX, however, spans every root (see
+      # #within_workspace?) so an added dir is also writable.
+      def self.workspace_root
+        Workspace.primary_root
+      end
+
+      # Every allowed root (primary + any --add-dir / /add-dir dirs). The
+      # sandbox accepts a target under ANY of these.
+      def self.workspace_roots
+        Workspace.roots
+      end
+
+      def workspace_root
+        self.class.workspace_root
+      end
+
+      def workspace_roots
+        self.class.workspace_roots
+      end
+
+      def workspace_strict?
+        Rubino.configuration.dig("tools", "workspace_strict") != false
+      end
+
+      # True when +expanded+ resolves under ANY allowed root. Generalised from
+      # the old single-root check so a write/edit/multi_edit under a dir added
+      # via --add-dir / /add-dir is accepted, while a path outside every root
+      # is still refused. Symlinks are resolved (canonical_path) before the
+      # comparison so an in-workspace symlink to /etc can't escape.
+      def within_workspace?(expanded)
+        return true unless workspace_strict?
+
+        target_real = canonical_path(expanded)
+        return false unless target_real
+
+        Workspace.canonical_roots.any? do |root_real|
+          target_real == root_real ||
+            target_real.start_with?("#{root_real}#{File::SEPARATOR}")
+        end
+      end
+
+      # Resolves `path` through every symlink to its canonical destination.
+      # When the path doesn't exist yet (create-new-file flow) walks up to
+      # the deepest existing ancestor, realpaths that, then re-joins the
+      # missing tail. The tail itself can't traverse — expand_path already
+      # collapsed `..` segments before we got here.
+      def canonical_path(path)
+        return nil if path.nil? || path.to_s.empty?
+
+        expanded = File.expand_path(path.to_s)
+        return File.realpath(expanded) if File.exist?(expanded)
+
+        ancestor = expanded
+        tail     = []
+        until File.exist?(ancestor)
+          parent = File.dirname(ancestor)
+          break if parent == ancestor
+
+          tail.unshift(File.basename(ancestor))
+          ancestor = parent
+        end
+        return nil unless File.exist?(ancestor)
+
+        File.join(File.realpath(ancestor), *tail)
+      rescue Errno::ENOENT, Errno::EACCES, Errno::ELOOP
+        nil
+      end
+
+      def workspace_violation_message(path)
+        roots = workspace_roots
+        where = roots.length == 1 ? roots.first : "any allowed root (#{roots.join(", ")})"
+        "Error: refusing to access '#{path}' — outside #{where}. " \
+          "Set tools.workspace_strict=false in config.yml to disable this check."
+      end
+
+      # Read-before-edit gate shared by EditTool and MultiEditTool. Refuses the
+      # write when the model never read this file in the current session, or
+      # read it but the file changed on disk since. Returns nil (proceed) or an
+      # error Hash carrying error_code: :stale_read for the model to recover
+      # from. No tracker injected → no gate (single-tool unit tests, MCP calls).
+      #
+      # `verb` is the only token that varies between callers ("edit" /
+      # "edits"); the wording is otherwise identical, so it lives here.
+      def read_gate_error(expanded, display_path, verb:)
+        return nil unless @read_tracker
+
+        unless @read_tracker.seen?(expanded)
+          return { output: "Error: must use the read tool on #{display_path} in this session before editing it. " \
+                           "Read it first so the #{verb} can verify the surrounding context.",
+                   error_code: :stale_read }
+        end
+
+        stashed = @read_tracker.mtime_at_read(expanded)
+        current = File.mtime(expanded)
+        return nil if stashed.nil? || current <= stashed
+
+        { output: "Error: #{display_path} changed on disk since the last read " \
+                  "(read at #{stashed.utc.iso8601}, now #{current.utc.iso8601}). " \
+                  "Re-read the file before editing so the #{verb} reflect the current contents.",
+          error_code: :stale_read }
+      end
+    end
+  end
+end

data/lib/rubino/tools/custom_tool_loader.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Rubino
+  module Tools
+    # Loads user-defined tools from .rubino/tools/ directories.
+    # Users can define tools using a simple Ruby DSL.
+    #
+    # Example tool file (.rubino/tools/my_tool.rb):
+    #
+    #   Rubino.define_tool do
+    #     name "my_custom_tool"
+    #     description "Does something custom"
+    #     input_schema type: "object", properties: { input: { type: "string" } }
+    #     risk_level :low
+    #
+    #     execute do |args|
+    #       "Result: #{args['input']}"
+    #     end
+    #   end
+    #
+    class CustomToolLoader
+      TOOL_GLOB = "*.rb"
+
+      # HOME-only by design (#44). This loader `load`s arbitrary Ruby, so it
+      # must NEVER read from a project's cwd `.rubino/tools` — that would let
+      # any directory you start rubino in execute code with zero prompt, the
+      # exact foot-gun the folder-trust model exists to prevent. The only
+      # allowed source is the user's own config dir under RUBINO_HOME, which is
+      # not attacker-controllable by cd-ing into a repo. (Previously the path
+      # list led with the cwd `.rubino/tools`; that entry is removed.)
+      def self.tool_paths
+        [File.join(Rubino.home_path, "tools")]
+      end
+
+      def initialize(paths: nil)
+        @paths = paths || self.class.tool_paths
+      end
+
+      # Loads all custom tools and registers them
+      def load_all!
+        loaded = 0
+
+        @paths.each do |dir|
+          expanded = File.expand_path(dir)
+          next unless File.directory?(expanded)
+
+          Dir.glob(File.join(expanded, TOOL_GLOB)).each do |path|
+            load_tool_file(path)
+            loaded += 1
+          rescue StandardError => e
+            Rubino.ui.warning("Failed to load tool #{path}: #{e.message}")
+          end
+        end
+
+        loaded
+      end
+
+      private
+
+      def load_tool_file(path)
+        # Load in a clean context
+        load(path)
+      end
+    end
+
+    # DSL builder for custom tools
+    class CustomToolBuilder
+      attr_reader :_name, :_description, :_input_schema, :_risk_level, :_execute_block
+
+      def initialize
+        @_risk_level = :low
+        @_input_schema = { type: "object", properties: {} }
+      end
+
+      def name(val)
+        @_name = val
+      end
+
+      def description(val)
+        @_description = val
+      end
+
+      def input_schema(val)
+        @_input_schema = val
+      end
+
+      def risk_level(val)
+        @_risk_level = val
+      end
+
+      def execute(&block)
+        @_execute_block = block
+      end
+
+      # Builds a Tool instance from the DSL
+      def build
+        builder = self
+        Class.new(Base) do
+          define_method(:name) { builder._name }
+          define_method(:description) { builder._description }
+          define_method(:input_schema) { builder._input_schema }
+          define_method(:risk_level) { builder._risk_level }
+          define_method(:call) { |args| builder._execute_block.call(args) }
+        end.new
+      end
+    end
+  end
+end
+
+# Module-level DSL method for defining custom tools
+module Rubino
+  def self.define_tool(&)
+    builder = Tools::CustomToolBuilder.new
+    builder.instance_eval(&)
+    tool = builder.build
+    Tools::Registry.register(tool)
+    tool
+  end
+end

data/lib/rubino/tools/edit_tool.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Rubino
+  module Tools
+    # Tool for performing exact string replacements in files.
+    # Replaces a specific old string with a new string - more precise than full file writes.
+    class EditTool < Base
+      def name
+        "edit"
+      end
+
+      def description
+        "Perform exact string replacement in a file. " \
+          "Specify the old text to find and the new text to replace it with. " \
+          "The old text must match exactly (including whitespace/indentation). " \
+          "Use replace_all to replace all occurrences."
+      end
+
+      def input_schema
+        {
+          type: "object",
+          properties: {
+            file_path: {
+              type: "string",
+              description: "The path to the file to edit"
+            },
+            old_string: {
+              type: "string",
+              description: "The exact text to find and replace"
+            },
+            new_string: {
+              type: "string",
+              description: "The text to replace it with"
+            },
+            replace_all: {
+              type: "boolean",
+              description: "Replace all occurrences (default: false, replaces first only)"
+            }
+          },
+          required: %w[file_path old_string new_string]
+        }
+      end
+
+      def risk_level
+        :medium
+      end
+
+      def call(arguments)
+        file_path = arguments["file_path"] || arguments[:file_path]
+        old_string = arguments["old_string"] || arguments[:old_string]
+        new_string = arguments["new_string"] || arguments[:new_string]
+        replace_all = arguments["replace_all"] || arguments[:replace_all] || false
+
+        expanded = File.expand_path(file_path)
+        return workspace_violation_message(file_path) unless within_workspace?(expanded)
+
+        return "Error: File not found: #{file_path}" unless File.exist?(expanded)
+
+        if (gate = read_gate_error(expanded, file_path, verb: "edit"))
+          return gate
+        end
+
+        content = File.read(expanded)
+
+        unless content.include?(old_string)
+          return "Error: old_string not found in file content. " \
+                 "Make sure the text matches exactly including whitespace."
+        end
+
+        # Count occurrences
+        count = content.scan(old_string).size
+        if count > 1 && !replace_all
+          return "Error: Found #{count} matches for old_string. " \
+                 "Provide more surrounding context to make it unique, " \
+                 "or set replace_all: true to replace all occurrences."
+        end
+
+        # Perform replacement — use block form so new_string is treated as a
+        # literal string, not a pattern (avoids \0, \1, \& interpolation bugs).
+        new_content = if replace_all
+                        content.gsub(old_string) { new_string }
+                      else
+                        content.sub(old_string) { new_string }
+                      end
+
+        File.write(expanded, new_content)
+
+        replaced_count = replace_all ? count : 1
+        added   = new_string.to_s.lines.size
+        removed = old_string.to_s.lines.size
+        { output: "Edit applied: #{replaced_count} replacement(s) in #{file_path}",
+          metrics: "#{replaced_count} replacement#{"s" if replaced_count != 1} · " \
+                   "+#{added * replaced_count} −#{removed * replaced_count}",
+          body: build_diff_preview(old_string, new_string, replaced_count),
+          body_kind: :diff }
+      end
+
+      private
+
+      # Inline diff shown between the `tool · edit` and `done · edit` headers.
+      # Not a real unified diff — just `- old` then `+ new` so the user can
+      # see at a glance what the model is changing without scrolling back to
+      # the approval prompt. Trimmed to the first 12 lines; long edits still
+      # apply, the body is only a preview.
+      MAX_DIFF_LINES = 12
+
+      def build_diff_preview(old_str, new_str, replaced_count)
+        minus = old_str.to_s.lines.map { |l| "- #{l.chomp}" }
+        plus  = new_str.to_s.lines.map { |l| "+ #{l.chomp}" }
+        lines = minus + plus
+        suffix = []
+        if lines.size > MAX_DIFF_LINES
+          dropped = lines.size - MAX_DIFF_LINES
+          lines   = lines.first(MAX_DIFF_LINES)
+          suffix << "  [… #{dropped} more line(s)]"
+        end
+        suffix << "  (× #{replaced_count} occurrences)" if replaced_count > 1
+        (lines + suffix).join("\n")
+      end
+    end
+  end
+end

data/lib/rubino/tools/git_tool.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Rubino
+  module Tools
+    # Tool for git operations: status, diff, log, branch info.
+    class GitTool < Base
+      def name
+        "git"
+      end
+
+      def description
+        "Execute git commands to inspect repository state. " \
+          "Supports status, diff, log, branch, and show operations."
+      end
+
+      def input_schema
+        {
+          type: "object",
+          properties: {
+            command: {
+              type: "string",
+              enum: %w[status diff log branch show],
+              description: "The git command to execute"
+            },
+            args: {
+              type: "string",
+              description: "Additional arguments for the command"
+            }
+          },
+          required: %w[command]
+        }
+      end
+
+      def risk_level
+        :low # Read-only git operations
+      end
+
+      def call(arguments)
+        command = arguments["command"] || arguments[:command]
+        args = arguments["args"] || arguments[:args] || ""
+
+        case command
+        when "status"
+          execute_git("status", args)
+        when "diff"
+          execute_git("diff", args)
+        when "log"
+          execute_git("log --oneline -20", args)
+        when "branch"
+          execute_git("branch", args)
+        when "show"
+          execute_git("show", args)
+        else
+          "Unknown git command: #{command}"
+        end
+      end
+
+      private
+
+      def execute_git(cmd, args)
+        # Split cmd into tokens and append sanitised args to avoid shell injection.
+        # IO.popen with an argv array never passes the arguments through a shell.
+        argv = ["git"] + cmd.split + args.split
+        result = IO.popen(argv, err: %i[child out], &:read)
+        result.empty? ? "(no output)" : result
+      rescue StandardError => e
+        "Git error: #{e.message}"
+      end
+    end
+  end
+end