riffer-rig 0.2.1 → 0.4.0

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

@@ -4,7 +4,7 @@
 # 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
+  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
@@ -12,9 +12,25 @@ class Riffer::Rig::UI::Smoother
   # 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.
-  BACKLOG_FRACTION_PER_TICK = Rational(1, 60)
-  MIN_CHARS_PER_TICK = Rational(1, 6)
+  #
+  BACKLOG_FRACTION_PER_TICK = Rational(1, 60) #: Rational
 
+  MIN_CHARS_PER_TICK = Rational(1, 6) #: Rational
+
+  # @rbs @io: untyped
+  # @rbs @theme: Riffer::Rig::UI::Theme
+  # @rbs @clock: singleton(Kernel)
+  # @rbs @backlog: String
+  # @rbs @carry: Rational
+  # @rbs @mutex: Mutex
+  # @rbs @thread: Thread?
+  # @rbs @stop: bool
+  # @rbs @newline_pending: bool
+
+  # @rbs io: untyped
+  # @rbs ?theme: Riffer::Rig::UI::Theme
+  # @rbs clock: singleton(Kernel)
+  # @rbs return: void
   def initialize(io: $stdout, theme: Riffer::Rig::UI::Theme.for(io), clock: Kernel)
     @io = io
     @theme = theme
@@ -24,8 +40,10 @@ class Riffer::Rig::UI::Smoother
     @mutex = Mutex.new
     @thread = nil
     @stop = false
+    @newline_pending = false
   end
 
+  # @rbs return: void
   def start
     return unless enabled?
     return if @thread
@@ -39,17 +57,24 @@ class Riffer::Rig::UI::Smoother
     end
   end
 
+  # @rbs content: String
+  # @rbs return: self
   def <<(content)
-    if enabled?
-      @mutex.synchronize { @backlog << content }
-    else
-      @io.print(content)
-      @io.flush
+    @mutex.synchronize do
+      if enabled?
+        @backlog << content
+      else
+        @io.print(content)
+        @io.flush
+      end
+      @newline_pending = !content.end_with?("\n")
     end
     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?
@@ -59,26 +84,42 @@ class Riffer::Rig::UI::Smoother
       return if count.zero?
 
       @carry -= count
-      @io.print(@backlog.slice!(0, count))
+      chunk = @backlog.slice!(0, count) || ''
+      @newline_pending = !chunk.end_with?("\n")
+      @io.print(chunk)
       @io.flush
     end
   end
 
-  # Called before non-delta output so printed order matches stream order.
+  # 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
-      return if @backlog.empty?
+      unless @backlog.empty?
+        backlog = @backlog.slice!(0, @backlog.length) || ''
+        @newline_pending = !backlog.end_with?("\n")
+        @io.print(backlog)
+      end
+      return unless @newline_pending
 
-      @io.print(@backlog.slice!(0, @backlog.length))
+      @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
-    if @thread
+    thread = @thread
+    if thread
       @stop = true
-      @thread.join
+      thread.join
       @thread = nil
     end
     drain
@@ -86,6 +127,7 @@ class Riffer::Rig::UI::Smoother
 
   private
 
+  # @rbs return: bool
   def enabled?
     @theme.enabled && @io.respond_to?(:tty?) && @io.tty?
   end

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

@@ -2,43 +2,74 @@
 
 # +enabled+ gates every escape so the same code path emits plain, escape-free
 # text when piped or tested.
-Riffer::Rig::UI::Theme = Data.define(:enabled)
-
-# Behaviour lives in a reopened class (rather than the `Data.define` block) so
-# the type checker can analyse the methods.
 class Riffer::Rig::UI::Theme
+  # @rbs @enabled: bool
+
+  # @rbs return: bool
+  # @dynamic enabled
+  attr_reader :enabled #: bool
+
+  # @rbs enabled: bool
+  # @rbs return: void
+  def initialize(enabled:)
+    @enabled = enabled
+  end
+
+  # @rbs io: untyped
+  # @rbs return: Riffer::Rig::UI::Theme
   def self.for(io)
     new(enabled: io.respond_to?(:tty?) && io.tty? && !ENV.key?('NO_COLOR'))
   end
 
+  # @rbs text: String
+  # @rbs rgb: Array[Integer]
+  # @rbs return: String
   def paint(text, rgb)
-    return text.to_s unless enabled
+    return text unless enabled
 
     "\e[38;2;#{rgb[0]};#{rgb[1]};#{rgb[2]}m#{text}\e[0m"
   end
 
+  # @rbs text: String
+  # @rbs return: String
   def pink(text) = paint(text, Riffer::Rig::UI::Palette::PINK)
 
+  # @rbs text: String
+  # @rbs return: String
   def magenta(text) = paint(text, Riffer::Rig::UI::Palette::MAGENTA)
 
+  # @rbs text: String
+  # @rbs return: String
   def purple(text) = paint(text, Riffer::Rig::UI::Palette::PURPLE)
 
+  # @rbs text: String
+  # @rbs return: String
   def blue(text) = paint(text, Riffer::Rig::UI::Palette::BLUE)
 
+  # @rbs text: String
+  # @rbs return: String
   def cyan(text) = paint(text, Riffer::Rig::UI::Palette::CYAN)
 
+  # @rbs text: String
+  # @rbs return: String
   def grey(text) = paint(text, Riffer::Rig::UI::Palette::GREY)
 
+  # @rbs text: String
+  # @rbs return: String
   def red(text) = paint(text, Riffer::Rig::UI::Palette::RED)
 
+  # @rbs text: String
+  # @rbs return: String
   def dim(text)
-    return text.to_s unless enabled
+    return text unless enabled
 
     "\e[2m#{text}\e[0m"
   end
 
+  # @rbs text: String
+  # @rbs return: String
   def bold(text)
-    return text.to_s unless enabled
+    return text unless enabled
 
     "\e[1m#{text}\e[0m"
   end

data/lib/riffer/rig/version.rb

@@ -2,6 +2,6 @@
 
 module Riffer
   module Rig
-    VERSION = '0.2.1'
+    VERSION = '0.4.0'
   end
 end

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

@@ -0,0 +1,41 @@
+# Generated from lib/riffer/rig/cli.rb with RBS::Inline
+
+module Riffer::Rig::CLI
+  PROVIDER_URLS: Hash[String, String]
+
+  # @rbs output: untyped
+  # @rbs input: untyped
+  # @rbs return: Integer
+  def start: (?output: untyped, ?input: untyped) -> 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: untyped
+  # @rbs input: untyped
+  # @rbs return: String?
+  def onboard: (String? provider, Riffer::Rig::UI::Theme theme, output: untyped, input: untyped) -> String?
+
+  # @rbs provider: String?
+  # @rbs return: String
+  def env_var_for: (String? provider) -> String
+
+  # @rbs input: untyped
+  # @rbs return: String?
+  def read_secret: (untyped input) -> String?
+
+  # @rbs theme: Riffer::Rig::UI::Theme
+  # @rbs animator: Riffer::Rig::UI::Animator
+  # @rbs model: String
+  # @rbs return: void
+  def reveal_banner: (Riffer::Rig::UI::Theme theme, Riffer::Rig::UI::Animator animator, String model) -> void
+
+  # @rbs return: String
+  def count_skills: () -> String
+end

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

@@ -0,0 +1,9 @@
+# Generated from lib/riffer/rig/coding_agent.rb with RBS::Inline
+
+class Riffer::Rig::CodingAgent < Riffer::Agent
+  GLOBAL_AGENTS_FILE: String
+
+  GLOBAL_SKILLS_DIR: String
+
+  PROJECT_SKILLS_DIR: ^() -> String
+end

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

@@ -0,0 +1,55 @@
+# Generated from lib/riffer/rig/credentials.rb with RBS::Inline
+
+# Reads and writes API keys for each supported provider in
+# <tt>~/.riffer/auth.json</tt>.
+#
+# Keys are stored under the provider name, e.g.:
+#
+#   {
+#     "anthropic": "sk-ant-...",
+#     "openai": "sk-...",
+#     "gemini": "...",
+#     "openrouter": "sk-or-..."
+#   }
+#
+# The environment variable checked per provider:
+#
+#   anthropic  → ANTHROPIC_API_KEY
+#   openai     → OPENAI_API_KEY
+#   gemini     → GEMINI_API_KEY
+#   openrouter → OPENROUTER_API_KEY
+module Riffer::Rig::Credentials
+  PATH: String
+
+  PROVIDER_ENV_VARS: 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: (String? provider, ?path: String) -> String?
+
+  # 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: (String provider, String key, ?path: String) -> String
+
+  private
+
+  # @rbs provider: String?
+  # @rbs path: String
+  # @rbs return: String?
+  def key_from_file: (String? provider, String path) -> String?
+
+  # 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: (String path) -> Hash[String, untyped]
+end

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

@@ -0,0 +1,68 @@
+# Generated from lib/riffer/rig/repl.rb with RBS::Inline
+
+class Riffer::Rig::REPL
+  EXIT_COMMANDS: Array[String]
+
+  SKILL_COMMAND: Regexp
+
+  @output: untyped
+
+  @input: untyped
+
+  @theme: Riffer::Rig::UI::Theme
+
+  @cursor: Riffer::Rig::UI::Cursor
+
+  @smoother: Riffer::Rig::UI::Smoother
+
+  @animator: Riffer::Rig::UI::Animator
+
+  @renderer: Riffer::Rig::UI::Renderer
+
+  @agent: Riffer::Agent
+
+  # @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: untyped, renderer: untyped, ?input: untyped, ?output: untyped, ?theme: untyped, ?animator: untyped, ?smoother: untyped, ?cursor: untyped) -> void
+
+  # @rbs return: Symbol
+  def run: () -> Symbol
+
+  private
+
+  # @rbs prompt: String
+  # @rbs return: void
+  def run_turn: (String prompt) -> void
+
+  # @rbs name: String
+  # @rbs args: String
+  # @rbs return: void
+  def run_skill_command: (String name, String args) -> void
+
+  # @rbs name: String
+  # @rbs return: String?
+  def activate_skill: (String name) -> String?
+
+  # @rbs name: String
+  # @rbs body: String
+  # @rbs return: String
+  def skill_block: (String name, String body) -> String
+
+  # 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: () ?{ (?) -> untyped } -> void
+
+  # @rbs message: Riffer::Messages::Base
+  # @rbs return: void
+  def render_tool_result: (Riffer::Messages::Base message) -> void
+end

data/sig/generated/riffer/rig/settings/pricing.rbs

@@ -0,0 +1,23 @@
+# Generated from lib/riffer/rig/settings/pricing.rb with RBS::Inline
+
+# 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: Float
+
+  # @dynamic input, output, cache_write, cache_read
+  attr_reader output: Float
+
+  # @dynamic input, output, cache_write, cache_read
+  attr_reader cache_write: Float
+
+  # @dynamic input, output, cache_write, cache_read
+  attr_reader cache_read: Float
+
+  # @rbs input: Float
+  # @rbs output: Float
+  # @rbs cache_write: Float
+  # @rbs cache_read: Float
+  # @rbs return: void
+  def initialize: (input: Float, output: Float, cache_write: Float, cache_read: Float) -> void
+end

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

@@ -0,0 +1,92 @@
+# Generated from lib/riffer/rig/settings.rb with RBS::Inline
+
+# 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
+  PATH: String
+
+  DEFAULT_MODEL: ::String
+
+  REASONING_LEVELS_BY_PROVIDER: Hash[String, Array[String]]
+
+  # Returns the configured model string, or +DEFAULT_MODEL+ if not set.
+  #
+  # @rbs path: String
+  # @rbs return: String
+  def model: (?path: String) -> String
+
+  # 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: String) -> Hash[Symbol, untyped]
+
+  # 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: (String model_string) -> String?
+
+  # Returns the pricing for +model+, or +nil+ if not configured.
+  #
+  # @rbs model: String
+  # @rbs path: String
+  # @rbs return: Pricing?
+  def pricing_for: (String model, ?path: String) -> Pricing?
+
+  private
+
+  # @rbs provider: String?
+  # @rbs return: Hash[Symbol, untyped]
+  def base_options: (String? provider) -> Hash[Symbol, untyped]
+
+  # @rbs path: String
+  # @rbs ?provider: String?
+  # @rbs return: String?
+  def reasoning_for: (?path: String, ?provider: untyped) -> String?
+
+  # 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: (String? level, String? provider) -> Hash[Symbol, untyped]
+
+  # 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: (String path) -> Hash[String, untyped]
+end

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

@@ -0,0 +1,61 @@
+# Generated from lib/riffer/rig/token_tally.rb with RBS::Inline
+
+# 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
+  @input_tokens: Integer
+
+  @output_tokens: Integer
+
+  @cache_write_tokens: Integer
+
+  @cache_read_tokens: Integer
+
+  @pricing: Riffer::Rig::Settings::Pricing?
+
+  # @dynamic input_tokens, output_tokens, cache_write_tokens, cache_read_tokens
+  attr_reader input_tokens: untyped
+
+  # @dynamic input_tokens, output_tokens, cache_write_tokens, cache_read_tokens
+  attr_reader output_tokens: untyped
+
+  # @dynamic input_tokens, output_tokens, cache_write_tokens, cache_read_tokens
+  attr_reader cache_write_tokens: untyped
+
+  # @dynamic input_tokens, output_tokens, cache_write_tokens, cache_read_tokens
+  attr_reader cache_read_tokens: untyped
+
+  # @rbs ?pricing: Riffer::Rig::Settings::Pricing?
+  # @rbs return: void
+  def initialize: (?pricing: untyped) -> void
+
+  # Accumulates token counts from a +Riffer::Providers::TokenUsage+ object.
+  #
+  # @rbs usage: Riffer::Providers::TokenUsage
+  # @rbs return: void
+  def add: (Riffer::Providers::TokenUsage usage) -> void
+
+  # Returns the total token count across all categories.
+  #
+  # @rbs return: Integer
+  def total_tokens: () -> Integer
+
+  # Returns +true+ if any tokens have been counted.
+  #
+  # @rbs return: bool
+  def any?: () -> bool
+
+  # Returns the estimated cost in USD, or +nil+ if no pricing was provided.
+  #
+  # @rbs return: Float?
+  def estimated_cost: () -> Float?
+end

data/sig/generated/riffer/rig/tools/bash.rbs

@@ -0,0 +1,28 @@
+# Generated from lib/riffer/rig/tools/bash.rb with RBS::Inline
+
+class Riffer::Rig::Tools::Bash < Riffer::Tool
+  DEFAULT_TIMEOUT_MS: Integer
+
+  MAX_OUTPUT_BYTES: Integer
+
+  # @rbs context: Riffer::Agent::Context?
+  # @rbs command: String
+  # @rbs ?timeout_ms: Integer
+  # @rbs return: Riffer::Tools::Response
+  def call: (context: Riffer::Agent::Context?, command: String, ?timeout_ms: untyped) -> Riffer::Tools::Response
+
+  private
+
+  # @rbs command: String
+  # @rbs timeout_seconds: Float
+  # @rbs return: [String, Integer]
+  def run: (String command, Float timeout_seconds) -> [ String, Integer ]
+
+  # @rbs pid: Integer
+  # @rbs return: Integer
+  def kill_group: (Integer pid) -> Integer
+
+  # @rbs output: String
+  # @rbs return: String
+  def truncate: (String output) -> String
+end

data/sig/generated/riffer/rig/tools/edit.rbs

@@ -0,0 +1,11 @@
+# Generated from lib/riffer/rig/tools/edit.rb with RBS::Inline
+
+class Riffer::Rig::Tools::Edit < Riffer::Tool
+  # @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: Riffer::Agent::Context?, path: String, old_string: String, new_string: String, ?replace_all: untyped) -> Riffer::Tools::Response
+end

data/sig/generated/riffer/rig/tools/read.rbs

@@ -0,0 +1,12 @@
+# Generated from lib/riffer/rig/tools/read.rb with RBS::Inline
+
+class Riffer::Rig::Tools::Read < Riffer::Tool
+  DEFAULT_LIMIT: Integer
+
+  # @rbs context: Riffer::Agent::Context?
+  # @rbs path: String
+  # @rbs ?offset: Integer?
+  # @rbs ?limit: Integer
+  # @rbs return: Riffer::Tools::Response
+  def call: (context: Riffer::Agent::Context?, path: String, ?offset: untyped, ?limit: untyped) -> Riffer::Tools::Response
+end

data/sig/generated/riffer/rig/tools/write.rbs

@@ -0,0 +1,9 @@
+# Generated from lib/riffer/rig/tools/write.rb with RBS::Inline
+
+class Riffer::Rig::Tools::Write < Riffer::Tool
+  # @rbs context: Riffer::Agent::Context?
+  # @rbs path: String
+  # @rbs content: String
+  # @rbs return: Riffer::Tools::Response
+  def call: (context: Riffer::Agent::Context?, path: String, content: String) -> Riffer::Tools::Response
+end