rubino-agent 0.3.0

data/lib/rubino/tools/multi_edit_tool.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Rubino
+  module Tools
+    # Applies an ordered list of exact string replacements to a single file
+    # in one transactional shot. If any edit fails (string not found, or
+    # non-unique without replace_all) the file is left untouched — the LLM
+    # gets a single error pointing at the offending edit index.
+    #
+    # Each subsequent edit sees the result of prior edits in the same call,
+    # so you can rename A→B and then change a line that contains B.
+    class MultiEditTool < Base
+      def name
+        "multi_edit"
+      end
+
+      def description
+        "Apply multiple exact string replacements to a single file atomically. " \
+          "Edits are applied sequentially in the given order; later edits see " \
+          "the result of earlier ones. If any edit fails, NO changes are written."
+      end
+
+      def input_schema
+        {
+          type: "object",
+          properties: {
+            file_path: {
+              type: "string",
+              description: "Path to the file to edit"
+            },
+            edits: {
+              type: "array",
+              description: "Ordered list of edits to apply",
+              items: {
+                type: "object",
+                properties: {
+                  old_string: { type: "string",  description: "Exact text to find" },
+                  new_string: { type: "string",  description: "Replacement text" },
+                  replace_all: { type: "boolean", description: "Replace all occurrences (default false)" }
+                },
+                required: %w[old_string new_string]
+              }
+            }
+          },
+          required: %w[file_path edits]
+        }
+      end
+
+      def risk_level
+        :medium
+      end
+
+      def call(arguments)
+        file_path = arguments["file_path"] || arguments[:file_path]
+        edits     = arguments["edits"]     || arguments[:edits] || []
+
+        return "Error: file_path is required" if file_path.nil? || file_path.to_s.empty?
+        return "Error: edits must be a non-empty array" if !edits.is_a?(Array) || edits.empty?
+
+        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: "edits"))
+          return gate
+        end
+
+        content       = File.read(expanded)
+        working       = content.dup
+        applied_count = 0
+
+        edits.each_with_index do |edit, idx|
+          if cancellation_requested?
+            return "Cancelled before edit ##{idx + 1} — no changes written " \
+                   "(multi_edit is atomic: stages in memory, writes once)"
+          end
+
+          old_s       = edit["old_string"]  || edit[:old_string]
+          new_s       = edit["new_string"]  || edit[:new_string]
+          replace_all = edit["replace_all"] || edit[:replace_all] || false
+
+          return "Error: edit ##{idx + 1} is missing old_string or new_string" if old_s.nil? || new_s.nil?
+          return "Error: edit ##{idx + 1}: old_string and new_string are identical" if old_s == new_s
+          unless working.include?(old_s)
+            return "Error: edit ##{idx + 1}: old_string not found (check whitespace; " \
+                   "remember edits see the result of prior edits)"
+          end
+
+          count = working.scan(old_s).size
+          if count > 1 && !replace_all
+            return "Error: edit ##{idx + 1}: #{count} matches for old_string. " \
+                   "Add surrounding context to disambiguate, or set replace_all: true."
+          end
+
+          working = if replace_all
+                      working.gsub(old_s) { new_s }
+                    else
+                      working.sub(old_s) { new_s }
+                    end
+          applied_count += replace_all ? count : 1
+        end
+
+        File.write(expanded, working)
+        "Applied #{edits.size} edit(s), #{applied_count} replacement(s) in #{file_path}"
+      rescue StandardError => e
+        "Error: #{e.message}"
+      end
+    end
+  end
+end

data/lib/rubino/tools/patch_tool.rb

@@ -0,0 +1,260 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Rubino
+  module Tools
+    # Tool for applying unified diff patches to files.
+    class PatchTool < Base
+      def name
+        "apply_patch"
+      end
+
+      def description
+        "Apply a unified diff patch to one or more files. " \
+          "Accepts standard unified diff format (like output from 'git diff')."
+      end
+
+      def input_schema
+        {
+          type: "object",
+          properties: {
+            patch: {
+              type: "string",
+              description: "The unified diff patch content to apply"
+            },
+            base_path: {
+              type: "string",
+              description: "Base directory for relative paths in the patch (defaults to cwd)"
+            }
+          },
+          required: %w[patch]
+        }
+      end
+
+      def risk_level
+        :medium
+      end
+
+      def call(arguments)
+        patch     = arguments["patch"]     || arguments[:patch]
+        base_path = arguments["base_path"] || arguments[:base_path] || Dir.pwd
+
+        hunks = parse_patch(patch)
+        return "No changes applied" if hunks.empty?
+
+        # Pass 1: validate every hunk against current disk state and compute
+        # the new content for each file in memory. NO disk writes here. If
+        # any single hunk fails (missing file, context mismatch, workspace
+        # escape) we abort the whole patch — partial application across
+        # multiple files leaves the tree in a state neither the user nor
+        # the agent can easily reason about, and reverting it requires
+        # knowing the prior contents which we no longer have.
+        pending, error = plan_operations(hunks, base_path)
+        return error if error
+
+        # Pass 2: execute. cancellation_requested? polled between operations
+        # so a Ctrl+C lands cleanly — at most one application is in flight.
+        apply_operations(pending)
+      end
+
+      private
+
+      def plan_operations(hunks, base_path)
+        pending = []
+
+        hunks.each do |hunk|
+          file_path = File.expand_path(hunk[:file], base_path)
+
+          unless within_workspace?(file_path)
+            return [nil, workspace_violation_message(hunk[:file]) +
+                         " (no changes applied — apply_patch is two-phase)"]
+          end
+
+          if hunk[:new_file]
+            pending << { kind: :create,
+                         path: file_path,
+                         display: hunk[:file],
+                         content: hunk[:additions].join("\n") + "\n" }
+          elsif hunk[:delete_file]
+            pending << { kind: :delete,
+                         path: file_path,
+                         display: hunk[:file] }
+          else
+            return [nil, "Error: File not found: #{hunk[:file]} (no changes applied)"] unless File.exist?(file_path)
+
+            content                   = File.read(file_path)
+            new_content, drift, fuzzy = apply_hunk(content, hunk)
+            if new_content.nil?
+              return [nil, "Error: Could not apply hunk to #{hunk[:file]} - " \
+                           "context mismatch (no changes applied)"]
+            end
+
+            pending << { kind: :patch,
+                         path: file_path,
+                         display: hunk[:file],
+                         content: new_content,
+                         drift: drift,
+                         fuzzy: fuzzy,
+                         adds: hunk[:additions].size,
+                         dels: hunk[:deletions].size }
+          end
+        end
+
+        [pending, nil]
+      end
+
+      def apply_operations(pending)
+        results = []
+
+        pending.each do |op|
+          if cancellation_requested?
+            remaining = pending.size - results.size
+            results << "[cancelled — #{remaining} operation(s) skipped]"
+            break
+          end
+
+          case op[:kind]
+          when :create
+            FileUtils.mkdir_p(File.dirname(op[:path]))
+            File.write(op[:path], op[:content])
+            results << "Created: #{op[:display]}"
+          when :delete
+            File.delete(op[:path]) if File.exist?(op[:path])
+            results << "Deleted: #{op[:display]}"
+          when :patch
+            File.write(op[:path], op[:content])
+            results << patch_result_line(op)
+          end
+        end
+
+        results.join("\n")
+      end
+
+      # The drift note is the bit that distinguishes "applied exactly where
+      # the diff said" from "found by fuzzy search ±20 lines away". The old
+      # tool silently let the fuzzy case through and reported success — if
+      # the model was off by 50 lines we'd write to the wrong place and
+      # claim it worked.
+      def patch_result_line(op)
+        base = "Patched: #{op[:display]} (#{op[:adds]} additions, #{op[:dels]} deletions)"
+        return base unless op[:fuzzy]
+
+        offset = op[:drift]
+        signed = "#{"+" if offset.positive?}#{offset}"
+        "#{base} [fuzzy match: applied #{signed} line(s) from requested position]"
+      end
+
+      def parse_patch(patch)
+        hunks        = []
+        current_file = nil
+        # Flags carried at the file level — set before any @@ hunk header
+        pending_new_file    = false
+        pending_delete_file = false
+
+        patch.each_line do |line|
+          case line
+          when %r{^--- /dev/null}
+            # New file: source is /dev/null
+            pending_new_file = true
+          when %r{^--- a/(.*)}
+            # Normal source file — set current_file and reset pending flags
+            current_file        = Regexp.last_match(1).strip
+            pending_new_file    = false
+            pending_delete_file = false
+          when %r{^\+\+\+ /dev/null}
+            # Delete file: destination is /dev/null; current_file already set by --- a/
+            pending_delete_file = true
+          when %r{^\+\+\+ b/(.*)}
+            current_file = Regexp.last_match(1).strip
+          when /^@@ -(\d+),?\d* \+(\d+),?\d* @@/
+            hunk = {
+              file: current_file,
+              start_line: Regexp.last_match(1).to_i,
+              new_start: Regexp.last_match(2).to_i,
+              context: [],
+              additions: [],
+              deletions: [],
+              lines: [],
+              new_file: pending_new_file,
+              delete_file: pending_delete_file
+            }
+            hunks << hunk
+            # Reset pending flags after consuming them
+            pending_new_file    = false
+            pending_delete_file = false
+          else
+            hunk = hunks.last
+            next unless hunk
+
+            if line.start_with?("+")
+              hunk[:additions] << line[1..].rstrip
+              hunk[:lines]     << { type: :add, content: line[1..].rstrip }
+            elsif line.start_with?("-")
+              hunk[:deletions] << line[1..].rstrip
+              hunk[:lines]     << { type: :del, content: line[1..].rstrip }
+            elsif line.start_with?(" ")
+              hunk[:context] << line[1..].rstrip
+              hunk[:lines]   << { type: :ctx, content: line[1..].rstrip }
+            end
+          end
+        end
+
+        hunks
+      end
+
+      # Returns [new_content, drift, fuzzy].
+      #   new_content: the rewritten file content, or nil if context can't
+      #                be found anywhere within the fuzzy search window.
+      #   drift:       signed line offset from the hunk's requested start
+      #                (0 = exact match).
+      #   fuzzy:       true iff the match was found by find_context rather
+      #                than at the requested line. The caller surfaces this
+      #                so the model can see "I asked line 10, you applied
+      #                at line 13" instead of trusting a silent fuzzy match.
+      def apply_hunk(content, hunk)
+        lines        = content.lines.map(&:rstrip)
+        requested_ix = hunk[:start_line] - 1
+        start_idx    = requested_ix
+        fuzzy        = false
+
+        expected = hunk[:lines].reject { |l| l[:type] == :add }.map { |l| l[:content] }
+
+        actual = lines[start_idx, expected.size]
+        unless actual && actual.map(&:rstrip) == expected.map(&:rstrip)
+          found_idx = find_context(lines, expected, start_idx)
+          return [nil, 0, false] unless found_idx
+
+          start_idx = found_idx
+          fuzzy     = (found_idx != requested_ix)
+        end
+
+        new_lines = lines[0...start_idx]
+        hunk[:lines].each do |line|
+          case line[:type]
+          when :add, :ctx
+            new_lines << line[:content]
+          when :del
+            # removed — skip
+          end
+        end
+        new_lines.concat(lines[(start_idx + expected.size)..] || [])
+
+        [new_lines.join("\n") + "\n", start_idx - requested_ix, fuzzy]
+      end
+
+      def find_context(lines, expected, hint_idx)
+        search_range = 20
+        start  = [0, hint_idx - search_range].max
+        finish = [lines.size - expected.size, hint_idx + search_range].min
+
+        (start..finish).each do |idx|
+          actual = lines[idx, expected.size]
+          return idx if actual && actual.map(&:rstrip) == expected.map(&:rstrip)
+        end
+
+        nil
+      end
+    end
+  end
+end

data/lib/rubino/tools/probe_tool.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+require_relative "subagent_probe"
+
+module Rubino
+  module Tools
+    # probe — the MODEL-callable EPHEMERAL peek into one of the caller's OWN
+    # running children (S3). The model counterpart of the human
+    # `/agents <id> probe "..."`. Two paths, both read-only (they append NOTHING
+    # to the child's session — the EPHEMERAL invariant):
+    #
+    #   live:false (DEFAULT, FREE): build the answer from the registry's
+    #     live-progress fields ONLY (status / tool_count / last_activity + the
+    #     bounded activity_log ring the /agents drill-in already tails). NO model
+    #     call — unlimited.
+    #   live:true (BILLED): run ONE side-inference over a read-only snapshot of
+    #     the child's transcript (SubagentProbe#peek) and return the answer. This
+    #     costs a model round-trip, so it is BUDGETED per child
+    #     (tasks.max_live_probes_per_child, default 5). Over budget → the model is
+    #     told to use the free snapshot.
+    #
+    # SCOPED AT CALL (the S1 correction): probe is registered for ALL agents and
+    # authorized by OWNERSHIP at call time — the target must be the caller's OWN
+    # direct child (BackgroundTasks.owned_by?). Registered normally, NOT on any
+    # strip list. Does NOT touch the human CLI probe path (executor.rb).
+    class ProbeTool < Base
+      # How many activity_log lines the cheap snapshot renders (matches the
+      # /agents drill-in's `recent:` ring).
+      RECENT_MAX = 6
+
+      # A probe is a snapshot at this instant: a child probed right after
+      # spawn has run nothing yet and honestly reports an empty/confused
+      # context, which reads as broken without this hint (#112).
+      JUST_STARTED_HINT = "(snapshot at this instant — the child just started and its " \
+                          "context is still empty; probe again in a moment)"
+
+      def initialize(probe: nil)
+        # Test seam: inject a SubagentProbe (or any object responding to #peek)
+        # so the live path can be driven without a real model.
+        @probe = probe
+      end
+
+      def name
+        "probe"
+      end
+
+      # Gated by the same `tools.task` delegation key — probing a child is
+      # meaningless without the delegation substrate.
+      def config_key
+        "task"
+      end
+
+      def description
+        "Check on one of YOUR OWN running subagents WITHOUT disturbing it (this " \
+          "is read-only — it changes nothing about what the child does). By default " \
+          "(live:false) it returns a FREE instant snapshot: the child's status, how " \
+          "many tools it has run, its last activity, and a few recent lines — no " \
+          "model call. Set live:true to ask the child a specific question answered " \
+          "from its current context by a one-shot model peek (this costs a billed " \
+          "round-trip and is budgeted per child; prefer the free snapshot). You can " \
+          "ONLY probe subagents you started (your direct children)."
+      end
+
+      def input_schema
+        {
+          type: "object",
+          properties: {
+            task_id: { type: "string", description: "The id (sa_…) of YOUR subagent to probe." },
+            question: { type: "string",
+                        description: "What you want to know. For a free snapshot this frames the check; for live:true it is the question the child answers from its context." },
+            live: {
+              type: "boolean",
+              description: "false (default) = FREE instant snapshot from the registry, no model call. " \
+                           "true = billed one-shot model peek over the child's transcript (budgeted per child)."
+            }
+          },
+          required: %w[task_id question]
+        }
+      end
+
+      def risk_level
+        :low
+      end
+
+      def call(arguments)
+        task_id  = (arguments["task_id"]  || arguments[:task_id]).to_s.strip
+        question = (arguments["question"] || arguments[:question]).to_s.strip
+        live     = live_arg(arguments)
+
+        caller_id = Rubino.current_subagent_id
+        registry  = BackgroundTasks.instance
+        entry     = task_id.empty? ? nil : registry.find(task_id)
+
+        return "Cannot probe #{task_id} — no such subagent." unless entry
+        return "Error: question is required" if question.empty?
+        unless registry.owned_by?(caller_id, task_id)
+          return "Error: #{task_id} is not one of your subagents — you can only probe children you started."
+        end
+        # A child parked on a BLOCKING ask_parent has no live activity to peek
+        # at — its pending tool_use is not in the persisted snapshot, so a
+        # billed live peek would honestly answer "I never called ask_parent"
+        # while task_result says blocked (#198). Short-circuit with the parked
+        # question and the one action that unblocks it (no billed peek).
+        return blocked_on_ask_answer(entry) if parked_on_ask?(entry)
+
+        live ? probe_live(registry, entry, question) : probe_cheap(entry)
+      end
+
+      private
+
+      # live defaults to FALSE (the free, unbilled snapshot). Only an explicit
+      # true opts into the billed model peek.
+      def live_arg(arguments)
+        raw = arguments.key?("live") ? arguments["live"] : arguments[:live]
+        [true, "true", 1, "1"].include?(raw)
+      end
+
+      def just_started?(entry)
+        entry.tool_count.to_i.zero?
+      end
+
+      # True when the child's thread is PARKED on a blocking ask_parent gate
+      # (a non-blocking ask keeps the blocked status on the card but the child
+      # keeps working, so it stays probeable).
+      def parked_on_ask?(entry)
+        entry.ask_gate && entry.ask_blocking &&
+          %i[blocked_on_human blocked_on_parent].include?(entry.status)
+      end
+
+      def blocked_on_ask_answer(entry)
+        "probe #{entry.id} · #{entry.subagent} · BLOCKED on ask_parent waiting for YOUR answer — " \
+          "question:\n#{entry.ask_question}\n" \
+          "Answer with answer_child(task_id: \"#{entry.id}\", answer: \"…\") to unblock it."
+      end
+
+      # FREE path: render the live-progress fields only. NO model call.
+      def probe_cheap(entry)
+        recent = Array(entry.activity_log).last(RECENT_MAX)
+        lines  = recent.empty? ? "(none yet)" : recent.join("\n")
+        out = "probe #{entry.id} · #{entry.subagent} · #{entry.status} · " \
+              "#{entry.tool_count.to_i} tools · last: #{entry.last_activity || "—"}\n" \
+              "recent:\n#{lines}"
+        out += "\n#{JUST_STARTED_HINT}" if just_started?(entry)
+        out
+      end
+
+      # BILLED path: enforce the per-child budget, then run the one-shot peek.
+      # peek is best-effort (never raises) — a failure is reported inline.
+      def probe_live(registry, entry, question)
+        max = max_live_probes
+        if entry.probe_count.to_i >= max
+          return "Error: live-probe budget exhausted for #{entry.id} (max #{max} per child). " \
+                 "Use live:false for a free snapshot."
+        end
+
+        registry.record_live_probe(entry.id)
+        answer = probe_engine.peek(entry: entry, question: question)
+        out    = "probe #{entry.id} (live) ⟵ #{answer}"
+        out += "\n#{JUST_STARTED_HINT}" if just_started?(entry)
+        out
+      end
+
+      def probe_engine
+        @probe ||= SubagentProbe.new
+      end
+
+      def max_live_probes
+        cfg = Rubino.configuration if Rubino.respond_to?(:configuration)
+        Integer(cfg&.tasks_max_live_probes_per_child)
+      rescue StandardError, TypeError, ArgumentError
+        5
+      end
+    end
+  end
+end

data/lib/rubino/tools/question_tool.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Rubino
+  module Tools
+    # Tool that asks the user interactive questions with predefined options.
+    # Allows the agent to gather clarification or preferences from the user.
+    class QuestionTool < Base
+      def name
+        "question"
+      end
+
+      def description
+        "Ask the user a question with optional predefined choices. " \
+          "Use this when you need clarification, user preferences, or a decision. " \
+          "The user can select from options or type a custom answer."
+      end
+
+      def input_schema
+        {
+          type: "object",
+          properties: {
+            question: {
+              type: "string",
+              description: "The question to ask the user"
+            },
+            options: {
+              type: "array",
+              items: {
+                type: "object",
+                properties: {
+                  label: { type: "string", description: "Short display text for the option" },
+                  description: { type: "string", description: "Explanation of this choice" }
+                },
+                required: %w[label]
+              },
+              description: "Available choices (optional). A 'Type your own' option is added automatically."
+            },
+            multiple: {
+              type: "boolean",
+              description: "Allow selecting multiple choices (default: false)"
+            }
+          },
+          required: %w[question]
+        }
+      end
+
+      def risk_level
+        :low
+      end
+
+      # Deterministic result when no user answer is available — the UI's #ask
+      # returned nil (non-interactive / piped session, or the user gave no
+      # response). Fail closed instead of reading ambient stdin or silently
+      # picking an option (#107): never assume a choice on the user's behalf.
+      NO_ANSWER = "No answer: no interactive user input available " \
+                  "(non-interactive session, or the user gave no response). " \
+                  "Do not assume a choice on the user's behalf; proceed with the " \
+                  "safest option and state the assumption, or finish and report " \
+                  "the open question."
+
+      def call(arguments)
+        question = arguments["question"] || arguments[:question]
+        options = arguments["options"] || arguments[:options]
+        multiple = arguments["multiple"] || arguments[:multiple] || false
+
+        ui = Rubino.ui
+
+        if options && !options.empty?
+          ask_with_options(ui, question, options, multiple)
+        else
+          ask_freeform(ui, question)
+        end
+      end
+
+      private
+
+      def ask_with_options(ui, question, options, multiple)
+        # Format options for display
+        formatted = options.map do |opt|
+          label = opt["label"] || opt[:label]
+          desc  = opt["description"] || opt[:description]
+          desc ? "#{label} - #{desc}" : label
+        end
+
+        # Build a SINGLE prompt carrying the question, the numbered options, the
+        # multiple-select hint, and the trailing instruction. On the API path the
+        # whole prompt becomes the clarify.required event's `question` payload, so
+        # the web clarify box renders the question next to the input (instead of
+        # only the generic "Your choice…" line, with the question lost up top).
+        lines = [question]
+        formatted.each_with_index do |opt, i|
+          lines << "  #{i + 1}. #{opt}"
+        end
+        lines << "  (Select multiple numbers separated by commas, or type a custom answer)" if multiple
+        lines << "Your choice#{"(s)" if multiple} (number or custom answer):"
+
+        answer = ui.ask(lines.join("\n"))
+        return NO_ANSWER if answer.nil?
+
+        # Parse single or multiple numeric selections
+        if multiple && answer&.match?(/\A[\d,\s]+\z/)
+          indices = answer.scan(/\d+/).map { |n| n.to_i - 1 }
+          selected = indices.filter_map do |idx|
+            options[idx]["label"] || options[idx][:label] if idx >= 0 && idx < options.size
+          end
+          selected.empty? ? "User answered: #{answer}" : "User selected: #{selected.join(", ")}"
+        elsif answer&.match?(/\A\d+\z/)
+          idx = answer.to_i - 1
+          if idx >= 0 && idx < options.size
+            selected = options[idx]
+            "User selected: #{selected["label"] || selected[:label]}"
+          else
+            "User answered: #{answer}"
+          end
+        else
+          "User answered: #{answer}"
+        end
+      end
+
+      def ask_freeform(ui, question)
+        answer = ui.ask(question)
+        return NO_ANSWER if answer.nil?
+
+        "User answered: #{answer}"
+      end
+    end
+  end
+end