rubino-agent 0.3.0

data/lib/rubino/ui/stdout_proxy.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+module Rubino
+  module UI
+    # An IO-shaped shim that routes everything written to it through a
+    # {BottomComposer#print_above}, so the ~30 existing +$stdout.print/puts+ call
+    # sites across UI::CLI / PrinterBase need ZERO changes. While a turn is
+    # active, the chat command swaps +$stdout+ for one of these (prompt_toolkit's
+    # +StdoutProxy+ model); on turn end it swaps the real IO back.
+    #
+    # Line buffering — the critical streaming nuance:
+    #   UI::CLI#stream emits PARTIAL tokens with NO trailing newline during model
+    #   streaming. A naive "print each write above the prompt" would scroll every
+    #   token onto its own row. Instead we hold the in-progress line in
+    #   +@partial+ and re-render it (the accumulating line) ABOVE the composer via
+    #   {BottomComposer#set_partial} as it grows — a transient row redrawn in
+    #   place — committing it to scrollback (via {BottomComposer#print_above})
+    #   only when a newline arrives. The way prompt_toolkit buffers and batches:
+    #   each newline-terminated segment becomes one committed row; the trailing
+    #   partial keeps showing live.
+    #
+    # The render mutex lives in the composer, so concurrent writes from the
+    # streaming thread and keystroke redraws stay serialized.
+    class StdoutProxy
+      # @param composer [BottomComposer] coordinator that owns print_above.
+      def initialize(composer)
+        @composer = composer
+        @partial  = +""
+      end
+
+      # The two methods UI code actually uses are #print and #puts; #write backs
+      # both formattings and is also what e.g. StringIO/IO duck-typers call.
+      def write(*args)
+        args.sum do |a|
+          append(a.to_s)
+          a.to_s.bytesize
+        end
+      end
+
+      def print(*args)
+        args.each { |a| append(a.to_s) }
+        nil
+      end
+
+      def puts(*args)
+        if args.empty?
+          append("\n")
+        else
+          args.each do |a|
+            if a.is_a?(Array)
+              a.each { |e| puts(e) }
+            else
+              # Append the line and its terminating newline in ONE append so the
+              # text commits straight to scrollback. Appending them separately
+              # showed the line as a TRANSIENT partial row below the subagent
+              # cards for a frame before the commit moved it above them — the
+              # user saw the same line twice around the live card block (#153).
+              s = a.to_s
+              append(s.end_with?("\n") ? s : "#{s}\n")
+            end
+          end
+        end
+        nil
+      end
+
+      def printf(format, *)
+        append(format(format, *))
+        nil
+      end
+
+      def <<(obj)
+        append(obj.to_s)
+        self
+      end
+
+      # Streaming writers call flush after each token. We treat flush as "show
+      # what you have now": re-render the accumulating partial line above the
+      # composer so streamed text appears live, without committing it to
+      # scrollback (it has no newline yet).
+      def flush
+        render_partial
+        self
+      end
+
+      # REPLACE the live region with +str+ (replace, not accumulate). The normal
+      # #append path GROWS @partial — right for token-by-token line buffering, but
+      # wrong for the streaming-markdown tail, which is the WHOLE in-progress block
+      # re-shown each time it changes. So we reset our own buffer and hand the raw
+      # tail straight to the composer's transient row. Used by UI::CLI#stream to
+      # show the incomplete block live while completed blocks commit above it.
+      def live(str)
+        @partial = +""
+        @composer.set_partial(str.to_s)
+        self
+      end
+
+      # Commit any held partial line as a final row. Called when the proxy is
+      # torn down so an unterminated last line (e.g. a stream that ended without
+      # stream_end) isn't lost.
+      def finish
+        return if @partial.empty?
+
+        line = @partial
+        @partial = +""
+        @composer.print_above(line)
+      end
+
+      # Best-effort IO compatibility for code that probes the stream.
+      def tty?   = false
+      def isatty = false
+      def sync   = true
+      def fileno = nil
+
+      # A faithful IO duck MUST answer #close: stdlib Logger::LogDevice treats a
+      # logdev that responds to :write but NOT :close as a FILENAME and does
+      # File.open(it) → "no implicit conversion of StdoutProxy into String" if a
+      # Logger is ever built against $stdout while we hold the swap. No-op close.
+      def close; end
+      def closed? = false
+
+      def sync=(_)
+        true
+      end
+
+      private
+
+      # Accumulate text, committing each complete (newline-terminated) line to
+      # scrollback via print_above and keeping any trailing remainder as the live
+      # partial. The partial is shown via #flush; many writers flush right after,
+      # but we also render it here so a partial that arrives without a following
+      # flush still appears.
+      def append(str)
+        return if str.nil? || str.empty?
+
+        @partial << str
+        commit_complete_lines
+        render_partial
+      end
+
+      def commit_complete_lines
+        while (idx = @partial.index("\n"))
+          line = @partial[0...idx]
+          @partial = @partial[(idx + 1)..] || +""
+          # A committed line is a finished row; embedded "\r" (e.g. the CLI's
+          # in-place clear before a streamed chunk) is preserved so print_above's
+          # clear-line semantics still apply.
+          @composer.print_above(line)
+        end
+      end
+
+      # Show the in-progress (un-newlined) line above the composer without
+      # committing it. set_partial renders it on a transient row directly above
+      # the input line, redrawn in place — so the live partial grows in place as
+      # tokens stream in rather than scrolling a copy per token. When the partial
+      # is empty (just committed a line), clear the transient row.
+      def render_partial
+        @composer.set_partial(@partial)
+      end
+    end
+  end
+end

data/lib/rubino/ui/streaming_markdown.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+module Rubino
+  module UI
+    # Incremental block splitter for streamed markdown.
+    #
+    # The model streams an assistant message token-by-token; we want to render
+    # COMPLETED markdown blocks above the composer as soon as they finish, while
+    # showing the still-incoming (incomplete) block raw in the live region. This
+    # buffer accumulates streamed text and decides where one block ends and the
+    # next begins, so {UI::CLI} can render+commit a finished block and leave only
+    # the in-progress tail live.
+    #
+    # Block boundary detection — a small line-oriented fence state machine (the
+    # mainstream approach used by md2term / mdterm / Glamour-style streamers: you
+    # must NOT render a fenced code block until its closing ``` arrives, or
+    # half-open fences render as garbage):
+    #
+    #   * Lines are split on "\n". A line is "complete" once its terminating "\n"
+    #     has been seen; the trailing remainder (no "\n" yet) is the live tail.
+    #   * A line matching ^\s*``` toggles the fence state.
+    #       - Entering a fence STARTS a code block (the fence line joins it).
+    #       - Leaving a fence ENDS the code block (the closing fence joins it);
+    #         the block is reported complete.
+    #   * While INSIDE a fence, blank lines do NOT split — code keeps its blanks.
+    #   * While OUTSIDE a fence, a blank line ENDS the current prose block. The
+    #     blank line itself is consumed as the separator (not re-emitted).
+    #
+    # API:
+    #   feed(text)  -> Array<String>  newly-completed block texts (state advances)
+    #   tail        -> String         the current incomplete block, raw (live)
+    #   flush       -> String|nil     the remaining buffered block on stream end
+    #                                 (an unclosed fence is returned so the caller
+    #                                 can emit it as plain text — never lost)
+    class StreamingMarkdown
+      FENCE_RE = /\A\s*```/
+      # An ordered ("1. ", "2) ") or unordered ("- ", "* ", "+ ") list item.
+      # Used so a loose list (blank lines BETWEEN items) is kept as ONE block
+      # instead of being split per-item: each split item was re-rendered on its
+      # own, and kramdown restarts ordered numbering at 1 for every block, which
+      # produced the "1. Mercury / 1. Venus / 1. Earth" off-by-one (B4).
+      LIST_ITEM_RE = /\A\s*(?:[-*+]|\d+[.)])\s/
+
+      def initialize
+        @pending = +""   # un-newlined remainder (the live tail-in-progress line)
+        @block   = []    # completed lines accumulated for the current block
+        @in_fence = false
+        @in_list  = false # current block is a markdown list (keep loose items together)
+        @blanks   = 0     # blank lines buffered inside a list, re-emitted iff it continues
+      end
+
+      # Accumulate streamed text; return the list of block texts that became
+      # COMPLETE as a result of this feed (possibly empty). Advances state.
+      def feed(text)
+        return [] if text.nil? || text.empty?
+
+        @pending << text
+        completed = []
+
+        while (idx = @pending.index("\n"))
+          line = @pending[0...idx]
+          @pending = @pending[(idx + 1)..] || +""
+          block = consume_line(line)
+          completed << block if block
+        end
+
+        completed
+      end
+
+      # The current incomplete block as raw text: any lines already buffered for
+      # the in-progress block plus the un-newlined remainder. Shown live; it gets
+      # re-rendered + committed once its block completes.
+      def tail
+        parts = @block.dup
+        parts << @pending unless @pending.empty?
+        parts.join("\n")
+      end
+
+      # The in-progress tail to show live (raw): the LAST +rows+ lines of the
+      # in-flight block — its most recent already-newlined lines plus the
+      # un-newlined remainder. Newline-joined; the live region renders one row
+      # per line.
+      #
+      # Why a rolling window and not the whole #tail: the live region must stay
+      # bounded (a long open fence/table must never push the prompt off-screen),
+      # so we keep "only the last block can change" (Textual/Rich, Streamdown,
+      # Glamour-style streamers) but show a FEW trailing lines instead of just
+      # the one being typed — a long list block used to vanish line-by-line as
+      # each item completed, leaving a single flickering raw line until the
+      # whole block committed (#127). Earlier lines stay buffered and the block
+      # still snaps to rendered markdown the moment it completes.
+      def live_tail(rows = 1)
+        lines = @block.last(rows)
+        lines += [@pending] unless @pending.empty?
+        lines.last(rows).join("\n")
+      end
+
+      # Drain the remainder on stream end. Promotes any un-newlined remainder to
+      # a final line, then returns the buffered block text (or nil if empty). An
+      # unclosed fence is returned all the same — the caller emits it as plain so
+      # output is never dropped.
+      def flush
+        unless @pending.empty?
+          @block << @pending
+          @pending = +""
+        end
+        return nil if @block.empty?
+
+        text = @block.join("\n")
+        @block = []
+        @in_fence = false
+        @in_list = false
+        @blanks = 0
+        text
+      end
+
+      private
+
+      # Feed one complete (newline-stripped) line through the state machine.
+      # Returns the finished block's text when this line closes a block, else nil.
+      def consume_line(line)
+        if @in_fence
+          @block << line
+          if line.match?(FENCE_RE) # closing fence ends the code block
+            @in_fence = false
+            return take_block
+          end
+          return nil
+        end
+
+        if line.match?(FENCE_RE) # opening fence starts a code block
+          @in_fence = true
+          flush_blanks
+          @block << line
+          return nil
+        end
+
+        if line.strip.empty?
+          # A blank line inside a list is BUFFERED, not a separator: it only ends
+          # the block if the list doesn't continue (handled when the next
+          # non-blank, non-item line arrives, or at flush). Outside a list a
+          # blank line ends the current prose block (separator consumed).
+          if @in_list
+            @blanks += 1
+            return nil
+          end
+          return nil if @block.empty?
+
+          return take_block
+        end
+
+        is_item = line.match?(LIST_ITEM_RE)
+
+        # A non-item line after a blank-separated list closes the list block
+        # first (so the list renders as one well-numbered unit), then this line
+        # starts a fresh block — its buffered blanks are dropped as the separator.
+        if @in_list && !is_item && @blanks.positive?
+          @blanks = 0 # drop the trailing blank(s) that separated list from this line
+          finished = take_block
+          @block << line
+          return finished
+        end
+
+        flush_blanks
+        @in_list = true if is_item
+        @block << line
+        nil
+      end
+
+      # Re-emit blank lines buffered inside a continuing list so loose-list
+      # spacing is preserved in the committed block text.
+      def flush_blanks
+        @blanks.times { @block << "" }
+        @blanks = 0
+      end
+
+      def take_block
+        flush_blanks
+        text = @block.join("\n")
+        @block = []
+        @in_list = false
+        text
+      end
+    end
+  end
+end

data/lib/rubino/ui/subagent_cards.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require "pastel"
+
+module Rubino
+  module UI
+    # Formats BackgroundTasks registry entries into the COLLAPSED LIVE CARDS the
+    # parent shows while one or more background subagents run (Variant A of the
+    # orchestration-UX blueprint). This is the single source of card text: the
+    # live region (UI::CLI#set_subagent_cards → BottomComposer) renders it while a
+    # turn runs, and the /agents drill-in reuses the same formatter for the
+    # expanded view. Pure formatting — it never touches the registry mutex itself
+    # (callers pass a snapshot) and writes nothing; the renderer decides where the
+    # lines go.
+    #
+    # Collapsed card (one row per running subagent, updates in place):
+    #   ▸ sa_9ae4 · explore · running · 14 tools · 38s · grep "def authenticate"
+    # plus a single shared hint line under the block.
+    #
+    # An entry parked on a human approval shows the approval prominently instead:
+    #   ● sa_9ae4 · explore · needs approval · shell rm -rf build
+    #
+    # Up to MAX_CARDS cards stack; a longer list collapses the overflow into a
+    # "+N more" tail so the live region stays bounded (and the single-row clamp
+    # in the composer never has to host an unbounded block).
+    class SubagentCards
+      # Cap the live block so it never grows past the registry's own
+      # MAX_CONCURRENT (3) live children — but defend against a stale/over-long
+      # list anyway with an explicit overflow tail.
+      MAX_CARDS = Tools::BackgroundTasks::MAX_CONCURRENT
+
+      # Collapsed glyph (a running card) / approval glyph (needs the human) /
+      # BLOCKED glyph (an escalated ask_parent waiting on the human — RESERVED for
+      # "the tree is blocked on you" and nothing else, the distinct-signal rule).
+      COLLAPSED = "▸"
+      APPROVAL  = "●"
+      BLOCKED   = "⛔"
+
+      def initialize(pastel: Pastel.new)
+        @pastel = pastel
+      end
+
+      # Renders the live CARD BLOCK for the running (or approval-pending)
+      # children in +entries+ as an array of ready-to-print lines. Returns [] when
+      # nothing is live, so the renderer can clear the region. +entries+ is a
+      # snapshot (BackgroundTasks#running) taken under the registry mutex by the
+      # caller — this method only reads the plain struct fields.
+      def card_lines(entries)
+        live = entries.select { |e| live?(e) }
+        return [] if live.empty?
+
+        shown    = live.first(MAX_CARDS)
+        overflow = live.size - shown.size
+        lines    = shown.map { |e| card_line(e) }
+        lines << @pastel.dim("  + #{overflow} more · /agents") if overflow.positive?
+        lines << hint_line(shown)
+        lines
+      end
+
+      # One collapsed card row for a single entry.
+      def card_line(entry)
+        if entry.status == :blocked_on_human
+          blocked_card_line(entry)
+        elsif entry.status == :needs_approval
+          approval_card_line(entry)
+        else
+          glyph = @pastel.cyan(COLLAPSED)
+          state = entry.status == :stopping ? "stopping" : "running"
+          count = entry.tool_count.to_i
+          body  = "#{entry.id} · #{entry.subagent} · #{state} · " \
+                  "#{count} tool#{"s" if count != 1} · #{elapsed(entry)}"
+          body += " · #{entry.last_activity}" unless entry.last_activity.to_s.empty?
+          "  #{glyph} #{body}"
+        end
+      end
+
+      # A card for a child parked on an escalated ask_parent — the ⛔ "tree is
+      # blocked on YOU" row, the loudest state. Leads with the red ⛔ glyph and
+      # the question, and points at /reply <id> (the answer verb), distinct from
+      # the approval row's /agents <id>.
+      def blocked_card_line(entry)
+        glyph    = @pastel.red(BLOCKED)
+        question = entry.ask_question.to_s
+        "  #{glyph} #{entry.id} · #{entry.subagent} · " +
+          @pastel.red("waiting on you") + ": #{first_line(question, 60)} " \
+                                          "· /reply #{entry.id}"
+      end
+
+      # A card for a child parked on a human approval — the approval is the most
+      # important thing on the row, so it leads (amber ●) with the command.
+      def approval_card_line(entry)
+        glyph   = @pastel.yellow(APPROVAL)
+        command = entry.approval_command.to_s
+        command = entry.approval_question.to_s if command.empty?
+        "  #{glyph} #{entry.id} · #{entry.subagent} · " +
+          @pastel.yellow("needs approval") + ": #{first_line(command, 60)} " \
+                                             "· /agents #{entry.id}"
+      end
+
+      private
+
+      def live?(entry)
+        %i[running needs_approval blocked_on_human stopping].include?(entry.status)
+      end
+
+      # Shared hint under the block. When something needs approval the hint leads
+      # with the answer affordance; otherwise it's the watch/stop hint.
+      def hint_line(shown)
+        blocked = shown.count { |e| e.status == :blocked_on_human }
+        if blocked.positive?
+          @pastel.red("    \u26d4 #{blocked} subagent waiting on you · /reply <id> to answer")
+        elsif shown.any? { |e| e.status == :needs_approval }
+          @pastel.dim("    └ /agents <id> to approve · --stop to cancel")
+        else
+          @pastel.dim("    └ /agents <id> to watch · --stop to cancel")
+        end
+      end
+
+      def elapsed(entry)
+        return "" unless entry.started_at
+
+        finish = entry.finished_at || Time.now
+        Rubino::Util::Duration.human_duration(finish - entry.started_at)
+      end
+
+      # First NON-BLANK line, elided to +max+. A ruby/shell approval command
+      # often starts with a newline or a blank line — taking `.lines.first`
+      # there rendered an EMPTY "needs approval:" body on the card (#141).
+      def first_line(text, max)
+        Rubino::Util::Output.first_line(text, max)
+      end
+    end
+  end
+end