riffer-rig 0.5.0 → 0.6.0

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

@@ -1,6 +1,5 @@
 # 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

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).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,18 +29,12 @@ 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?
@@ -83,8 +42,46 @@ module Riffer::Rig::Settings
     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,9 +99,6 @@ module Riffer::Rig::Settings
     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]
@@ -121,16 +115,19 @@ module Riffer::Rig::Settings
     end
   end
 
-  # The parsed settings file, or an empty document when the file is absent or
-  # malformed.
-  #
   # @rbs path: String
   # @rbs return: Document
   def read(path)
-    return Document.new({}) unless File.file?(path)
+    Document.new(read_source(path))
+  end
+
+  # @rbs path: String
+  # @rbs return: Hash[String, untyped]
+  def read_source(path)
+    return {} unless File.file?(path)
 
-    Document.new(JSON.parse(File.read(path)))
+    JSON.parse(File.read(path))
   rescue JSON::ParserError
-    Document.new({})
+    {}
   end
 end

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
@@ -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,
@@ -26,7 +28,8 @@ class Riffer::Rig::Tools::Bash < Riffer::Tool
   # @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/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
 
@@ -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)
@@ -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
 

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

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-# 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" #: String
 

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

@@ -39,28 +39,24 @@ class Riffer::Rig::UI::Renderer
     when Riffer::StreamEvents::Interrupt
       render_block(0) { @theme.dim("[interrupted: #{event.reason}]") }
     when Riffer::StreamEvents::TokenUsageDone
+      # 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.
       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
+    # 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 return: void
   def flush_usage
     usage = @deferred_usage
@@ -86,11 +82,6 @@ class Riffer::Rig::UI::Renderer
 
   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
@@ -102,13 +93,11 @@ class Riffer::Rig::UI::Renderer
     @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")
@@ -125,12 +114,10 @@ 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
@@ -157,8 +144,6 @@ class Riffer::Rig::UI::Renderer
     @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
 

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

@@ -1,20 +1,15 @@
 # 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
   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
@@ -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/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
   # @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 env: Riffer::Rig::Env
   # @rbs return: Riffer::Rig::UI::Theme
-  def self.for(io)
-    new(enabled: io.tty? && !ENV.key?('NO_COLOR'))
+  def self.for(io, env: Riffer::Rig::Env.new)
+    new(enabled: io.tty? && !env.no_color)
   end
 
   # @rbs text: String

data/lib/riffer/rig/version.rb

@@ -2,6 +2,6 @@
 
 module Riffer
   module Rig
-    VERSION = '0.5.0'
+    VERSION = '0.6.0'
   end
 end

data/lib/riffer/rig.rb

@@ -13,13 +13,6 @@ module Riffer::Rig
   # @rbs self.@extensions: Hash[String, Riffer::Rig::Extension]
   @extensions = {} #: Hash[String, Riffer::Rig::Extension]
 
-  # Records an extension block in the process registry and returns the
-  # extension object. Re-recording a name replaces the block.
-  #
-  #   Riffer::Rig.extension('git') do |rig|
-  #     rig.tool GitLog
-  #   end
-  #
   # @rbs name: String
   # @rbs requires: String?
   # @rbs &block: (::Riffer::Rig::Registrar) -> void
@@ -31,6 +24,8 @@ module Riffer::Rig
             "extension #{name} requires riffer-rig #{ext.requires}, found #{Riffer::Rig::VERSION}"
     end
 
+    # Keyed by name so reloading a file replaces its block rather than
+    # duplicating it.
     @extensions[name] = ext
   end
 

data/sig/generated/riffer/rig/cli.rbs

@@ -1,30 +1,38 @@
 # Generated from lib/riffer/rig/cli.rb with RBS::Inline
 
 module Riffer::Rig::CLI
-  PROVIDER_URLS: Hash[String, String]
-
   # @rbs output: IO
   # @rbs input: IO
+  # @rbs model: String
+  # @rbs env: Riffer::Rig::Env
   # @rbs return: Integer
-  def start: (?output: IO, ?input: IO) -> Integer
+  def start: (?output: IO, ?input: IO, ?model: String, ?env: Riffer::Rig::Env) -> Integer
 
   private
 
-  # @rbs provider: String?
-  # @rbs api_key: String
-  # @rbs return: void
-  def configure_provider: (String? provider, String api_key) -> void
+  # @rbs provider: String
+  # @rbs theme: Riffer::Rig::UI::Theme
+  # @rbs output: IO
+  # @rbs input: IO
+  # @rbs env: Riffer::Rig::Env
+  # @rbs return: Hash[Symbol, String]?
+  def credentials_for: (String provider, Riffer::Rig::UI::Theme theme, output: IO, input: IO, env: Riffer::Rig::Env) -> Hash[Symbol, String]?
 
-  # @rbs provider: String?
+  # @rbs provider: String
+  # @rbs resolution: Riffer::Rig::Credentials::Resolution
   # @rbs theme: Riffer::Rig::UI::Theme
   # @rbs output: IO
   # @rbs input: IO
-  # @rbs return: String?
-  def onboard: (String? provider, Riffer::Rig::UI::Theme theme, output: IO, input: IO) -> String?
+  # @rbs return: Hash[Symbol, String]?
+  def onboard: (String provider, Riffer::Rig::Credentials::Resolution resolution, Riffer::Rig::UI::Theme theme, output: IO, input: IO) -> Hash[Symbol, String]?
 
-  # @rbs provider: String?
+  # @rbs provider: String
+  # @rbs field: Riffer::Rig::ProviderSetup::Field
+  # @rbs theme: Riffer::Rig::UI::Theme
+  # @rbs output: IO
+  # @rbs input: IO
   # @rbs return: String
-  def env_var_for: (String? provider) -> String
+  def prompt: (String provider, Riffer::Rig::ProviderSetup::Field field, Riffer::Rig::UI::Theme theme, output: IO, input: IO) -> String
 
   # @rbs input: IO
   # @rbs return: String?

data/sig/generated/riffer/rig/credentials/resolution.rbs

@@ -0,0 +1,13 @@
+# Generated from lib/riffer/rig/credentials/resolution.rb with RBS::Inline
+
+class Riffer::Rig::Credentials::Resolution
+  # @dynamic values, missing
+  attr_reader values: Hash[Symbol, String]
+
+  attr_reader missing: Array[Symbol]
+
+  # @rbs values: Hash[Symbol, String]
+  # @rbs missing: Array[Symbol]
+  # @rbs return: void
+  def initialize: (values: Hash[Symbol, String], missing: Array[Symbol]) -> void
+end