rubino-agent 0.3.0

data/lib/rubino/ui/escape_reader.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+module Rubino
+  module UI
+    # Reads and parses the byte tail of an ESC keystroke for the
+    # {BottomComposer}: arrows / Home / End / Delete / word-jump / Shift+Tab /
+    # Alt+Enter and the bracketed-paste body. PURE input: it only consumes
+    # bytes from the keystroke source and returns a semantic action tuple —
+    # the composer maps actions to its editing/menu/turn behavior, so all
+    # rendering and state stay on its side of the seam.
+    #
+    # Three escape families are handled:
+    #   * CSI  — ESC '[' params final  (arrows, Home/End, Delete, Shift+Tab,
+    #            xterm modified keys like ESC[1;5C for Ctrl+→, bracketed paste)
+    #   * SS3  — ESC 'O' final          (application-cursor arrows / Home/End)
+    #   * Meta — ESC b / ESC f          (Alt+b / Alt+f word-jump on many terms)
+    class EscapeReader
+      # Bracketed paste (DEC 2004) end marker tail: the terminal closes a paste
+      # with ESC[201~ (the opener ESC[200~ arrives as a normal CSI above).
+      PASTE_END = "201~"
+
+      # @param source [#call] returns the keystroke IO to read from. A callable
+      #   rather than a captured IO so the reader always follows the composer's
+      #   CURRENT input — the escape tail must come from the same stream the
+      #   leading "\e" byte was read from, even if the IO is swapped (tests).
+      def initialize(source)
+        @source = source
+      end
+
+      # Consume the remainder of the escape sequence after a read "\e" and
+      # return what it MEANS, as one of:
+      #
+      #   [:esc]                      lone ESC (no following bytes)
+      #   [:esc_esc]                  two ESC bytes in ONE burst (fast double-tap)
+      #   [:alt_enter]                Alt/Meta+Enter (ESC CR / ESC LF)
+      #   [:paste, body]              bracketed paste with its raw body
+      #   [:mode_cycle]               Shift+Tab (ESC[Z)
+      #   [:history_up] / [:history_down]      ↑ / ↓
+      #   [:move_by, ±1]              bare ← / →
+      #   [:word_left] / [:word_right]         modified ←/→, Alt+b/f
+      #   [:move_home] / [:move_end]  Home / End (CSI, SS3 and tilde forms)
+      #   [:delete_forward]           Delete (ESC[3~)
+      #   nil                         unrecognized sequence (a quiet no-op)
+      #
+      # Non-blocking reads so a lone ESC doesn't hang.
+      def read_action
+        case read_nonblock_char
+        when nil        then [:esc]
+        when "\e"       then double_escape_action
+        when "\r", "\n" then [:alt_enter]
+        when "["        then csi_action(read_csi)
+        when "O"        then final_action(read_nonblock_char, modifier: 1)
+        when "b"        then [:word_left]
+        when "f"        then [:word_right]
+        end
+      end
+
+      private
+
+      # Two ESC bytes arrived in ONE burst: a fast Esc-Esc double-tap lands
+      # both before the reader wakes, so the second ESC shows up as the tail
+      # of the first. With nothing after it that IS the double-tap
+      # ([:esc_esc] — the composer treats it as two lone Escs for the rewind
+      # chord); with a real sequence after it (ESC ESC [ A — a Meta-prefixed
+      # arrow on some terminals) the leading ESC is just the Meta prefix, so
+      # the inner action passes through unchanged.
+      def double_escape_action
+        inner = read_action
+        inner == [:esc] ? [:esc_esc] : inner
+      end
+
+      # Acts on a parsed CSI sequence. Bracketed paste and Shift+Tab are
+      # special; everything else splits into "params;…final" so a modified
+      # arrow (ESC[1;5C = Ctrl+→) routes to the same move as the bare arrow
+      # plus the modifier that promotes it to a word-jump.
+      def csi_action(seq)
+        case seq
+        when "200~" then return [:paste, read_paste_body]
+        when "Z"    then return [:mode_cycle] # Shift+Tab arrives as ESC[Z
+        end
+
+        final = seq[-1]
+        params = seq[0...-1].split(";")
+        # The modifier param is the 2nd field for xterm "1;mod<final>" form; the
+        # numpad/edit keys (Home/End/Delete) carry "<n>;mod~". Default mod 1.
+        modifier = (params[1] || params[0] || "1").to_i
+        modifier = 1 if modifier.zero?
+        if final == "~"
+          tilde_action(params.first.to_i)
+        else
+          final_action(final, modifier: modifier)
+        end
+      end
+
+      # Final-byte cursor keys (and SS3 arrows). A modifier > 1 (Ctrl=5, Alt=3,
+      # Shift=2, etc.) promotes ←/→ to a word-jump, matching how terminals
+      # encode Ctrl/Alt + arrow.
+      def final_action(final, modifier:)
+        word = modifier > 1
+        case final
+        when "A" then [:history_up]
+        when "B" then [:history_down]
+        when "C" then word ? [:word_right] : [:move_by, 1]
+        when "D" then word ? [:word_left] : [:move_by, -1]
+        when "H" then [:move_home]
+        when "F" then [:move_end]
+        end
+      end
+
+      # Tilde-terminated edit keys: 1/7 = Home, 4/8 = End, 3 = Delete-forward.
+      def tilde_action(code)
+        case code
+        when 1, 7 then [:move_home]
+        when 4, 8 then [:move_end]
+        when 3    then [:delete_forward]
+        end
+      end
+
+      # Reads the remainder of a CSI sequence: params (digits + ';') up to and
+      # including the final byte in 0x40..0x7E. Returns the raw param/final
+      # string, e.g. "A", "3~", "1;5C".
+      def read_csi
+        seq = +""
+        loop do
+          c = read_nonblock_char
+          break if c.nil?
+
+          seq << c
+          break if c.ord.between?(0x40, 0x7E)
+        end
+        seq
+      end
+
+      # Accumulate a bracketed-paste body until the closing ESC[201~ marker.
+      # Blocking reads here: a paste is a contiguous burst, so we won't hang
+      # waiting on the user.
+      def read_paste_body
+        body = +""
+        until body.end_with?(PASTE_END)
+          c = read_paste_char
+          break if c.nil?
+
+          body << c
+        end
+        body = body[0...-PASTE_END.length] if body.end_with?(PASTE_END)
+        # Drop the ESC[ that precedes the 201~ end marker.
+        body.sub(/\e\[\z/, "")
+      end
+
+      # Blocking single-char read for the paste body (a paste arrives as one
+      # uninterrupted burst).
+      def read_paste_char
+        input.getc
+      rescue IOError, Errno::EIO # IOError covers EOFError
+        nil
+      end
+
+      def read_nonblock_char
+        input.read_nonblock(1)
+      rescue IO::WaitReadable, IOError, Errno::EIO # IOError covers EOFError
+        nil
+      end
+
+      def input
+        @source.call
+      end
+    end
+  end
+end

data/lib/rubino/ui/indented_io.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Rubino
+  module UI
+    # Output decorator that left-pads everything written through it by a fixed
+    # indent, so a TTY::Prompt menu renders in the SAME column as the card
+    # above it (P7) instead of flush-left at column 0.
+    #
+    # tty-prompt repaints its frame by moving the cursor up, clearing lines,
+    # and re-printing — so "start of line" is not only "after a newline": a
+    # carriage return or a cursor column-reset escape (`\e[<n>G`) also restart
+    # the line. The transform tracks that state ACROSS writes and injects the
+    # indent before the first visible character of every line, leaving all
+    # escape sequences untouched.
+    #
+    # Resolves the underlying IO from the given block on every call (default:
+    # the current $stdout) so a composer/proxy swap can never strand a stale
+    # handle. Everything else (tty?, winsize, …) delegates to that IO.
+    class IndentedIO
+      # ANSI CSI/OSC sequences pass through unindented; any other single
+      # character is a candidate for the line-start indent.
+      TOKEN_RE = /\e\[[\d;?]*[A-Za-z]|\e\][^\a\e]*(?:\a|\e\\)|./m
+
+      def initialize(indent: "  ", io: nil)
+        @indent        = indent
+        @resolve       = io ? -> { io } : -> { $stdout }
+        @at_line_start = true
+      end
+
+      def print(*args)
+        io.print(*args.map { |a| transform(a.to_s) })
+      end
+
+      def write(*args)
+        io.write(*args.map { |a| transform(a.to_s) })
+      end
+
+      def puts(*args)
+        if args.empty?
+          @at_line_start = true
+          io.puts
+        else
+          print("#{args.join("\n")}\n")
+        end
+      end
+
+      def <<(text)
+        write(text)
+        self
+      end
+
+      def flush
+        io.flush
+      end
+
+      def method_missing(name, *, &)
+        io.respond_to?(name) ? io.public_send(name, *, &) : super
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        io.respond_to?(name, include_private) || super
+      end
+
+      private
+
+      def io
+        @resolve.call
+      end
+
+      def transform(text)
+        text.gsub(TOKEN_RE) do |tok|
+          if ["\n", "\r"].include?(tok)
+            @at_line_start = true
+            tok
+          elsif tok.start_with?("\e")
+            @at_line_start = true if tok.match?(/\e\[\d*G\z/)
+            tok
+          elsif @at_line_start
+            @at_line_start = false
+            "#{@indent}#{tok}"
+          else
+            tok
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubino/ui/input_history.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require "reline"
+
+module Rubino
+  module UI
+    # Prompt history for the bottom composer, backed by the SAME store the old
+    # Reline idle prompt used (+Reline::HISTORY+) so continuity is preserved when
+    # the composer becomes the single idle input path — a session's earlier
+    # entries (and anything Reline itself recorded) stay navigable.
+    #
+    # Navigation model mirrors a shell / Reline: ↑ walks BACK toward older
+    # entries, ↓ walks FORWARD toward newer ones and finally back to the live
+    # draft the user was typing. The in-progress draft is stashed on the first ↑
+    # so ↓-ing all the way down restores exactly what the user had typed, never
+    # losing it.
+    #
+    # Like +LineInput#remember+, consecutive duplicates are de-duped on push so a
+    # repeated command doesn't clutter the ring.
+    class InputHistory
+      def initialize(store: Reline::HISTORY)
+        @store  = store
+        # Cursor into the history ring. nil = "on the live draft" (not navigating
+        # history). 0 = most recent entry, increasing = older.
+        @index  = nil
+        @draft  = nil
+      end
+
+      # Append a submitted line, de-duping a consecutive duplicate (matches
+      # LineInput#remember). Blank lines are not recorded. Resets navigation so
+      # the next ↑ starts from the newest entry again.
+      def remember(line)
+        reset!
+        return if line.nil?
+
+        stripped = line.strip
+        return if stripped.empty? || last == stripped
+        # Slash commands (/new, /help, …) are control input, not prompts — keep
+        # them out of recall so ↑ surfaces real messages, not commands (H1).
+        return if stripped.start_with?("/")
+
+        @store.push(stripped)
+      end
+
+      # Move toward OLDER entries (↑). +current+ is the buffer the user is
+      # editing right now; it's stashed as the draft on the first move up so ↓
+      # can restore it. Returns the entry to show, or nil when there's nothing
+      # older (caller keeps the current buffer).
+      def up(current)
+        entries = to_a
+        return nil if entries.empty?
+
+        if @index.nil?
+          # dup, not to_s: String#to_s returns self, so a later in-place
+          # @buffer.replace by the caller would mutate the stashed draft too.
+          @draft = current.to_s.dup
+          @index = 0
+        elsif @index < entries.size - 1
+          @index += 1
+        else
+          return nil # already on the oldest entry — clamp
+        end
+        entries[entries.size - 1 - @index]
+      end
+
+      # Move toward NEWER entries (↓). Returns the newer entry, or the stashed
+      # draft when stepping back below the newest entry, or nil when not
+      # currently navigating history (caller keeps the current buffer).
+      def down(_current = nil)
+        return nil if @index.nil?
+
+        entries = to_a
+        if @index.positive?
+          @index -= 1
+          entries[entries.size - 1 - @index]
+        else
+          # Stepped below the newest entry → back to the live draft.
+          @index = nil
+          d = @draft.to_s
+          @draft = nil
+          d
+        end
+      end
+
+      # True while the cursor is walking the history ring (not on the draft).
+      def navigating?
+        !@index.nil?
+      end
+
+      # Drop navigation state (called on submit / any direct edit so a fresh ↑
+      # starts from the newest entry and a typed edit isn't treated as history).
+      def reset!
+        @index = nil
+        @draft = nil
+      end
+
+      private
+
+      def to_a
+        @store.respond_to?(:to_a) ? @store.to_a : Array(@store)
+      end
+
+      def last
+        to_a.last
+      end
+    end
+  end
+end

data/lib/rubino/ui/live_region.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+require "unicode/display_width"
+
+module Rubino
+  module UI
+    # The {BottomComposer}'s live-region renderer: the rows redrawn IN PLACE
+    # above the prompt every frame (subagent cards, completion menu, transient
+    # announce, queued indicators, streamed partial). Owns the count of rows
+    # currently on screen and the scroll-safe erase→commit→redraw discipline;
+    # the composer assembles the row list and draws the prompt row itself.
+    # Pure output: no state of its own beyond the row count, and it NEVER takes
+    # the render mutex — the composer holds it around every call.
+    #
+    # Scroll-safe strategy (mirrors prompt_toolkit / Ink): ERASE the whole live
+    # region first (the prompt row, plus the rows above it) so nothing stale is
+    # left, then print any committed output and let the terminal scroll
+    # NATURALLY, then redraw the live region FRESH from wherever the cursor
+    # lands. We never issue a post-scroll +\e[1A+ that assumes the pre-scroll
+    # geometry: such a relative move desyncs the instant a trailing newline
+    # scrolls the screen at the bottom row, which is exactly what wiped the
+    # typed input.
+    class LiveRegion
+      def initialize(output)
+        @output = output
+        # How many rows the live region currently occupies ABOVE the input
+        # block. The clear walks up exactly this many rows, so a multi-line
+        # block clears cleanly without a single-row \e[1A desyncing it.
+        @rows_above = 0
+        # INPUT-BLOCK geometry, relative to the row the terminal cursor is
+        # parked on (the caret's visual row): how many input rows sit ABOVE it
+        # and how many rows sit BELOW it (wrapped input rows after the caret +
+        # the status bar). The composer records these after every #draw_input
+        # via {#input_drawn}, so {#clear_input_block} can erase the whole block
+        # — multi-row input + status bar — before the next draw.
+        @input_above = 0
+        @input_below = 0
+      end
+
+      attr_reader :rows_above, :input_above, :input_below
+
+      # True when any rows are currently drawn above the input block.
+      def live?
+        @rows_above.positive?
+      end
+
+      # Record the input block's geometry for the frame just drawn (see
+      # ivar docs above). Called by the composer at the end of #draw_input.
+      def input_drawn(above:, below:)
+        @input_above = above
+        @input_below = below
+      end
+
+      # Erase the INPUT BLOCK in place (every wrapped input row + the status
+      # bar) and park the cursor, column 0, on the block's TOP row — where the
+      # next #draw_input begins. Walks DOWN from the caret row clearing the
+      # rows below first (status bar + wrapped rows after the caret), returns,
+      # clears the caret row, then walks UP clearing the rows above. All moves
+      # are relative and happen BEFORE any printing, so nothing has scrolled
+      # and the walk is valid. Leaves the above-block live rows untouched.
+      def clear_input_block
+        if @input_below.positive?
+          @input_below.times { @output.print("\e[1B\e[2K") }
+          @output.print("\e[#{@input_below}A")
+        end
+        @output.print("\r\e[2K")
+        @input_above.times { @output.print("\e[1A\e[2K") }
+        @input_above = 0
+        @input_below = 0
+      end
+
+      # Draws one atomic frame. Layout (top → bottom): the committed lines (only
+      # when given; they scroll into scrollback and stay there), then the live
+      # +rows+ redrawn in place, then the prompt row drawn by the block.
+      # Must be called while the composer holds its render mutex.
+      def frame(committed:, rows:, cols:)
+        clear # 1) erase prompt (+ live) rows, BEFORE any scroll
+        commit(committed) # 2) print committed output, scroll naturally
+        # 3) redraw fresh from the post-scroll cursor row
+        rows.each { |row| emit_row(row, cols) }
+        yield # the prompt row — ALWAYS last, so it survives every scroll
+      end
+
+      # Erase the live region IN PLACE and park the cursor on its TOP row:
+      # clear the input block (wrapped rows + status bar, see
+      # {#clear_input_block}), then walk UP and clear each of the rows above it
+      # in turn, leaving the cursor on the now-blank top row. This runs BEFORE
+      # any output is printed, so the screen has not scrolled yet and the
+      # relative walks are valid; afterward the cursor sits on a blank row with
+      # nothing stale below.
+      def clear
+        clear_input_block
+        @rows_above.times { @output.print("\e[1A\e[2K") }
+        @rows_above = 0
+      end
+
+      # Print ONE live row clamped to one column SHORT of the width and
+      # terminated with a CRLF (which scrolls naturally if we're at the bottom),
+      # bumping the row count so the NEXT frame's clear walks up exactly this
+      # many rows.
+      #
+      # The one-column-short clamp matters: a glyph in the final column arms the
+      # terminal's deferred auto-wrap ("pending wrap"), and the following CRLF
+      # can then resolve as a double scroll on some terminals — which slides the
+      # live region out from under the next frame's relative \e[1A walk-up and
+      # wipes the prompt. One spare column keeps each row scroll-deterministic.
+      def emit_row(row, cols)
+        @output.print("\r\e[2K#{self.class.clamp(row, cols - 1)}\r\n")
+        @rows_above += 1
+      end
+
+      # Commit finished output from the blank top row. It scrolls into
+      # scrollback NATURALLY; after the trailing CRLF the cursor sits on a fresh
+      # blank line at the (possibly new) bottom — the anchor the live rows are
+      # redrawn from. Crucially we make NO relative cursor move after this, so a
+      # scroll here can never desync the redraw. Each line is emitted with a
+      # trailing "\r\n" because OPOST is off in raw mode (a bare "\n" would not
+      # return the carriage and the next line would stair-step).
+      # An EMPTY committed line is a deliberate blank row (the P3 rhythm gaps —
+      # one blank before the answer block, the separator before a tool run):
+      # it must scroll a real row, not be dropped, or the in-turn rhythm
+      # differs from the between-turns one. Only nil is a no-op.
+      def commit(committed)
+        return if committed.nil?
+
+        normalized = committed.to_s.gsub("\r\n", "\n").gsub("\n", "\r\n")
+        @output.print(normalized)
+        @output.print("\r\n") unless normalized.end_with?("\r\n")
+      end
+
+      class << self
+        # Clamp a single visible line to the terminal width (one row), left-
+        # truncating with a leading "…" so a long line never wraps and desyncs
+        # the frame.
+        #
+        # Width is measured in terminal DISPLAY COLUMNS, not characters: a wide
+        # glyph (CJK / emoji like ✅ 🔄) occupies two columns but counts as one
+        # String#length char. Measuring by char count let a "clamped" line
+        # render WIDER than the row, so xterm wrapped it to a second physical
+        # line that the single-row clear (\e[1A) never erased — the residue
+        # accumulated downward (the streaming-table trail). Truncating by
+        # display width keeps each row exactly one physical line so the clear
+        # math stays valid.
+        def clamp(str, cols)
+          flat = str.to_s.tr("\n", " ")
+          # Guard a non-positive width (winsize can report 0 cols in some
+          # terminals/multiplexers, at startup, or a zero-height window):
+          # without this truncation could return an empty/over-wide line and
+          # desync the frame, which escaped run_turn's `rescue Interrupt` and
+          # killed the whole chat mid-turn.
+          cols = 1 if cols.nil? || cols < 1
+          return flat if display_width(flat) <= cols
+
+          # Leading "…" costs one column; fill the rest from the END of the line.
+          "…#{take_last_columns(flat, cols - 1)}"
+        end
+
+        # Terminal display columns for a string (wide glyphs count as 2).
+        def display_width(str)
+          Unicode::DisplayWidth.of(str.to_s)
+        end
+
+        # The longest SUFFIX of +str+ whose display width is <= +cols+. Walks
+        # from the end so a wide trailing glyph is dropped whole (never
+        # half-rendered) rather than cut mid-cell.
+        def take_last_columns(str, cols)
+          return "" if cols <= 0
+
+          used  = 0
+          taken = []
+          str.to_s.chars.reverse_each do |ch|
+            w = display_width(ch)
+            break if used + w > cols
+
+            taken << ch
+            used += w
+          end
+          taken.reverse.join
+        end
+      end
+    end
+  end
+end