riffer 0.29.0 → 0.29.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: be73ae37c66f2f6ad16acdd7b52c271a782172878086821a9c95dbbe238541d3
-  data.tar.gz: 29ea65859395f2e6daaa993d9e8c60cf1908781f1acf79b642588439f4e41781
+  metadata.gz: 91f54f388c63e670d155ae2b8d84bdafe18edd2f29423d92b52c9bfb686332d3
+  data.tar.gz: 7b1bc3bb32951cadbadfe4ba388ca4dc805849a2724cbfae944daf1a59ea241c
 SHA512:
-  metadata.gz: cce21dcb1840e39b96032cf6061dcce6030e35c21c1ce8f3937138405067cd39644f4a55fd4fddfcc9623549441dccb0d76b5443e7fa890ab84ce73f6af2736d
-  data.tar.gz: 3c0e8a0fbcd42c3aceee9b4d8837188e260d444c2e22df72f1976bdfc7b05bf2669f2494d3121ca066d142baa8629bdd01c51acd294869702b5357d83943a4a6
+  metadata.gz: 5e573dd0b3ad056266a7c8a88b24754a510ceac1737f730cedf98e73dc18be17e2f9dc93ebe47d4c89e2d483c1c40c40a7fcbad586ba1ceac949b11af2011a8c
+  data.tar.gz: c1aa387e0298c3999da9da89a640a86048207dd54abe6a336781a9dd265acec49939729fcca7378872efa595131357601b5639b2437508225470fe473a9a5989

data/.agents/rbs-inline.md

@@ -98,6 +98,23 @@ VERSION = "1.0.0" #: String
 DEFAULTS = {}.freeze #: Hash[Symbol, untyped]
 ```
 
+### Instance variables
+
+The `#:` shorthand on an assignment is a Steep _assertion_ — it types the expression but does
+**not declare the ivar**. To declare an ivar's type, use a `# @rbs` comment inside the class
+body. `# @rbs` is used **only** for ivar declarations in this codebase; everything else uses
+`#:`.
+
+```ruby
+class Riffer::Agent::Session
+  # @rbs @callbacks: Array[^(Riffer::Messages::Base) -> void]   # instance ivar
+end
+
+module Riffer
+  # @rbs self.@config: Riffer::Config?                          # class/module-level ivar
+end
+```
+
 ## Common Type Patterns
 
 | Pattern                   | Meaning                     |
@@ -112,6 +129,40 @@ DEFAULTS = {}.freeze #: Hash[Symbol, untyped]
 | `untyped`                 | Any type                    |
 | `void`                    | No meaningful return        |
 
+## Optional-dependency types (consumer-safe signatures)
+
+`sig/generated/` ships with the gem and is loaded by downstream projects (`rbs collection` / `rbs -r riffer`). rbs-inline copies a method's `#:` signature **verbatim** into the shipped sig, so **never name an optional-dependency type in a `#:` signature** — `OpenAI::*`, `Anthropic::*`, `Aws::*`, `MCP::*`, `Async::*`, `Zeitwerk::*`, etc. A consumer who installs riffer without that gem would hit `Cannot find type`, because those providers are pluggable and the gems ship no usable RBS of their own.
+
+**Workaround — assert the type inside the method body instead.** An inline assertion (`local = arg #: OpenAI::Models::…`) is a Steep-only hint that rbs-inline does **not** emit into the signature. Leave the SDK param/return `untyped` in the `#:` line, keep every riffer/stdlib param and return typed, and recover the SDK type with a body assertion:
+
+```ruby
+#: (untyped) -> String
+def extract_content(response)
+  message = response #: Anthropic::Models::Message
+  message.content&.first&.text || ""        # fully type-checked against the SDK type
+end
+
+#: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+def handle_stream_chunk(chunk, state:, yielder:)
+  typed = chunk #: OpenAI::Models::Chat::ChatCompletionChunk
+  # ...
+end
+
+# When the return value IS the SDK object, type the return `untyped` (no body assertion needed):
+#: (Hash[Symbol, untyped]) -> untyped
+def execute_generate(params)
+  @client.messages.create(**params)
+end
+```
+
+`test/shipped_signatures_test.rb` enforces this — it fails if any optional-dependency type appears in `sig/generated/` or `sig/manual/`.
+
+### Where stubs and stdlib deps live
+
+- `sig/_private/` — signatures that must **not** ship. RBS **skips** `_`-prefixed directories in library mode, so consumers never load them; riffer's own `steep check` does (via the `Steepfile`). Two kinds, by predictable path: external-gem signatures are named by gem at the top level (`async.rbs`, `mcp.rbs`, `zeitwerk.rbs`, `openai.rbs`, `anthropic.rbs`, `aws-sdk-core/*` — full stubs for RBS-less gems plus arity patches for the provider SDKs); riffer's own hidden stubs mirror `lib/` under `riffer/` (e.g. `riffer/providers/anthropic.rbs` declares the SDK-typed `@client` ivar).
+- `sig/manual/` — hand-written riffer-only signatures that are **safe to ship**, for the few things rbs-inline can't generate _at all_ (mirroring `lib/`). In practice that's `extend self` modules (`riffer/agent/run.rbs`, `riffer/helpers/call_or_value.rbs`) and modeling an include applied dynamically (`riffer/tools/toolable.rbs`). SDK-free ivars are **not** hand-written here — declare them inline with `# @rbs` (see "Instance variables"). SDK-typed ivars can't ship, so they go in `_private/riffer/providers/` (`@client`).
+- `sig/manifest.yaml` — declares the **stdlib** RBS the shipped sigs reference (`uri`, `net-http`) so `rbs -r riffer` resolves them.
+
 ## Workflow
 
 After changing type annotations:

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.29.0"
+  ".": "0.29.1"
 }

data/CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.29.1](https://github.com/janeapp/riffer/compare/riffer/v0.29.0...riffer/v0.29.1) (2026-06-01)
+
+
+### Bug Fixes
+
+* **rbs:** ship consumer-safe RBS signatures ([#286](https://github.com/janeapp/riffer/issues/286)) ([ac8ce6c](https://github.com/janeapp/riffer/commit/ac8ce6c40ab665456cee6cd9275649024492f4a0))
+
 ## [0.29.0](https://github.com/janeapp/riffer/compare/riffer/v0.28.0...riffer/v0.29.0) (2026-05-29)
 
 

data/Steepfile

@@ -2,7 +2,8 @@ D = Steep::Diagnostic
 
 target :lib do
   signature "sig/generated"
-  signature "sig/stubs"
+  signature "sig/manual"
+  signature "sig/_private"
 
   check "lib"
 

data/lib/riffer/agent/context.rb

@@ -19,6 +19,8 @@
 #   context.token_usage  # => nil
 #
 class Riffer::Agent::Context
+  # @rbs @data: Hash[Symbol, untyped]
+
   # Keys reserved for framework use. Passing any of these to the
   # constructor raises +Riffer::ArgumentError+.
   RESERVED_KEYS = [:skills, :token_usage].freeze #: Array[Symbol]

data/lib/riffer/agent/response.rb

@@ -13,6 +13,8 @@
 #     puts response.content
 #   end
 class Riffer::Agent::Response
+  # @rbs @interrupted: bool
+
   # The response content.
   attr_reader :content #: String
 

data/lib/riffer/agent/session.rb

@@ -18,6 +18,8 @@
 class Riffer::Agent::Session
   include Enumerable #[Riffer::Messages::Base]
 
+  # @rbs @callbacks: Array[^(Riffer::Messages::Base) -> void]
+
   # The message history.
   attr_reader :messages #: Array[Riffer::Messages::Base]
 

data/lib/riffer/agent.rb

@@ -19,6 +19,8 @@ require "json"
 #   agent.generate('Hello!')
 #
 class Riffer::Agent
+  # @rbs self.@config: Riffer::Agent::Config?
+
   include Riffer::Messages::Converter
   extend Riffer::Helpers::ClassNameConverter
 

data/lib/riffer/evals/evaluator.rb

@@ -16,6 +16,11 @@
 #   end
 #
 class Riffer::Evals::Evaluator
+  # @rbs self.@instructions: String?
+  # @rbs self.@higher_is_better: bool?
+  # @rbs self.@judge_model: String?
+  # @rbs @judge: Riffer::Evals::Judge?
+
   class << self
     # Gets or sets the evaluation instructions (criteria and scoring rubric).
     #

data/lib/riffer/evals/judge.rb

@@ -19,6 +19,11 @@ require "json"
 #   result[:reason] # => "The response is relevant..."
 #
 class Riffer::Evals::Judge
+  # @rbs @provider_options: Hash[Symbol, untyped]
+  # @rbs @provider_instance: Riffer::Providers::Base?
+  # @rbs @provider_name: String?
+  # @rbs @model_name: String?
+
   # Internal tool for structured evaluation output.
   class EvaluationTool < Riffer::Tool
     identifier "evaluation"

data/lib/riffer/mcp/client.rb

@@ -16,6 +16,8 @@
 class Riffer::Mcp::Client
   include Riffer::Helpers::Dependencies
 
+  # @rbs @client: untyped
+
   #--
   #: (endpoint: String, ?headers: (Hash[String, String] | Proc), ?client: untyped?) -> void
   def initialize(endpoint:, headers: {}, client: nil)

data/lib/riffer/mcp/registration.rb

@@ -7,6 +7,10 @@
 # +tools/list+ call, then generates tool classes.
 #
 class Riffer::Mcp::Registration
+  # @rbs @cancelled: bool
+  # @rbs @tools: Array[singleton(Riffer::Tool)]
+  # @rbs @mutex: Thread::Mutex
+
   # The manifest that describes this server.
   attr_reader :manifest #: Riffer::Mcp::Manifest
 

data/lib/riffer/mcp/registry.rb

@@ -6,6 +6,9 @@
 # Keyed by manifest name. All public methods are mutex-guarded.
 #
 module Riffer::Mcp::Registry
+  # @rbs self.@mutex: Thread::Mutex
+  # @rbs self.@store: Hash[String, Riffer::Mcp::Registration]
+
   @mutex = Mutex.new
   @store = {} #: Hash[String, Riffer::Mcp::Registration]
 

data/lib/riffer/messages/file_part.rb

@@ -15,6 +15,8 @@ require "uri"
 #   file.document?   # => true
 #
 class Riffer::Messages::FilePart
+  # @rbs @url_string: String?
+
   MEDIA_TYPES = {
     ".jpg" => "image/jpeg",
     ".jpeg" => "image/jpeg",

data/lib/riffer/providers/amazon_bedrock.rb

@@ -92,15 +92,16 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
   end
 
   #--
-  #: (Hash[Symbol, untyped]) -> Aws::BedrockRuntime::Client::_ConverseResponseSuccess
+  #: (Hash[Symbol, untyped]) -> untyped
   def execute_generate(params)
     @client.converse(**params)
   end
 
   #--
-  #: (Aws::BedrockRuntime::Client::_ConverseResponseSuccess) -> Riffer::Providers::TokenUsage?
+  #: (untyped) -> Riffer::Providers::TokenUsage?
   def extract_token_usage(response)
-    usage = response.usage
+    typed_response = response #: Aws::BedrockRuntime::Client::_ConverseResponseSuccess
+    usage = typed_response.usage
 
     Riffer::Providers::TokenUsage.new(
       input_tokens: usage.input_tokens,
@@ -111,9 +112,10 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
   end
 
   #--
-  #: (Aws::BedrockRuntime::Client::_ConverseResponseSuccess) -> String
+  #: (untyped) -> String
   def extract_content(response)
-    content_blocks = response.output&.message&.content
+    typed_response = response #: Aws::BedrockRuntime::Client::_ConverseResponseSuccess
+    content_blocks = typed_response.output&.message&.content
     return "" if content_blocks.nil? || content_blocks.empty?
 
     text_content = ""
@@ -126,9 +128,10 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
   end
 
   #--
-  #: (Aws::BedrockRuntime::Client::_ConverseResponseSuccess) -> Array[Riffer::Messages::Assistant::ToolCall]
+  #: (untyped) -> Array[Riffer::Messages::Assistant::ToolCall]
   def extract_tool_calls(response)
-    content_blocks = response.output&.message&.content
+    typed_response = response #: Aws::BedrockRuntime::Client::_ConverseResponseSuccess
+    content_blocks = typed_response.output&.message&.content
     return [] if content_blocks.nil? || content_blocks.empty?
 
     tool_calls = [] #: Array[Riffer::Messages::Assistant::ToolCall]
@@ -195,28 +198,31 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
   end
 
   #--
-  #: (Aws::BedrockRuntime::Types::ContentBlockStartEvent, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  #: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
   def handle_content_block_start_tool_use(event, state:, yielder:)
+    typed_event = event #: Aws::BedrockRuntime::Types::ContentBlockStartEvent
     state[:tool_call] = {
-      id: event.start.tool_use.tool_use_id,
-      name: decode_tool_name(event.start.tool_use.name, tools: @current_tools),
+      id: typed_event.start.tool_use.tool_use_id,
+      name: decode_tool_name(typed_event.start.tool_use.name, tools: @current_tools),
       arguments: ""
     }
   end
 
   #--
-  #: (Aws::BedrockRuntime::Types::ContentBlockDeltaEvent, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  #: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
   def handle_content_block_delta_text_delta(event, state:, yielder:)
-    delta_text = event.delta.text
+    typed_event = event #: Aws::BedrockRuntime::Types::ContentBlockDeltaEvent
+    delta_text = typed_event.delta.text
     state[:text] ||= ""
     state[:text] += delta_text
     yielder << Riffer::StreamEvents::TextDelta.new(delta_text)
   end
 
   #--
-  #: (Aws::BedrockRuntime::Types::ContentBlockDeltaEvent, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  #: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
   def handle_content_block_delta_tool_use(event, state:, yielder:)
-    input_delta = event.delta.tool_use.input
+    typed_event = event #: Aws::BedrockRuntime::Types::ContentBlockDeltaEvent
+    input_delta = typed_event.delta.tool_use.input
 
     state[:tool_call][:arguments] += input_delta
 
@@ -228,14 +234,14 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
   end
 
   #--
-  #: (Aws::BedrockRuntime::Types::ContentBlockStopEvent, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  #: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
   def handle_content_block_stop_text_delta(_event, state:, yielder:)
     yielder << Riffer::StreamEvents::TextDone.new(state[:text])
     state[:text] = nil
   end
 
   #--
-  #: (Aws::BedrockRuntime::Types::ContentBlockStopEvent, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  #: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
   def handle_content_block_stop_tool_use(_event, state:, yielder:)
     tool_call = state[:tool_call]
     yielder << Riffer::StreamEvents::ToolCallDone.new(
@@ -248,14 +254,15 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
   end
 
   #--
-  #: (Aws::BedrockRuntime::Types::ConverseStreamMetadataEvent, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  #: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
   def handle_metadata_usage(event, state:, yielder:)
+    typed_event = event #: Aws::BedrockRuntime::Types::ConverseStreamMetadataEvent
     yielder << Riffer::StreamEvents::TokenUsageDone.new(
       token_usage: Riffer::Providers::TokenUsage.new(
-        input_tokens: event.usage.input_tokens,
-        output_tokens: event.usage.output_tokens,
-        cache_creation_tokens: event.usage.cache_write_input_tokens,
-        cache_read_tokens: event.usage.cache_read_input_tokens
+        input_tokens: typed_event.usage.input_tokens,
+        output_tokens: typed_event.usage.output_tokens,
+        cache_creation_tokens: typed_event.usage.cache_write_input_tokens,
+        cache_read_tokens: typed_event.usage.cache_read_input_tokens
       )
     )
   end

data/lib/riffer/providers/anthropic.rb

@@ -77,15 +77,16 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
   end
 
   #--
-  #: (Hash[Symbol, untyped]) -> Anthropic::Models::Message
+  #: (Hash[Symbol, untyped]) -> untyped
   def execute_generate(params)
     @client.messages.create(**params)
   end
 
   #--
-  #: (Anthropic::Models::Message) -> Riffer::Providers::TokenUsage?
+  #: (untyped) -> Riffer::Providers::TokenUsage?
   def extract_token_usage(response)
-    usage = response.usage
+    message = response #: Anthropic::Models::Message
+    usage = message.usage
 
     Riffer::Providers::TokenUsage.new(
       input_tokens: usage.input_tokens,
@@ -96,9 +97,10 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
   end
 
   #--
-  #: (Anthropic::Models::Message) -> String
+  #: (untyped) -> String
   def extract_content(response)
-    content_blocks = response.content
+    message = response #: Anthropic::Models::Message
+    content_blocks = message.content
     return "" if content_blocks.nil? || content_blocks.empty?
 
     text_content = ""
@@ -111,9 +113,10 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
   end
 
   #--
-  #: (Anthropic::Models::Message) -> Array[Riffer::Messages::Assistant::ToolCall]
+  #: (untyped) -> Array[Riffer::Messages::Assistant::ToolCall]
   def extract_tool_calls(response)
-    content_blocks = response.content
+    message = response #: Anthropic::Models::Message
+    content_blocks = message.content
     return [] if content_blocks.nil? || content_blocks.empty?
 
     tool_calls = [] #: Array[Riffer::Messages::Assistant::ToolCall]
@@ -285,9 +288,10 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
   end
 
   #--
-  #: (untyped, accumulated_message: Anthropic::Models::Message?, yielder: Enumerator::Yielder) -> void
+  #: (untyped, accumulated_message: untyped, yielder: Enumerator::Yielder) -> void
   def handle_message_stop(_event, accumulated_message:, yielder:)
-    usage = accumulated_message&.usage
+    message = accumulated_message #: Anthropic::Models::Message?
+    usage = message&.usage
     return unless usage
 
     yielder << Riffer::StreamEvents::TokenUsageDone.new(

data/lib/riffer/providers/base.rb

@@ -17,6 +17,8 @@ require "json"
 # [extract_content] extract text content from the SDK response
 # [extract_tool_calls] extract tool calls from the SDK response
 class Riffer::Providers::Base
+  # @rbs @current_tools: Array[singleton(Riffer::Tool)]
+
   include Riffer::Helpers::Dependencies
   include Riffer::Messages::Converter
 

data/lib/riffer/providers/gemini.rb

@@ -8,6 +8,10 @@ require "uri"
 
 # Google Gemini provider for Gemini models via the Gemini REST API.
 class Riffer::Providers::Gemini < Riffer::Providers::Base
+  # @rbs @api_key: String?
+  # @rbs @open_timeout: Integer
+  # @rbs @read_timeout: Integer
+
   BASE_URI = URI("https://generativelanguage.googleapis.com") #: URI::Generic
   VALID_MODEL_PATTERN = /\A[a-zA-Z0-9._-]+\z/ #: Regexp
   DEFAULT_OPEN_TIMEOUT = 10 #: Integer

data/lib/riffer/providers/mock.rb

@@ -5,6 +5,10 @@
 #
 # No external gems required.
 class Riffer::Providers::Mock < Riffer::Providers::Base
+  # @rbs @responses: Array[Hash[Symbol, untyped]]
+  # @rbs @current_index: Integer
+  # @rbs @stubbed_responses: Array[Hash[Symbol, untyped]]
+
   # Returns the preferred skill adapter for the given mock model.
   #
   # Mock is used to stand in for any real provider in tests, so the model

data/lib/riffer/providers/open_ai.rb

@@ -66,15 +66,16 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
   end
 
   #--
-  #: (Hash[Symbol, untyped]) -> OpenAI::Models::Responses::Response
+  #: (Hash[Symbol, untyped]) -> untyped
   def execute_generate(params)
     @client.responses.create(params)
   end
 
   #--
-  #: (OpenAI::Models::Responses::Response) -> Riffer::Providers::TokenUsage?
+  #: (untyped) -> Riffer::Providers::TokenUsage?
   def extract_token_usage(response)
-    usage = response.usage
+    typed_response = response #: OpenAI::Models::Responses::Response
+    usage = typed_response.usage
     return nil unless usage
 
     Riffer::Providers::TokenUsage.new(
@@ -84,11 +85,12 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
   end
 
   #--
-  #: (OpenAI::Models::Responses::Response) -> String
+  #: (untyped) -> String
   def extract_content(response)
+    typed_response = response #: OpenAI::Models::Responses::Response
     text_content = ""
 
-    response.output.each do |item|
+    typed_response.output.each do |item|
       next unless item.is_a?(::OpenAI::Models::Responses::ResponseOutputMessage)
 
       text_block = item.content.find { |c| c.is_a?(::OpenAI::Models::Responses::ResponseOutputText) }
@@ -99,11 +101,12 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
   end
 
   #--
-  #: (OpenAI::Models::Responses::Response) -> Array[Riffer::Messages::Assistant::ToolCall]
+  #: (untyped) -> Array[Riffer::Messages::Assistant::ToolCall]
   def extract_tool_calls(response)
+    typed_response = response #: OpenAI::Models::Responses::Response
     tool_calls = [] #: Array[Riffer::Messages::Assistant::ToolCall]
 
-    response.output.each do |item|
+    typed_response.output.each do |item|
       next unless item.is_a?(::OpenAI::Models::Responses::ResponseFunctionToolCall)
 
       tool_calls << Riffer::Messages::Assistant::ToolCall.new(

data/lib/riffer/providers/open_router.rb

@@ -64,15 +64,16 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
   end
 
   #--
-  #: (Hash[Symbol, untyped]) -> OpenAI::Models::Chat::ChatCompletion
+  #: (Hash[Symbol, untyped]) -> untyped
   def execute_generate(params)
     @client.chat.completions.create(**params)
   end
 
   #--
-  #: (OpenAI::Models::Chat::ChatCompletion) -> Riffer::Providers::TokenUsage?
+  #: (untyped) -> Riffer::Providers::TokenUsage?
   def extract_token_usage(response)
-    usage = response.usage
+    typed_response = response #: OpenAI::Models::Chat::ChatCompletion
+    usage = typed_response.usage
     return nil unless usage
 
     Riffer::Providers::TokenUsage.new(
@@ -82,15 +83,17 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
   end
 
   #--
-  #: (OpenAI::Models::Chat::ChatCompletion) -> String
+  #: (untyped) -> String
   def extract_content(response)
-    response.choices.first&.message&.content || ""
+    typed_response = response #: OpenAI::Models::Chat::ChatCompletion
+    typed_response.choices.first&.message&.content || ""
   end
 
   #--
-  #: (OpenAI::Models::Chat::ChatCompletion) -> Array[Riffer::Messages::Assistant::ToolCall]
+  #: (untyped) -> Array[Riffer::Messages::Assistant::ToolCall]
   def extract_tool_calls(response)
-    message = response.choices.first&.message
+    typed_response = response #: OpenAI::Models::Chat::ChatCompletion
+    message = typed_response.choices.first&.message
     return [] unless message
 
     tool_calls = message.tool_calls
@@ -145,9 +148,10 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
   end
 
   #--
-  #: (OpenAI::Models::Chat::ChatCompletionChunk, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  #: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
   def handle_stream_chunk(chunk, state:, yielder:)
-    choice = chunk.choices&.first
+    typed_chunk = chunk #: OpenAI::Models::Chat::ChatCompletionChunk
+    choice = typed_chunk.choices&.first
     delta = choice&.delta
 
     if delta
@@ -160,20 +164,21 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
       emit_tool_call_done_events(state: state, yielder: yielder)
     end
 
-    return unless chunk.usage
+    return unless typed_chunk.usage
 
     yielder << Riffer::StreamEvents::TokenUsageDone.new(
       token_usage: Riffer::Providers::TokenUsage.new(
-        input_tokens: chunk.usage.prompt_tokens,
-        output_tokens: chunk.usage.completion_tokens
+        input_tokens: typed_chunk.usage.prompt_tokens,
+        output_tokens: typed_chunk.usage.completion_tokens
       )
     )
   end
 
   #--
-  #: (OpenAI::Models::Chat::ChatCompletionChunk::Choice::Delta, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  #: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
   def handle_text_delta(delta, state:, yielder:)
-    content = delta.content
+    typed_delta = delta #: OpenAI::Models::Chat::ChatCompletionChunk::Choice::Delta
+    content = typed_delta.content
     return if content.nil? || content.empty?
 
     state[:text] << content
@@ -194,9 +199,10 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
   end
 
   #--
-  #: (OpenAI::Models::Chat::ChatCompletionChunk::Choice::Delta, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  #: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
   def handle_tool_call_deltas(delta, state:, yielder:)
-    tool_calls = delta.tool_calls
+    typed_delta = delta #: OpenAI::Models::Chat::ChatCompletionChunk::Choice::Delta
+    tool_calls = typed_delta.tool_calls
     return if tool_calls.nil? || tool_calls.empty?
 
     tool_calls.each do |tc|
@@ -236,9 +242,10 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
   end
 
   #--
-  #: (OpenAI::Models::Chat::ChatCompletionChunk::Choice) -> bool
+  #: (untyped) -> bool
   def finish_reason_is_tool_calls?(choice)
-    choice.finish_reason.to_s == "tool_calls"
+    typed_choice = choice #: OpenAI::Models::Chat::ChatCompletionChunk::Choice
+    typed_choice.finish_reason.to_s == "tool_calls"
   end
 
   #--

data/lib/riffer/runner/fibers.rb

@@ -14,6 +14,8 @@
 #   runner.map(items) { |item| expensive_operation(item) }
 #
 class Riffer::Runner::Fibers < Riffer::Runner
+  # @rbs @max_concurrency: Integer?
+
   include Riffer::Helpers::Dependencies
 
   # [max_concurrency] maximum number of fibers to run simultaneously.

data/lib/riffer/runner/threaded.rb

@@ -14,6 +14,8 @@
 #   runner.map(items) { |item| expensive_operation(item) }
 #
 class Riffer::Runner::Threaded < Riffer::Runner
+  # @rbs @max_concurrency: Integer
+
   DEFAULT_MAX_CONCURRENCY = 5 #: Integer
 
   # [max_concurrency] maximum number of threads to run simultaneously.

data/lib/riffer/skills/config.rb

@@ -11,6 +11,11 @@
 #     activate ["code-review"]
 #   end
 class Riffer::Skills::Config
+  # @rbs @backend: (Riffer::Skills::Backend | Proc)?
+  # @rbs @adapter: singleton(Riffer::Skills::Adapter)?
+  # @rbs @activate: (Array[String] | Proc)?
+  # @rbs @activate_tool: singleton(Riffer::Tool)?
+
   # Creates a new Config with all options unset.
   #
   #--

data/lib/riffer/skills/context.rb

@@ -11,6 +11,9 @@
 #
 # See Riffer::Skills::Backend, Riffer::Skills::Frontmatter.
 class Riffer::Skills::Context
+  # @rbs @backend: Riffer::Skills::Backend
+  # @rbs @activated: Hash[String, String]
+
   # Skill catalog indexed by name.
   attr_reader :skills #: Hash[String, Riffer::Skills::Frontmatter]
 

data/lib/riffer/skills/filesystem_backend.rb

@@ -11,6 +11,9 @@
 #   backend.read_skill("code-review")  # => "Full skill instructions..."
 #
 class Riffer::Skills::FilesystemBackend < Riffer::Skills::Backend
+  # @rbs @paths: Array[String]
+  # @rbs @skills_cache: Hash[String, String]?
+
   # Creates a new FilesystemBackend.
   #
   # [paths] one or more directory paths to scan for skills.

data/lib/riffer/tools/response.rb

@@ -18,6 +18,8 @@ require "json"
 #   end
 #
 class Riffer::Tools::Response
+  # @rbs @success: bool
+
   VALID_FORMATS = %i[text json].freeze #: Array[Symbol]
 
   attr_reader :content #: String