riffer-rig 0.2.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 935cb9bdd3c8aee780466f38ac5ee4122b22e63718140399df5f94e1c0d4dd26
-  data.tar.gz: 3ddc6c58d14e306f12a6d14f86d958df336f718a4d4c0b12be19ee34e9736dad
+  metadata.gz: e833f2a4dfe0b87598e2be9d585f3cb772562ab39a2dd528684a38dca87f63ab
+  data.tar.gz: f469b328103a49e52773c0073e02d8c2fbd06d8cf6779daa50c09b49ab2eba8e
 SHA512:
-  metadata.gz: 629aa97a63e9437f086f36e373c1720965936f86aa5d4dfbc9d546143a42c8500bd89e3b820a655fcc848df53e25903c57ad1b744d9b4c33975b7858db714cef
-  data.tar.gz: 6e73d9d8d1f6d2ef95b5692e1a506eb2b7440937475a873a3db73713d130591b1f47926bec7c34ff57218f2c230f167077160ce22358bd508ae7a0fe36be5196
+  metadata.gz: 696e8b92a7c1b7a3b71e1f628894e89aed725fbe072dba712d94df277fc5730b06d74def094445b02842d0849409b7900038aedf5d65f29f5416d1450a5b5121
+  data.tar.gz: 3dc42ac6e625d292462e00119bd7b3c7a8d1f23ad3c4f66763fff96cbfc3328f962dca67bdc4613e884ba81a6e3f61d9af86f1ba1d8bbd16e0f3caa307ca453c

data/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## [0.4.0](https://github.com/bottrall/riffer-rig/compare/v0.3.0...v0.4.0) (2026-09-13)
+
+
+### Features
+
+* **ui:** one blank line between blocks, prompt-owned gaps ([#170](https://github.com/bottrall/riffer-rig/issues/170)) ([636e4d8](https://github.com/bottrall/riffer-rig/commit/636e4d82a069f158775043037a43e2aa494f56dc))
+
+
+### Bug Fixes
+
+* **lint:** adjust rubocop rules and reformat to match ([#168](https://github.com/bottrall/riffer-rig/issues/168)) ([56b81aa](https://github.com/bottrall/riffer-rig/commit/56b81aa904609f246340c8b8135ee7e57791abdd))
+
+## [0.3.0](https://github.com/bottrall/riffer-rig/compare/v0.2.1...v0.3.0) (2026-09-10)
+
+
+### Features
+
+* **types:** strict rbs-inline typing with collection-managed third-party RBS ([#164](https://github.com/bottrall/riffer-rig/issues/164)) ([be59fb9](https://github.com/bottrall/riffer-rig/commit/be59fb9102d9c6f9bae2a5f456650cc68131924f))
+
+
+### Bug Fixes
+
+* print tool call lines after the round's stats line ([#166](https://github.com/bottrall/riffer-rig/issues/166)) ([dcc4e80](https://github.com/bottrall/riffer-rig/commit/dcc4e8093ffaec0bc93bb3eaafb47acd72292710))
+
 ## [0.2.1](https://github.com/bottrall/riffer-rig/compare/v0.2.0...v0.2.1) (2026-09-08)
 
 

data/README.md

@@ -46,10 +46,10 @@ Every project chore is a script in `bin/`. The Rakefile behind them is an implem
 
 | Script          | What it does                                                                                   |
 | --------------- | ---------------------------------------------------------------------------------------------- |
-| `bin/setup`     | Install dependencies on a fresh checkout                                                       |
+| `bin/setup`     | Install dependencies on a fresh checkout (gems + rbs collection)                               |
 | `bin/test`      | Run the test suite. Pass files and/or Minitest flags: `bin/test test/foo_test.rb -n /pattern/` |
 | `bin/lint`      | Run RuboCop. Arguments are forwarded, e.g. `bin/lint -a`                                       |
-| `bin/typecheck` | Check `sig/generated` is current, then type-check with Steep                                   |
+| `bin/typecheck` | Check the rbs collection lockfile and `sig/generated` are current, then type-check with Steep  |
 | `bin/rbs`       | Regenerate `sig/generated` from the inline annotations in `lib/`                               |
 | `bin/rbs-watch` | Regenerate `sig/generated` whenever `lib/` changes                                             |
 | `bin/ci`        | Run everything CI runs, serially. Use before pushing                                           |

data/lib/riffer/rig/cli.rb

@@ -10,8 +10,11 @@ module Riffer::Rig::CLI
     'openai' => 'https://platform.openai.com/api-keys',
     'gemini' => 'https://aistudio.google.com/app/apikey',
     'openrouter' => 'https://openrouter.ai/keys'
-  }.freeze
+  }.freeze #: Hash[String, String]
 
+  # @rbs output: untyped
+  # @rbs input: untyped
+  # @rbs return: Integer
   def start(output: $stdout, input: $stdin)
     theme = Riffer::Rig::UI::Theme.for(output)
 
@@ -38,6 +41,9 @@ module Riffer::Rig::CLI
 
   private
 
+  # @rbs provider: String?
+  # @rbs api_key: String
+  # @rbs return: void
   def configure_provider(provider, api_key)
     case provider
     when 'anthropic'  then Riffer.configure { |c| c.anthropic.api_key  = api_key }
@@ -47,6 +53,11 @@ module Riffer::Rig::CLI
     end
   end
 
+  # @rbs provider: String?
+  # @rbs theme: Riffer::Rig::UI::Theme
+  # @rbs output: untyped
+  # @rbs input: untyped
+  # @rbs return: String?
   def onboard(provider, theme, output:, input:)
     url  = (provider && PROVIDER_URLS[provider]) || 'your provider'
     name = provider ? provider.capitalize : 'provider'
@@ -68,23 +79,41 @@ module Riffer::Rig::CLI
     key
   end
 
+  # @rbs provider: String?
+  # @rbs return: String
   def env_var_for(provider)
     (provider && Riffer::Rig::Credentials::PROVIDER_ENV_VARS[provider]) || 'the appropriate API key env var'
   end
 
+  # @rbs input: untyped
+  # @rbs return: String?
   def read_secret(input)
     return input.noecho(&:gets) if input.respond_to?(:noecho) && input.tty?
 
     input.gets
   end
 
+  # @rbs theme: Riffer::Rig::UI::Theme
+  # @rbs animator: Riffer::Rig::UI::Animator
+  # @rbs model: String
+  # @rbs return: void
   def reveal_banner(theme, animator, model)
     loaded  = [Riffer::Rig::CodingAgent::GLOBAL_AGENTS_FILE, File.join(Dir.pwd, 'AGENTS.md')].select { |path| File.file?(path) }
     context = loaded.empty? ? 'none' : loaded.join(', ')
 
-    animator.reveal([Riffer::Rig::UI::Banner.lines(theme, model: model, cwd: Dir.pwd, context: context, skills: count_skills, version: Riffer::Rig::VERSION)])
+    animator.reveal(
+      [Riffer::Rig::UI::Banner.lines(
+        theme,
+        model: model,
+        cwd: Dir.pwd,
+        context: context,
+        skills: count_skills,
+        version: Riffer::Rig::VERSION
+      )]
+    )
   end
 
+  # @rbs return: String
   def count_skills
     dirs    = [Riffer::Rig::CodingAgent::GLOBAL_SKILLS_DIR, Riffer::Rig::CodingAgent::PROJECT_SKILLS_DIR.call]
     backend = Riffer::Skills::FilesystemBackend.new(*dirs)

data/lib/riffer/rig/coding_agent.rb

@@ -3,9 +3,11 @@
 require 'date'
 
 class Riffer::Rig::CodingAgent < Riffer::Agent
-  GLOBAL_AGENTS_FILE = File.expand_path('~/.riffer/AGENTS.md')
-  GLOBAL_SKILLS_DIR  = File.expand_path('~/.riffer/skills')
-  PROJECT_SKILLS_DIR = -> { File.join(Dir.pwd, '.skills') }
+  GLOBAL_AGENTS_FILE = File.expand_path('~/.riffer/AGENTS.md') #: String
+
+  GLOBAL_SKILLS_DIR  = File.expand_path('~/.riffer/skills') #: String
+
+  PROJECT_SKILLS_DIR = -> { File.join(Dir.pwd, '.skills') } #: ^() -> String
 
   model Riffer::Rig::Settings.model
   model_options Riffer::Rig::Settings.model_options
@@ -23,32 +25,34 @@ class Riffer::Rig::CodingAgent < Riffer::Agent
 
   max_steps nil
 
-  instructions(lambda do
-    context_files = [GLOBAL_AGENTS_FILE, File.join(Dir.pwd, 'AGENTS.md')]
-      .select { |path| File.file?(path) }
-      .map { |path| "<project_instructions path=\"#{path}\">\n#{File.read(path)}\n</project_instructions>" }
-
-    project_context =
-      if context_files.empty?
-        ''
-      else
-        "\n\n<project_context>\n#{context_files.join("\n\n")}\n</project_context>"
-      end
-
-    <<~PROMPT.chomp + project_context + "\n\nCurrent date: #{Date.today}\nCurrent working directory: #{Dir.pwd}"
-      You are an expert coding assistant running inside riffer-rig, a terminal coding agent. You help the user by reading files, running shell commands, editing code, and writing new files.
-
-      Available tools:
-      - read: read a file's contents
-      - write: create or overwrite a file
-      - edit: replace an exact string in a file
-      - bash: run a shell command (use it for ls, rg/grep, find, tests, git, etc.)
-
-      Guidelines:
-      - Be concise and direct in your responses.
-      - Show file paths clearly when working with files.
-      - Use bash for file exploration (ls, rg, find) rather than guessing.
-      - Prefer editing existing files over creating new ones.
-    PROMPT
-  end)
+  instructions(
+    lambda do
+      context_files = [GLOBAL_AGENTS_FILE, File.join(Dir.pwd, 'AGENTS.md')]
+        .select { |path| File.file?(path) }
+        .map { |path| "<project_instructions path=\"#{path}\">\n#{File.read(path)}\n</project_instructions>" }
+
+      project_context =
+        if context_files.empty?
+          ''
+        else
+          "\n\n<project_context>\n#{context_files.join("\n\n")}\n</project_context>"
+        end
+
+      <<~PROMPT.chomp + project_context + "\n\nCurrent date: #{Date.today}\nCurrent working directory: #{Dir.pwd}"
+        You are an expert coding assistant running inside riffer-rig, a terminal coding agent. You help the user by reading files, running shell commands, editing code, and writing new files.
+
+        Available tools:
+        - read: read a file's contents
+        - write: write content to a file
+        - edit: replace an exact string in a file
+        - bash: run a shell command in the working directory
+
+        Guidelines:
+        - Be concise and direct in your responses.
+        - Show file paths clearly when working with files.
+        - Use bash for file exploration (ls, rg, find) rather than guessing.
+        - Prefer editing existing files over creating new ones.
+      PROMPT
+    end
+  )
 end

data/lib/riffer/rig/credentials.rb

@@ -25,24 +25,33 @@ require 'fileutils'
 module Riffer::Rig::Credentials
   extend self
 
-  PATH = File.expand_path('~/.riffer/auth.json')
+  PATH = File.expand_path('~/.riffer/auth.json') #: String
 
   PROVIDER_ENV_VARS = {
     'anthropic' => 'ANTHROPIC_API_KEY',
     'openai' => 'OPENAI_API_KEY',
     'gemini' => 'GEMINI_API_KEY',
     'openrouter' => 'OPENROUTER_API_KEY'
-  }.freeze
+  }.freeze #: Hash[String, String]
 
   # Returns the API key for +provider+, checking the environment variable first,
   # then the stored file. Returns +nil+ if no key is available.
+  #
+  # @rbs provider: String?
+  # @rbs path: String
+  # @rbs return: String?
   def api_key_for(provider, path: PATH)
-    env_var = PROVIDER_ENV_VARS[provider]
+    env_var = provider && PROVIDER_ENV_VARS[provider]
     key = env_var && ENV.fetch(env_var, nil).then { |v| v unless v.nil? || v.strip.empty? }
     key || key_from_file(provider, path)
   end
 
   # Saves an API key for +provider+ to the auth file with 0600 permissions.
+  #
+  # @rbs provider: String
+  # @rbs key: String
+  # @rbs path: String
+  # @rbs return: String
   def save_api_key(provider, key, path: PATH)
     FileUtils.mkdir_p(File.dirname(path), mode: 0o700)
     data = read(path).tap { |h| h[provider] = key }
@@ -54,11 +63,22 @@ module Riffer::Rig::Credentials
 
   private
 
+  # @rbs provider: String?
+  # @rbs path: String
+  # @rbs return: String?
   def key_from_file(provider, path)
     key = read(path)[provider]
-    key unless key.nil? || key.strip.empty?
+    return nil unless key.is_a?(String)
+    return key unless key.strip.empty?
+
+    nil
   end
 
+  # The parsed auth file, or an empty hash when the file is absent or
+  # malformed.
+  #
+  # @rbs path: String
+  # @rbs return: Hash[String, untyped]
   def read(path)
     return {} unless File.file?(path)
 

data/lib/riffer/rig/repl.rb

@@ -1,10 +1,38 @@
 # frozen_string_literal: true
 
 class Riffer::Rig::REPL
-  EXIT_COMMANDS = ['/exit', '/quit'].freeze
-  SKILL_COMMAND = %r{\A/skill:([a-z0-9]+(?:-[a-z0-9]+)*)(?:\s+(.*))?\z}m
-
-  def initialize(agent:, renderer:, input: $stdin, output: $stdout, theme: Riffer::Rig::UI::Theme.for(output), animator: Riffer::Rig::UI::Animator.new(io: output, theme:), smoother: Riffer::Rig::UI::Smoother.new(io: output, theme:), cursor: Riffer::Rig::UI::Cursor.new(io: output, theme:))
+  EXIT_COMMANDS = ['/exit', '/quit'].freeze #: Array[String]
+
+  SKILL_COMMAND = %r{\A/skill:([a-z0-9]+(?:-[a-z0-9]+)*)(?:\s+(.*))?\z}m #: Regexp
+
+  # @rbs @agent: Riffer::Agent
+  # @rbs @renderer: Riffer::Rig::UI::Renderer
+  # @rbs @animator: Riffer::Rig::UI::Animator
+  # @rbs @smoother: Riffer::Rig::UI::Smoother
+  # @rbs @cursor: Riffer::Rig::UI::Cursor
+  # @rbs @theme: Riffer::Rig::UI::Theme
+  # @rbs @input: untyped
+  # @rbs @output: untyped
+
+  # @rbs ?agent: Riffer::Agent
+  # @rbs ?renderer: Riffer::Rig::UI::Renderer
+  # @rbs input: untyped
+  # @rbs output: untyped
+  # @rbs ?theme: Riffer::Rig::UI::Theme
+  # @rbs ?animator: Riffer::Rig::UI::Animator
+  # @rbs ?smoother: Riffer::Rig::UI::Smoother
+  # @rbs ?cursor: Riffer::Rig::UI::Cursor
+  # @rbs return: void
+  def initialize(agent:, renderer:, input: $stdin, output: $stdout, theme: Riffer::Rig::UI::Theme.for(output),
+                 animator: Riffer::Rig::UI::Animator.new(
+                   io: output,
+                   theme:
+                 ), smoother: Riffer::Rig::UI::Smoother.new(
+                   io: output,
+                   theme:
+                 ), cursor: Riffer::Rig::UI::Cursor.new(
+                   io: output, theme:
+                 ))
     @agent = agent
     @renderer = renderer
     @animator = animator
@@ -16,9 +44,10 @@ class Riffer::Rig::REPL
     @agent.session.on_message { |message| render_tool_result(message) }
   end
 
+  # @rbs return: Symbol
   def run
     loop do
-      @output.print("\n#{@theme.pink('›')} ")
+      @renderer.prompt
       line = @input.gets
       break if line.nil?
 
@@ -35,11 +64,14 @@ class Riffer::Rig::REPL
       end
     end
 
-    @output.puts("\n#{@theme.grey('see you on the next riff.')}")
+    print_block { @theme.grey('see you on the next riff.') }
+    :done
   end
 
   private
 
+  # @rbs prompt: String
+  # @rbs return: void
   def run_turn(prompt)
     @cursor.hide
     @animator.start
@@ -51,17 +83,20 @@ class Riffer::Rig::REPL
       when Riffer::StreamEvents::ReasoningDone
         @animator.start
       when Riffer::StreamEvents::ToolCallDelta, Riffer::StreamEvents::FinishReasonDone
-        # Round bookkeeping: nothing renders, so the indicator just carries on
-        # (or stays parked while the smoother finishes typing earlier text).
         next
-      when Riffer::StreamEvents::ToolCallDone, Riffer::StreamEvents::SkillActivation, Riffer::StreamEvents::TokenUsageDone
-        # The spinner shares its line with what's about to print, and tool
-        # execution plus the next model invocation emit no events — stop it for
-        # the render, then bring it straight back to cover the silent stretch.
+      when Riffer::StreamEvents::SkillActivation
+        # Tool execution and the next model invocation emit no events, so the
+        # spinner comes straight back on to cover the silent stretch.
         @animator.stop
         @renderer.render(event)
         @animator.start
         next
+      when Riffer::StreamEvents::TokenUsageDone
+        # Usage renders nothing inline — it flushes below the turn's output.
+        # Restarting here covers the silent tool-execution stretch that follows.
+        @renderer.render(event)
+        @animator.start
+        next
       else
         @animator.stop
       end
@@ -69,15 +104,18 @@ class Riffer::Rig::REPL
     end
     @animator.stop
     @smoother.finish
-    @output.puts
+    @renderer.flush_usage
   rescue StandardError => e
-    @output.puts("\nError: #{e.message}")
-  ensure
     @smoother.finish
+    print_block { @theme.red("Error: #{e.message}") }
+  ensure
     @animator.stop
     @cursor.show
   end
 
+  # @rbs name: String
+  # @rbs args: String
+  # @rbs return: void
   def run_skill_command(name, args)
     block = activate_skill(name)
     return if block.nil?
@@ -85,11 +123,13 @@ class Riffer::Rig::REPL
     run_turn([block, args].reject(&:empty?).join("\n\n"))
   end
 
+  # @rbs name: String
+  # @rbs return: String?
   def activate_skill(name)
     skills = @agent.context.skills
 
     unless skills
-      @output.puts(@theme.grey('No skills configured.'))
+      print_block { @theme.grey('No skills configured.') }
       return
     end
 
@@ -97,23 +137,36 @@ class Riffer::Rig::REPL
     # a non-mutating Context#read. `activate` marks the skill model-activated as
     # a side effect, which drops it from the model's catalog after manual use.
     body = skills.activate(name)
-    @output.puts(@theme.magenta("✦ skill: #{name}"))
+    print_block { @theme.magenta("✦ skill: #{name}") }
     skill_block(name, body)
   rescue Riffer::ArgumentError
-    @output.puts(@theme.red("Unknown skill: #{name}"))
+    print_block { @theme.red("Unknown skill: #{name}") }
     nil
   rescue StandardError => e
-    @output.puts(@theme.red("Error activating skill: #{e.message}"))
+    print_block { @theme.red("Error activating skill: #{e.message}") }
     nil
   end
 
+  # @rbs name: String
+  # @rbs body: String
+  # @rbs return: String
   def skill_block(name, body)
     "<skill name=\"#{name}\">\n#{body}\n</skill>"
   end
 
-  # Tool results can land mid-animation (tool execution emits no stream events,
-  # so the indicator is up); stop it around the line so its next frame doesn't
-  # erase what we printed.
+  # Chrome lines that never pass through the renderer (errors, exit line) end
+  # their line with a newline but leave the renderer's tool-group state alone —
+  # they can only follow prose, never mid-group.
+  #
+  # @rbs return: void
+  def print_block(&)
+    @output.puts
+    @output.puts(yield)
+    @output.flush
+  end
+
+  # @rbs message: Riffer::Messages::Base
+  # @rbs return: void
   def render_tool_result(message)
     return unless message.is_a?(Riffer::Messages::Tool)
 

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

@@ -0,0 +1,19 @@
+# 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 input: Float
+  # @rbs output: Float
+  # @rbs cache_write: Float
+  # @rbs cache_read: Float
+  # @rbs return: void
+  def initialize(input:, output:, cache_write:, cache_read:)
+    @input = input
+    @output = output
+    @cache_write = cache_write
+    @cache_read = cache_read
+  end
+end

data/lib/riffer/rig/settings.rb

@@ -36,22 +36,29 @@ require 'fileutils'
 module Riffer::Rig::Settings
   extend self
 
-  PATH = File.expand_path('~/.riffer/settings.json')
+  PATH = File.expand_path('~/.riffer/settings.json') #: String
+
   DEFAULT_MODEL = 'anthropic/claude-sonnet-4-6'
 
   REASONING_LEVELS_BY_PROVIDER = {
     'anthropic' => %w[low medium high xhigh max].freeze,
     'openai' => %w[low medium high xhigh].freeze,
     'openrouter' => %w[low medium high xhigh].freeze
-  }.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)
   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)
     provider = provider_for(model(path:))
     base_options(provider).merge(reasoning_options(reasoning_for(path:, provider:), provider))
@@ -60,34 +67,43 @@ module Riffer::Rig::Settings
   # 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 hash for +model+, or +nil+ if not configured.
+  # Returns the pricing for +model+, or +nil+ if not configured.
   #
-  # The returned hash has symbol keys +:input+, +:output+, +:cache_write+,
-  # +:cache_read+ (all Float, USD per million tokens).
+  # @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
+    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
-    }
+    )
   end
 
   private
 
+  # @rbs provider: String?
+  # @rbs return: Hash[Symbol, untyped]
   def base_options(provider)
     return { cache_control: { type: :ephemeral } } if provider == 'anthropic'
 
     {}
   end
 
+  # @rbs path: String
+  # @rbs ?provider: String?
+  # @rbs return: String?
   def reasoning_for(path: PATH, provider: nil)
     level = read(path)['reasoning']
     valid_levels = (provider && REASONING_LEVELS_BY_PROVIDER[provider]) || []
@@ -96,6 +112,10 @@ module Riffer::Rig::Settings
 
   # 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]
   def reasoning_options(level, provider)
     return {} unless level
 
@@ -109,6 +129,11 @@ 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]
   def read(path)
     return {} unless File.file?(path)
 

data/lib/riffer/rig/token_tally.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
 # Accumulates token usage across multiple turns in a session and computes an
-# estimated cost based on a pricing hash sourced from +Riffer::Rig::Settings+.
+# 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.
@@ -12,8 +13,17 @@
 #   tally.estimated_cost  # => 0.000042  (USD), or nil if pricing is nil
 #
 class Riffer::Rig::TokenTally
+  # @rbs @input_tokens: Integer
+  # @rbs @output_tokens: Integer
+  # @rbs @cache_write_tokens: Integer
+  # @rbs @cache_read_tokens: Integer
+  # @rbs @pricing: Riffer::Rig::Settings::Pricing?
+
+  # @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 return: void
   def initialize(pricing: nil)
     @pricing = pricing
     @input_tokens = 0
@@ -24,6 +34,8 @@ class Riffer::Rig::TokenTally
 
   # Accumulates token counts from a +Riffer::Providers::TokenUsage+ object.
   #
+  # @rbs usage: Riffer::Providers::TokenUsage
+  # @rbs return: void
   def add(usage)
     @input_tokens += usage.input_tokens
     @output_tokens += usage.output_tokens
@@ -33,26 +45,30 @@ class Riffer::Rig::TokenTally
 
   # 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
-    return nil unless @pricing
+    pricing = @pricing
+    return nil unless pricing
 
     (
-      (@input_tokens       * @pricing[:input]) +
-      (@output_tokens      * @pricing[:output])       +
-      (@cache_write_tokens * @pricing[:cache_write])  +
-      (@cache_read_tokens  * @pricing[:cache_read])
+      (@input_tokens       * pricing.input) +
+      (@output_tokens      * pricing.output)       +
+      (@cache_write_tokens * pricing.cache_write)  +
+      (@cache_read_tokens  * pricing.cache_read)
     ) / 1_000_000.0
   end
 end