rubino-agent 0.3.0

data/lib/rubino/tools/result.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Rubino
+  module Tools
+    # Encapsulates the result of a tool execution.
+    class Result
+      attr_reader :name, :call_id, :output, :status, :error, :session_id,
+                  :metrics, :error_code, :artifact
+
+      # `error_code` is an optional Symbol surface for callers (UI badges,
+      # automation, future contract tests) that want to branch on the
+      # failure mode without parsing the human-facing error string. Today
+      # the canonical signal is still the output text — the symbol is a
+      # belt-and-suspenders next to it, not a replacement.
+      #
+      # `artifact` is an optional Hash carrying { path:, filename:,
+      # content_type:, byte_size: } when a tool produced a downloadable
+      # user-facing file. The agent loop reads this and emits an
+      # ARTIFACT_CREATED bus event so SSE consumers (the web UI, the CLI)
+      # can offer a download.
+      def initialize(name:, call_id:, output:, status:, error: nil,
+                     metrics: nil, error_code: nil, artifact: nil)
+        @name = name
+        @call_id = call_id
+        @output = output
+        @status = status
+        @error = error
+        @metrics = metrics
+        @error_code = error_code
+        @artifact = artifact
+        @session_id = nil
+      end
+
+      def success?
+        @status == :success
+      end
+
+      def failed?
+        @status == :error
+      end
+
+      def denied?
+        @status == :denied
+      end
+
+      # True when this result represents a failure for DISPLAY purposes, even
+      # when the tool didn't raise. Many tools (read, edit, …) report a soft
+      # failure by RETURNING an "Error: …" string (status stays :success) or by
+      # setting an error_code, instead of raising. The CLI used to render those
+      # as a green "✓ done" because it only checked #success?. This is the
+      # single predicate the UI uses so an errored tool shows "✗" regardless of
+      # which failure convention the tool used.
+      def errorish?
+        return true unless success?
+        return true unless @error_code.nil?
+
+        @output.to_s.start_with?("Error:")
+      end
+
+      # Returns a truncated preview for display
+      def truncated_preview(max_length: 80)
+        text = @output.to_s
+        text.length > max_length ? "#{text[0...max_length]}..." : text
+      end
+
+      # Substituted when a tool legitimately produces no output (e.g. `touch`).
+      # The string survives persistence and load_history, where nil/"" would
+      # be dropped and leave a tool_call orphaned — the provider then 400s
+      # the next turn for a tool_call with no matching tool_result.
+      EMPTY_OUTPUT_PLACEHOLDER = "(no output)"
+
+      # Factory methods
+      def self.success(name:, call_id:, output:, metrics: nil, error_code: nil, artifact: nil)
+        new(name: name, call_id: call_id, output: normalize_output(output),
+            status: :success, metrics: metrics, error_code: error_code, artifact: artifact)
+      end
+
+      def self.error(name:, call_id:, error:, error_code: nil)
+        msg = error.to_s
+        msg = "unknown error" if msg.empty?
+        new(name: name, call_id: call_id, output: "Error: #{msg}", status: :error,
+            error: error, error_code: error_code)
+      end
+
+      # Model-facing text per denial reason (#143). Only a real human decision
+      # may read "denied by user" — an automatic denial must name the policy
+      # that fired, otherwise a child agent reports (and propagates upward)
+      # that "the user denied my tools" when no human ever decided anything.
+      DENIED_OUTPUTS = {
+        user: "Tool execution denied by user.",
+        policy: "Tool execution denied by policy (not by the user).",
+        hardline: "Tool execution blocked by policy (hardline safety floor, not by the user): " \
+                  "this command is never allowed.",
+        permission_rule: "Tool execution blocked by policy (a configured permissions deny rule, " \
+                         "not by the user).",
+        doom_loop: "Tool execution blocked by the doom-loop guard (policy, not by the user): " \
+                   "this exact call was already made repeatedly. Change strategy instead of " \
+                   "retrying it — e.g. wait for the background-task completion notice instead " \
+                   "of polling."
+      }.freeze
+
+      def self.denied(name:, call_id:, reason: :user)
+        key = DENIED_OUTPUTS.key?(reason) ? reason : :policy
+        new(name: name, call_id: call_id, output: DENIED_OUTPUTS[key], status: :denied)
+      end
+
+      def self.normalize_output(output)
+        text = output.to_s
+        text.empty? ? EMPTY_OUTPUT_PLACEHOLDER : text
+      end
+    end
+  end
+end

data/lib/rubino/tools/session_search_tool.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Rubino
+  module Tools
+    # Full-text search across the agent's own message history, backed by the
+    # `messages_fts` FTS5 index. Lets the model recall prior conversations
+    # without forcing the user to paste them back in.
+    #
+    # Returns a JSON array of match hits with a highlighted snippet so the
+    # model can decide whether to follow up with /v1/sessions/:id.
+    class SessionSearchTool < Base
+      DEFAULT_LIMIT = 20
+      MAX_LIMIT     = 100
+
+      def name
+        "session_search"
+      end
+
+      def description
+        "Full-text search across past session messages. " \
+          "Returns matched messages with highlighted snippets and the owning session id. " \
+          "Use to recall earlier conversations or look up what a tool returned previously."
+      end
+
+      def input_schema
+        {
+          type: "object",
+          properties: {
+            query: {
+              type: "string",
+              description: "Free-text search query (FTS5 MATCH)."
+            },
+            since: {
+              type: "string",
+              description: "ISO8601 lower bound on message created_at."
+            },
+            until: {
+              type: "string",
+              description: "ISO8601 upper bound on message created_at."
+            },
+            role: {
+              type: "string",
+              enum: %w[user assistant tool],
+              description: "Restrict to a single message role."
+            },
+            tool: {
+              type: "string",
+              description: "Restrict to a specific tool_name (when role=tool)."
+            },
+            limit: {
+              type: "integer",
+              description: "Max results to return (default 20, max 100)."
+            }
+          },
+          required: %w[query]
+        }
+      end
+
+      def risk_level
+        :low
+      end
+
+      def call(arguments)
+        query = arguments["query"] || arguments[:query]
+        return "Error: query is required" if query.nil? || query.to_s.strip.empty?
+
+        limit = (arguments["limit"] || arguments[:limit] || DEFAULT_LIMIT).to_i
+        limit = DEFAULT_LIMIT if limit <= 0
+        limit = MAX_LIMIT if limit > MAX_LIMIT
+
+        rows = store.search(
+          query: query,
+          since: arguments["since"] || arguments[:since],
+          until_: arguments["until"] || arguments[:until],
+          role: arguments["role"] || arguments[:role],
+          tool: arguments["tool"] || arguments[:tool],
+          limit: limit
+        )
+
+        results = rows.map do |row|
+          {
+            session_id: row[:session_id],
+            run_id: row[:run_id],
+            message_id: row[:message_id],
+            role: row[:role],
+            snippet: row[:snippet],
+            created_at: row[:created_at]
+          }
+        end
+
+        JSON.generate(results)
+      end
+
+      private
+
+      def store
+        @store ||= Rubino::Session::Store.new
+      end
+    end
+  end
+end

data/lib/rubino/tools/shell_input_tool.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Rubino
+  module Tools
+    # Feeds input to a background shell's stdin (registered by ShellTool when
+    # run_in_background: true). This is how the agent answers an interactive
+    # prompt a running command emits — Y/N confirmations, "select region"
+    # menus, apt-style questions — without having to pre-bake the answer at
+    # spawn time (`echo y | cmd`, `-y`, heredoc).
+    #
+    # Typical loop: shell(run_in_background: true) → shell_output (see the
+    # prompt) → shell_input(run_id:, text: "y") → shell_output (see the result).
+    #
+    # By default a newline is appended (like pressing Enter). Pass
+    # `enter: false` to send raw bytes without a newline. Pass `eof: true` to
+    # close stdin (send EOF) after writing — for commands that read until EOF.
+    #
+    # Works for line-oriented prompts. Full-screen TTY programs (vim, REPLs
+    # that require a real terminal) are out of scope: the background shell uses
+    # a plain pipe, not a pseudo-terminal.
+    class ShellInputTool < Base
+      def name
+        "shell_input"
+      end
+
+      def description
+        "Send input to a background shell started via `shell` with " \
+          "run_in_background: true — answer an interactive prompt (Y/N, menu " \
+          "selection, password) of a running command. A newline is appended by " \
+          "default (like pressing Enter); pass enter: false for raw bytes, or " \
+          "eof: true to close stdin (EOF). Read the prompt and the result with " \
+          "`shell_output`."
+      end
+
+      def input_schema
+        {
+          type: "object",
+          properties: {
+            run_id: {
+              type: "string",
+              description: "The run_id returned by `shell` when launched in background"
+            },
+            text: {
+              type: "string",
+              description: "The text to write to the process's stdin (e.g. \"y\", \"2\")"
+            },
+            enter: {
+              type: "boolean",
+              description: "Append a newline like pressing Enter (default true)"
+            },
+            eof: {
+              type: "boolean",
+              description: "Close stdin / send EOF after writing (default false)"
+            }
+          },
+          required: %w[run_id]
+        }
+      end
+
+      def risk_level
+        :medium
+      end
+
+      def call(arguments)
+        run_id = arguments["run_id"] || arguments[:run_id]
+        text   = arguments["text"]   || arguments[:text] || ""
+        enter  = arguments.fetch("enter", arguments.fetch(:enter, true))
+        eof    = arguments["eof"] || arguments[:eof] || false
+
+        return "Error: run_id is required" if run_id.nil? || run_id.to_s.empty?
+
+        registry = ShellRegistry.instance
+        entry    = registry.find(run_id)
+        return "Error: no background shell with run_id=#{run_id}" unless entry
+
+        unless entry.wait_thr.alive?
+          return "Error: [#{run_id}] already exited (exit=#{registry.exit_code(entry)}) — cannot send input"
+        end
+
+        written =
+          begin
+            registry.write_input(entry, text, enter: enter)
+          rescue IOError, Errno::EPIPE => e
+            return "Error: [#{run_id}] stdin is closed (#{e.message})"
+          end
+
+        registry.close_stdin(entry) if eof
+
+        msg = "[#{run_id}] wrote #{written} byte#{"s" unless written == 1} to stdin"
+        msg << " (EOF sent)" if eof
+        msg << "\nRead the result: shell_output run_id=#{run_id}"
+        msg
+      end
+    end
+  end
+end

data/lib/rubino/tools/shell_kill_tool.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Rubino
+  module Tools
+    # Terminates a background shell. Sends SIGTERM to the whole process
+    # group first; if the process is still alive after a 2s grace period,
+    # follows up with SIGKILL.
+    class ShellKillTool < Base
+      GRACE_SECONDS = 2
+
+      def name
+        "shell_kill"
+      end
+
+      def description
+        "Terminate a background shell started via `shell` with run_in_background: true. " \
+          "Sends SIGTERM to the process group, waits #{GRACE_SECONDS}s, then SIGKILL if " \
+          "the process is still alive."
+      end
+
+      def input_schema
+        {
+          type: "object",
+          properties: {
+            run_id: {
+              type: "string",
+              description: "The run_id returned by `shell` when launched in background"
+            }
+          },
+          required: %w[run_id]
+        }
+      end
+
+      def risk_level
+        :medium
+      end
+
+      def call(arguments)
+        run_id = arguments["run_id"] || arguments[:run_id]
+        return "Error: run_id is required" if run_id.nil? || run_id.to_s.empty?
+
+        registry = ShellRegistry.instance
+        entry    = registry.find(run_id)
+        return "Error: no background shell with run_id=#{run_id}" unless entry
+
+        unless entry.wait_thr.alive?
+          registry.remove(run_id)
+          return "[#{run_id}] already exited (exit=#{registry.exit_code(entry)})"
+        end
+
+        send_signal(entry.pgid, "TERM")
+        GRACE_SECONDS.times do
+          break unless entry.wait_thr.alive?
+
+          sleep 1
+        end
+
+        if entry.wait_thr.alive?
+          send_signal(entry.pgid, "KILL")
+          sleep 0.1
+        end
+
+        registry.remove(run_id)
+        "[#{run_id}] terminated (SIGTERM" + (entry.wait_thr.alive? ? "+SIGKILL" : "") + ")"
+      end
+
+      private
+
+      def send_signal(pgid, signal)
+        Process.kill(signal, -pgid)
+      rescue Errno::ESRCH, Errno::EPERM
+        # Already dead or not ours.
+      end
+    end
+  end
+end

data/lib/rubino/tools/shell_output_tool.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Rubino
+  module Tools
+    # Reads stdout/stderr accumulated by a background shell (registered by
+    # ShellTool when run_in_background: true).
+    #
+    # By default returns only the bytes produced since the last call —
+    # repeated polling shows incremental progress like `tail -F`. Pass
+    # `mode: "all"` for the full buffer (bounded by ShellRegistry::RING_BYTES).
+    class ShellOutputTool < Base
+      def name
+        "shell_output"
+      end
+
+      def description
+        "Read output from a background shell started via `shell` with " \
+          "run_in_background: true. By default returns only new bytes since " \
+          "the previous read. Pass mode: 'all' for the full buffered output."
+      end
+
+      def input_schema
+        {
+          type: "object",
+          properties: {
+            run_id: {
+              type: "string",
+              description: "The run_id returned by `shell` when launched in background"
+            },
+            mode: {
+              type: "string",
+              enum: %w[new all],
+              description: "'new' (default) = bytes since last read; 'all' = full buffer"
+            }
+          },
+          required: %w[run_id]
+        }
+      end
+
+      def risk_level
+        :low
+      end
+
+      def call(arguments)
+        run_id = arguments["run_id"] || arguments[:run_id]
+        mode   = (arguments["mode"]  || arguments[:mode] || "new").to_s
+
+        return "Error: run_id is required" if run_id.nil? || run_id.to_s.empty?
+
+        registry = ShellRegistry.instance
+        entry    = registry.find(run_id)
+        return "Error: no background shell with run_id=#{run_id}" unless entry
+
+        body = mode == "all" ? registry.read_all(entry) : registry.read_new(entry)
+        status = registry.status(entry)
+        exit_code = registry.exit_code(entry)
+
+        header = "[#{run_id}] status=#{status}"
+        header << " exit=#{exit_code}" if exit_code
+        header << " (#{body.bytesize} bytes #{mode == "all" ? "total" : "new"})"
+
+        registry.remove(run_id) unless status == :running
+
+        if body.empty?
+          status == :running ? "#{header}\n(no new output)" : header
+        else
+          "#{header}\n#{body}"
+        end
+      end
+    end
+  end
+end

data/lib/rubino/tools/shell_registry.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "open3"
+
+module Rubino
+  module Tools
+    # Process-wide registry for shell commands started with `run_in_background`.
+    # Each entry owns a pgid (process group), a reader thread that drains
+    # stdout+stderr into an in-memory ring buffer, and the wait_thr for exit.
+    #
+    # The registry survives a single CLI/server process — it is intentionally
+    # NOT persisted to disk. Background shells die with the agent process.
+    class ShellRegistry
+      RING_BYTES = 256 * 1024 # cap per run; older bytes are dropped
+
+      Entry = Struct.new(
+        :id, :command, :cwd, :pid, :pgid, :wait_thr, :reader_thr,
+        :buffer, :mutex, :started_at, :read_offset, :stdin,
+        keyword_init: true
+      )
+
+      class << self
+        def instance
+          @instance ||= new
+        end
+      end
+
+      def initialize
+        @entries = {}
+        @mutex   = Mutex.new
+      end
+
+      # Spawns `command` detached in its own process group so a single kill
+      # takes out the whole subtree. Returns the new entry.
+      def spawn(command:, cwd:)
+        rd, wr = IO.pipe
+        # Writable stdin pipe: the agent feeds answers to interactive prompts
+        # (Y/N, "select region", apt-style) via the `shell_input` tool, which
+        # writes to `in_wr`. Line-oriented `read`/prompt commands consume this
+        # fine; full-screen TTY programs (vim, REPLs that require [ -t 0 ]) are
+        # out of scope for a plain pipe.
+        in_rd, in_wr = IO.pipe
+        # pgroup: true → child becomes leader of a new process group whose
+        # pgid == child pid. Lets shell_kill send SIGTERM to the whole tree.
+        # bash -o pipefail keeps this path consistent with the foreground
+        # shell: a mid-pipeline crash surfaces as the exit status (#156).
+        pid = Process.spawn("bash", "-o", "pipefail", "-c", command,
+                            chdir: cwd, pgroup: true, in: in_rd, out: wr, err: wr)
+        wr.close
+        in_rd.close
+
+        entry = Entry.new(
+          id: new_id,
+          command: command,
+          cwd: cwd,
+          pid: pid,
+          pgid: pid,
+          wait_thr: Process.detach(pid),
+          buffer: +"",
+          mutex: Mutex.new,
+          started_at: Time.now,
+          read_offset: 0,
+          stdin: in_wr
+        )
+        entry.reader_thr = Thread.new { drain_into(entry, rd) }
+
+        @mutex.synchronize { @entries[entry.id] = entry }
+        entry
+      end
+
+      def find(id)
+        @mutex.synchronize { @entries[id] }
+      end
+
+      def remove(id)
+        entry = @mutex.synchronize { @entries.delete(id) }
+        close_stdin(entry) if entry
+        entry
+      end
+
+      # Writes `text` to the background process's stdin (with a trailing
+      # newline unless `enter: false`) — the "press Enter to answer a prompt"
+      # path. Returns the number of bytes written, or raises if stdin is gone.
+      def write_input(entry, text, enter: true)
+        io = entry.stdin
+        raise IOError, "stdin already closed" if io.nil? || io.closed?
+
+        payload = enter ? "#{text}\n" : text.to_s
+        io.write(payload)
+        io.flush
+        payload.bytesize
+      end
+
+      # Closes the write end of the child's stdin (sends EOF). Idempotent.
+      def close_stdin(entry)
+        io = entry&.stdin
+        io.close if io && !io.closed?
+      rescue IOError
+        # already closed
+      end
+
+      # Reads accumulated bytes since the last `read_new` call. Returns the
+      # full snapshot if `since` is nil. Thread-safe.
+      def read_new(entry)
+        entry.mutex.synchronize do
+          snapshot = entry.buffer.byteslice(entry.read_offset..) || ""
+          entry.read_offset = entry.buffer.bytesize
+          snapshot
+        end
+      end
+
+      def read_all(entry)
+        entry.mutex.synchronize { entry.buffer.dup }
+      end
+
+      def status(entry)
+        return :running if entry.wait_thr.alive?
+
+        code = entry.wait_thr.value.exitstatus
+        code && ShellTool.success_exit?(code) ? :completed : :failed
+      end
+
+      def exit_code(entry)
+        return nil if entry.wait_thr.alive?
+
+        entry.wait_thr.value.exitstatus
+      end
+
+      private
+
+      def new_id
+        "bg_#{SecureRandom.hex(4)}"
+      end
+
+      # Single-reader pattern: only this thread writes to entry.buffer, the
+      # mutex protects only against concurrent reads from shell_output_tool.
+      def drain_into(entry, rd)
+        rd.each_line do |chunk|
+          entry.mutex.synchronize do
+            entry.buffer << chunk
+            overflow = entry.buffer.bytesize - RING_BYTES
+            if overflow.positive?
+              entry.buffer = entry.buffer.byteslice(overflow..) || +""
+              # Reset read_offset proportionally so the next read still sees
+              # only fresh bytes, not whatever survived the trim.
+              entry.read_offset = [entry.read_offset - overflow, 0].max
+            end
+          end
+        end
+      rescue IOError, Errno::EBADF
+        # pipe closed — process exited
+      ensure
+        rd.close unless rd.closed?
+      end
+    end
+  end
+end