riffer-rig 0.4.0 → 0.6.0

data/lib/riffer/rig/runtime.rb

@@ -0,0 +1,225 @@
+# frozen_string_literal: true
+
+require 'date'
+require 'securerandom'
+
+# Never renders, prints or reads the filesystem: anything a host needs is a
+# Runtime feature, so embedders get it too.
+class Riffer::Rig::Runtime
+  class BusyError < StandardError; end
+
+  class ClosedError < StandardError; end
+
+  BASE_PROMPT_TEMPLATE = <<~TEXT
+    You are %<name>s, a general-purpose agent. You work by using the tools you have
+    been given; each tool describes what it does and when to use it.
+
+    - Verify with your tools before answering. When a tool can settle a question,
+      look rather than guess.
+    - Do what was asked, and all of what was asked. Do not widen the scope, tidy
+      nearby things, or add extras that were not requested.
+    - Be concise. Lead with the outcome; do not restate the question.
+  TEXT
+
+  DEFAULT_NAME = 'riffer'
+
+  # Unlimited: riffer's own default (16) is too small for a general-purpose
+  # harness.
+  DEFAULT_MAX_STEPS = nil #: Integer?
+
+  INTERRUPT_CANCELLED = :cancelled #: Symbol
+
+  # @rbs @agent: Riffer::Agent
+  # @rbs @base_prompt: String
+  # @rbs @cancel_flag: Riffer::Rig::Runtime::CancelFlag
+  # @rbs @credentials: Hash[Symbol, Hash[Symbol, String]]
+  # @rbs @cwd: String
+  # @rbs @host: Riffer::Rig::Hosts::Mirror
+  # @rbs @id: String
+  # @rbs @settings: Hash[Symbol, untyped]
+  # @rbs @busy: bool
+  # @rbs @closed: bool
+  # @rbs @session_start_pending: bool
+  # @rbs @registrar: Riffer::Rig::Registrar
+
+  # @dynamic agent, credentials, cwd, host, id, settings
+  attr_reader :agent #: Riffer::Agent
+  attr_reader :credentials #: Hash[Symbol, Hash[Symbol, String]]
+  attr_reader :cwd #: String
+  attr_reader :host #: Riffer::Rig::Hosts::Mirror
+  attr_reader :id #: String
+  attr_reader :settings #: Hash[Symbol, untyped]
+
+  # @rbs model: String
+  # @rbs extensions: Array[Riffer::Rig::Extension]
+  # @rbs tools: Array[String]?
+  # @rbs settings: Hash[Symbol, untyped]
+  # @rbs host: Riffer::Rig::Hosts::Base
+  # @rbs cwd: String?
+  # @rbs name: String
+  # @rbs instructions: String?
+  # @rbs credentials: Hash[Symbol, Hash[Symbol, String]]
+  # @rbs pricing: Hash[String, Riffer::Rig::Settings::Pricing]
+  # @rbs max_steps: Integer?
+  # @rbs snapshot: Hash[Symbol, untyped]?
+  # @rbs return: void
+  def initialize(
+    model,
+    extensions: [],
+    tools: nil,
+    settings: {},
+    host: Riffer::Rig::Hosts::Null.new,
+    cwd: nil,
+    name: DEFAULT_NAME,
+    instructions: nil,
+    credentials: {},
+    pricing: {},
+    max_steps: DEFAULT_MAX_STEPS,
+    snapshot: nil
+  )
+    # Doubles as the snapshot id and ACP sessionId.
+    @id = ::SecureRandom.uuid_v7
+    @host = Riffer::Rig::Hosts::Mirror.new(host)
+    @cwd = cwd || Dir.pwd
+    @settings = settings
+    @credentials = credentials
+
+    @busy = false
+    @closed = false
+    @cancel_flag = Riffer::Rig::Runtime::CancelFlag.new
+    @session_start_pending = true
+    @registrar = build_registrar(extensions)
+    tool_classes = select_tools(@registrar.tools, tools)
+    @base_prompt = instructions || format(BASE_PROMPT_TEMPLATE, name: name)
+
+    @agent = Riffer::Agent.new(
+      context: { cancel_flag: @cancel_flag },
+      config: Riffer::Agent::Config.new(
+        model: model,
+        instructions: system_prompt([]),
+        tools_config: tool_classes,
+        max_steps: max_steps
+      )
+    )
+    @agent.session.on_message { |_message| interrupt_if_cancelled }
+  end
+
+  # @rbs text: String
+  # @rbs &block: ?(::Riffer::StreamEvents::Base | Riffer::Rig::Events::Event) -> void
+  # @rbs return: (nil | Enumerator[::Riffer::StreamEvents::Base | Riffer::Rig::Events::Event, Riffer::Agent::Response])
+  def prompt(text, &block)
+    raise BusyError, 'a prompt is already running on this Runtime' if @busy
+    raise ClosedError, 'this Runtime is closed' if @closed
+
+    @busy = true
+    @cancel_flag.clear
+    refresh_system_message
+    if block
+      wrap_stream(@agent.stream(text)).each(&block)
+      nil
+    else
+      wrap_stream(@agent.stream(text))
+    end
+  ensure
+    @busy = false
+  end
+
+  # @rbs text: String
+  # @rbs return: Riffer::Agent::Response
+  def ask(text)
+    raise BusyError, 'a prompt is already running on this Runtime' if @busy
+    raise ClosedError, 'this Runtime is closed' if @closed
+
+    @busy = true
+    @cancel_flag.clear
+    refresh_system_message
+    @agent.stream(text).each { |event| event }
+  ensure
+    @busy = false
+  end
+
+  # @rbs return: nil
+  def cancel
+    @cancel_flag.set
+    nil
+  end
+
+  # @rbs return: void
+  def close
+    # TODO: emit Riffer::Rig::Events::SessionEnd once the rebuild ticket settles
+    # the stream's session_end reasons.
+    @closed = true
+  end
+
+  private
+
+  # @rbs stream: Enumerator[Riffer::StreamEvents::Base, Riffer::Agent::Response]
+  # @rbs return: Enumerator[::Riffer::StreamEvents::Base | Riffer::Rig::Events::Event, Riffer::Agent::Response]
+  def wrap_stream(stream)
+    Enumerator.new do |yielder|
+      yielder << Riffer::Rig::Events::SessionStart.new(@id, :new) if @session_start_pending
+      @session_start_pending = false
+      @host.drain.each { |event| yielder << event }
+      response = stream.each { |event| yielder << event }
+      yielder << Riffer::Rig::Events::TurnEnd.new(stop_reason(response.outcome), response.token_usage)
+      response
+    end
+  end
+
+  # @rbs return: void
+  def interrupt_if_cancelled
+    return unless @cancel_flag.set?
+
+    @agent.session.discard_pending_tool_calls
+    # Upstream candidate: a cancel token on riffer's run loop. Until then the
+    # loop can only be stopped from inside, at a message boundary.
+    @agent.interrupt!(INTERRUPT_CANCELLED)
+  end
+
+  # @rbs outcome: Riffer::Agent::Outcome
+  # @rbs return: Symbol
+  def stop_reason(outcome)
+    # Upstream candidate: riffer's outcome vocabulary is closed, so a cancel
+    # reaches us as :interrupted with the reason in detail.
+    cancelled = outcome.reason == :interrupted && outcome.detail == INTERRUPT_CANCELLED.to_s
+    cancelled ? INTERRUPT_CANCELLED : outcome.reason
+  end
+
+  # @rbs extensions: Array[Riffer::Rig::Extension]
+  # @rbs return: Riffer::Rig::Registrar
+  def build_registrar(extensions)
+    raise BusyError, 'a prompt is already running on this Runtime' if @busy
+
+    extensions.each_with_object(Riffer::Rig::Registrar.new) do |extension, registrar|
+      extension.run(registrar)
+    end
+  end
+
+  # @rbs registered: Array[singleton(Riffer::Tool)]
+  # @rbs allowlist: Array[String]?
+  # @rbs return: Array[singleton(Riffer::Tool)]
+  def select_tools(registered, allowlist)
+    return registered if allowlist.nil?
+
+    registered.select { |klass| allowlist.include?(klass.name) }
+  end
+
+  # @rbs return: void
+  def refresh_system_message
+    # Upstream candidate: riffer resolves `instructions` once, in Agent.new, so
+    # a per-turn system message has to be swapped into the session by hand.
+    session = @agent.session
+    session.set([Riffer::Messages::System.new(system_prompt(rendered_sections)), *session.messages.drop(1)])
+  end
+
+  # @rbs return: Array[String]
+  def rendered_sections
+    @registrar.prompts.each_value.map { |section| section.call(self).to_s }.reject(&:empty?)
+  end
+
+  # @rbs sections: Array[String]
+  # @rbs return: String
+  def system_prompt(sections)
+    [@base_prompt, *sections, "Current date: #{Date.today}\nCurrent working directory: #{@cwd}"].join("\n\n")
+  end
+end

data/lib/riffer/rig/settings/document.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+class Riffer::Rig::Settings::Document
+  # @rbs @model: String?
+  # @rbs @reasoning: String?
+  # @rbs @models: Hash[String, Riffer::Rig::Settings::Pricing]
+  # @rbs @providers: Hash[String, Hash[String, String]]
+
+  # @dynamic model, reasoning, models, providers
+  attr_reader :model #: String?
+  attr_reader :reasoning #: String?
+  attr_reader :models #: Hash[String, Riffer::Rig::Settings::Pricing]
+  attr_reader :providers #: Hash[String, Hash[String, String]]
+
+  # @rbs source: untyped
+  # @rbs return: void
+  def initialize(source)
+    @model = source['model'].is_a?(String) ? source['model'] : nil
+    @reasoning = source['reasoning'].is_a?(String) ? source['reasoning'] : nil
+    entries = source['models'].is_a?(Hash) ? source['models'] : {} #: Hash[String, untyped]
+    @models = entries.filter_map do |name, entry|
+      [name, Riffer::Rig::Settings::Pricing.from(entry)] if name.is_a?(String) && entry.is_a?(Hash)
+    end.to_h
+    blocks = source['providers'].is_a?(Hash) ? source['providers'] : {} #: Hash[String, untyped]
+    @providers = blocks.select { |_identifier, fields| fields.is_a?(Hash) }
+                       .transform_values { |fields| fields.select { |_name, value| value.is_a?(String) } }
+  end
+end

data/lib/riffer/rig/settings/pricing.rb

@@ -1,10 +1,20 @@
 # frozen_string_literal: true
 
-# USD per million tokens, parsed from a model's entry in the settings file.
 class Riffer::Rig::Settings::Pricing
   # @dynamic input, output, cache_write, cache_read
   attr_reader :input, :output, :cache_write, :cache_read #: Float
 
+  # @rbs entry: Hash[String, untyped]
+  # @rbs return: ::Riffer::Rig::Settings::Pricing
+  def self.from(entry)
+    new(
+      input: entry.fetch('input', 0).to_f,
+      output: entry.fetch('output', 0).to_f,
+      cache_write: entry.fetch('cache_write', 0).to_f,
+      cache_read: entry.fetch('cache_read', 0).to_f
+    )
+  end
+
   # @rbs input: Float
   # @rbs output: Float
   # @rbs cache_write: Float

data/lib/riffer/rig/settings.rb

@@ -3,36 +3,6 @@
 require 'json'
 require 'fileutils'
 
-# Reads and writes the riffer-rig user settings file at
-# <tt>~/.riffer/settings.json</tt>.
-#
-# Example file:
-#
-#   {
-#     "model": "anthropic/claude-sonnet-4-6",
-#     "reasoning": "low",
-#     "models": {
-#       "anthropic/claude-sonnet-4-6": {
-#         "input": 3.0,
-#         "output": 15.0,
-#         "cache_write": 3.75,
-#         "cache_read": 0.3
-#       }
-#     }
-#   }
-#
-# All keys are optional. Missing pricing means cost display is suppressed.
-# <tt>"reasoning"</tt> is translated to the appropriate provider-specific
-# parameter on each API call; accepted values depend on the provider:
-#
-# - Anthropic: <tt>"low"</tt>, <tt>"medium"</tt>, <tt>"high"</tt>,
-#   <tt>"xhigh"</tt>, <tt>"max"</tt>
-# - OpenAI / OpenRouter: <tt>"low"</tt>, <tt>"medium"</tt>, <tt>"high"</tt>,
-#   <tt>"xhigh"</tt>
-#
-# Omitting the key (or supplying an unrecognised value) leaves the model's
-# default reasoning behaviour unchanged.
-#
 module Riffer::Rig::Settings
   extend self
 
@@ -46,17 +16,12 @@ module Riffer::Rig::Settings
     'openrouter' => %w[low medium high xhigh].freeze
   }.freeze #: Hash[String, Array[String]]
 
-  # Returns the configured model string, or +DEFAULT_MODEL+ if not set.
-  #
   # @rbs path: String
   # @rbs return: String
   def model(path: PATH)
-    read(path).fetch('model', DEFAULT_MODEL)
+    read(path).model || DEFAULT_MODEL
   end
 
-  # Returns model options for the configured model and reasoning level, ready
-  # to pass directly to the Riffer agent's +model_options+.
-  #
   # @rbs path: String
   # @rbs return: Hash[Symbol, untyped]
   def model_options(path: PATH)
@@ -64,35 +29,59 @@ module Riffer::Rig::Settings
     base_options(provider).merge(reasoning_options(reasoning_for(path:, provider:), provider))
   end
 
-  # Returns the provider prefix for +model_string+, e.g. <tt>"anthropic"</tt>
-  # for <tt>"anthropic/claude-sonnet-4-6"</tt>. Returns +nil+ if the model
-  # string contains no slash.
-  #
   # @rbs model_string: String
   # @rbs return: String?
   def provider_for(model_string)
     model_string.split('/', 2).first if model_string.include?('/')
   end
 
-  # Returns the pricing for +model+, or +nil+ if not configured.
-  #
   # @rbs model: String
   # @rbs path: String
   # @rbs return: Pricing?
   def pricing_for(model, path: PATH)
-    entry = read(path).dig('models', model)
-    return nil unless entry.is_a?(Hash)
-
-    Pricing.new(
-      input: entry.fetch('input', 0).to_f,
-      output: entry.fetch('output', 0).to_f,
-      cache_write: entry.fetch('cache_write', 0).to_f,
-      cache_read: entry.fetch('cache_read', 0).to_f
-    )
+    read(path).models[model]
+  end
+
+  # @rbs identifier: String
+  # @rbs path: String
+  # @rbs return: Hash[String, String]
+  def provider_fields(identifier, path: PATH)
+    read(path).providers[identifier] || {}
+  end
+
+  # @rbs identifier: String
+  # @rbs fields: Hash[String, String]
+  # @rbs path: String
+  # @rbs return: void
+  def store_provider(identifier, fields, path: PATH)
+    update_providers(path) do |providers|
+      providers.merge(identifier => fields) { |_identifier, stored, given| stored.merge(given) }
+    end
+  end
+
+  # @rbs identifier: String
+  # @rbs path: String
+  # @rbs return: void
+  def remove_provider(identifier, path: PATH)
+    update_providers(path) { |providers| providers.except(identifier) }
   end
 
   private
 
+  # @rbs path: String
+  # @rbs &: (Hash[String, Hash[String, String]]) -> Hash[String, Hash[String, String]]
+  # @rbs return: void
+  def update_providers(path)
+    source = read_source(path)
+    current = Document.new(source).providers
+    providers = yield current
+    return if providers == current
+
+    FileUtils.mkdir_p(File.dirname(path), mode: 0o700)
+    document = providers.empty? ? source.except('providers') : source.merge('providers' => providers)
+    File.write(path, JSON.pretty_generate(document))
+  end
+
   # @rbs provider: String?
   # @rbs return: Hash[Symbol, untyped]
   def base_options(provider)
@@ -102,17 +91,14 @@ module Riffer::Rig::Settings
   end
 
   # @rbs path: String
-  # @rbs ?provider: String?
+  # @rbs provider: String?
   # @rbs return: String?
   def reasoning_for(path: PATH, provider: nil)
-    level = read(path)['reasoning']
+    level = read(path).reasoning
     valid_levels = (provider && REASONING_LEVELS_BY_PROVIDER[provider]) || []
     valid_levels.include?(level) ? level : nil
   end
 
-  # Maps a reasoning level to the provider-specific model option hash expected
-  # by Riffer. Returns an empty hash when +level+ is +nil+.
-  #
   # @rbs level: String?
   # @rbs provider: String?
   # @rbs return: Hash[Symbol, untyped]
@@ -129,12 +115,15 @@ module Riffer::Rig::Settings
     end
   end
 
-  # The parsed settings file, or an empty hash when the file is absent or
-  # malformed.
-  #
   # @rbs path: String
-  # @rbs return: Hash[String, untyped]
+  # @rbs return: Document
   def read(path)
+    Document.new(read_source(path))
+  end
+
+  # @rbs path: String
+  # @rbs return: Hash[String, untyped]
+  def read_source(path)
     return {} unless File.file?(path)
 
     JSON.parse(File.read(path))

data/lib/riffer/rig/token_tally.rb

@@ -1,17 +1,5 @@
 # frozen_string_literal: true
 
-# Accumulates token usage across multiple turns in a session and computes an
-# estimated cost based on a pricing object sourced from
-# +Riffer::Rig::Settings+.
-#
-# Instantiate once per REPL session, call +add+ after each turn, then read
-# +total_tokens+ and +estimated_cost+ for display.
-#
-#   pricing = Riffer::Rig::Settings.pricing_for('anthropic/claude-sonnet-4-6')
-#   tally = Riffer::Rig::TokenTally.new(pricing: pricing)
-#   tally.add(usage)
-#   tally.estimated_cost  # => 0.000042  (USD), or nil if pricing is nil
-#
 class Riffer::Rig::TokenTally
   # @rbs @input_tokens: Integer
   # @rbs @output_tokens: Integer
@@ -22,7 +10,7 @@ class Riffer::Rig::TokenTally
   # @dynamic input_tokens, output_tokens, cache_write_tokens, cache_read_tokens
   attr_reader :input_tokens, :output_tokens, :cache_write_tokens, :cache_read_tokens
 
-  # @rbs ?pricing: Riffer::Rig::Settings::Pricing?
+  # @rbs pricing: Riffer::Rig::Settings::Pricing?
   # @rbs return: void
   def initialize(pricing: nil)
     @pricing = pricing
@@ -32,8 +20,6 @@ class Riffer::Rig::TokenTally
     @cache_read_tokens = 0
   end
 
-  # Accumulates token counts from a +Riffer::Providers::TokenUsage+ object.
-  #
   # @rbs usage: Riffer::Providers::TokenUsage
   # @rbs return: void
   def add(usage)
@@ -43,22 +29,16 @@ class Riffer::Rig::TokenTally
     @cache_read_tokens += usage.cache_read_tokens || 0
   end
 
-  # Returns the total token count across all categories.
-  #
   # @rbs return: Integer
   def total_tokens
     @input_tokens + @output_tokens + @cache_write_tokens + @cache_read_tokens
   end
 
-  # Returns +true+ if any tokens have been counted.
-  #
   # @rbs return: bool
   def any?
     total_tokens.positive?
   end
 
-  # Returns the estimated cost in USD, or +nil+ if no pricing was provided.
-  #
   # @rbs return: Float?
   def estimated_cost
     pricing = @pricing

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

@@ -13,6 +13,8 @@ class Riffer::Rig::Tools::Bash < Riffer::Tool
 
   MAX_OUTPUT_BYTES = 30_000 #: Integer
 
+  POLL_SECONDS = 0.1 #: Float
+
   params do
     required :command, String, description: 'The shell command to run'
     optional :timeout_ms,
@@ -23,10 +25,11 @@ class Riffer::Rig::Tools::Bash < Riffer::Tool
 
   # @rbs context: Riffer::Agent::Context?
   # @rbs command: String
-  # @rbs ?timeout_ms: Integer
+  # @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)
+    cancel_flag = context&.[](:cancel_flag) #: Riffer::Rig::Runtime::CancelFlag?
+    output, status = run(command, timeout_ms / 1000.0, cancel_flag)
     output = truncate(output.rstrip)
 
     return error("Command exited with status #{status}\n#{output}", type: :command_failed) unless status.zero?
@@ -38,23 +41,41 @@ class Riffer::Rig::Tools::Bash < Riffer::Tool
 
   # @rbs command: String
   # @rbs timeout_seconds: Float
+  # @rbs cancel_flag: Riffer::Rig::Runtime::CancelFlag?
   # @rbs return: [String, Integer]
-  def run(command, timeout_seconds)
+  def run(command, timeout_seconds, cancel_flag)
     stdin, stdout_and_stderr, wait_thread = Open3.popen2e(command, chdir: Dir.pwd, pgroup: true)
     stdin.close
 
-    joined = wait_thread.join(timeout_seconds) #: Thread?
+    ending = await(wait_thread, monotonic_now + timeout_seconds, cancel_flag)
+    kill_group(wait_thread.pid) unless ending == :exited
+    output = stdout_and_stderr.read
+    stdout_and_stderr.close
 
-    unless joined
-      kill_group(wait_thread.pid)
-      output = stdout_and_stderr.read
-      stdout_and_stderr.close
-      return ["#{output}\n[timed out after #{timeout_seconds.round}s]", 124]
+    case ending
+    when :timed_out then ["#{output}\n[timed out after #{timeout_seconds.round}s]", 124]
+    when :cancelled then ["#{output}\n[cancelled]", 130]
+    else [output, wait_thread.value.exitstatus || 1]
     end
+  end
 
-    output = stdout_and_stderr.read
-    stdout_and_stderr.close
-    [output, wait_thread.value.exitstatus || 1]
+  # @rbs wait_thread: Process::Waiter
+  # @rbs deadline: Float
+  # @rbs cancel_flag: Riffer::Rig::Runtime::CancelFlag?
+  # @rbs return: Symbol
+  def await(wait_thread, deadline, cancel_flag)
+    # Upstream candidate: a cancel token on riffer's run loop would reach a
+    # running tool directly; until then the flag is polled from the context.
+    until wait_thread.join(POLL_SECONDS)
+      return :cancelled if cancel_flag&.set?
+      return :timed_out if monotonic_now >= deadline
+    end
+    :exited
+  end
+
+  # @rbs return: Float
+  def monotonic_now
+    Process.clock_gettime(Process::CLOCK_MONOTONIC)
   end
 
   # @rbs pid: Integer

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

@@ -19,7 +19,7 @@ class Riffer::Rig::Tools::Edit < Riffer::Tool
   # @rbs path: String
   # @rbs old_string: String
   # @rbs new_string: String
-  # @rbs ?replace_all: bool
+  # @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)

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

@@ -15,8 +15,8 @@ class Riffer::Rig::Tools::Read < Riffer::Tool
 
   # @rbs context: Riffer::Agent::Context?
   # @rbs path: String
-  # @rbs ?offset: Integer?
-  # @rbs ?limit: Integer
+  # @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)

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

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-# 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 #: Float
 
@@ -23,15 +21,15 @@ class Riffer::Rig::UI::Animator
 
   REASONING_TICK_RANGE = (1..5) #: Range[Integer]
 
-  # @rbs @io: untyped
+  # @rbs @io: IO
   # @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 io: IO
+  # @rbs theme: Riffer::Rig::UI::Theme
   # @rbs return: void
   def initialize(io: $stdout, theme: Riffer::Rig::UI::Theme.for(io))
     @io = io
@@ -41,8 +39,6 @@ class Riffer::Rig::UI::Animator
     @phrase = nil
   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)
@@ -60,7 +56,7 @@ class Riffer::Rig::UI::Animator
     end
   end
 
-  # @rbs ?mode: Symbol
+  # @rbs mode: Symbol
   # @rbs return: void
   def start(mode = :neutral)
     return unless enabled?
@@ -88,7 +84,7 @@ class Riffer::Rig::UI::Animator
   end
 
   # @rbs tick: Integer
-  # @rbs ?label: String
+  # @rbs label: String
   # @rbs return: String
   def equalizer(tick, label = NEUTRAL_LABEL)
     bars = Array.new(EQ_BARS) do |i|
@@ -104,7 +100,7 @@ class Riffer::Rig::UI::Animator
   # @rbs return: void
   def animate
     tick = 0
-    roll_at = 0.0 # force an immediate phrase roll when entering reasoning mode
+    roll_at = 0.0
     until @stop
       roll_at = roll_phrase(roll_at)
       @io.print("\r  #{equalizer(tick, label)}\e[K")
@@ -114,8 +110,6 @@ class Riffer::Rig::UI::Animator
     end
   end
 
-  # Re-rolls both phrase and duration whenever the reasoning tick expires.
-  #
   # @rbs roll_at: Float
   # @rbs return: Float
   def roll_phrase(roll_at)
@@ -126,11 +120,10 @@ class Riffer::Rig::UI::Animator
     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)
+    # Range rand returns nil for an empty range; this one is a non-empty constant.
     x || 0
   end
 
@@ -141,6 +134,6 @@ class Riffer::Rig::UI::Animator
 
   # @rbs return: bool
   def enabled?
-    @theme.enabled && @io.respond_to?(:tty?) && @io.tty?
+    @theme.enabled && @io.tty?
   end
 end