riffer-rig 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f87fb650798f95679ff56654620a0fcb3cc383d8ce650849d9e33382a7837a6f
-  data.tar.gz: e8784d13f472d45c5ffb7f1d269c5ab8ff7d0b41a62cfae446ceaee2345413b9
+  metadata.gz: 01f34d2a4cb9347ea2d9f7a81a0969415c98b6622d4f78e123034f9b2c15509e
+  data.tar.gz: 5a61c231fcf2832a514ec62513bdf42e56c87dc08ec994f9fb04fa263188b53d
 SHA512:
-  metadata.gz: '09252fc5c265fdc91be5fc8753b3407560c3be9f94af9616b2d3ae9e8e3c28f100374bb1014d7b8038bd51abc5f86875e6116fc874733ba58dda87254b15e3cc'
-  data.tar.gz: 7f1cc7dae6f6ccf69cf370296458d1eef837111f01041adae31a59e48df6719903c1c43630cf0248ba4b7ba140d420f663a585dcb13f5c945d5f105eaa2b8fc9
+  metadata.gz: 1b8518928f77909373cfdfe2783372aa1a6ebb04fed67a70951041c0adf637bf3aba0ee8b85051f9bdb63c1cdcda91554b2fd9c86b4f82a279eed30964984588
+  data.tar.gz: 3cd5548405bcf8607d516e7f8a585cdf327cfc904e1641458aca4802e8a3654127c6ed44a46435003faeca1eaaafcd4bed0968c0787a90aca8c586438b685146

data/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## [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)
+
+
+### Bug Fixes
+
+* **ui:** hide the cursor while a turn is in flight ([#161](https://github.com/bottrall/riffer-rig/issues/161)) ([0d18fe0](https://github.com/bottrall/riffer-rig/commit/0d18fe06c51bb75a8f3002d22d64bda23671bad6))
+* **ui:** stop the equalizer before the end-of-turn newline ([#158](https://github.com/bottrall/riffer-rig/issues/158)) ([00edaa3](https://github.com/bottrall/riffer-rig/commit/00edaa3bbf35a7d797ca3596820d11bd8c62789a))
+
 ## [0.2.0](https://github.com/bottrall/riffer-rig/compare/v0.1.2...v0.2.0) (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,16 +79,24 @@ 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(', ')
@@ -85,6 +104,7 @@ module Riffer::Rig::CLI
     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
@@ -40,9 +42,9 @@ class Riffer::Rig::CodingAgent < Riffer::Agent
 
       Available tools:
       - read: read a file's contents
-      - write: create or overwrite a file
+      - write: write content to 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.)
+      - bash: run a shell command in the working directory
 
       Guidelines:
       - Be concise and direct in your responses.

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,20 +1,43 @@
 # 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:))
+  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 @pending_tool_calls: Array[Riffer::StreamEvents::ToolCallDone]
+
+  # @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
     @smoother = smoother
+    @cursor = cursor
     @theme = theme
     @input = input
     @output = output
+    @pending_tool_calls = []
     @agent.session.on_message { |message| render_tool_result(message) }
   end
 
+  # @rbs return: Symbol
   def run
     loop do
       @output.print("\n#{@theme.pink('›')} ")
@@ -35,11 +58,15 @@ class Riffer::Rig::REPL
     end
 
     @output.puts("\n#{@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
     @smoother.start
     @agent.stream(prompt).each do |event|
@@ -52,28 +79,44 @@ class Riffer::Rig::REPL
         # 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
+      when Riffer::StreamEvents::ToolCallDone
+        # Tool call lines are held back so the round's stats line can print
+        # above them (see flush_pending_tool_calls).
+        @pending_tool_calls << event
+        next
+      when 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.
+        # Stats print before any pending tool call lines (see below).
         @animator.stop
         @renderer.render(event)
+        flush_pending_tool_calls
         @animator.start
         next
       else
         @animator.stop
       end
+      flush_pending_tool_calls
       @renderer.render(event)
     end
+    @animator.stop
+    flush_pending_tool_calls
     @smoother.finish
     @output.puts
   rescue StandardError => e
+    @animator.stop
+    flush_pending_tool_calls
     @output.puts("\nError: #{e.message}")
   ensure
     @smoother.finish
     @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?
@@ -81,6 +124,8 @@ 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
 
@@ -103,13 +148,33 @@ class Riffer::Rig::REPL
     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 call lines print below their round's stats line to reflect the actual
+  # timeline (usage is reported when the model stream closes, after the calls
+  # were decided). ToolCallDone events are therefore held until the stats line
+  # or the next event forces them out. Callers must have the spinner stopped —
+  # the flush renders between their existing stop/start pair.
+  #
+  # @rbs return: void
+  def flush_pending_tool_calls
+    return if @pending_tool_calls.empty?
+
+    @pending_tool_calls.each { |event| @renderer.render(event) }
+    @pending_tool_calls = []
+  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.
+  #
+  # @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

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

@@ -9,14 +9,19 @@ 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
   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 +33,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 +54,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

@@ -12,6 +12,12 @@ class Riffer::Rig::Tools::Edit < Riffer::Tool
     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)

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))