octo-agent 0.11.2

data/lib/octo/ui2/progress_handle.rb

@@ -0,0 +1,362 @@
+# frozen_string_literal: true
+
+require "monitor"
+
+module Octo
+  module UI2
+    # An *owned* progress indicator.
+    #
+    # Why this exists
+    # ---------------
+    # The previous design had a single, globally-shared spinner slot on
+    # UiController (`@progress_id` / `@progress_thread` / `@progress_message`
+    # / `@progress_start_time`). Every caller — Agent#run, Agent#think,
+    # LlmCaller retry, idle compression, MemoryUpdater — wrote into the
+    # same slot and hoped to remember to close it. When control flow was
+    # interrupted (user types a new message during idle compression,
+    # AgentInterrupted is raised) a ticker thread would be left running
+    # and a new spinner would reuse the same entry, producing two
+    # concurrent tickers repainting the same line in different colors.
+    #
+    # In the new design each caller owns a ProgressHandle. The handle
+    # encapsulates:
+    #
+    # - its own OutputBuffer entry id (may become nil while another
+    #   handle is on top — see "Stack semantics" below);
+    # - its own ticker thread (exactly one per handle, stopped and
+    #   joined on +finish+);
+    # - its own message, style, start time;
+    #
+    # Owners (UiController) keep a stack of live handles and follow the
+    # protocol below.
+    #
+    # Owner protocol
+    # --------------
+    # An "owner" must respond to three methods:
+    #
+    #   register_progress(handle) -> Integer (entry_id) | nil
+    #     Called exactly once when the handle starts. The owner pushes
+    #     the handle onto its stack, creates an OutputBuffer entry, and
+    #     returns that entry id. Before pushing, the owner may detach
+    #     the previous top-of-stack (Plan B: its entry is removed from
+    #     the buffer until the new top finishes).
+    #
+    #   unregister_progress(handle, final_frame:) -> void
+    #     Called exactly once when the handle finishes. The owner pops
+    #     the handle from its stack, renders +final_frame+ into the
+    #     entry (or removes the entry if +final_frame+ is nil), and may
+    #     reattach the new top-of-stack if one exists.
+    #
+    #   render_frame(handle, frame) -> void
+    #     Called by the ticker (and by +update+) on every paint. The
+    #     owner is responsible for ignoring the call if +handle+ is not
+    #     currently top-of-stack — the handle itself does NOT know about
+    #     the stack.
+    #
+    # Stack semantics (Plan B)
+    # ------------------------
+    # When a new handle is pushed on top of an existing one, the lower
+    # handle's OutputBuffer entry is removed (owner calls
+    # +__detach_entry!+ on it). When the new top finishes, the owner
+    # re-creates an entry for the lower handle and calls
+    # +__reattach_entry!+ with the new id. This keeps the visible output
+    # clean: exactly one progress line on screen at a time, and no
+    # visual "stacking" of frozen progress lines.
+    #
+    # Thread safety
+    # -------------
+    # The handle uses a Monitor (reentrant) to serialize state changes
+    # between the caller thread and the ticker thread. Public methods
+    # (+start+, +update+, +finish+) are safe to call from any thread.
+    class ProgressHandle
+      # Default tick interval (seconds). Matches the old global spinner
+      # cadence. Tests may pass a smaller interval for speed.
+      DEFAULT_TICK_INTERVAL = 0.25
+
+      # Style hint for the renderer. The owner decides what colors to use;
+      # the handle only forwards the hint as part of the frame metadata
+      # so the renderer can pick between e.g. yellow "working" and gray
+      # "quiet" palettes.
+      #
+      #   :primary  — foreground task, should also update sessionbar
+      #   :quiet    — background task (idle compression, retries); does
+      #               NOT bump sessionbar to 'working'
+      VALID_STYLES = %i[primary quiet].freeze
+
+      attr_reader :entry_id, :message, :style, :start_time
+
+      # Threshold (seconds) below which a +quiet_on_fast_finish+ handle
+      # collapses its final frame — i.e. the progress line is REMOVED
+      # from the output buffer instead of being kept as a permanent
+      # "Executing foo… (0s)" log line. Operations that finish this fast
+      # didn't need a spinner in the first place; keeping the final
+      # frame would be visual noise.
+      FAST_FINISH_THRESHOLD_SECONDS = 2
+
+      # Show "Thinking for Ns" once the gap since the last LLM stream
+      # chunk reaches this many seconds. Bedrock often pauses 5–18s
+      # while generating large content blocks (long tool_use JSON in
+      # particular); without this hint users assume the agent is stuck.
+      IDLE_HINT_THRESHOLD_SECONDS = 2
+
+      # @param owner [#register_progress, #unregister_progress, #render_frame]
+      # @param message [String] Initial progress message.
+      # @param style [Symbol] :primary or :quiet (see VALID_STYLES).
+      # @param tick_interval [Float] Seconds between auto-renders.
+      # @param quiet_on_fast_finish [Boolean] When true and the elapsed
+      #   time on +finish+ is under FAST_FINISH_THRESHOLD_SECONDS, the
+      #   owner is told to remove the progress entry (+final_frame: nil+)
+      #   instead of committing a permanent final frame. This is the
+      #   preferred mode for tool execution wrappers, where fast tools
+      #   (edit, write, read) don't need a lingering "Executing edit…
+      #   (0s)" line after completion.
+      # @param clock [#call] Test hook: returns current Time (default Time.now).
+      def initialize(owner:, message:, style: :primary, tick_interval: DEFAULT_TICK_INTERVAL, quiet_on_fast_finish: false, clock: -> { Time.now })
+        unless VALID_STYLES.include?(style)
+          raise ArgumentError, "unknown progress style: #{style.inspect} (valid: #{VALID_STYLES.inspect})"
+        end
+
+        @owner                = owner
+        @message              = message.to_s
+        @style                = style
+        @tick_interval        = tick_interval
+        @quiet_on_fast_finish = quiet_on_fast_finish
+        @clock                = clock
+
+        @entry_id      = nil
+        @start_time    = nil
+        @ticker        = nil
+        @state         = :fresh     # :fresh → :running → :closed
+        @metadata      = {}
+        @last_chunk_at = nil
+        @monitor       = Monitor.new
+      end
+
+      # Start rendering. Registers with the owner (allocating an entry id
+      # and pushing onto its stack) and launches the ticker thread.
+      #
+      # @return [self]
+      def start
+        @monitor.synchronize do
+          return self unless @state == :fresh
+
+          @state         = :running
+          @start_time    = @clock.call
+          @last_chunk_at = @start_time
+          @entry_id      = @owner.register_progress(self)
+        end
+
+        # Fire one initial frame synchronously so the user sees the
+        # spinner immediately — no "blank line for half a second" bug.
+        render_now
+
+        start_ticker
+        self
+      end
+
+      # Change the message or metadata mid-flight. Safe to call from any
+      # thread. Triggers an immediate re-render (if top-of-stack; the
+      # owner will ignore the call otherwise).
+      #
+      # @param message [String, nil]
+      # @param metadata [Hash] Renderer-specific extras (e.g. retry counts).
+      def update(message: nil, metadata: nil)
+        @monitor.synchronize do
+          return if @state != :running
+          @message  = message.to_s if message
+          if metadata
+            @metadata = metadata
+            @last_chunk_at = @clock.call
+          end
+        end
+      end
+
+      # Stop the ticker, render one final frame, and unregister from the
+      # owner. Idempotent — calling twice is a no-op.
+      #
+      # @param final_message [String, nil] Optional override for the last
+      #   frame. If nil, the handle composes "<message>… (<elapsed>s)".
+      def finish(final_message: nil)
+        snapshot = @monitor.synchronize do
+          return if @state != :running
+          @state = :closed
+          { message: final_message || @message, elapsed: elapsed_seconds }
+        end
+
+        stop_ticker
+        # Collapse fast-finishers to a removed entry so tools that complete
+        # in under FAST_FINISH_THRESHOLD_SECONDS don't leave a permanent
+        # "Executing foo… (0s)" line. The owner interprets final_frame: nil
+        # as "remove the entry entirely".
+        final_frame =
+          if @quiet_on_fast_finish && snapshot[:elapsed] < FAST_FINISH_THRESHOLD_SECONDS
+            nil
+          else
+            compose_final_frame(snapshot[:message], snapshot[:elapsed])
+          end
+        @owner.unregister_progress(self, final_frame: final_frame)
+      end
+      alias_method :cancel, :finish
+
+      # True while the ticker thread is alive.
+      def ticker_alive?
+        t = @ticker
+        !!(t && t.alive?)
+      end
+
+      # True between +start+ and +finish+.
+      def running?
+        @monitor.synchronize { @state == :running }
+      end
+
+      # Compose the current visual frame. The owner gets this string via
+      # +render_frame+ and is responsible for writing it into the entry.
+      def current_frame
+        @monitor.synchronize do
+          compose_frame(@message, elapsed_seconds, @metadata, idle_seconds)
+        end
+      end
+
+      # ---- owner-facing hooks (Plan B stack machinery) ----------------
+      #
+      # These double-underscore methods are part of the owner protocol.
+      # They are NOT meant for general callers.
+
+      # Owner calls this when this handle is being pushed below a new
+      # top. The handle loses its OutputBuffer entry until restored.
+      def __detach_entry!
+        @monitor.synchronize { @entry_id = nil }
+      end
+
+      # Owner calls this when this handle becomes top-of-stack again
+      # (the handle above finished). A fresh entry id is supplied.
+      def __reattach_entry!(new_entry_id)
+        @monitor.synchronize { @entry_id = new_entry_id }
+        render_now
+      end
+
+      # Like __reattach_entry! but skips the render_now hop. Used by the
+      # owner when it has just painted a frame into the new entry itself
+      # (e.g. while rotating the handle to remain at the buffer tail) and
+      # is still inside its own synchronization — calling render_now there
+      # would re-enter the owner's mutex.
+      def __rebind_entry!(new_entry_id)
+        @monitor.synchronize { @entry_id = new_entry_id }
+      end
+
+      # Test hook: force a synchronous render regardless of tick cadence.
+      def __force_render!
+        render_now
+      end
+
+      private def start_ticker
+        @ticker = Thread.new do
+          Thread.current.name = "progress-ticker-#{object_id}"
+          begin
+            loop do
+              sleep @tick_interval
+              break if @monitor.synchronize { @state != :running }
+              render_now
+            end
+          rescue StandardError
+            # Ticker must never crash the process — the caller's main
+            # thread still owns the real control flow.
+          end
+        end
+      end
+
+      private def stop_ticker
+        t = @ticker
+        return unless t
+        # The loop checks @state on each iteration, so once we're
+        # :closed the next wake-up exits cleanly. Give it 1s; if
+        # something is stuck, kill as a last resort.
+        joined = t.join(1.0)
+        t.kill unless joined
+        @ticker = nil
+      end
+
+      private def render_now
+        frame = current_frame
+        @owner.render_frame(self, frame)
+      rescue StandardError
+        # Rendering must never propagate.
+      end
+
+      private def elapsed_seconds
+        return 0 unless @start_time
+        (@clock.call - @start_time).to_i
+      end
+
+      # Seconds since the last metadata update (i.e. the last LLM stream
+      # chunk that carried token info). Used to surface "Thinking for Ns"
+      # in the live frame so users can see the agent isn't stuck even
+      # when token counts plateau during long Bedrock content blocks.
+      private def idle_seconds
+        return 0 unless @last_chunk_at
+        (@clock.call - @last_chunk_at).to_i
+      end
+
+      # Live-frame format:
+      #   "<message>… (<elapsed>s · ↓N tokens · reasoning…)"
+      # The "reasoning" tail only appears once tokens have started
+      # streaming AND the gap since the last chunk reaches the threshold
+      # — signalling the model is between tool_use blocks doing extended
+      # thinking. No seconds shown there to avoid duplicating elapsed;
+      # animated dots (1→2→3) provide the "still alive" cue.
+      private def compose_frame(message, elapsed, metadata, idle = 0)
+        head = message.to_s
+        if metadata && (attempt = metadata[:attempt]) && (total = metadata[:total])
+          head = "#{head} [#{attempt}/#{total}]"
+        end
+
+        token_part = metadata && format_token_progress(metadata)
+
+        suffix_parts = []
+        suffix_parts << "#{elapsed}s" if elapsed > 0
+        suffix_parts << token_part if token_part
+        if token_part && idle >= IDLE_HINT_THRESHOLD_SECONDS
+          suffix_parts << "reasoning #{spinner_frame} "
+        end
+
+        return "#{head}…" if suffix_parts.empty?
+        "#{head}… (#{suffix_parts.join(" · ")})"
+      end
+
+      SPINNER_FRAMES = %w[⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏].freeze
+      SPINNER_INTERVAL_MS = 250
+
+      private def spinner_frame
+        ms = (@clock.call.to_f * 1000).to_i
+        SPINNER_FRAMES[(ms / SPINNER_INTERVAL_MS) % SPINNER_FRAMES.length]
+      end
+
+      # Render LLM streaming token counts as "↑1.2k ↓234 tokens".
+      # When input_tokens is unknown (e.g. OpenAI-compat streaming where
+      # prompt_tokens only arrives in the final frame), shows "↑—" so the
+      # column doesn't flicker between absent / present.
+      private def format_token_progress(metadata)
+        output = metadata[:output_tokens]
+        return nil if output.nil? || output.to_i <= 0
+        "↓ #{compact_count(output.to_i)} tokens"
+      end
+
+      private def compact_count(n)
+        return n.to_s if n < 1000
+        if n < 1_000_000
+          k = n / 1000.0
+          k >= 10 ? "#{k.to_i}k" : "%.1fk" % k
+        else
+          m = n / 1_000_000.0
+          m >= 10 ? "#{m.to_i}M" : "%.1fM" % m
+        end
+      end
+
+      # Final frame (used by +finish+). Same as +compose_frame+ but we
+      # always include elapsed time so the last line carries a duration.
+      private def compose_final_frame(message, elapsed)
+        "#{message}… (#{elapsed}s)"
+      end
+    end
+  end
+end

data/lib/octo/ui2/progress_indicator.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Octo
+  class ProgressIndicator
+    def initialize(verbose: false, message: nil)
+      @verbose = verbose
+      @start_time = nil
+      @custom_message = message
+      @thinking_verb = message || THINKING_VERBS.sample
+      @running = false
+      @update_thread = nil
+    end
+
+    def start
+      @start_time = Time.now
+      @running = true
+      # Save cursor position after the [..] symbol
+      print "\e[s"  # Save cursor position
+      print_thinking_status("#{@thinking_verb}… (ctrl+c to interrupt)")
+
+      # Start background thread to update elapsed time
+      @update_thread = Thread.new do
+        while @running
+          sleep 0.1
+          update if @running
+        end
+      end
+    end
+
+    def update
+      return unless @start_time
+
+      elapsed = (Time.now - @start_time).to_i
+      print_thinking_status("#{@thinking_verb}… (ctrl+c to interrupt · #{elapsed}s)")
+    end
+
+    def finish
+      @running = false
+      @update_thread&.join
+      # Restore cursor and clear to end of line
+      print "\e[u"     # Restore cursor position
+      print "\e[K"     # Clear to end of line
+      puts ""          # Add newline after finishing
+    end
+
+
+    def print_thinking_status(text)
+      print "\e[u"     # Restore cursor position (to after [..] symbol)
+      print "\e[K"     # Clear to end of line from cursor
+      print text
+      print " "
+      $stdout.flush
+    end
+  end
+end

data/lib/octo/ui2/screen_buffer.rb

@@ -0,0 +1,273 @@
+# frozen_string_literal: true
+
+require "tty-screen"
+require "io/console"
+require_relative "../utils/encoding"
+
+module Octo
+  module UI2
+    # ScreenBuffer manages terminal screen state and provides low-level rendering primitives
+    class ScreenBuffer
+      attr_reader :width, :height
+
+      def initialize
+        @width = TTY::Screen.width
+        @height = TTY::Screen.height
+        @buffer = []
+        @last_input_time = nil
+        @rapid_input_threshold = 0.01 # 10ms threshold for detecting paste-like rapid input
+
+        # Keep stdin in UTF-8 mode so getc returns complete multi-byte characters (e.g. CJK).
+        # Switching to BINARY would cause getc to return one byte at a time, breaking Chinese input.
+        $stdin.set_encoding('UTF-8')
+      end
+
+      # Move cursor to specific position (0-indexed)
+      # @param row [Integer] Row position
+      # @param col [Integer] Column position
+      def move_cursor(row, col)
+        print "\e[#{row + 1};#{col + 1}H"
+      end
+
+      # Clear screen with different modes:
+      #   :preserve - clear visible screen, scrollback history preserved (default)
+      #   :current  - cursor to top-left and erase to end, no new scrollback produced
+      #   :reset    - clear visible screen AND scrollback history (full reset)
+      # @param mode [Symbol] Clear mode (:preserve, :current, :reset)
+      def clear_screen(mode: :preserve)
+        case mode
+        when :reset
+          print "\e[3J"    # erase scrollback buffer
+          print "\e[H\e[J" # cursor to top-left, erase to end of screen
+        when :current
+          print "\e[H\e[J" # cursor to top-left, erase to end of screen
+        else # :preserve
+          print "\e[2J\e[H"    # erase visible screen, scrollback preserved
+        end
+        move_cursor(0, 0)
+      end
+
+      # Clear current line
+      def clear_line
+        print "\e[2K"
+      end
+
+      # Clear from cursor to end of line
+      def clear_to_eol
+        print "\e[K"
+      end
+
+      # Hide cursor
+      def hide_cursor
+        print "\e[?25l"
+      end
+
+      # Show cursor
+      def show_cursor
+        print "\e[?25h"
+      end
+
+      # Save cursor position
+      def save_cursor
+        print "\e[s"
+      end
+
+      # Restore cursor position
+      def restore_cursor
+        print "\e[u"
+      end
+
+      # Enable alternative screen buffer (like vim/less)
+      def enable_alt_screen
+        print "\e[?1049h"
+      end
+
+      # Disable alternative screen buffer
+      def disable_alt_screen
+        print "\e[?1049l"
+      end
+
+      # Set scroll region (DECSTBM - DEC Set Top and Bottom Margins)
+      # Content written in this region will scroll, content outside will stay fixed
+      # @param top [Integer] Top row (1-indexed)
+      # @param bottom [Integer] Bottom row (1-indexed)
+      def set_scroll_region(top, bottom)
+        print "\e[#{top};#{bottom}r"
+      end
+
+      # Reset scroll region to full screen
+      def reset_scroll_region
+        print "\e[r"
+      end
+
+      # Scroll the scroll region up by n lines
+      # @param n [Integer] Number of lines to scroll
+      def scroll_up(n = 1)
+        print "\e[#{n}S"
+      end
+
+      # Scroll the scroll region down by n lines
+      # @param n [Integer] Number of lines to scroll
+      def scroll_down(n = 1)
+        print "\e[#{n}T"
+      end
+
+      # Get current screen dimensions
+      def update_dimensions
+        @width = TTY::Screen.width
+        @height = TTY::Screen.height
+      end
+
+      # Enable raw mode (disable line buffering)
+      def enable_raw_mode
+        $stdin.raw!
+      end
+
+      # Disable raw mode
+      def disable_raw_mode
+        $stdin.cooked!
+      end
+
+      # Read a single character without echo
+      # @param timeout [Float] Timeout in seconds (nil for blocking)
+      # @return [String, nil] Character or nil if timeout
+      def read_char(timeout: nil)
+        if timeout
+          return nil unless IO.select([$stdin], nil, nil, timeout)
+        end
+
+        $stdin.getc
+      end
+
+      # Read a key including special keys (arrows, etc.)
+      # @param timeout [Float] Timeout in seconds
+      # @return [Symbol, String, Hash, nil] Key symbol, character, or { type: :rapid_input, text: String }
+      def read_key(timeout: nil)
+        current_time = Time.now.to_f
+        is_rapid_input = @last_input_time && (current_time - @last_input_time) < @rapid_input_threshold
+        @last_input_time = current_time
+
+        char = read_char(timeout: timeout)
+        return nil unless char
+
+        # Convert raw BINARY bytes to valid UTF-8. Invalid/undefined bytes are dropped
+        # rather than raising ArgumentError (which would crash the input loop).
+        char = safe_to_utf8(char) if char.is_a?(String)
+
+        # Handle escape sequences for special keys
+        if char == "\e"
+          # Non-blocking read for escape sequence
+          char2 = read_char(timeout: 0.01)
+          return :escape unless char2
+
+          if char2 == "["
+            char3 = read_char(timeout: 0.01)
+            case char3
+            when "A" then return :up_arrow
+            when "B" then return :down_arrow
+            when "C" then return :right_arrow
+            when "D" then return :left_arrow
+            when "H" then return :home
+            when "F" then return :end
+            when "Z" then return :shift_tab
+            when "3"
+              char4 = read_char(timeout: 0.01)
+              return :delete if char4 == "~"
+            end
+          end
+        end
+
+        # Check if there are more characters available (for rapid input detection)
+        has_more_input = IO.select([$stdin], nil, nil, 0)
+
+        # If this is rapid input or there are more characters available
+        if is_rapid_input || has_more_input
+          buffer = char.to_s.dup
+
+          # Keep reading available characters
+          loop_count = 0
+          empty_checks = 0
+
+          loop do
+            # Check if there's data available immediately
+            has_data = IO.select([$stdin], nil, nil, 0)
+
+            if has_data
+              next_char = $stdin.getc rescue nil
+              break unless next_char
+
+              next_char = safe_to_utf8(next_char)
+              buffer << next_char
+              loop_count += 1
+              empty_checks = 0  # Reset empty check counter
+            else
+              # No immediate data, but wait a bit to see if more is coming
+              # This handles the case where paste data arrives in chunks
+              empty_checks += 1
+              if empty_checks == 1
+                # First empty check - wait 10ms for more data
+                sleep 0.01
+              else
+                # Second empty check - really no more data
+                break
+              end
+            end
+          end
+
+          # If we buffered multiple characters or newlines, treat as rapid input (paste)
+          if buffer.length > 1 || buffer.include?("\n") || buffer.include?("\r")
+            # Ensure the accumulated buffer is valid UTF-8 before regex operations
+            buffer = safe_to_utf8(buffer)
+            # Remove any trailing \r or \n from rapid input buffer
+            cleaned_buffer = buffer.gsub(/[\r\n]+\z/, '')
+            return { type: :rapid_input, text: cleaned_buffer } if cleaned_buffer.length > 0
+          end
+
+          # Single character, continue to normal handling
+          char = buffer[0] if buffer.length == 1
+        end
+
+        # Handle control characters
+        case char
+        when "\r" then :enter
+        when "\n" then :newline  # Shift+Enter sends \n
+        when "\u007F", "\b" then :backspace
+        when "\u0001" then :ctrl_a
+        when "\u0002" then :ctrl_b
+        when "\u0003" then :ctrl_c
+        when "\u0004" then :ctrl_d
+        when "\u0005" then :ctrl_e
+        when "\u0006" then :ctrl_f
+        when "\u000B" then :ctrl_k
+        when "\u000C" then :ctrl_l
+        when "\u000F" then :ctrl_o
+        when "\u0012" then :ctrl_r
+        when "\u0015" then :ctrl_u
+        when "\u0016" then :ctrl_v
+        when "\u0017" then :ctrl_w
+        when "\t"     then :tab
+        else char
+        end
+      end
+
+      # Flush output
+      def flush
+        $stdout.flush
+      end
+
+
+      # Ensure a string is valid UTF-8.
+      # stdin stays in UTF-8 mode so getc returns complete characters (including CJK).
+      # This method handles the rare case where an invalid byte slips through
+      # (e.g. a stray terminal escape or a partial sequence) by scrubbing it out
+      # rather than letting ArgumentError crash the input loop.
+      # @param str [String] String from getc (UTF-8 encoded, but may have invalid bytes)
+      # @return [String] Valid UTF-8 string
+      private def safe_to_utf8(str)
+        return str if str.valid_encoding?
+
+        Octo::Utils::Encoding.sanitize_utf8(str)
+      end
+    end
+  end
+end