rubino-agent 0.3.0

data/lib/rubino/tools/test_tool.rb

@@ -0,0 +1,454 @@
+# frozen_string_literal: true
+
+module Rubino
+  module Tools
+    # Runs the workspace project's test suite and returns a STRUCTURED result
+    # instead of the raw toolchain firehose the `shell` tool emits.
+    #
+    # Why this exists (issue #101): to run tests the model used to drive `shell`
+    # and reason its way through the whole Ruby toolchain — bundler version
+    # mismatches, missing gems, which command to use. On real tasks that burned
+    # several tool calls and twice sent the agent chasing toolchain errors
+    # (bundler `GemNotFound`, an `undefined method 'untaint'` crash from an old
+    # pinned bundler) instead of the user's actual request; one earlier run even
+    # drifted toward `gem uninstall bundler` / `rm -rf …`. This tool:
+    #
+    #   - auto-detects the framework (rspec / minitest / rake) and the right
+    #     invocation, preferring `bundle exec` when a Gemfile is present and the
+    #     bundle is usable, falling back to the bare runner when it is not (so a
+    #     stale lockfile degrades gracefully rather than making the model fight
+    #     bundler),
+    #   - returns pass/fail counts, the failing examples (name + file:line +
+    #     short message) parsed from the runner output, and a short raw tail —
+    #     not the full backtrace,
+    #   - distinguishes "the suite could not even start" (toolchain error) from
+    #     "the suite ran and N failed", via the structured `error_code`.
+    #
+    # Execution mirrors ShellTool's foreground path: own process group, SIGTERM
+    # on timeout/cancel, cwd = workspace root (same resolution as ruby/shell).
+    class TestTool < Base
+      DEFAULT_TIMEOUT = 300
+      MAX_TIMEOUT     = 600
+      TICK            = 0.05
+      # Lines of raw runner output to keep for context. Enough to show the
+      # tail of a failure dump without dragging the full backtrace into context.
+      RAW_TAIL_LINES  = 40
+
+      def name
+        "run_tests"
+      end
+
+      def description
+        "Run the workspace project's test suite and return a structured result " \
+          "(framework, command, exit status, example/failure counts, and the " \
+          "failing examples with file:line and message). Auto-detects RSpec, " \
+          "Minitest, or a Rakefile default task; prefers `bundle exec` when a " \
+          "Gemfile is present and falls back to the bare runner if the bundle is " \
+          "broken. Optional `path` runs a single file or pattern; optional " \
+          "`framework` (rspec/minitest/rake) overrides detection. Use this " \
+          "instead of driving `shell` by hand to run tests."
+      end
+
+      def input_schema
+        {
+          type: "object",
+          properties: {
+            path: {
+              type: "string",
+              description: "Optional file or pattern to run a subset (e.g. " \
+                           "'spec/models/user_spec.rb' or 'spec/models/'). " \
+                           "Runs the whole suite when omitted."
+            },
+            framework: {
+              type: "string",
+              enum: %w[rspec minitest rake],
+              description: "Override framework detection. Omit to auto-detect."
+            },
+            timeout: {
+              type: "integer",
+              description: "Timeout in seconds (default #{DEFAULT_TIMEOUT}, max #{MAX_TIMEOUT})."
+            }
+          },
+          required: []
+        }
+      end
+
+      # Runs project code (the test suite), so gated like `ruby`: not
+      # destructive, but it does execute arbitrary code. :medium → asks in
+      # manual mode, auto-allowed in auto mode.
+      def risk_level
+        :medium
+      end
+
+      def call(arguments)
+        args      = arguments.is_a?(Hash) ? arguments : {}
+        path      = args["path"]      || args[:path]
+        override  = args["framework"] || args[:framework]
+        timeout   = (args["timeout"]  || args[:timeout] || DEFAULT_TIMEOUT).to_i
+        timeout   = [[timeout, 1].max, MAX_TIMEOUT].min
+
+        root = resolve_workspace
+        return { output: "Error: cannot access workspace directory", error_code: :workspace_error } unless root
+
+        framework = (override && !override.to_s.empty? ? override.to_s : detect_framework(root))
+        unless framework
+          return { output: "Error: no test setup detected in #{root} — looked for " \
+                           "spec/ (.rspec), test/, and a Rakefile. Pass `framework` " \
+                           "to override, or use the shell tool for a custom command.",
+                   error_code: :no_test_setup }
+        end
+
+        command = build_command(root, framework, path)
+        run     = execute(command, root, timeout)
+
+        build_result(framework, command, run)
+      end
+
+      private
+
+      # Same cwd resolution as ruby_tool/shell_tool: terminal.cwd or Dir.pwd,
+      # fully resolved through symlinks. nil if it can't be reached.
+      def resolve_workspace
+        candidate = Rubino::Workspace.primary_root
+        path = File.realpath(File.expand_path(candidate))
+        File.directory?(path) ? path : nil
+      rescue Errno::ENOENT, Errno::EACCES, Errno::ELOOP
+        nil
+      end
+
+      # Detection order mirrors the issue: RSpec first (most common in gems),
+      # then Minitest, then a bare Rakefile default task.
+      def detect_framework(root)
+        return "rspec"    if rspec?(root)
+        return "minitest" if minitest?(root)
+        return "rake"     if File.exist?(File.join(root, "Rakefile"))
+
+        nil
+      end
+
+      def rspec?(root)
+        File.exist?(File.join(root, ".rspec")) ||
+          File.directory?(File.join(root, "spec"))
+      end
+
+      def minitest?(root)
+        return false unless File.directory?(File.join(root, "test"))
+
+        # A `test/` dir alone is the signal; rake/rails drive it. We don't try
+        # to grep for `require "minitest"` — too fragile across layouts.
+        true
+      end
+
+      def gemfile?(root)
+        File.exist?(File.join(root, "Gemfile"))
+      end
+
+      # Prefer `bundle exec` when a Gemfile is present AND the bundle resolves;
+      # otherwise fall back to the bare runner. The fallback is the whole point
+      # of #101: a stale/pinned lockfile must not make the model fight bundler.
+      def build_command(root, framework, path)
+        bundle = gemfile?(root) && bundle_usable?(root)
+        prefix = bundle ? "bundle exec " : ""
+
+        case framework
+        when "rspec"
+          target = path && !path.to_s.empty? ? " #{shellescape(path)}" : ""
+          "#{prefix}rspec#{target}"
+        when "minitest"
+          build_minitest_command(root, prefix, path)
+        when "rake"
+          "#{prefix}rake"
+        end
+      end
+
+      # `rake test` is the canonical entry for a Minitest project (it sets up
+      # $LOAD_PATH and picks up test/**). When the model wants a single file we
+      # can't go through rake's task, so run it with ruby -Itest -Ilib directly.
+      def build_minitest_command(root, prefix, path)
+        if path && !path.to_s.empty?
+          "#{prefix}ruby -Itest -Ilib #{shellescape(path)}"
+        elsif rails?(root)
+          "#{prefix}bin/rails test"
+        else
+          "#{prefix}rake test"
+        end
+      end
+
+      def rails?(root)
+        File.exist?(File.join(root, "bin", "rails"))
+      end
+
+      # Cheap, non-mutating bundle check: `bundle check` exits 0 only when the
+      # gems in the lockfile are installed and satisfiable. Catches the #101
+      # cases (version-mismatched / pinned-bundler lockfiles) before we commit
+      # to `bundle exec`, so we degrade to the bare runner instead of letting
+      # the model watch a bundler backtrace scroll by. Capped tight so a slow
+      # `bundle check` never dominates the call.
+      def bundle_usable?(root)
+        _, status = Open3.capture2e(
+          { "BUNDLE_GEMFILE" => File.join(root, "Gemfile") },
+          "bundle", "check",
+          chdir: root
+        )
+        status&.success?
+      rescue StandardError
+        # bundler not installed, or it crashed (the untaint-style failure):
+        # treat the bundle as unusable and fall back to the bare runner.
+        false
+      end
+
+      def shellescape(str)
+        require "shellwords"
+        Shellwords.escape(str.to_s)
+      end
+
+      # Foreground exec in its own process group, SIGTERM on timeout/cancel.
+      # Merged stdout+stderr — the runners interleave results and warnings, and
+      # we parse the combined stream anyway. Returns a structured run hash.
+      def execute(command, cwd, timeout)
+        require "open3"
+        rd, wr = IO.pipe
+        pid    = Process.spawn(command, chdir: cwd, pgroup: true, out: wr, err: wr)
+        pgid   = pid
+        wr.close
+
+        buf = +""
+        reader = Thread.new do
+          rd.each_line do |line|
+            buf << line
+            emit_chunk(line)
+          end
+        rescue IOError, Errno::EBADF
+          # pipe closed — process exited
+        ensure
+          rd.close unless rd.closed?
+        end
+
+        started  = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        deadline = Time.now + timeout
+        status   = nil
+
+        loop do
+          wpid, status = Process.waitpid2(pid, Process::WNOHANG)
+          break if wpid
+
+          if cancellation_requested?
+            terminate_group(pgid)
+            reader.join(0.5)
+            begin
+              Process.kill("KILL", -pgid)
+            rescue StandardError
+              nil
+            end
+            begin
+              Process.waitpid2(pid)
+            rescue StandardError
+              nil
+            end
+            return { output: buf.dup, exit_code: nil, cancelled: true, timed_out: false,
+                     duration_ms: elapsed_ms(started) }
+          end
+
+          if Time.now >= deadline
+            terminate_group(pgid)
+            _, status = Process.waitpid2(pid, Process::WNOHANG)
+            unless status
+              reader.join(2)
+              begin
+                Process.kill("KILL", -pgid)
+              rescue StandardError
+                nil
+              end
+              _, status = Process.waitpid2(pid)
+            end
+            reader.join(0.5)
+            return { output: buf.dup, exit_code: nil, cancelled: false, timed_out: true,
+                     duration_ms: elapsed_ms(started) }
+          end
+
+          sleep TICK
+        end
+
+        reader.join
+        { output: buf, exit_code: status&.exitstatus, cancelled: false, timed_out: false,
+          duration_ms: elapsed_ms(started) }
+      rescue StandardError => e
+        { output: "Error launching tests: #{e.message}", exit_code: nil, cancelled: false,
+          timed_out: false, started_error: true, duration_ms: 0 }
+      ensure
+        rd.close if rd && !rd.closed?
+      end
+
+      def terminate_group(pgid)
+        Process.kill("TERM", -pgid)
+      rescue Errno::ESRCH, Errno::EPERM
+        # already gone / not ours
+      end
+
+      def elapsed_ms(started)
+        ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000).round
+      end
+
+      # Turns the run hash into the model-facing structured Result. Parses the
+      # combined output into counts + failing examples, classifies the outcome,
+      # and keeps a short raw tail for context.
+      def build_result(framework, command, run)
+        raw     = run[:output].to_s
+        parsed  = parse_output(framework, raw)
+        ran     = parsed[:ran]
+        tail    = tail_lines(raw)
+
+        outcome, error_code = classify(run, parsed)
+
+        summary = build_summary(framework, command, run, parsed, outcome)
+        body    = [summary, "", "--- raw output (tail) ---", tail].join("\n")
+
+        {
+          output: body,
+          body: summary,
+          body_kind: :plain,
+          metrics: "#{outcome} · #{format_ms(run[:duration_ms])}",
+          error_code: error_code,
+          # Structured fields, so the executor / future contract tests can
+          # branch without re-parsing the text.
+          framework: framework,
+          command: command,
+          exit_code: run[:exit_code],
+          ran: ran,
+          examples: parsed[:examples],
+          failures: parsed[:failures],
+          failing: parsed[:failing]
+        }
+      end
+
+      # outcome label + error_code symbol. The critical distinction (#101):
+      # the suite NOT starting (toolchain error) vs. running with failures.
+      def classify(run, parsed)
+        return ["cancelled", :cancelled]      if run[:cancelled]
+        return ["timeout", :timeout]          if run[:timed_out]
+        return ["could not start", :test_runner_error] if run[:started_error] || !parsed[:ran]
+        return ["#{parsed[:failures]} failed", :tests_failed] if parsed[:failures].to_i.positive?
+        return ["nonzero exit", :exit_nonzero] if run[:exit_code] && run[:exit_code] != 0
+
+        ["passed", nil]
+      end
+
+      def build_summary(framework, command, run, parsed, outcome)
+        lines = []
+        lines << "framework: #{framework}"
+        lines << "command:   #{command}"
+        lines << "exit:      #{run[:exit_code].nil? ? "(none)" : run[:exit_code]}"
+        lines << "outcome:   #{outcome}"
+        if parsed[:ran]
+          lines << "examples:  #{parsed[:examples].nil? ? "?" : parsed[:examples]}"
+          lines << "failures:  #{parsed[:failures].nil? ? "?" : parsed[:failures]}"
+          unless parsed[:failing].empty?
+            lines << "failing:"
+            parsed[:failing].each do |f|
+              loc  = f[:location] ? " (#{f[:location]})" : ""
+              desc = f[:description].to_s
+              msg  = f[:message].to_s.empty? ? "" : " — #{f[:message]}"
+              lines << "  - #{desc}#{loc}#{msg}"
+            end
+          end
+        else
+          lines << "note:      the suite did not run (toolchain/setup error) — " \
+                   "see the raw tail below"
+        end
+        lines.join("\n")
+      end
+
+      def tail_lines(raw)
+        lines = raw.lines.map(&:chomp)
+        return raw.chomp if lines.size <= RAW_TAIL_LINES
+
+        ["… [#{lines.size - RAW_TAIL_LINES} earlier lines omitted] …"]
+          .concat(lines.last(RAW_TAIL_LINES)).join("\n")
+      end
+
+      def parse_output(framework, raw)
+        case framework
+        when "rspec"          then parse_rspec(raw)
+        when "minitest"       then parse_minitest(raw)
+        else                       parse_generic(raw)
+        end
+      end
+
+      # RSpec: "N examples, M failures[, K pending]" summary line, and the
+      # "Failures:" block with "rspec ./path:line # description".
+      def parse_rspec(raw)
+        summary = raw.match(/(\d+)\s+examples?,\s+(\d+)\s+failures?/)
+        return parse_generic(raw) unless summary
+
+        examples = summary[1].to_i
+        failures = summary[2].to_i
+
+        failing = []
+        # The rerun lines RSpec prints at the bottom give location +
+        # description; the numbered Failures: block gives the message.
+        messages = rspec_failure_messages(raw)
+        raw.scan(%r{^rspec\s+(\.?/?\S+:\d+)\s+#\s+(.+)$}).each_with_index do |(loc, desc), i|
+          failing << { description: desc.strip, location: loc.strip, message: messages[i] }
+        end
+
+        { ran: true, examples: examples, failures: failures, failing: failing }
+      end
+
+      # Pulls the first line of each numbered failure block in RSpec's
+      # "Failures:" section: "  1) Some description\n     Failure/Error: ...\n
+      # <message>". We grab the message line(s) after Failure/Error.
+      def rspec_failure_messages(raw)
+        section = raw[/^Failures:\n(.*?)(?:\n\nFinished|\n\n\d+ examples?)/m, 1]
+        return [] unless section
+
+        section.split(/^\s*\d+\)\s/).reject(&:empty?).map do |block|
+          msg = block[%r{Failure/Error:.*?\n\s*\n?\s*(.+)}m, 1] ||
+                block[%r{Failure/Error:\s*(.+)}, 1]
+          msg.to_s.lines.first.to_s.strip
+        end
+      end
+
+      # Minitest: "N runs, M assertions, F failures, E errors, S skips".
+      # Failures/errors print as numbered blocks headed by
+      # "TestClass#test_name [file:line]:".
+      def parse_minitest(raw)
+        summary = raw.match(/(\d+)\s+runs?,\s+(\d+)\s+assertions?,\s+(\d+)\s+failures?,\s+(\d+)\s+errors?/)
+        return parse_generic(raw) unless summary
+
+        runs     = summary[1].to_i
+        failures = summary[3].to_i + summary[4].to_i # failures + errors
+
+        failing = []
+        raw.scan(/^\s*\d+\)\s+(?:Failure|Error):\n\s*(\S+)\s*\[([^\]]+)\]:\n(.+)/).each do |name, loc, msg|
+          failing << { description: name.strip, location: loc.strip, message: msg.to_s.lines.first.to_s.strip }
+        end
+        # Some minitest reporters omit the "Failure:/Error:" label line.
+        if failing.empty?
+          raw.scan(/^\s*\d+\)\s+(\S+#\S+)\s*\[([^\]]+)\]:\n(.+)/).each do |name, loc, msg|
+            failing << { description: name.strip, location: loc.strip, message: msg.to_s.lines.first.to_s.strip }
+          end
+        end
+
+        { ran: true, examples: runs, failures: failures, failing: failing }
+      end
+
+      # No recognizable summary line: we can't trust counts. Treat as "ran" only
+      # if there's a hint the runner produced test output; otherwise leave ran
+      # to the exit-code classifier (started_error / nonzero) upstream.
+      def parse_generic(raw)
+        ran = raw.match?(/\d+\s+(examples?|runs?|tests?)/) ||
+              raw.match?(/Finished in/)
+        { ran: ran, examples: nil, failures: nil, failing: [] }
+      end
+
+      def format_ms(ms)
+        if ms < 1000      then "#{ms}ms"
+        elsif ms < 60_000 then "#{(ms / 1000.0).round(1)}s"
+        else
+          mins, rem = ms.divmod(60_000)
+          "#{mins}m#{(rem / 1000.0).round}s"
+        end
+      end
+    end
+  end
+end

data/lib/rubino/tools/todo_tool.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Rubino
+  module Tools
+    # Tool for managing a task/todo list during a session.
+    # Allows the agent to track progress on complex multi-step tasks.
+    class TodoTool < Base
+      def name
+        "todowrite"
+      end
+
+      def description
+        "Create and manage a structured task list for the current session. " \
+          "Use this to track progress on complex multi-step tasks. " \
+          "Tasks have content, status (pending/in_progress/completed/cancelled), and priority."
+      end
+
+      def input_schema
+        {
+          type: "object",
+          properties: {
+            todos: {
+              type: "array",
+              items: {
+                type: "object",
+                properties: {
+                  content: { type: "string", description: "Brief description of the task" },
+                  status: {
+                    type: "string",
+                    enum: %w[pending in_progress completed cancelled],
+                    description: "Current task status"
+                  },
+                  priority: {
+                    type: "string",
+                    enum: %w[high medium low],
+                    description: "Task priority level"
+                  }
+                },
+                required: %w[content status priority]
+              },
+              description: "The complete updated todo list"
+            }
+          },
+          required: %w[todos]
+        }
+      end
+
+      def risk_level
+        :low
+      end
+
+      def call(arguments)
+        todos = arguments["todos"] || arguments[:todos]
+        return "Error: No todos provided" unless todos.is_a?(Array)
+
+        format_todo_summary(todos)
+      end
+
+      private
+
+      def format_todo_summary(todos)
+        completed = todos.count { |t| t["status"] == "completed" || t[:status] == "completed" }
+        in_progress = todos.count { |t| t["status"] == "in_progress" || t[:status] == "in_progress" }
+        pending = todos.count { |t| t["status"] == "pending" || t[:status] == "pending" }
+        cancelled = todos.count { |t| t["status"] == "cancelled" || t[:status] == "cancelled" }
+
+        lines = ["Todo list updated (#{todos.size} items):"]
+        lines << "  Completed: #{completed}" if completed > 0
+        lines << "  In Progress: #{in_progress}" if in_progress > 0
+        lines << "  Pending: #{pending}" if pending > 0
+        lines << "  Cancelled: #{cancelled}" if cancelled > 0
+        lines << ""
+
+        todos.each do |todo|
+          content = todo["content"] || todo[:content]
+          status = todo["status"] || todo[:status]
+          priority = todo["priority"] || todo[:priority]
+
+          icon = case status
+                 when "completed" then "[x]"
+                 when "in_progress" then "[>]"
+                 when "cancelled" then "[-]"
+                 else "[ ]"
+                 end
+
+          lines << "  #{icon} #{content} (#{priority})"
+        end
+
+        lines.join("\n")
+      end
+    end
+  end
+end

data/lib/rubino/tools/tool_call_repository.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "json"
+
+module Rubino
+  module Tools
+    # Persists tool call audit records to the database.
+    # Extracted from Agent::ToolExecutor to respect the separation between
+    # domain execution logic and storage concerns.
+    class ToolCallRepository
+      # Persists a tool call record. Failures are swallowed so that a
+      # database outage never causes a tool call to fail.
+      def record(name:, call_id:, arguments:, result:, status:, error: nil)
+        now = Time.now.utc.iso8601
+        Rubino.database.db[:tool_calls].insert(
+          id: call_id || SecureRandom.uuid,
+          session_id: result.session_id,
+          tool_name: name,
+          input_json: JSON.generate(arguments),
+          output: result.output,
+          status: status,
+          started_at: now,
+          finished_at: now,
+          error: error
+        )
+      rescue StandardError
+        # Don't fail the tool call just because audit persistence failed.
+        nil
+      end
+    end
+  end
+end

data/lib/rubino/tools/vision_tool.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require_relative "../llm/auxiliary_client"
+
+module Rubino
+  module Tools
+    # Delegates image-understanding to a multimodal aux model so a text-only
+    # primary can still "see" what the user uploaded. Implements the
+    # agent-as-tool semantics from the OpenAI Agents SDK: the primary stays
+    # in control, calls this tool with a focused question, and receives a
+    # structured (text) reply — no conversation handoff, no shared history.
+    #
+    # The aux model is resolved from `auxiliary.vision` in config. When the
+    # primary already supports vision (per Configuration#model_supports_vision?)
+    # AND no aux is configured, Registry hides this tool — there's no useful
+    # delegation to perform.
+    class VisionTool < Base
+      def name
+        "vision"
+      end
+
+      def description
+        "Ask a multimodal model to describe or interpret an image. " \
+          "Use when you need to understand visual content (charts, screenshots, " \
+          "diagrams, photos). Provide an optional focused question to direct the " \
+          "analysis; default is a full markdown description."
+      end
+
+      def input_schema
+        {
+          type: "object",
+          properties: {
+            file_path: {
+              type: "string",
+              description: "Absolute path to an image file (.png .jpg .jpeg .webp .gif .bmp)"
+            },
+            question: {
+              type: "string",
+              description: "Optional focused question. Default: 'Describe what you see in markdown.'"
+            }
+          },
+          required: %w[file_path]
+        }
+      end
+
+      def risk_level
+        :low
+      end
+
+      def call(arguments)
+        path     = (arguments["file_path"] || arguments[:file_path]).to_s
+        question = (arguments["question"]  || arguments[:question] ||
+                    "Describe what you see in markdown.").to_s
+
+        return "Error: file_path is required" if path.empty?
+
+        expanded = File.expand_path(path)
+        return "Error: file not found: #{path}" unless File.exist?(expanded)
+        return "Error: not a regular file: #{path}" unless File.file?(expanded)
+
+        ext = File.extname(expanded).downcase
+        unless LLM::ContentBuilder::SUPPORTED_IMAGE_TYPES.include?(ext)
+          return "Error: unsupported image extension '#{ext}'. " \
+                 "Supported: #{LLM::ContentBuilder::SUPPORTED_IMAGE_TYPES.join(", ")}"
+        end
+
+        # Pass the image through ruby_llm's native `with:` slot (image_paths),
+        # NOT as an OpenAI-style content array. ruby_llm's `ask` stringifies an
+        # array content, so the base64 bytes would reach the model as TEXT and
+        # it hallucinates (prod sessions 38/41: M3 saw the image perfectly when
+        # called directly, but got a text blob through this path). image_paths
+        # attaches the file as a real multimodal part — same route the primary
+        # uses for native vision.
+        response = LLM::AuxiliaryClient.new.call(
+          task: :vision,
+          messages: [{ role: "user", content: question }],
+          image_paths: [expanded]
+        )
+        response.content.to_s
+      rescue StandardError => e
+        "Error calling vision model: #{e.class}: #{e.message}"
+      end
+    end
+  end
+end