rubino-agent 0.3.0

data/lib/rubino/ui/subagent_view.rb

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+require "pastel"
+require "zlib"
+
+module Rubino
+  module UI
+    # Nested UI adapter for a running subagent (the `task` tool).
+    #
+    # While the parent loop delegates to a subagent, the child runs its own
+    # isolated Agent::Runner. By default that child is wired with UI::Null, so
+    # its activity is invisible. This adapter makes the child's TOOL ACTIVITY
+    # visible INLINE — compact rows indented under the parent's
+    # "● delegated → X" delegation boundary, in a per-subagent color — so the
+    # user can watch what the subagent is doing live.
+    #
+    # DISPLAY ONLY. This adapter writes to $stdout (which, during a parent turn,
+    # is the composer proxy → committed above the bottom composer like every
+    # other timeline row). It never touches the parent loop's `messages` or the
+    # parent recorder: the result-only contract is unchanged. The parent model
+    # still receives ONLY the subagent's final result (the `task` tool result).
+    #
+    # COLLAPSED-CARD MODE (Variant A — kills the flood, #124): instead of
+    # writing one $stdout row per child tool call (which buried the parent
+    # prompt), tool_started/tool_finished now feed the BackgroundTasks REGISTRY
+    # entry for this run (last_activity + a tool counter + a bounded recent-ring)
+    # and ask the parent UI to repaint its collapsed live CARD. The card shows a
+    # single in-place line per subagent (`▸ sa_… · explore · running · N tools ·
+    # Ns · <last_activity>`) that updates without scrolling — see UI::CLI
+    # #set_subagent_cards / UI::SubagentCards. The /agents <id> drill-in tails the
+    # same registry ring for the live recent: list (#71).
+    #
+    # The view is wired with the entry id at construction (TaskTool builds it per
+    # background run). With no id (legacy/foreground synchronous path, tests) it
+    # falls back to the OLD inline rows so the synchronous delegation surface and
+    # its specs are unchanged.
+    #
+    # Inline (legacy) format, 2-space extra indent under the delegation row:
+    #   `    ⟂ explore · read lib/foo.rb`
+    #   `    ⟂ explore · ✓ grep · 3 matches`
+    #
+    # Noise control:
+    #   - stream / stream_end / assistant_text / thinking_started are SUPPRESSED
+    #     (the subagent's prose isn't shown — only its steps and the final
+    #     result, which the parent already prints as "✓ X: result");
+    #   - note / status / info render as dim nested lines (low-noise) ONLY in the
+    #     legacy inline path; in card mode they fold into the registry too;
+    #   - confirm: in card mode it does NOT auto-deny — it surfaces the approval
+    #     on the card and parks the child on a per-entry gate (Option 2; wired by
+    #     TaskTool). With no approval handler (legacy/foreground) it auto-DENIES
+    #     so a subagent never blocks on a prompt no one can answer.
+    class SubagentView < Base
+      # Deterministic per-subagent palette. Chosen by hashing the agent name so
+      # the same subagent always renders in the same color (no Math.random),
+      # and concurrent/sequential delegations to different subagents stay
+      # visually distinct. All names are valid Pastel foreground colors.
+      PALETTE = %i[cyan magenta blue yellow green bright_cyan].freeze
+
+      # Nested-row indent: 2 spaces beyond the CLI's own 2-space body indent so
+      # the subagent's steps read as nested under the "● delegated → X" row.
+      INDENT = "    "
+
+      # Glyph prefixing every subagent activity row.
+      GLYPH = "⟂"
+
+      # @param entry_id [String, nil] the BackgroundTasks entry this view feeds
+      #   in card mode. nil ⇒ legacy inline-row mode (synchronous/foreground path).
+      # @param parent_ui [UI::CLI, nil] the parent CLI whose live region hosts the
+      #   collapsed card; #set_subagent_cards repaints it. Captured at spawn on the
+      #   parent thread (the child thread has no access to the parent's UI).
+      # @param approve [#call, nil] in card mode, the approval handler TaskTool
+      #   wires: called with (question, scope:, command:) and returns the boolean
+      #   decision. nil ⇒ #confirm auto-denies (legacy behavior).
+      def initialize(agent_name:, out: $stdout, pastel: Pastel.new,
+                     entry_id: nil, parent_ui: nil, approve: nil)
+        @agent_name = agent_name.to_s
+        @out        = out
+        @pastel     = pastel
+        @color      = PALETTE[color_index(@agent_name)]
+        @entry_id   = entry_id
+        @parent_ui  = parent_ui
+        @approve    = approve
+      end
+
+      # The color this view paints its rows in (exposed for tests).
+      attr_reader :color
+
+      # True when this view feeds a registry entry (collapsed-card mode) rather
+      # than flooding $stdout with per-tool rows (legacy inline mode).
+      def card_mode?
+        !@entry_id.nil?
+      end
+
+      # --- Rendered: tool activity (the "what it's doing") -------------------
+
+      # Card mode: record the tool start on the registry entry (last_activity +
+      # tool counter) and repaint the parent's collapsed card — NO $stdout row, so
+      # a read-heavy child never floods the parent terminal (#124). Legacy mode:
+      # the old inline `    ⟂ explore · read lib/foo.rb` row.
+      def tool_started(name, arguments: nil, at: nil)
+        hint = args_hint(arguments)
+        if card_mode?
+          activity = hint ? "#{name} #{hint}" : name.to_s
+          Tools::BackgroundTasks.instance.record_tool_started(@entry_id, activity)
+          repaint_cards
+        else
+          body = hint ? "#{name} #{hint}" : name.to_s
+          row(body)
+        end
+      end
+
+      # Card mode: append the terse finish line to the entry's recent-ring (which
+      # the /agents drill-in tails) and repaint. Legacy mode: the old inline row.
+      def tool_finished(name, result: nil)
+        failed = result.respond_to?(:success?) && !result.success?
+        icon   = failed ? "✗" : "✓"
+        suffix = result_metric(result)
+        body   = suffix ? "#{icon} #{name} · #{suffix}" : "#{icon} #{name}"
+        if card_mode?
+          Tools::BackgroundTasks.instance.record_tool_finished(@entry_id, body)
+          repaint_cards
+        else
+          row(body)
+        end
+      end
+
+      # tool_body / tool_chunk: the child's tool previews/streamed chunks. Kept
+      # quiet to stay low-noise — the start/finish rows already say what ran.
+      def tool_body(_text, kind: :plain); end
+      def tool_chunk(_name, _chunk); end
+
+      # --- Suppressed: the child's prose / token stream ---------------------
+
+      def stream(_chunk); end
+      def stream_end; end
+      def assistant_text(_text); end
+      def body(_text); end
+      def thinking_started; end
+      def replay_user_input(_text, at: nil); end
+      def table(headers:, rows:); end
+
+      # --- Low-noise: dim nested annotations -------------------------------
+
+      # In card mode these fold away (the card is the only surface); in legacy
+      # inline mode they keep their dim nested rows.
+      def note(text)   = card_mode? ? nil : dim_row(text)
+      def status(text) = card_mode? ? nil : dim_row(text)
+      def info(text)   = card_mode? ? nil : dim_row(text)
+
+      def success(message) = card_mode? ? nil : row("✓ #{message}")
+      def warning(message) = card_mode? ? nil : row("⚠ #{message}")
+      def error(message)   = card_mode? ? nil : row("✗ #{message}")
+
+      # --- Suppressed lifecycle chrome ------------------------------------
+
+      def separator; end
+      def blank_line; end
+      def compression_started(at: nil); end
+      def compression_finished(_metadata, at: nil); end
+      def job_enqueued(_type); end
+      def job_started(_type); end
+      def job_finished(_type); end
+      def mode_changed(_name, previous: nil); end
+      def box_open(*_pieces, at: nil, color: nil); end
+      def box_close(*_pieces, color: nil); end
+      def queued(_text); end
+      def input_injected(_text); end
+
+      # --- Interactive: surface the approval, don't auto-deny -------------
+
+      # Option 2 — approval-surfacing. In card mode WITH an approval handler
+      # (wired by TaskTool), a child tool that needs approval is NOT silently
+      # denied: we hand off to @approve, which flips the registry entry to
+      # :needs_approval (surfacing it on the card + a parent note) and BLOCKS the
+      # child thread on a per-entry Run::ApprovalGate until the user answers via
+      # /agents <id> (or the 15-min bound auto-denies). The handler returns the
+      # boolean decision, which we return so the child's tool proceeds or denies.
+      #
+      # Without a handler (legacy inline / foreground path) we keep the old
+      # AUTO-DENY (false): a subagent there must never hang on a prompt no one can
+      # answer.
+      def confirm(question, scope: nil, **context)
+        return @approve.call(question, scope: scope, **context) if @approve
+
+        false
+      end
+
+      # No interactive clarification mid-delegation either.
+      def ask(_prompt)
+        nil
+      end
+
+      private
+
+      # Asks the parent CLI to repaint the collapsed card block from the
+      # registry's current snapshot. Best-effort and quiet: a repaint is cosmetic
+      # and must never break the child's run. No-op when there's no parent CLI
+      # (the registry still has the fresh data for the /agents drill-in).
+      def repaint_cards
+        @parent_ui.set_subagent_cards if @parent_ui.respond_to?(:set_subagent_cards)
+      rescue StandardError
+        nil
+      end
+
+      # Stable palette index for a name: CRC32 keeps it deterministic across
+      # processes (Ruby's String#hash is salted per-run) and dependency-free.
+      def color_index(name)
+        Zlib.crc32(name) % PALETTE.size
+      end
+
+      # Emits one colored, indented, name-prefixed activity row.
+      def row(text)
+        return if text.nil? || text.to_s.strip.empty?
+
+        @out.puts @pastel.public_send(@color, "#{INDENT}#{GLYPH} #{@agent_name} · #{text}")
+      end
+
+      # Dim variant for low-priority annotations (note/status/info).
+      def dim_row(text)
+        return if text.nil? || text.to_s.strip.empty?
+
+        @out.puts @pastel.dim("#{INDENT}#{GLYPH} #{@agent_name} · #{first_line(text, 80)}")
+      end
+
+      # A compact metric for the finish row: prefer the tool's own metrics,
+      # else a truncated preview of the output.
+      def result_metric(result)
+        return nil unless result
+
+        metric = result.metrics if result.respond_to?(:metrics)
+        return first_line(metric, 60) if metric && !metric.to_s.strip.empty?
+
+        preview = result.truncated_preview if result.respond_to?(:truncated_preview)
+        preview && !preview.to_s.strip.empty? ? first_line(preview, 60) : nil
+      end
+
+      # Short identifier piece from the tool arguments (path/pattern/command).
+      def args_hint(arguments)
+        return nil unless arguments.is_a?(Hash)
+
+        %i[file_path path pattern command].each do |k|
+          v = arguments[k] || arguments[k.to_s]
+          return first_line(v, 60) if v && !v.to_s.strip.empty?
+        end
+        nil
+      end
+
+      # First NON-BLANK line, elided to +max+ — a multi-line ruby/shell command
+      # often starts with a blank line, which would render an empty hint (#141).
+      def first_line(text, max)
+        Rubino::Util::Output.first_line(text, max)
+      end
+    end
+  end
+end

data/lib/rubino/ui.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Rubino
+  # UI module namespace and factory.
+  # All output in the application flows through a UI adapter.
+  module UI
+    # Factory method to build the appropriate UI adapter
+    def self.build(adapter_name)
+      case adapter_name.to_s
+      when "cli"
+        CLI.new
+      when "api"
+        API.new
+      when "null"
+        Null.new
+      else
+        raise ConfigurationError, "Unknown UI adapter: #{adapter_name}"
+      end
+    end
+  end
+end

data/lib/rubino/update_check.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+require "time"
+require "fileutils"
+
+module Rubino
+  # Boot-time "new version available" notice + the `rubino update` mechanics.
+  #
+  # Two decoupled concerns, mirroring how `gh`/update-notifier do it:
+  #
+  #   * SHOW (sync, zero network): `notice_from_cache` reads
+  #     <RUBINO_HOME>/update_check.json and returns a one-line notice only when
+  #     the cached `latest` is a valid Gem::Version strictly greater than the
+  #     running VERSION. Pure local read — cannot slow boot, works offline.
+  #
+  #   * REFRESH (out-of-band): `refresh_async_if_stale` spawns a detached,
+  #     fully-rescued Thread (≈1.5s timeout) that GETs RubyGems and rewrites the
+  #     cache for the NEXT boot. It is never joined, so this boot never blocks.
+  #     Gated to once/24h, TTY-only, not-in-CI, and skipped entirely when
+  #     RUBINO_NO_UPDATE_CHECK is set.
+  #
+  # The whole feature no-ops until rubino-agent is actually published: RubyGems
+  # currently returns {"version":"unknown"}, and "unknown" / non-semver / nil /
+  # any network error are all treated as "no info" → no notice.
+  module UpdateCheck
+    LATEST_URL    = "https://rubygems.org/api/v1/versions/rubino-agent/latest.json"
+    GEM_NAME      = "rubino-agent"
+    CACHE_FILE    = "update_check.json"
+    CHECK_INTERVAL = 24 * 60 * 60 # 24h, like gh/Homebrew
+    NET_TIMEOUT = 1.5
+
+    module_function
+
+    # ---- SHOW (pure local read) -------------------------------------------
+
+    # One-line dim notice when a newer version is cached, else nil. The
+    # RUBINO_NO_UPDATE_CHECK opt-out disables the feature ENTIRELY — "no
+    # network, no notice" per docs/commands.md — so a previously-cached
+    # notice must not leak through either (#66).
+    def notice_from_cache
+      return nil if opted_out?
+
+      latest = cached_latest
+      return nil unless newer?(latest)
+
+      "▸ rubino v#{latest} available — run `rubino update`"
+    end
+
+    # ---- REFRESH (out-of-band, never awaited) -----------------------------
+
+    # Refresh the cache in a detached thread iff enabled and stale. Returns the
+    # spawned Thread (tests can join it) or nil when gated out. The caller never
+    # joins it on the boot path, so this boot is never slowed.
+    def refresh_async_if_stale
+      return nil unless checks_enabled?
+      return nil unless stale?
+
+      Thread.new do
+        latest = fetch_latest
+        write_cache(latest) if latest
+      rescue StandardError
+        # Offline, DNS, TLS, JSON garbage, FS — silent. The cache is left as-is,
+        # so a transient failure simply shows no notice.
+        nil
+      end
+    end
+
+    # ---- network ----------------------------------------------------------
+
+    # The latest published version string, or nil on failure / "unknown" /
+    # non-semver. Synchronous + short-timeout; callers that must not block run
+    # it on a detached thread (refresh_async_if_stale).
+    def fetch_latest
+      uri = URI(LATEST_URL)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = (uri.scheme == "https")
+      http.open_timeout = NET_TIMEOUT
+      http.read_timeout = NET_TIMEOUT
+
+      req = Net::HTTP::Get.new(uri)
+      req["User-Agent"] = "Rubino/#{Rubino::VERSION}"
+
+      res = http.request(req)
+      return nil unless res.is_a?(Net::HTTPSuccess)
+
+      version = JSON.parse(res.body)["version"].to_s
+      semver?(version) ? version : nil
+    rescue StandardError
+      nil
+    end
+
+    # ---- cache ------------------------------------------------------------
+
+    def cache_path
+      File.join(Rubino::Config::Loader.default_home_path, CACHE_FILE)
+    end
+
+    def cached_latest
+      return nil unless File.exist?(cache_path)
+
+      JSON.parse(File.read(cache_path))["latest"]
+    rescue StandardError
+      nil
+    end
+
+    # Atomic write (temp + rename) so a crashed refresh never leaves a torn file.
+    def write_cache(latest)
+      dir = File.dirname(cache_path)
+      FileUtils.mkdir_p(dir)
+      tmp = "#{cache_path}.#{Process.pid}.tmp"
+      File.write(tmp, JSON.generate("checked_at" => Time.now.utc.iso8601, "latest" => latest))
+      File.rename(tmp, cache_path)
+    rescue StandardError
+      nil
+    end
+
+    def clear_cache!
+      File.delete(cache_path) if File.exist?(cache_path)
+    rescue StandardError
+      nil
+    end
+
+    # ---- gating -----------------------------------------------------------
+
+    # The user's full opt-out: RUBINO_NO_UPDATE_CHECK set (to anything
+    # non-blank) disables refresh AND the cached boot notice.
+    def opted_out?
+      !ENV["RUBINO_NO_UPDATE_CHECK"].to_s.strip.empty?
+    end
+
+    # All must hold (mirrors gh): no opt-out env, interactive TTY, not CI.
+    def checks_enabled?
+      !opted_out? &&
+        $stdout.tty? &&
+        ENV["CI"].to_s.strip.empty?
+    end
+
+    # True when the cache is missing or its checked_at is older than 24h.
+    def stale?
+      return true unless File.exist?(cache_path)
+
+      checked_at = JSON.parse(File.read(cache_path))["checked_at"]
+      Time.now.utc - Time.parse(checked_at) >= CHECK_INTERVAL
+    rescue StandardError
+      true
+    end
+
+    # ---- update mechanics -------------------------------------------------
+
+    # How rubino was installed: :gem when a matching RubyGems spec is loaded,
+    # else :source (dev checkout / built from source / vendored).
+    def install_method
+      installed_gem_version(GEM_NAME) ? :gem : :source
+    end
+
+    def installed_gem_version(name)
+      Gem::Specification.find_by_name(name).version.to_s
+    rescue Gem::MissingSpecError, StandardError
+      nil
+    end
+
+    # Argv form (no shell) + active interpreter via Gem.ruby → updates the right
+    # install on a multi-Ruby machine and is injection-safe.
+    def gem_update_command
+      [Gem.ruby, "-S", "gem", "update", GEM_NAME]
+    end
+
+    # ---- version helpers --------------------------------------------------
+
+    # X.Y / X.Y.Z[.pre] — strict enough to reject "unknown" and other garbage.
+    def semver?(str)
+      !!(str.to_s =~ /\A\d+\.\d+(\.\d+)?([-.][0-9A-Za-z.-]+)?\z/)
+    end
+
+    # latest is a valid version strictly greater than the running VERSION.
+    def newer?(latest)
+      return false unless semver?(latest)
+
+      Gem::Version.new(latest) > Gem::Version.new(Rubino::VERSION)
+    rescue ArgumentError
+      false
+    end
+  end
+end

data/lib/rubino/util/duration.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Rubino
+  module Util
+    # Compact, human-readable elapsed-time formatting shared by the agent
+    # cards and the /sessions + /agents listings (was copy-pasted into
+    # UI::SubagentCards, CLI::ChatCommand, and Commands::Executor).
+    #
+    # Coarse on purpose: seconds under a minute, then whole minutes, then
+    # whole hours — enough to read "how long" at a glance without a clock.
+    module Duration
+      module_function
+
+      def human_duration(seconds)
+        secs = seconds.to_i
+        return "#{secs}s" if secs < 60
+        return "#{secs / 60}m" if secs < 3600
+
+        "#{secs / 3600}h"
+      end
+    end
+  end
+end

data/lib/rubino/util/hyperlink.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Rubino
+  module Util
+    # OSC 8 terminal hyperlinks — wraps text in escape sequences that a
+    # supporting terminal renders as clickable links.
+    #
+    # Sequence shape:  `\e]8;;URI\e\\LABEL\e]8;;\e\\`
+    # The first `\e]8;;` opens the link, `\e\\` (String Terminator) ends
+    # the URI segment, LABEL is what the user sees, and the trailing
+    # `\e]8;;\e\\` closes the link.
+    #
+    # ## Support detection
+    # OSC 8 is supported by iTerm2, WezTerm, vscode integrated terminal,
+    # Hyper, Ghostty, and kitty. Apple_Terminal does NOT support it and
+    # would render the escape codes as visible garbage. Detection is
+    # CONSERVATIVE: unknown terminals default to off, so users on
+    # Terminal.app or a tmux session whose outer terminal we can't
+    # introspect never see junk in their scrollback.
+    #
+    # Override with `RUBINO_HYPERLINKS=1` to force on (useful in
+    # tmux when you know the outer terminal supports OSC 8) or `=0` to
+    # force off. `NO_COLOR=1` also forces off, matching the broader
+    # convention used by every other ANSI-emitting tool in this CLI.
+    #
+    # ## Scope
+    # OSC 8 lives ENTIRELY in the CLI adapter. The API adapter emits raw
+    # structured events (tool name, arguments hash) and the web UI builds
+    # its own `<a>` elements from that — terminal escape codes have no
+    # business inside a JSON payload.
+    module Hyperlink
+      OPEN_PREFIX  = "\e]8;;"
+      CLOSE_SUFFIX = "\e]8;;\e\\"
+      ST           = "\e\\" # String Terminator
+
+      # Terminals known to render OSC 8 correctly. Conservative list —
+      # additions welcome as we confirm support elsewhere.
+      KNOWN_TERM_PROGRAMS = %w[iTerm.app WezTerm vscode Hyper ghostty].freeze
+
+      # True when the current terminal renders OSC 8 hyperlinks. Result is
+      # cached per process because env vars don't change mid-run.
+      def self.supported?
+        return @supported if defined?(@supported)
+
+        @supported = compute_support
+      end
+
+      # Test-only hook to reset the memoized support flag (specs flip env
+      # vars between examples). Not part of the public contract.
+      def self.reset!
+        remove_instance_variable(:@supported) if defined?(@supported)
+      end
+
+      # Wraps LABEL in the OSC 8 sequence pointing to URI. Returns LABEL
+      # unchanged when hyperlinks aren't supported, so callers can use the
+      # result unconditionally — no escape codes leak into a Terminal.app
+      # scrollback or an SSE payload.
+      def self.wrap(label, uri:)
+        return label.to_s if label.nil?
+        return label.to_s unless supported?
+        return label.to_s if uri.nil? || uri.to_s.empty?
+
+        "#{OPEN_PREFIX}#{uri}#{ST}#{label}#{CLOSE_SUFFIX}"
+      end
+
+      # Builds a `file://` URI for the given path, expanding to absolute
+      # so the terminal's URI handler doesn't try to resolve it against
+      # its own cwd. Returns nil when the path is empty or doesn't exist
+      # — callers should fall back to the raw label in that case.
+      def self.file_uri(path)
+        return nil if path.nil? || path.to_s.empty?
+
+        abs = File.expand_path(path.to_s)
+        return nil unless File.exist?(abs)
+
+        "file://#{abs}"
+      end
+
+      # Convenience for the common case: "I have a file path, wrap it as
+      # a clickable link to that file." Pass a different `label:` when
+      # the displayed text differs from the path (e.g. truncated to fit
+      # a header rule).
+      def self.wrap_path(path, label: nil)
+        uri  = file_uri(path)
+        text = (label || path).to_s
+        return text if uri.nil?
+
+        wrap(text, uri: uri)
+      end
+
+      class << self
+        private
+
+        def compute_support
+          return false if ENV["NO_COLOR"] && !ENV["NO_COLOR"].empty?
+          return true  if ENV["RUBINO_HYPERLINKS"] == "1"
+          return false if ENV["RUBINO_HYPERLINKS"] == "0"
+          return true  if ENV["TERM"] == "xterm-kitty"
+
+          KNOWN_TERM_PROGRAMS.include?(ENV.fetch("TERM_PROGRAM", nil))
+        end
+      end
+    end
+  end
+end