riffer-rig 0.2.1 → 0.4.0

data/lib/riffer/rig/tools/bash.rb

@@ -9,14 +9,22 @@ class Riffer::Rig::Tools::Bash < Riffer::Tool
 
   timeout 600
 
-  DEFAULT_TIMEOUT_MS = 120_000
-  MAX_OUTPUT_BYTES = 30_000
+  DEFAULT_TIMEOUT_MS = 120_000 #: Integer
+
+  MAX_OUTPUT_BYTES = 30_000 #: Integer
 
   params do
     required :command, String, description: 'The shell command to run'
-    optional :timeout_ms, Integer, description: 'Kill the command after this many milliseconds', default: DEFAULT_TIMEOUT_MS
+    optional :timeout_ms,
+             Integer,
+             description: 'Kill the command after this many milliseconds',
+             default: DEFAULT_TIMEOUT_MS
   end
 
+  # @rbs context: Riffer::Agent::Context?
+  # @rbs command: String
+  # @rbs ?timeout_ms: Integer
+  # @rbs return: Riffer::Tools::Response
   def call(context:, command:, timeout_ms: DEFAULT_TIMEOUT_MS)
     output, status = run(command, timeout_ms / 1000.0)
     output = truncate(output.rstrip)
@@ -28,11 +36,16 @@ class Riffer::Rig::Tools::Bash < Riffer::Tool
 
   private
 
+  # @rbs command: String
+  # @rbs timeout_seconds: Float
+  # @rbs return: [String, Integer]
   def run(command, timeout_seconds)
     stdin, stdout_and_stderr, wait_thread = Open3.popen2e(command, chdir: Dir.pwd, pgroup: true)
     stdin.close
 
-    unless wait_thread.join(timeout_seconds)
+    joined = wait_thread.join(timeout_seconds) #: Thread?
+
+    unless joined
       kill_group(wait_thread.pid)
       output = stdout_and_stderr.read
       stdout_and_stderr.close
@@ -44,12 +57,17 @@ class Riffer::Rig::Tools::Bash < Riffer::Tool
     [output, wait_thread.value.exitstatus || 1]
   end
 
+  # @rbs pid: Integer
+  # @rbs return: Integer
   def kill_group(pid)
     Process.kill('TERM', -Process.getpgid(pid))
+    Process.getpgid(pid)
   rescue Errno::ESRCH, Errno::EPERM
-    nil
+    0
   end
 
+  # @rbs output: String
+  # @rbs return: String
   def truncate(output)
     return output if output.bytesize <= MAX_OUTPUT_BYTES
 

data/lib/riffer/rig/tools/edit.rb

@@ -9,9 +9,18 @@ class Riffer::Rig::Tools::Edit < Riffer::Tool
     required :path, String, description: 'Path to the file (absolute, or relative to the working directory)'
     required :old_string, String, description: 'The exact text to replace'
     required :new_string, String, description: 'The text to replace it with'
-    optional :replace_all, Riffer::Params::Boolean, description: 'Replace all occurrences instead of requiring a unique match', default: false
+    optional :replace_all,
+             Riffer::Params::Boolean,
+             description: 'Replace all occurrences instead of requiring a unique match',
+             default: false
   end
 
+  # @rbs context: Riffer::Agent::Context?
+  # @rbs path: String
+  # @rbs old_string: String
+  # @rbs new_string: String
+  # @rbs ?replace_all: bool
+  # @rbs return: Riffer::Tools::Response
   def call(context:, path:, old_string:, new_string:, replace_all: false)
     resolved = File.expand_path(path, Dir.pwd)
     return error("File not found: #{path}", type: :not_found) unless File.file?(resolved)
@@ -20,7 +29,12 @@ class Riffer::Rig::Tools::Edit < Riffer::Tool
     occurrences = content.scan(old_string).length
 
     return error("old_string not found in #{path}", type: :not_found) if occurrences.zero?
-    return error("old_string is not unique in #{path} (#{occurrences} matches). Pass replace_all or add more context.", type: :ambiguous_match) if occurrences > 1 && !replace_all
+    if occurrences > 1 && !replace_all
+      return error(
+        "old_string is not unique in #{path} (#{occurrences} matches). Pass replace_all or add more context.",
+        type: :ambiguous_match
+      )
+    end
 
     # Block form so backslash sequences in new_string (\0, \1, \\) are inserted
     # literally instead of being interpreted as regexp backreferences.

data/lib/riffer/rig/tools/read.rb

@@ -5,7 +5,7 @@ class Riffer::Rig::Tools::Read < Riffer::Tool
   description 'Read a file from the filesystem. Returns its contents with line numbers. ' \
               'Use offset/limit to read a slice of a large file.'
 
-  DEFAULT_LIMIT = 2000
+  DEFAULT_LIMIT = 2000 #: Integer
 
   params do
     required :path, String, description: 'Path to the file (absolute, or relative to the working directory)'
@@ -13,6 +13,11 @@ class Riffer::Rig::Tools::Read < Riffer::Tool
     optional :limit, Integer, description: 'Maximum number of lines to read', default: DEFAULT_LIMIT
   end
 
+  # @rbs context: Riffer::Agent::Context?
+  # @rbs path: String
+  # @rbs ?offset: Integer?
+  # @rbs ?limit: Integer
+  # @rbs return: Riffer::Tools::Response
   def call(context:, path:, offset: nil, limit: DEFAULT_LIMIT)
     resolved = File.expand_path(path, Dir.pwd)
     return error("File not found: #{path}", type: :not_found) unless File.file?(resolved)

data/lib/riffer/rig/tools/write.rb

@@ -11,6 +11,10 @@ class Riffer::Rig::Tools::Write < Riffer::Tool
     required :content, String, description: 'The full content to write to the file'
   end
 
+  # @rbs context: Riffer::Agent::Context?
+  # @rbs path: String
+  # @rbs content: String
+  # @rbs return: Riffer::Tools::Response
   def call(context:, path:, content:)
     resolved = File.expand_path(path, Dir.pwd)
     FileUtils.mkdir_p(File.dirname(resolved))

data/lib/riffer/rig/ui/animator.rb

@@ -3,20 +3,36 @@
 # Animated output is gated behind an interactive, colour-enabled TTY, so piped
 # or tested runs stay silent and escape-free.
 class Riffer::Rig::UI::Animator
-  REVEAL_FRAME_SECONDS = 0.05
-  SPINNER_FRAME_SECONDS = 0.12
-  EQ_LEVELS = '▁▂▃▄▅▆▇█'.chars.freeze
-  EQ_BARS = 7
-  NEUTRAL_LABEL = 'riffing…'
+  REVEAL_FRAME_SECONDS = 0.05 #: Float
+
+  SPINNER_FRAME_SECONDS = 0.12 #: Float
+
+  EQ_LEVELS = '▁▂▃▄▅▆▇█'.chars.freeze #: Array[String]
+
+  EQ_BARS = 7 #: Integer
+
+  NEUTRAL_LABEL = 'riffing…' #: String
+
   REASONING_PHRASES = [
     'contemplating…', 'pondering…', 'mulling it over…', 'reasoning…',
     'connecting the dots…', 'herding thoughts…', 'consulting the muse…',
     'doing some deep listening…', 'warming up…', 'tuning up…',
     'in the woodshed…', 'vamping…', 'finding the key…', 'counting it off…',
     'jamming internally…'
-  ].freeze
-  REASONING_TICK_RANGE = (1..5)
+  ].freeze #: Array[String]
 
+  REASONING_TICK_RANGE = (1..5) #: Range[Integer]
+
+  # @rbs @io: untyped
+  # @rbs @theme: Riffer::Rig::UI::Theme
+  # @rbs @thread: Thread?
+  # @rbs @mode: Symbol
+  # @rbs @phrase: String?
+  # @rbs @stop: bool
+
+  # @rbs io: untyped
+  # @rbs ?theme: Riffer::Rig::UI::Theme
+  # @rbs return: void
   def initialize(io: $stdout, theme: Riffer::Rig::UI::Theme.for(io))
     @io = io
     @theme = theme
@@ -26,6 +42,9 @@ class Riffer::Rig::UI::Animator
   end
 
   # When not on a TTY, prints the final frame once instead of animating.
+  #
+  # @rbs frames: Array[Array[String]]
+  # @rbs return: void
   def reveal(frames)
     unless enabled?
       frames.last.each { |line| @io.puts(line) }
@@ -41,6 +60,8 @@ class Riffer::Rig::UI::Animator
     end
   end
 
+  # @rbs ?mode: Symbol
+  # @rbs return: void
   def start(mode = :neutral)
     return unless enabled?
 
@@ -54,16 +75,21 @@ class Riffer::Rig::UI::Animator
     @thread = Thread.new { animate }
   end
 
+  # @rbs return: void
   def stop
-    return unless @thread
+    thread = @thread
+    return unless thread
 
     @stop = true
-    @thread.join
+    thread.join
     @thread = nil
     @io.print("\r\e[K")
     @io.flush
   end
 
+  # @rbs tick: Integer
+  # @rbs ?label: String
+  # @rbs return: String
   def equalizer(tick, label = NEUTRAL_LABEL)
     bars = Array.new(EQ_BARS) do |i|
       height = (Math.sin((tick + i) * 0.6).abs * (EQ_LEVELS.length - 1)).round
@@ -75,6 +101,7 @@ class Riffer::Rig::UI::Animator
 
   private
 
+  # @rbs return: void
   def animate
     tick = 0
     roll_at = 0.0 # force an immediate phrase roll when entering reasoning mode
@@ -88,18 +115,31 @@ class Riffer::Rig::UI::Animator
   end
 
   # Re-rolls both phrase and duration whenever the reasoning tick expires.
+  #
+  # @rbs roll_at: Float
+  # @rbs return: Float
   def roll_phrase(roll_at)
     now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
     return roll_at unless @mode == :reasoning && now >= roll_at
 
     @phrase = REASONING_PHRASES.sample
-    now + rand(REASONING_TICK_RANGE)
+    now + roll_rand
+  end
+
+  # Range rand returns nil for an empty range; this one is a non-empty constant.
+  #
+  # @rbs return: Integer
+  def roll_rand
+    x = rand(REASONING_TICK_RANGE)
+    x || 0
   end
 
+  # @rbs return: String
   def label
-    @mode == :reasoning ? @phrase : NEUTRAL_LABEL
+    @mode == :reasoning ? @phrase || NEUTRAL_LABEL : NEUTRAL_LABEL
   end
 
+  # @rbs return: bool
   def enabled?
     @theme.enabled && @io.respond_to?(:tty?) && @io.tty?
   end

data/lib/riffer/rig/ui/banner.rb

@@ -10,7 +10,7 @@ module Riffer::Rig::UI::Banner
     '██╔══██╗██║██╔══╝  ██╔══╝  ██╔══╝  ██╔══██╗',
     '██║  ██║██║██║     ██║     ███████╗██║  ██║',
     '╚═╝  ╚═╝╚═╝╚═╝     ╚═╝     ╚══════╝╚═╝  ╚═╝'
-  ].freeze
+  ].freeze #: Array[String]
 
   ROW_COLOURS = [
     Riffer::Rig::UI::Palette::PINK,
@@ -19,25 +19,49 @@ module Riffer::Rig::UI::Banner
     Riffer::Rig::UI::Palette::BLUE,
     Riffer::Rig::UI::Palette::CYAN,
     Riffer::Rig::UI::Palette::CYAN
-  ].freeze
+  ].freeze #: Array[Array[Integer]]
 
-  INFO_LABEL_WIDTH = 8
-  INDENT = '  '
+  INFO_LABEL_WIDTH = 8 #: Integer
 
+  INDENT = '  ' #: String
+
+  # @rbs theme: Riffer::Rig::UI::Theme
+  # @rbs model: String
+  # @rbs cwd: String
+  # @rbs context: String
+  # @rbs skills: String
+  # @rbs version: String
+  # @rbs return: String
   def call(theme, model:, cwd:, context:, skills:, version:)
     lines(theme, model: model, cwd: cwd, context: context, skills: skills, version: version).join("\n")
   end
 
+  # @rbs theme: Riffer::Rig::UI::Theme
+  # @rbs model: String
+  # @rbs cwd: String
+  # @rbs context: String
+  # @rbs skills: String
+  # @rbs version: String
+  # @rbs return: Array[String]
   def lines(theme, model:, cwd:, context:, skills:, version:)
     [''] + art(theme) + [''] +
       info(theme, model: model, cwd: cwd, context: context, skills: skills, version: version) + ['']
   end
 
+  # @rbs theme: Riffer::Rig::UI::Theme
+  # @rbs return: Array[String]
   def art(theme)
     art = WORDMARK.each_index.map { |i| "#{INDENT}#{theme.paint(WORDMARK[i], ROW_COLOURS[i])}" }
     art + ["#{INDENT}#{theme.cyan("♪ let's riff ♪")}"]
   end
 
+  # @rbs theme: Riffer::Rig::UI::Theme
+  # @rbs model: String
+  # @rbs cwd: String
+  # @rbs context: String
+  # @rbs skills: String
+  # @rbs version: String
+  # @rbs return: Array[String]
   def info(theme, model:, cwd:, context:, skills:, version:)
     rows = { model: model, cwd: cwd, context: context, skills: skills, version: version }.map do |label, value|
       "  #{theme.magenta('▸')} #{theme.grey(label.to_s.ljust(INFO_LABEL_WIDTH))}#{value}"

data/lib/riffer/rig/ui/cursor.rb

@@ -3,24 +3,35 @@
 # Hides the terminal cursor while a turn is in flight: a hidden cursor can't
 # flicker against the animator's erase-and-redraw churn.
 class Riffer::Rig::UI::Cursor
-  HIDE = "\e[?25l"
-  SHOW = "\e[?25h"
+  HIDE = "\e[?25l" #: String
 
+  SHOW = "\e[?25h" #: String
+
+  # @rbs @io: untyped
+  # @rbs @theme: Riffer::Rig::UI::Theme
+
+  # @rbs io: untyped
+  # @rbs ?theme: Riffer::Rig::UI::Theme
+  # @rbs return: void
   def initialize(io: $stdout, theme: Riffer::Rig::UI::Theme.for(io))
     @io = io
     @theme = theme
   end
 
+  # @rbs return: void
   def hide
     write(HIDE)
   end
 
+  # @rbs return: void
   def show
     write(SHOW)
   end
 
   private
 
+  # @rbs sequence: String
+  # @rbs return: void
   def write(sequence)
     return unless enabled?
 
@@ -28,6 +39,7 @@ class Riffer::Rig::UI::Cursor
     @io.flush
   end
 
+  # @rbs return: bool
   def enabled?
     @theme.enabled && @io.respond_to?(:tty?) && @io.tty?
   end

data/lib/riffer/rig/ui/palette.rb

@@ -1,11 +1,17 @@
 # frozen_string_literal: true
 
 module Riffer::Rig::UI::Palette
-  PINK = [255, 106, 193].freeze
-  MAGENTA = [192, 76, 253].freeze
-  PURPLE = [122, 92, 255].freeze
-  BLUE = [77, 124, 255].freeze
-  CYAN = [45, 226, 230].freeze
-  GREY = [138, 139, 154].freeze
-  RED = [255, 92, 122].freeze
+  PINK = [255, 106, 193].freeze #: Array[Integer]
+
+  MAGENTA = [192, 76, 253].freeze #: Array[Integer]
+
+  PURPLE = [122, 92, 255].freeze #: Array[Integer]
+
+  BLUE = [77, 124, 255].freeze #: Array[Integer]
+
+  CYAN = [45, 226, 230].freeze #: Array[Integer]
+
+  GREY = [138, 139, 154].freeze #: Array[Integer]
+
+  RED = [255, 92, 122].freeze #: Array[Integer]
 end

data/lib/riffer/rig/ui/renderer.rb

@@ -3,83 +3,189 @@
 require 'json'
 
 class Riffer::Rig::UI::Renderer
-  RESULT_PREVIEW_LIMIT = 200
-
+  RESULT_PREVIEW_LIMIT = 200 #: Integer
+
+  # @rbs @io: untyped
+  # @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 @prose_gap_pending: bool
+
+  # @rbs io: untyped
+  # @rbs ?theme: Riffer::Rig::UI::Theme
+  # @rbs ?tally: Riffer::Rig::TokenTally?
+  # @rbs ?smoother: Riffer::Rig::UI::Smoother | PassThroughSmoother?
+  # @rbs return: void
   def initialize(io: $stdout, theme: Riffer::Rig::UI::Theme.for(io), tally: nil, smoother: nil)
     @io = io
     @theme = theme
     @tally = tally
     @smoother = smoother
+    @deferred_usage = nil
+    @prose_gap_pending = false
   end
 
+  # @rbs event: Riffer::StreamEvents::Base
+  # @rbs return: void
   def render(event)
     case event
     when Riffer::StreamEvents::TextDelta
-      smoother << event.content
+      render_prose(event.content)
     when Riffer::StreamEvents::ToolCallDone
-      drain_smoother
-      @io.puts("\n#{@theme.cyan("⚙ #{event.name}(#{format_arguments(event.arguments)})")}")
+      render_tool_activity(2) { @theme.cyan("⚙ #{event.name}(#{format_arguments(event.arguments)})") }
     when Riffer::StreamEvents::SkillActivation
-      drain_smoother
-      @io.puts("\n#{@theme.magenta("✦ skill: #{event.name}")}")
+      render_block(0) { @theme.magenta("✦ skill: #{event.name}") }
     when Riffer::StreamEvents::Interrupt
-      drain_smoother
-      @io.puts(@theme.dim("[interrupted: #{event.reason}]"))
+      render_block(0) { @theme.dim("[interrupted: #{event.reason}]") }
     when Riffer::StreamEvents::TokenUsageDone
-      drain_smoother
-      render_token_usage(event.token_usage)
+      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 return: void
+  def prompt
+    @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 return: void
+  def flush_usage
+    usage = @deferred_usage
+    @deferred_usage = nil
+    tally = @tally
+    return unless usage && tally
+
+    tally.add(usage)
+    render_block(0) { @theme.dim(usage_line(usage, tally)) }
+  end
+
+  # @rbs message: Riffer::Messages::Base
+  # @rbs return: void
   def render_tool_result(message)
     return unless message.is_a?(Riffer::Messages::Tool)
 
+    open_tool_activity
     line = "↳ #{preview(message.content)}"
-    @io.puts(message.error? ? @theme.red(line) : @theme.dim(line))
+    styled = message.error? ? @theme.red(line) : @theme.dim(line)
+    @io.print("    #{styled}\n")
+    @io.flush
   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 return: void
+  def render_block(indent, &)
+    drain_smoother
+    @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)
+    if @prose_gap_pending
+      @prose_gap_pending = false
+      @io.print("\n")
+    end
+    smoother << content
+  end
+
+  # @rbs indent: Integer
+  # @rbs return: void
+  def render_tool_activity(indent, &)
+    open_tool_activity
+    @io.puts((' ' * indent) + yield)
+    @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
+    return if @prose_gap_pending
+
+    drain_smoother
+    @io.puts
+    @prose_gap_pending = true
+  end
+
+  # @rbs usage: Riffer::Providers::TokenUsage
+  # @rbs tally: Riffer::Rig::TokenTally
+  # @rbs return: String
+  def usage_line(usage, tally)
+    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 << 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 Renderer still prints
+  # Stand-in when no smoother is injected, so a bare Riffer::Rig::UI::Renderer still prints
   # synchronously.
   class PassThroughSmoother
+    # @rbs @io: untyped
+
+    # @rbs io: untyped
+    # @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
 
-  def render_token_usage(usage)
-    return unless @tally
-
-    @tally.add(usage)
-
-    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?
-
-    session_parts = ["session #{@tally.total_tokens} tok"]
-    cost = @tally.estimated_cost
-    session_parts << format('~$%.4f', cost) if cost
-
-    @io.puts("\n#{@theme.dim("#{parts.join(' · ')}   #{session_parts.join(' · ')}")}")
-  end
-
+  # @rbs arguments: String
+  # @rbs return: String
   def format_arguments(arguments)
     parsed = JSON.parse(arguments)
     parsed.map { |key, value| "#{key}: #{value.inspect}" }.join(', ')
@@ -87,6 +193,8 @@ class Riffer::Rig::UI::Renderer
     arguments
   end
 
+  # @rbs content: String
+  # @rbs return: String
   def preview(content)
     first_line = content.to_s.lines.first.to_s.chomp
     return first_line if first_line.length <= RESULT_PREVIEW_LIMIT