samagotchi 0.2.0

data/lib/samagotchi/terminal_ui/attached_view.rb

@@ -0,0 +1,264 @@
+# frozen_string_literal: true
+
+require "monitor"
+require_relative "formatting"
+require_relative "../output_formatter"
+require_relative "../turn_tally"
+require_relative "thinking_line"
+
+module Samagotchi
+  class TerminalUI
+    # EventRenderer's view in attached mode, drawn on a Screen: the
+    # thinking feedback is the activity slot, one row right above the prompt
+    # (spinner frame, then the running tool or the newest sentence of the
+    # model's thinking or text, ThinkingLine),
+    # and every finished line is committed output. The local REPL's
+    # multi-line spinner redraws in place, which can't share the terminal
+    # with an open prompt.
+    #
+    # The spinner turns with time, not per chunk: while the slot is shown a
+    # ticker thread redraws it every TICK_INTERVAL, so a turn that gets no
+    # chunks (a queued remote request, a long prompt eval) still looks alive,
+    # and after WAIT_NOTICE_AFTER seconds with no chunk it says how long it
+    # has been waiting for the first token.
+    #
+    # From a turn's TurnTally::MIN_CALLS-th tool call, a second, dim row under
+    # it tallies the turn's calls (TurnTally).
+    class AttachedView
+      include Formatting
+
+      FRAMES = ["|", "/", "-", "\\"].freeze
+      # Chunks arrive faster than a status line is worth redrawing.
+      MIN_REDRAW_INTERVAL = 0.08
+      # Seconds per spinner frame.
+      FRAME_INTERVAL = 0.25
+      # Seconds between the ticker's redraws (specs stub it to nil: no thread).
+      TICK_INTERVAL = FRAME_INTERVAL
+      WAIT_NOTICE_AFTER = 2.0
+
+      attr_reader :context_status
+
+      # @param screen [Surface] with #columns (a Screen)
+      # @param tick_interval [Numeric, nil] seconds between the ticker's
+      #   redraws; nil: no ticker thread (specs call #tick)
+      def initialize(screen, clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }, tick_interval: TICK_INTERVAL)
+        @screen = screen
+        @clock = clock
+        @tick_interval = tick_interval
+        @origin = clock.call
+        @lock = Monitor.new
+        @ticker = nil
+        @tally = TurnTally.new
+        @line = ThinkingLine.new(clock: clock)
+        # Plugins' init tasks running now (chi.init), id => "bundle: label".
+        @init_tasks = {}
+        reset_turn_feedback
+      end
+
+      def print_line(text)
+        @screen.commit(text)
+      end
+
+      # A new turn: its tally starts over too.
+      def reset_turn_feedback
+        @lock.synchronize do
+          reset_feedback_state
+          @tally.reset
+        end
+      end
+
+      # @param _event [Hash] :generation_started (its context window isn't
+      #   shown: the status line is one row)
+      def generation_feedback_started(_event = {})
+        @lock.synchronize do
+          @thinking = true
+          @line.reset
+          @tool = nil
+          @waiting_since = @clock.call
+          redraw_status
+        end
+      end
+
+      def generation_feedback_retrying(event)
+        @lock.synchronize do
+          @retry = "retrying (attempt #{event[:attempt]})"
+          # The retry streams from the start: wait for its first token again.
+          @waiting_since = @clock.call if @thinking
+          redraw_status
+        end
+      end
+
+      def generation_feedback_chunk(event)
+        @lock.synchronize do
+          @retry = nil
+          @waiting_since = nil
+          @line.chunk(event)
+          redraw_status(throttle: true)
+        end
+      end
+
+      def tool_call_feedback_started(event)
+        @lock.synchronize do
+          @retry = nil
+          @waiting_since = nil
+          @tool = "running #{event[:tool]}"
+          @tally.started(key: tally_key(event), tool: event[:tool], params: event[:params])
+          redraw_status
+        end
+      end
+
+      def tool_call_feedback_completed(event)
+        @lock.synchronize do
+          @tally.completed(key: tally_key(event), tool: event[:tool],
+                           status: event.dig(:activity, :status), params: event.dig(:activity, :params))
+        end
+      end
+
+      def clear_generation_retry
+        @lock.synchronize { @retry = nil }
+      end
+
+      def generation_feedback_finished
+        @lock.synchronize do
+          @thinking = false
+          @line.reset
+          @waiting_since = nil
+          redraw_status
+        end
+      end
+
+      # The turn's answer (or a merge's) is out: the slot goes (unless a
+      # plugin's init task still runs). The tally keeps counting until the
+      # next turn starts (a merge goes on).
+      def finish_thinking_spinner
+        @lock.synchronize do
+          reset_feedback_state
+          @init_tasks.empty? ? @screen.clear_slot(:activity) : redraw_status
+        end
+      end
+
+      # A plugin's init task runs (between turns too): the slot turns with
+      # its label until it ends.
+      # @param task [Hash] {bundle:, id:, label:} (an event or a snapshot's)
+      def init_started(task)
+        @lock.synchronize do
+          @init_tasks[task[:id].to_s] = "#{task[:bundle]}: #{task[:label]}"
+          redraw_status
+        end
+      end
+
+      def init_finished(task)
+        @lock.synchronize do
+          @init_tasks.delete(task[:id].to_s)
+          redraw_status
+        end
+      end
+
+      # The turn waits for them: the slot already shows them.
+      def init_wait_feedback(_event); end
+
+      # Pick up a turn joined mid-way (from the Bridge snapshot): the model's
+      # thinking or text so far (+lane+ :thinking or :writing), or the tool it
+      # is running, and the tally of its tool parts.
+      def resume(tail: nil, lane: :writing, tool: nil, parts: nil)
+        @lock.synchronize do
+          @tally.reset.seed(parts) if parts
+          @thinking = true
+          @line.reset
+          @line.resume(lane, tail)
+          @tool = tool && "running #{tool}"
+          @waiting_since = nil
+          redraw_status
+        end
+      end
+
+      # Redraw the slot for the time that passed (the ticker calls it).
+      # @return [Boolean] whether the slot is still shown
+      def tick
+        @lock.synchronize do
+          return false unless status_text
+
+          redraw_status
+          true
+        end
+      end
+
+      # End the ticker (the loop is over; nothing may draw after it).
+      def stop
+        ticker = @lock.synchronize { @ticker.tap { @ticker = nil } }
+        ticker&.kill
+        ticker&.join(0.5)
+      end
+
+      def capture_context_status(status)
+        @context_status = status if status
+      end
+
+      # The REPL's sticky memories line has no source in attached mode.
+      def emit_active_memories_line; end
+
+      private
+
+      def reset_feedback_state
+        @thinking = false
+        @line.reset
+        @tool = nil
+        @retry = nil
+        @waiting_since = nil
+      end
+
+      def tally_key(event)
+        [event[:iteration].to_i, event[:call_index].to_i]
+      end
+
+      def redraw_status(throttle: false)
+        now = @clock.call
+        return if throttle && @last_redraw && (now - @last_redraw) < MIN_REDRAW_INTERVAL
+
+        @last_redraw = now
+        @line.tick
+        text = status_text
+        if text
+          tally = @tally.text(width: @screen.columns - 1)
+          @screen.set_slot(:activity, tally ? [text, paint(tally, 90)] : [text])
+          start_ticker
+        else
+          @screen.clear_slot(:activity)
+        end
+      end
+
+      # One thread per shown slot; it ends when the slot goes (see #tick).
+      def start_ticker
+        return unless @tick_interval
+        return if @ticker&.alive?
+
+        @ticker = Thread.new do
+          loop do
+            sleep(@tick_interval)
+            break unless tick
+          end
+        rescue StandardError
+          nil
+        end
+        @ticker.report_on_exception = false
+      end
+
+      def status_text
+        now = @clock.call
+        frame = FRAMES[((now - @origin) / FRAME_INTERVAL).floor % FRAMES.length]
+        return "#{frame} #{@retry}" if @retry
+        return "#{frame} #{@tool}…" if @tool
+        return "#{frame} #{@init_tasks.values.join(" · ")}…" if !@thinking && @init_tasks.any?
+        return nil unless @thinking
+
+        waited = @waiting_since ? now - @waiting_since : 0
+        return "#{frame} waiting for the first token… #{waited.floor}s" if waited >= WAIT_NOTICE_AFTER
+
+        return "#{frame} thinking…" if @line.empty?
+
+        prefix = "#{frame} #{@line.label} · "
+        prefix + paint(@line.fit(@screen.columns - 1 - prefix.length), 90)
+      end
+    end
+  end
+end

data/lib/samagotchi/terminal_ui/event_renderer.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+require "set"
+
+module Samagotchi
+  class TerminalUI
+    # Renders one UI's view of Engine turn events: the thinking spinner while
+    # the model generates, a `tool>` line per completed tool call, and the
+    # answer (with any tool activity not already shown) from :turn_completed's
+    # turn_summary. It is the `on_event:` sink the REPL hands Engine#run_turn.
+    #
+    # Drawing is delegated to a +view+ (the TerminalUI), so the same dispatch
+    # can later render events that arrive over the Bridge. The renderer keeps
+    # only per-turn bookkeeping that must come from the events themselves:
+    # which tool lines were already streamed, and when each tool call started.
+    # Events that came over the Bridge as JSON (string keys) are symbolized first.
+    class EventRenderer
+      def initialize(view, clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
+        @view = view
+        @clock = clock
+        @streamed_tool_activity = Hash.new(0)
+        @tool_started_at = {}
+        # Card ids shown so far (across turns): one shown again is updated.
+        @card_ids = Set.new
+      end
+
+      # Deep-convert a string-keyed event (JSON from the Bridge) to the local
+      # shape: symbol keys and a symbol :type. Other values stay as they are.
+      def self.symbolize(event)
+        event = deep_symbolize_keys(event)
+        event[:type] = event[:type].to_sym if event[:type].is_a?(String)
+        event
+      end
+
+      def self.deep_symbolize_keys(value)
+        case value
+        when Hash then value.to_h { |k, v| [k.is_a?(String) ? k.to_sym : k, deep_symbolize_keys(v)] }
+        when Array then value.map { |v| deep_symbolize_keys(v) }
+        else value
+        end
+      end
+
+      def call(event)
+        event = self.class.symbolize(event) if event.key?("type")
+        case event[:type]
+        when :turn_started
+          begin_turn
+          Array(event[:images]).each { |ref| @view.print_line(@view.format_image_line(ref)) }
+        when :generation_started
+          @view.generation_feedback_started(event)
+        when :generation_retrying
+          @view.generation_feedback_retrying(event)
+        when :generation_chunk
+          @view.generation_feedback_chunk(event)
+        when :tool_call_started
+          @tool_started_at[tool_call_key(event)] = @clock.call
+          @view.tool_call_feedback_started(event)
+        when :tool_call_completed
+          @view.clear_generation_retry
+          @view.tool_call_feedback_completed(event)
+          render_streamed_tool_activity(event[:activity], duration_ms: tool_duration_ms(event), images: event[:images])
+        when :generation_completed, :generation_cancelled, :tool_dispatch_started
+          @view.generation_feedback_finished
+        when :pending_input_merged
+          render_merge(event)
+        when :turn_completed
+          render_turn_summary(event[:turn_summary]) if event[:turn_summary]
+        when :guardrail_warning
+          @view.print_line(self.class.load_warning_line(event))
+        when :hook_notice
+          @view.print_line(self.class.hook_notice_line(event))
+        when :card
+          render_card(event)
+        # A turn waits for plugins' slow setup before its first request.
+        when :plugin_init_wait
+          @view.init_wait_feedback(event)
+        end
+      end
+
+      # Print a card (a :card event or a snapshot's card) as a framed block;
+      # one whose id was shown before is printed again, marked (updated).
+      # @param updated [Boolean] marked (updated) anyway (a snapshot's card)
+      def render_card(card, updated: false)
+        id = card[:id].to_s
+        updated ||= !id.empty? && @card_ids.include?(id)
+        @card_ids << id unless id.empty?
+        @view.print_line(@view.card_block(card, updated: updated))
+      end
+
+      # @return [Boolean] whether a card with this id was shown here
+      def card_shown?(id) = @card_ids.include?(id.to_s)
+
+      # What failed to load, labelled by what it is: guardrails (the
+      # default) or plugins.
+      def self.load_warning_line(event)
+        "#{event[:label] || "guardrails"}> #{event[:message]}"
+      end
+
+      # A hook's notice as one line: "<bundle>> text" for a bundle hook,
+      # "hook> text" for a config or turn hook (a warn one says so).
+      # @param event [Hash] :hook_notice event or a snapshot part with
+      #   hook:, text:, level:
+      def self.hook_notice_line(event)
+        label = event[:hook].to_s[/\(bundle (.+)\)\z/, 1] || "hook"
+        text = event[:text].to_s
+        text = "warning: #{text}" if event[:level].to_s == "warn"
+        "#{label}> #{text}"
+      end
+
+      # A plugin's init task (chi.init) as one line: "<bundle>> <label>…"
+      # as it starts, "<bundle>> ✓ <summary>" when it is done. A failed
+      # one is a warn card, not a line.
+      # @return [String, nil]
+      def self.init_line(event)
+        case event[:type].to_s
+        when "plugin_init_started" then "#{event[:bundle]}> #{event[:label]}…"
+        when "plugin_init_finished"
+          return nil unless event[:ok]
+
+          "#{event[:bundle]}> ✓ #{event[:summary] || "#{event[:label]}: done"}"
+        end
+      end
+
+      # Start a turn's bookkeeping and reset the view's per-turn feedback.
+      # Also called directly by REPL paths that drive the kernel without
+      # Engine#run_turn (so no :turn_started).
+      def begin_turn
+        @streamed_tool_activity = Hash.new(0)
+        @tool_started_at = {}
+        @view.reset_turn_feedback
+      end
+
+      # Render a finished turn: tool activity the stream did not already show,
+      # the status lines, the answer, and the iteration-limit notice.
+      # @param summary [Hash] Engine#turn_summary
+      def render_turn_summary(summary)
+        @view.finish_thinking_spinner
+        @view.capture_context_status(summary[:context_status])
+        Array(summary[:tool_activity]).each do |activity|
+          next if consume_streamed_tool_activity(activity)
+
+          @view.print_line(@view.format_tool_activity_line(activity))
+        end
+        @view.emit_active_memories_line
+        @view.print_line(summary[:output])
+        @view.print_line("iteration limit reached") if summary[:resumable]
+      end
+
+# Steering merged into the running turn: the answer it follows first
+# (the turn summary shows only the last one), then the note.
+def render_merge(event)
+  @view.finish_thinking_spinner
+  @view.print_line(event[:answer]) unless event[:answer].to_s.strip.empty?
+  count = event[:count].to_i
+  @view.print_line("(#{count} message#{"s" unless count == 1} merged into the running turn)")
+end
+
+private
+
+      def render_streamed_tool_activity(activity, duration_ms:, images: nil)
+        return if activity.nil?
+
+        @streamed_tool_activity[tool_activity_key(activity)] += 1
+        line = @view.format_tool_activity_line(activity, duration_ms: duration_ms)
+        line += @view.format_tool_image_suffix(images) if images&.any?
+        @view.print_line(line)
+      end
+
+      def consume_streamed_tool_activity(activity)
+        key = tool_activity_key(activity)
+        count = @streamed_tool_activity[key]
+        return false unless count.positive?
+
+        @streamed_tool_activity[key] = count - 1
+        true
+      end
+
+      def tool_activity_key(activity)
+        [activity[:action], activity[:tool], activity[:params], activity[:status]].map(&:to_s).join("|")
+      end
+
+      def tool_call_key(event)
+        [event[:iteration].to_i, event[:call_index].to_i, event[:tool].to_s]
+      end
+
+      def tool_duration_ms(event)
+        started_at = @tool_started_at.delete(tool_call_key(event))
+        started_at && ((@clock.call - started_at) * 1000.0)
+      end
+    end
+  end
+end