riffer-rig 0.5.0 → 0.7.0

data/lib/riffer/rig/{ui → terminal}/renderer.rb

@@ -2,31 +2,34 @@
 
 require 'json'
 
-class Riffer::Rig::UI::Renderer
+class Riffer::Rig::Terminal::Renderer
   RESULT_PREVIEW_LIMIT = 200 #: Integer
 
   # @rbs @io: IO
-  # @rbs @theme: Riffer::Rig::UI::Theme
-  # @rbs @tally: Riffer::Rig::TokenTally?
-  # @rbs @smoother: Riffer::Rig::UI::Smoother | PassThroughSmoother?
-  # @rbs @deferred_usage: Riffer::Providers::TokenUsage?
+  # @rbs @theme: Riffer::Rig::Terminal::Theme
+  # @rbs @smoother: Riffer::Rig::Terminal::Smoother | PassThroughSmoother
+  # @rbs @cursor: Riffer::Rig::Terminal::Cursor
   # @rbs @prose_gap_pending: bool
 
   # @rbs io: IO
-  # @rbs theme: Riffer::Rig::UI::Theme
-  # @rbs tally: Riffer::Rig::TokenTally?
-  # @rbs smoother: Riffer::Rig::UI::Smoother | PassThroughSmoother?
+  # @rbs theme: Riffer::Rig::Terminal::Theme
+  # @rbs smoother: Riffer::Rig::Terminal::Smoother | PassThroughSmoother
+  # @rbs cursor: Riffer::Rig::Terminal::Cursor
   # @rbs return: void
-  def initialize(io: $stdout, theme: Riffer::Rig::UI::Theme.for(io), tally: nil, smoother: nil)
+  def initialize(
+    io: $stdout,
+    theme: Riffer::Rig::Terminal::Theme.for(io),
+    smoother: PassThroughSmoother.new(io),
+    cursor: Riffer::Rig::Terminal::Cursor.new(io: io, theme: theme)
+  )
     @io = io
     @theme = theme
-    @tally = tally
     @smoother = smoother
-    @deferred_usage = nil
+    @cursor = cursor
     @prose_gap_pending = false
   end
 
-  # @rbs event: Riffer::StreamEvents::Base
+  # @rbs event: Riffer::StreamEvents::TextDelta | Riffer::StreamEvents::ToolCallDone | Riffer::StreamEvents::Interrupt
   # @rbs return: void
   def render(event)
     case event
@@ -34,42 +37,91 @@ class Riffer::Rig::UI::Renderer
       render_prose(event.content)
     when Riffer::StreamEvents::ToolCallDone
       render_tool_activity(2) { @theme.cyan("⚙ #{event.name}(#{format_arguments(event.arguments)})") }
-    when Riffer::StreamEvents::SkillActivation
-      render_block(0) { @theme.magenta("✦ skill: #{event.name}") }
     when Riffer::StreamEvents::Interrupt
       render_block(0) { @theme.dim("[interrupted: #{event.reason}]") }
-    when Riffer::StreamEvents::TokenUsageDone
-      current = @deferred_usage
-      @deferred_usage = current ? current + event.token_usage : event.token_usage
     end
   end
 
-  # The prompt holds the line open for typed input, so unlike render_block it
-  # ends without a newline. It sits at the renderer so a tool group left open by
-  # the previous turn closes here, and the next turn's blocks open cleanly.
-  #
+  # @rbs name: String
+  # @rbs return: void
+  def skill(name)
+    render_block(0) { @theme.magenta("✦ skill: #{name}") }
+  end
+
+  # @rbs text: String
+  # @rbs return: void
+  def notice(text)
+    render_block(0) { @theme.grey(text) }
+  end
+
+  # @rbs text: String
+  # @rbs return: void
+  def error(text)
+    render_block(0) { @theme.red(text) }
+  end
+
+  # @rbs message: String
+  # @rbs level: Symbol
+  # @rbs return: void
+  def notify(message, level)
+    level == :error ? error(message) : notice(message)
+  end
+
+  # @rbs usage: Riffer::Providers::TokenUsage?
+  # @rbs session: Riffer::Providers::TokenUsage?
+  # @rbs return: void
+  def usage(usage, session)
+    return unless usage && session
+
+    render_block(0) { @theme.dim(usage_line(usage, session)) }
+  end
+
   # @rbs return: void
   def prompt
+    # Closes any tool group the previous turn left open, so the next turn's
+    # blocks open cleanly.
     @prose_gap_pending = true
     @io.puts
     @io.print("#{@theme.pink('›')} ")
     @io.flush
   end
 
-  # Usage arrives per model call but tool results arrive via the session
-  # callback after each call's stream ends, so rendering inline would print the
-  # stats above the results they belong with. Held until the turn's output is
-  # done, then printed as one line below it.
-  #
+  # @rbs question: String?
+  # @rbs options: Array[String]?
+  # @rbs secret: bool
   # @rbs return: void
-  def flush_usage
-    usage = @deferred_usage
-    @deferred_usage = nil
-    tally = @tally
-    return unless usage && tally
+  def question(question, options, secret)
+    drain
+    @io.puts
+    @io.puts(question) if question
+    options&.each_with_index { |option, index| @io.puts("  #{@theme.magenta("#{index + 1}.")} #{option}") }
+    @io.print("#{@theme.pink('›')} #{@theme.grey('(hidden) ') if secret}")
+    @io.flush
+  end
 
-    tally.add(usage)
-    render_block(0) { @theme.dim(usage_line(usage, tally)) }
+  # @rbs return: void
+  def newline
+    @io.puts
+    @io.flush
+  end
+
+  # @rbs return: void
+  def begin_turn
+    # A hidden cursor can't flicker against the animator's erase-and-redraw
+    # churn.
+    @cursor.hide
+    @smoother.start
+  end
+
+  # @rbs return: void
+  def end_turn
+    @smoother.finish
+    @cursor.show
+  end
+
+  # @rbs return: void
+  def drain
+    @smoother.drain
   end
 
   # @rbs message: Riffer::Messages::Base
@@ -84,36 +136,54 @@ class Riffer::Rig::UI::Renderer
     @io.flush
   end
 
+  class PassThroughSmoother
+    # @rbs @io: IO
+
+    # @rbs io: IO
+    # @rbs return: void
+    def initialize(io) = @io = io
+
+    # @rbs content: String
+    # @rbs return: self
+    def <<(content)
+      @io.print(content)
+      @io.flush
+      self
+    end
+
+    # @rbs return: nil
+    def start = nil
+
+    # @rbs return: nil
+    def drain = nil
+
+    # @rbs return: nil
+    def finish = nil
+  end
+
   private
 
-  # Rule 2 for one-off blocks (skill line, interrupt, stats): one blank line
-  # above, no indent. The smoother drains first so any pending partial prose
-  # block ends cleanly before the gap is written, and any open tool group closes
-  # so the next group opens with its own gap.
-  #
   # @rbs indent: Integer
   # @rbs &block: () -> String
   # @rbs return: void
   def render_block(indent, &)
-    drain_smoother
+    drain
     @io.puts
     @prose_gap_pending = true
     @io.puts((' ' * indent) + yield)
     @io.flush
   end
 
-  # The blank line above a prose block is written at the first delta after a
-  # non-prose block. Streaming makes "which block is first?" a stateful
-  # question, so the answer is tracked rather than embedded at each render site.
-  #
   # @rbs content: String
   # @rbs return: void
   def render_prose(content)
+    # Streaming makes "which delta opens a prose block?" a stateful question,
+    # so the gap is tracked in a flag rather than written at each render site.
     if @prose_gap_pending
       @prose_gap_pending = false
       @io.print("\n")
     end
-    smoother << content
+    @smoother << content
   end
 
   # @rbs indent: Integer
@@ -125,67 +195,31 @@ class Riffer::Rig::UI::Renderer
     @io.flush
   end
 
-  # Tool-activity lines (⚙ calls, ↳ results) share one blank line above the
-  # group instead of one between each line — the gap goes between groups, not
-  # inside a pair. The group stays open so prose after it pays the closing gap.
-  #
   # @rbs return: void
   def open_tool_activity
+    # Tool-activity lines (⚙ calls, ↳ results) share one blank line above the
+    # group; the group stays open so the prose after it pays the closing gap.
     return if @prose_gap_pending
 
-    drain_smoother
+    drain
     @io.puts
     @prose_gap_pending = true
   end
 
   # @rbs usage: Riffer::Providers::TokenUsage
-  # @rbs tally: Riffer::Rig::TokenTally
+  # @rbs session: Riffer::Providers::TokenUsage
   # @rbs return: String
-  def usage_line(usage, tally)
+  def usage_line(usage, session)
     parts = ["↑#{usage.input_tokens}", "↓#{usage.output_tokens}"]
     parts << "cache_write:#{usage.cache_write_tokens}" if usage.cache_write_tokens&.positive?
     parts << "cache_read:#{usage.cache_read_tokens}" if usage.cache_read_tokens&.positive?
-    parts << "session #{tally.total_tokens} tok"
-    cost = tally.estimated_cost
+    parts << "session #{session.total_tokens} tok"
+    cost = session.cost
     parts << format('~$%.4f', cost) if cost
 
     parts.join(' · ')
   end
 
-  # @rbs return: Riffer::Rig::UI::Smoother | PassThroughSmoother
-  def smoother
-    @smoother || PassThroughSmoother.new(@io)
-  end
-
-  # Stand-in when no smoother is injected, so a bare Riffer::Rig::UI::Renderer still prints
-  # synchronously.
-  class PassThroughSmoother
-    # @rbs @io: IO
-
-    # @rbs io: IO
-    # @rbs return: void
-    def initialize(io) = @io = io
-
-    # @rbs content: String
-    # @rbs return: self
-    def <<(content)
-      @io.print(content)
-      @io.flush
-      self
-    end
-
-    # @rbs return: nil
-    def drain = nil
-
-    # @rbs return: nil
-    def finish = nil
-  end
-
-  # @rbs return: void
-  def drain_smoother
-    smoother.drain
-  end
-
   # @rbs arguments: String
   # @rbs return: String
   def format_arguments(arguments)

data/lib/riffer/rig/{ui → terminal}/smoother.rb

@@ -1,24 +1,19 @@
 # frozen_string_literal: true
 
-# Paces streamed text onto a 60fps cadence so API bursts read as continuous
-# typing. On a non-TTY output it is transparent: writes pass through
-# synchronously and no thread ever runs.
-class Riffer::Rig::UI::Smoother
+class Riffer::Rig::Terminal::Smoother
   TICK_SECONDS = 1.0 / 60.0 #: Float
 
-  # A frame removes only a sixtieth of the remaining backlog — an exponential
-  # decay whose tail keeps text flowing for a second or more, so the reveal
-  # never visibly stops between chunks. The carry accrues sub-character
-  # releases so the effective rate can settle at the provider's throughput;
-  # the floor is fractional (10 chars/s) so it can't over-drain a backlog
-  # that's trickling in slower than 60 chars/s.
-  #
+  # Releasing a fraction of the backlog, not a fixed rate, makes the reveal an
+  # exponential decay: its tail keeps text flowing for a second or more, so
+  # output never visibly stops between chunks.
   BACKLOG_FRACTION_PER_TICK = Rational(1, 60) #: Rational
 
+  # Fractional (10 chars/s) so the floor can't over-drain a backlog that's
+  # trickling in slower than 60 chars/s.
   MIN_CHARS_PER_TICK = Rational(1, 6) #: Rational
 
   # @rbs @io: IO
-  # @rbs @theme: Riffer::Rig::UI::Theme
+  # @rbs @theme: Riffer::Rig::Terminal::Theme
   # @rbs @clock: singleton(Kernel)
   # @rbs @backlog: String
   # @rbs @carry: Rational
@@ -28,10 +23,10 @@ class Riffer::Rig::UI::Smoother
   # @rbs @newline_pending: bool
 
   # @rbs io: IO
-  # @rbs theme: Riffer::Rig::UI::Theme
+  # @rbs theme: Riffer::Rig::Terminal::Theme
   # @rbs clock: singleton(Kernel)
   # @rbs return: void
-  def initialize(io: $stdout, theme: Riffer::Rig::UI::Theme.for(io), clock: Kernel)
+  def initialize(io: $stdout, theme: Riffer::Rig::Terminal::Theme.for(io), clock: Kernel)
     @io = io
     @theme = theme
     @clock = clock
@@ -72,13 +67,13 @@ class Riffer::Rig::UI::Smoother
     self
   end
 
-  # The write sits inside the mutex so a concurrent tick can't reorder a drain.
-  #
   # @rbs return: void
   def tick
     @mutex.synchronize do
       return if @backlog.empty?
 
+      # The carry accrues sub-character releases so the effective rate can
+      # settle at the provider's throughput.
       @carry += [@backlog.length * BACKLOG_FRACTION_PER_TICK, MIN_CHARS_PER_TICK].max
       count = @carry.floor
       return if count.zero?
@@ -86,16 +81,12 @@ class Riffer::Rig::UI::Smoother
       @carry -= count
       chunk = @backlog.slice!(0, count) || ''
       @newline_pending = !chunk.end_with?("\n")
+      # Written inside the mutex so a concurrent drain can't reorder output.
       @io.print(chunk)
       @io.flush
     end
   end
 
-  # Called before non-prose output so printed order matches stream order. The
-  # backlog is flushed, then any partial prose block the model left without a
-  # trailing newline gets one, so block spacing never depends on the model's
-  # last character.
-  #
   # @rbs return: void
   def drain
     @mutex.synchronize do
@@ -106,16 +97,17 @@ class Riffer::Rig::UI::Smoother
       end
       return unless @newline_pending
 
+      # Block spacing must not depend on whether the model ended its prose
+      # with a newline.
       @newline_pending = false
       @io.print("\n")
       @io.flush
     end
   end
 
-  # Idempotent: the REPL's ensure path runs it even after a happy-path finish.
-  #
   # @rbs return: void
   def finish
+    # Idempotent: the REPL's ensure path runs it even after a happy-path finish.
     thread = @thread
     if thread
       @stop = true

data/lib/riffer/rig/{ui → terminal}/theme.rb

@@ -1,11 +1,8 @@
 # frozen_string_literal: true
 
-# +enabled+ gates every escape so the same code path emits plain, escape-free
-# text when piped or tested.
-class Riffer::Rig::UI::Theme
+class Riffer::Rig::Terminal::Theme
   # @rbs @enabled: bool
 
-  # @rbs return: bool
   # @dynamic enabled
   attr_reader :enabled #: bool
 
@@ -16,9 +13,10 @@ class Riffer::Rig::UI::Theme
   end
 
   # @rbs io: IO
-  # @rbs return: Riffer::Rig::UI::Theme
-  def self.for(io)
-    new(enabled: io.tty? && !ENV.key?('NO_COLOR'))
+  # @rbs no_color: bool
+  # @rbs return: Riffer::Rig::Terminal::Theme
+  def self.for(io, no_color: false)
+    new(enabled: io.tty? && !no_color)
   end
 
   # @rbs text: String
@@ -32,31 +30,31 @@ class Riffer::Rig::UI::Theme
 
   # @rbs text: String
   # @rbs return: String
-  def pink(text) = paint(text, Riffer::Rig::UI::Palette::PINK)
+  def pink(text) = paint(text, Riffer::Rig::Terminal::Palette::PINK)
 
   # @rbs text: String
   # @rbs return: String
-  def magenta(text) = paint(text, Riffer::Rig::UI::Palette::MAGENTA)
+  def magenta(text) = paint(text, Riffer::Rig::Terminal::Palette::MAGENTA)
 
   # @rbs text: String
   # @rbs return: String
-  def purple(text) = paint(text, Riffer::Rig::UI::Palette::PURPLE)
+  def purple(text) = paint(text, Riffer::Rig::Terminal::Palette::PURPLE)
 
   # @rbs text: String
   # @rbs return: String
-  def blue(text) = paint(text, Riffer::Rig::UI::Palette::BLUE)
+  def blue(text) = paint(text, Riffer::Rig::Terminal::Palette::BLUE)
 
   # @rbs text: String
   # @rbs return: String
-  def cyan(text) = paint(text, Riffer::Rig::UI::Palette::CYAN)
+  def cyan(text) = paint(text, Riffer::Rig::Terminal::Palette::CYAN)
 
   # @rbs text: String
   # @rbs return: String
-  def grey(text) = paint(text, Riffer::Rig::UI::Palette::GREY)
+  def grey(text) = paint(text, Riffer::Rig::Terminal::Palette::GREY)
 
   # @rbs text: String
   # @rbs return: String
-  def red(text) = paint(text, Riffer::Rig::UI::Palette::RED)
+  def red(text) = paint(text, Riffer::Rig::Terminal::Palette::RED)
 
   # @rbs text: String
   # @rbs return: String

data/lib/riffer/rig/terminal.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+class Riffer::Rig::Terminal
+  EXIT_COMMANDS = %w[/exit /quit].freeze #: Array[String]
+
+  SLASH_COMMAND = %r{\A/(\S+)\s*(.*)\z}m #: Regexp
+
+  SKILL_COMMAND_PREFIX = 'skill:'
+
+  EXIT_HINT = 'Press Ctrl-C again to exit.'
+
+  FAREWELL = 'see you on the next riff.'
+
+  # @rbs @input: IO
+  # @rbs @host: Riffer::Rig::Hosts::_Host
+  # @rbs @renderer: Riffer::Rig::Terminal::Renderer
+  # @rbs @animator: Riffer::Rig::Terminal::Animator
+  # @rbs @theme: Riffer::Rig::Terminal::Theme
+  # @rbs @version: String
+
+  # @rbs input: IO
+  # @rbs output: IO
+  # @rbs version: String
+  # @rbs no_color: bool
+  # @rbs return: Riffer::Rig::Terminal
+  def self.for(input:, output:, version:, no_color: false)
+    theme = Theme.for(output, no_color: no_color)
+    smoother = Smoother.new(io: output, theme: theme)
+    renderer = Renderer.new(io: output, theme: theme, smoother: smoother, cursor: Cursor.new(io: output, theme: theme))
+    animator = Animator.new(io: output, theme: theme)
+    host = Riffer::Rig::Terminal::Host.new(input: input, renderer: renderer, animator: animator)
+    new(input: input, host: host, renderer: renderer, animator: animator, theme: theme, version: version)
+  end
+
+  # @rbs input: IO
+  # @rbs host: Riffer::Rig::Hosts::_Host
+  # @rbs renderer: Riffer::Rig::Terminal::Renderer
+  # @rbs animator: Riffer::Rig::Terminal::Animator
+  # @rbs theme: Riffer::Rig::Terminal::Theme
+  # @rbs version: String
+  # @rbs return: void
+  def initialize(input:, host:, renderer:, animator:, theme:, version:)
+    @input = input
+    @host = host
+    @renderer = renderer
+    @animator = animator
+    @theme = theme
+    @version = version
+  end
+
+  # @rbs &build: (Riffer::Rig::Hosts::_Host) -> Riffer::Rig::Runtime
+  # @rbs return: Integer
+  def run(&build)
+    runtime = load(build)
+    return 1 unless runtime
+
+    begin
+      runtime.on_message { |message| render_tool_result(message) }
+      reveal_banner(runtime)
+      repl(runtime)
+      @renderer.notice(FAREWELL)
+      0
+    ensure
+      runtime.close
+    end
+  end
+
+  private
+
+  # @rbs build: ^(Riffer::Rig::Hosts::_Host) -> Riffer::Rig::Runtime
+  # @rbs return: Riffer::Rig::Runtime?
+  def load(build)
+    build.call(@host)
+  rescue Riffer::Rig::Loader::ConfigurationError => e
+    @renderer.error(e.message)
+    nil
+  rescue Interrupt
+    @renderer.newline
+    nil
+  end
+
+  # @rbs runtime: Riffer::Rig::Runtime
+  # @rbs return: void
+  def reveal_banner(runtime)
+    skills = runtime.commands.count { |command| command.name.start_with?(SKILL_COMMAND_PREFIX) }
+    lines = Banner.lines(
+      @theme,
+      model: runtime.model,
+      cwd: runtime.cwd,
+      skills: skills.zero? ? 'none' : skills.to_s,
+      version: @version
+    )
+    @animator.reveal([lines])
+  end
+
+  # @rbs runtime: Riffer::Rig::Runtime
+  # @rbs return: void
+  def repl(runtime)
+    armed = false
+    loop do
+      case (line = read_line)
+      when nil then break
+      when :interrupt
+        break if armed
+
+        armed = true
+        @renderer.notice(EXIT_HINT)
+      else
+        armed = false
+        text = line.strip
+        break if EXIT_COMMANDS.include?(text)
+
+        dispatch(runtime, text) unless text.empty?
+      end
+    end
+  end
+
+  # @rbs return: String | :interrupt | nil
+  def read_line
+    @renderer.prompt
+    @input.gets
+  rescue Interrupt
+    :interrupt
+  end
+
+  # @rbs runtime: Riffer::Rig::Runtime
+  # @rbs text: String
+  # @rbs return: void
+  def dispatch(runtime, text)
+    command = SLASH_COMMAND.match(text)
+    turn(runtime) do |emit|
+      if command
+        runtime.run_command(command[1].to_s, command[2].to_s, &emit)
+      else
+        runtime.prompt(text, &emit)
+      end
+    end
+  end
+
+  # @rbs runtime: Riffer::Rig::Runtime
+  # @rbs &block: (^(::Riffer::StreamEvents::Base | Riffer::Rig::Events::_Event) -> void) -> void
+  # @rbs return: void
+  def turn(runtime)
+    # Runtime#cancel takes a Mutex, which Ruby refuses inside a trap handler,
+    # so the handler hands the cancel to a thread.
+    previous = Signal.trap('INT') { Thread.new { runtime.cancel } }
+    begin
+      @renderer.begin_turn
+      start_animator
+      yield(->(event) { render(runtime, event) })
+    rescue StandardError => e
+      @animator.stop
+      @renderer.error("Error: #{e.message}")
+    ensure
+      Signal.trap('INT', previous)
+      @animator.stop
+      @renderer.end_turn
+    end
+  end
+
+  # @rbs runtime: Riffer::Rig::Runtime
+  # @rbs event: ::Riffer::StreamEvents::Base | Riffer::Rig::Events::_Event
+  # @rbs return: void
+  def render(runtime, event)
+    case event
+    when Riffer::StreamEvents::ReasoningDelta
+      start_animator(:reasoning)
+    when Riffer::StreamEvents::ReasoningDone, Riffer::StreamEvents::TokenUsageDone
+      # Tool execution and the next model call emit no events, so the spinner
+      # comes straight back on to cover the silent stretch.
+      start_animator
+    when Riffer::StreamEvents::TextDelta, Riffer::StreamEvents::ToolCallDone, Riffer::StreamEvents::Interrupt
+      @animator.stop
+      @renderer.render(event)
+    when Riffer::StreamEvents::SkillActivation, Riffer::Rig::Events::SkillActivated
+      @animator.stop
+      @renderer.skill(event.name)
+      start_animator
+    when Riffer::Rig::Events::CommandOutput
+      @animator.stop
+      @renderer.notice(event.text)
+    when Riffer::Rig::Events::TurnEnd
+      @animator.stop
+      @renderer.usage(event.usage, runtime.tally)
+    end
+  end
+
+  # @rbs message: Riffer::Messages::Base
+  # @rbs return: void
+  def render_tool_result(message)
+    return unless message.is_a?(Riffer::Messages::Tool)
+
+    @animator.stop
+    @renderer.render_tool_result(message)
+    start_animator
+  end
+
+  # @rbs mode: Symbol
+  # @rbs return: void
+  def start_animator(mode = :neutral)
+    # The smoother's backlog may still be trickling out from streamed prose,
+    # and spinner frames drawn mid-drain would carve `\r…\e[K` through a
+    # half-printed sentence.
+    @renderer.drain
+    @animator.start(mode)
+  end
+end