riffer 0.47.2 → 0.49.0

data/sig/generated/riffer/providers/base.rbs

@@ -1,9 +1,5 @@
 # Generated from lib/riffer/providers/base.rb with RBS::Inline
 
-# Base class for all LLM providers. A template-method flow: subclasses implement
-# the hooks (+build_request_params+, +execute_generate+, +execute_stream+,
-# +extract_token_usage+, +extract_content+, +extract_tool_calls+) and the base
-# class orchestrates them.
 class Riffer::Providers::Base
   self.@semconv_provider_name: String?
 
@@ -15,51 +11,35 @@ class Riffer::Providers::Base
 
   WIRE_SEPARATOR: String
 
-  # Returns the preferred skill adapter for this provider; override in
-  # subclasses (optionally introspecting +model+) for provider-specific formats.
   # --
   # : (?String?) -> singleton(Riffer::Skills::Adapter)
   def self.skills_adapter: (?String?) -> singleton(Riffer::Skills::Adapter)
 
-  # Returns the provider name stamped as <tt>gen_ai.provider.name</tt> on trace
-  # spans, ideally a GenAI semconv well-known value. Defaults to the snake_cased
-  # class name rather than raising like the abstract provider methods, so
-  # enabling tracing never breaks an otherwise-working custom provider.
   # --
   # : () -> String
   def self.semconv_provider_name: () -> String
 
-  # Generates text using the provider.
-  #
   # --
-  # : (?prompt: String?, ?system: String?, ?messages: Array[Hash[Symbol, untyped] | Riffer::Messages::Base]?, ?model: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, **untyped) -> Riffer::Messages::Assistant
-  def generate_text: (?prompt: String?, ?system: String?, ?messages: Array[Hash[Symbol, untyped] | Riffer::Messages::Base]?, ?model: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, **untyped) -> Riffer::Messages::Assistant
+  # : (?prompt: String?, ?system: String?, ?messages: Array[Hash[Symbol, untyped] | Riffer::Messages::Base]?, ?model: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::User::FilePart]?, **untyped) -> Riffer::Messages::Assistant
+  def generate_text: (?prompt: String?, ?system: String?, ?messages: Array[Hash[Symbol, untyped] | Riffer::Messages::Base]?, ?model: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::User::FilePart]?, **untyped) -> Riffer::Messages::Assistant
 
-  # Streams text from the provider.
-  #
   # --
-  # : (?prompt: String?, ?system: String?, ?messages: Array[Hash[Symbol, untyped] | Riffer::Messages::Base]?, ?model: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, **untyped) -> Enumerator[Riffer::StreamEvents::Base, void]
-  def stream_text: (?prompt: String?, ?system: String?, ?messages: Array[Hash[Symbol, untyped] | Riffer::Messages::Base]?, ?model: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, **untyped) -> Enumerator[Riffer::StreamEvents::Base, void]
+  # : (?prompt: String?, ?system: String?, ?messages: Array[Hash[Symbol, untyped] | Riffer::Messages::Base]?, ?model: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::User::FilePart]?, **untyped) -> Enumerator[Riffer::StreamEvents::Base, void]
+  def stream_text: (?prompt: String?, ?system: String?, ?messages: Array[Hash[Symbol, untyped] | Riffer::Messages::Base]?, ?model: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::User::FilePart]?, **untyped) -> Enumerator[Riffer::StreamEvents::Base, void]
 
   # --
-  # : (Riffer::Messages::FilePart) -> Symbol
-  def file_delivery: (Riffer::Messages::FilePart) -> Symbol
+  # : (Riffer::Messages::User::FilePart) -> Symbol
+  def file_delivery: (Riffer::Messages::User::FilePart) -> Symbol
 
   private
 
   # : (String) -> true
   def depends_on: (String) -> true
 
-  # Returns the client for the current LLM call. A configured client wins,
-  # resolved on every call so a Proc can vary the client by process or
-  # credential lifetime; otherwise the provider builds one from the configured
-  # credentials, memoized for the life of the provider.
   # --
   # : () -> untyped
   def client: () -> untyped
 
-  # Returns the consumer-configured client for this provider; nil when none is
-  # configured, and for providers that take no configuration at all.
   # --
   # : () -> untyped
   def global_client: () -> untyped
@@ -99,12 +79,14 @@ class Riffer::Providers::Base
   # : () -> Riffer::Config::Pricing::Rates?
   def pricing_rates: () -> Riffer::Config::Pricing::Rates?
 
-  # Defaults to nil rather than raising — finish reasons are optional, so
-  # providers that don't report one stay valid.
   # --
   # : (untyped) -> Riffer::Providers::FinishReason?
   def extract_finish_reason: (untyped) -> Riffer::Providers::FinishReason?
 
+  # --
+  # : (untyped) -> Array[Riffer::Messages::Assistant::ReasoningPart]
+  def extract_reasoning: (untyped) -> Array[Riffer::Messages::Assistant::ReasoningPart]
+
   # --
   # : (untyped) -> String
   def extract_content: (untyped) -> String
@@ -124,8 +106,6 @@ class Riffer::Providers::Base
   # : (String?, Hash[Symbol, untyped]) -> Hash[String, untyped]
   def chat_span_attributes: (String?, Hash[Symbol, untyped]) -> Hash[String, untyped]
 
-  # Maps normalized tags to their namespaced span attribute form. An empty map
-  # yields an empty hash, so merging it is a no-op.
   # --
   # : (Hash[String, String]) -> Hash[String, String]
   def tag_attributes: (Hash[String, String]) -> Hash[String, String]
@@ -150,6 +130,10 @@ class Riffer::Providers::Base
   # : ((Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span)) -> bool
   def capture_messages?: (Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span) -> bool
 
+  # --
+  # : (Riffer::Providers::_EventSink, String) -> void
+  def yield_reasoning_done: (Riffer::Providers::_EventSink, String) -> void
+
   # --
   # : (Riffer::Providers::_EventSink, Riffer::Providers::FinishReason?) -> void
   def yield_finish_reason: (Riffer::Providers::_EventSink, Riffer::Providers::FinishReason?) -> void
@@ -159,8 +143,8 @@ class Riffer::Providers::Base
   def parse_structured_output: (String) -> Hash[Symbol, untyped]?
 
   # --
-  # : ((String | Hash[String, untyped])?) -> Hash[String, untyped]
-  def parse_tool_arguments: ((String | Hash[String, untyped])?) -> Hash[String, untyped]
+  # : (String) -> Hash[String, untyped]
+  def parse_tool_arguments: (String) -> Hash[String, untyped]
 
   # --
   # : (Array[Riffer::Messages::Base]) -> Array[Riffer::Messages::Base]
@@ -171,8 +155,8 @@ class Riffer::Providers::Base
   def validate_input!: (prompt: String?, system: String?, messages: Array[Hash[Symbol | String, untyped] | Riffer::Messages::Base]?) -> void
 
   # --
-  # : (prompt: String?, system: String?, messages: Array[Hash[Symbol, untyped] | Riffer::Messages::Base]?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?) -> Array[Riffer::Messages::Base]
-  def normalize_messages: (prompt: String?, system: String?, messages: Array[Hash[Symbol, untyped] | Riffer::Messages::Base]?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?) -> Array[Riffer::Messages::Base]
+  # : (prompt: String?, system: String?, messages: Array[Hash[Symbol, untyped] | Riffer::Messages::Base]?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::User::FilePart]?) -> Array[Riffer::Messages::Base]
+  def normalize_messages: (prompt: String?, system: String?, messages: Array[Hash[Symbol, untyped] | Riffer::Messages::Base]?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::User::FilePart]?) -> Array[Riffer::Messages::Base]
 
   # --
   # : (Array[Riffer::Messages::Base]) -> void

data/sig/generated/riffer/providers/finish_reason.rbs

@@ -1,18 +1,12 @@
 # Generated from lib/riffer/providers/finish_reason.rb with RBS::Inline
 
-# Normalized reason an LLM call finished, paired with the provider's raw
-# wire value. +reason+ carries the same meaning for every provider.
 class Riffer::Providers::FinishReason
-  # The normalized vocabulary every provider maps into.
   VALUES: Array[Symbol]
 
-  # The normalized reason.
   attr_reader reason: Symbol
 
-  # The provider's raw finish-reason value, when one exists on the wire.
   attr_reader raw: String?
 
-  # Raises Riffer::ArgumentError when +reason+ is outside VALUES.
   # --
   # : (reason: Symbol, ?raw: String?) -> void
   def initialize: (reason: Symbol, ?raw: String?) -> void

data/sig/generated/riffer/providers/gemini/client.rbs

@@ -1,17 +1,7 @@
 # Generated from lib/riffer/providers/gemini/client.rb with RBS::Inline
 
-# HTTP transport for the Gemini REST API. Riffer builds one from the
-# configured +api_key+ by default; construct your own to tune the HTTP knobs
-# and assign it to <tt>Riffer.config.gemini.client</tt>. Any object
-# implementing +post+ and +post_stream+ with these contracts works there —
-# the class is a default implementation, not a required base.
-#
-#   Riffer.configure do |config|
-#     config.gemini.client = Riffer::Providers::Gemini::Client.new(
-#       api_key: ENV["GEMINI_API_KEY"],
-#       read_timeout: 120
-#     )
-#   end
+# <tt>Riffer.config.gemini.client</tt> accepts any object implementing +post+ and +post_stream+
+# with these contracts; this class is the default, not a required base.
 class Riffer::Providers::Gemini::Client
   @proxy_port: Integer?
 
@@ -36,15 +26,12 @@ class Riffer::Providers::Gemini::Client
   # : (?api_key: String?, ?base_url: String, ?open_timeout: Integer, ?read_timeout: Integer, ?write_timeout: Integer?, ?proxy_address: String?, ?proxy_port: Integer?) -> void
   def initialize: (?api_key: String?, ?base_url: String, ?open_timeout: Integer, ?read_timeout: Integer, ?write_timeout: Integer?, ?proxy_address: String?, ?proxy_port: Integer?) -> void
 
-  # POSTs a JSON body to an API path and returns the parsed response hash.
-  # Raises Riffer::Error when the API responds with a non-success status.
+  # Raises Riffer::Error on a non-success status.
   # --
   # : (String, Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
   def post: (String, Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
 
-  # POSTs a JSON body to an API path, yielding raw response body chunks as
-  # they arrive. Raises Riffer::Error when the API responds with a
-  # non-success status.
+  # Raises Riffer::Error on a non-success status.
   # --
   # : (String, Hash[Symbol, untyped]) { (String) -> void } -> void
   def post_stream: (String, Hash[Symbol, untyped]) { (String) -> void } -> void

data/sig/generated/riffer/providers/gemini.rbs

@@ -1,19 +1,17 @@
 # Generated from lib/riffer/providers/gemini.rb with RBS::Inline
 
-# Google Gemini provider for Gemini models via the Gemini REST API.
 class Riffer::Providers::Gemini < Riffer::Providers::Base
   VALID_MODEL_PATTERN: Regexp
 
   FINISH_REASONS: Hash[String, Symbol]
 
-  # The GenAI semconv well-known provider name.
   # --
   # : () -> String
   def self.semconv_provider_name: () -> String
 
   # --
-  # : (Riffer::Messages::FilePart) -> Symbol
-  def file_delivery: (Riffer::Messages::FilePart) -> Symbol
+  # : (Riffer::Messages::User::FilePart) -> Symbol
+  def file_delivery: (Riffer::Messages::User::FilePart) -> Symbol
 
   private
 
@@ -49,14 +47,10 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
   # : (Hash[Symbol, untyped]) -> Riffer::Providers::FinishReason?
   def extract_finish_reason: (Hash[Symbol, untyped]) -> Riffer::Providers::FinishReason?
 
-  # Gemini reports STOP even when the candidate carries functionCall parts,
-  # so tool-call presence overrides the raw value.
   # --
   # : (String?, tool_calls: bool) -> Riffer::Providers::FinishReason?
   def build_finish_reason: (String?, tool_calls: bool) -> Riffer::Providers::FinishReason?
 
-  # Gemini reports thinking tokens outside +candidatesTokenCount+;
-  # TokenUsage's output includes them.
   # --
   # : (Hash[Symbol, untyped]) -> Riffer::Providers::TokenUsage
   def build_token_usage: (Hash[Symbol, untyped]) -> Riffer::Providers::TokenUsage
@@ -74,8 +68,8 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
   def convert_assistant_to_gemini_format: (Riffer::Messages::Assistant) -> Hash[Symbol, untyped]
 
   # --
-  # : (Riffer::Messages::FilePart) -> Hash[Symbol, untyped]
-  def convert_file_part_to_gemini_format: (Riffer::Messages::FilePart) -> Hash[Symbol, untyped]
+  # : (Riffer::Messages::User::FilePart) -> Hash[Symbol, untyped]
+  def convert_file_part_to_gemini_format: (Riffer::Messages::User::FilePart) -> Hash[Symbol, untyped]
 
   # --
   # : (singleton(Riffer::Tool)) -> Hash[Symbol, untyped]

data/sig/generated/riffer/providers/mock.rbs

@@ -1,6 +1,5 @@
 # Generated from lib/riffer/providers/mock.rb with RBS::Inline
 
-# Mock provider for mocking LLM responses in tests; no external gems required.
 class Riffer::Providers::Mock < Riffer::Providers::Base
   @stubbed_responses: Array[Hash[Symbol, untyped]]
 
@@ -8,48 +7,24 @@ class Riffer::Providers::Mock < Riffer::Providers::Base
 
   @responses: Array[Hash[Symbol, untyped]]
 
-  # Returns the skill adapter for the mock model — XML when the model name
-  # contains +claude+ (mirroring a real Claude provider), else Markdown.
   # --
   # : (?String?) -> singleton(Riffer::Skills::Adapter)
   def self.skills_adapter: (?String?) -> singleton(Riffer::Skills::Adapter)
 
-  # The GenAI semconv well-known provider name.
   # --
   # : () -> String
   def self.semconv_provider_name: () -> String
 
-  # Array of recorded method calls for assertions.
   attr_reader calls: Array[Hash[Symbol, untyped]]
 
-  # +responses:+ pre-configures canned responses (same shape as
-  # +#stub_response+) for standalone use; agent tests queue responses on
-  # <tt>agent.provider</tt> via +#stub_response+ instead.
-  #
-  #   Riffer::Providers::Mock.new(responses: [
-  #     {content: "", tool_calls: [{name: "tool_a", arguments: "{}"}]},
-  #     {content: "Final answer"}
-  #   ])
-  #
   # --
   # : (?responses: Array[Hash[Symbol, untyped]]) -> void
   def initialize: (?responses: Array[Hash[Symbol, untyped]]) -> void
 
-  # Stubs the next response; call repeatedly to queue several. +finish_reason+
-  # defaults to +:tool_calls+ when tool calls are present, else +:stop+.
-  #
-  #   provider.stub_response("Hello")
-  #   provider.stub_response("", tool_calls: [{name: "my_tool", arguments: '{"key":"value"}'}])
-  #   provider.stub_response("Final response",
-  #                          token_usage: Riffer::Providers::TokenUsage.new(input_tokens: 10, output_tokens: 5))
-  #   provider.stub_response("Truncated...", finish_reason: :length)
-  #
   # --
-  # : (String, ?tool_calls: Array[Hash[Symbol, untyped]], ?token_usage: Riffer::Providers::TokenUsage?, ?finish_reason: Symbol?) -> void
-  def stub_response: (String, ?tool_calls: Array[Hash[Symbol, untyped]], ?token_usage: Riffer::Providers::TokenUsage?, ?finish_reason: Symbol?) -> void
+  # : (String, ?tool_calls: Array[Hash[Symbol, untyped]], ?token_usage: Riffer::Providers::TokenUsage?, ?finish_reason: Symbol?, ?reasoning: Array[Hash[Symbol, untyped] | Riffer::Messages::Assistant::ReasoningPart]) -> void
+  def stub_response: (String, ?tool_calls: Array[Hash[Symbol, untyped]], ?token_usage: Riffer::Providers::TokenUsage?, ?finish_reason: Symbol?, ?reasoning: Array[Hash[Symbol, untyped] | Riffer::Messages::Assistant::ReasoningPart]) -> void
 
-  # Clears all stubbed responses.
-  #
   # --
   # : () -> void
   def clear_stubs: () -> void
@@ -76,6 +51,10 @@ class Riffer::Providers::Mock < Riffer::Providers::Base
   # : (untyped) -> Riffer::Providers::FinishReason?
   def extract_finish_reason: (untyped) -> Riffer::Providers::FinishReason?
 
+  # --
+  # : (untyped) -> Array[Riffer::Messages::Assistant::ReasoningPart]
+  def extract_reasoning: (untyped) -> Array[Riffer::Messages::Assistant::ReasoningPart]
+
   # --
   # : (untyped) -> String
   def extract_content: (untyped) -> String

data/sig/generated/riffer/providers/open_ai.rbs

@@ -1,15 +1,12 @@
 # Generated from lib/riffer/providers/open_ai.rb with RBS::Inline
 
-# OpenAI provider for GPT models. Requires the +openai+ gem.
 class Riffer::Providers::OpenAI < Riffer::Providers::Base
   WEB_SEARCH_TOOL_TYPE: String
 
-  # The Responses API has no finish_reason field. The response +status+ is
-  # the primary signal; an +incomplete+ status is only meaningful together
-  # with <tt>incomplete_details.reason</tt>, so that branch nests one level.
+  # The Responses API has no finish_reason field, and an +incomplete+ status is only meaningful
+  # together with <tt>incomplete_details.reason</tt>.
   FINISH_REASONS: Hash[String, Symbol | Hash[String, Symbol]]
 
-  # The GenAI semconv well-known provider name.
   # --
   # : () -> String
   def self.semconv_provider_name: () -> String
@@ -19,8 +16,8 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
   def initialize: () -> void
 
   # --
-  # : (Riffer::Messages::FilePart) -> Symbol
-  def file_delivery: (Riffer::Messages::FilePart) -> Symbol
+  # : (Riffer::Messages::User::FilePart) -> Symbol
+  def file_delivery: (Riffer::Messages::User::FilePart) -> Symbol
 
   private
 
@@ -28,9 +25,6 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
   # : () -> untyped
   def global_client: () -> untyped
 
-  # Compacted so an unset value stays absent: the SDK reads +OPENAI_API_KEY+ /
-  # +OPENAI_BASE_URL+ only for a missing argument, and an explicit nil would
-  # suppress that fallback.
   # --
   # : () -> untyped
   def build_client: () -> untyped
@@ -59,7 +53,6 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
   # : (untyped) -> Riffer::Providers::FinishReason?
   def build_finish_reason: (untyped) -> Riffer::Providers::FinishReason?
 
-  # The nested field that names the cause behind an ambiguous status.
   # --
   # : (untyped, String) -> String?
   def finish_detail: (untyped, String) -> String?
@@ -125,8 +118,8 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
   def convert_assistant_to_openai_format: (Riffer::Messages::Assistant) -> (Hash[Symbol, untyped] | Array[Hash[Symbol, untyped]])
 
   # --
-  # : (Riffer::Messages::FilePart) -> Hash[Symbol, untyped]
-  def convert_file_part_to_openai_format: (Riffer::Messages::FilePart) -> Hash[Symbol, untyped]
+  # : (Riffer::Messages::User::FilePart) -> Hash[Symbol, untyped]
+  def convert_file_part_to_openai_format: (Riffer::Messages::User::FilePart) -> Hash[Symbol, untyped]
 
   # --
   # : (singleton(Riffer::Tool)) -> Hash[Symbol, untyped]

data/sig/generated/riffer/providers/open_router.rbs

@@ -1,15 +1,17 @@
 # Generated from lib/riffer/providers/open_router.rb with RBS::Inline
 
-# OpenRouter provider (https://openrouter.ai). Requires the +openai+ gem —
-# OpenRouter exposes an OpenAI-compatible endpoint, so this reuses the OpenAI
-# SDK with a +base_url+ override. +api_key+ resolves from config, then
-# +OPENROUTER_API_KEY+.
 class Riffer::Providers::OpenRouter < Riffer::Providers::Base
   BASE_URL: String
 
   FINISH_REASONS: Hash[String, Symbol]
 
-  # The GenAI semconv well-known provider name.
+  REASONING_TYPES: Hash[String, Symbol]
+
+  # The +reasoning_details+ formats OpenRouter documents. Only parts tagged with
+  # one of them are replayed, so parts from other adapters, or with no format,
+  # never reach the request.
+  REASONING_FORMATS: Array[String]
+
   # --
   # : () -> String
   def self.semconv_provider_name: () -> String
@@ -19,8 +21,8 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
   def initialize: () -> void
 
   # --
-  # : (Riffer::Messages::FilePart) -> Symbol
-  def file_delivery: (Riffer::Messages::FilePart) -> Symbol
+  # : (Riffer::Messages::User::FilePart) -> Symbol
+  def file_delivery: (Riffer::Messages::User::FilePart) -> Symbol
 
   private
 
@@ -28,11 +30,6 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
   # : () -> untyped
   def global_client: () -> untyped
 
-  # Deliberately not compacted: this borrows the OpenAI SDK to talk to a
-  # different vendor, so omitting an unset +api_key+ would let the SDK fall
-  # back to +OPENAI_API_KEY+ and send an OpenAI credential to OpenRouter.
-  # Passing nil raises in the SDK instead. +OPENROUTER_API_KEY+ is read here
-  # rather than left to the SDK for the same reason.
   # --
   # : () -> untyped
   def build_client: () -> untyped
@@ -57,14 +54,10 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
   # : (untyped) -> Riffer::Providers::FinishReason?
   def extract_finish_reason: (untyped) -> Riffer::Providers::FinishReason?
 
-  # +native+ is the upstream model's own finish reason, which OpenRouter
-  # reports alongside its normalized one; it wins as +raw+ when present.
   # --
   # : (untyped, ?native: untyped) -> Riffer::Providers::FinishReason?
   def build_finish_reason: (untyped, ?native: untyped) -> Riffer::Providers::FinishReason?
 
-  # +native_finish_reason+ is outside the OpenAI schema, so it is only
-  # reachable through the SDK model's raw data hash.
   # --
   # : (untyped) -> untyped
   def native_finish_reason: (untyped) -> untyped
@@ -77,6 +70,20 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
   # : (untyped) -> Array[Riffer::Messages::Assistant::ToolCall]
   def extract_tool_calls: (untyped) -> Array[Riffer::Messages::Assistant::ToolCall]
 
+  # --
+  # : (untyped) -> Array[Riffer::Messages::Assistant::ReasoningPart]
+  def extract_reasoning: (untyped) -> Array[Riffer::Messages::Assistant::ReasoningPart]
+
+  # The openai gem's typed models strip fields outside OpenAI's spec, so
+  # +reasoning_details+ is only reachable through the model's raw data hash.
+  # --
+  # : (untyped) -> Array[Hash[Symbol, untyped]]?
+  def reasoning_details: (untyped) -> Array[Hash[Symbol, untyped]]?
+
+  # --
+  # : (Hash[Symbol, untyped]) -> Riffer::Messages::Assistant::ReasoningPart?
+  def build_reasoning_part: (Hash[Symbol, untyped]) -> Riffer::Messages::Assistant::ReasoningPart?
+
   # --
   # : (Hash[Symbol, untyped], Riffer::Providers::_EventSink) -> void
   def execute_stream: (Hash[Symbol, untyped], Riffer::Providers::_EventSink) -> void
@@ -93,6 +100,14 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
   # : (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
   def handle_reasoning_delta: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
 
+  # OpenRouter streams one reasoning block as many fragments sharing an
+  # +index+: prose and payload arrive in pieces to concatenate, while the
+  # signature, id, and format arrive once, often on the last fragment. Keying
+  # on +type+ as well keeps index-less fragments of different kinds apart.
+  # --
+  # : (Hash[untyped, Hash[Symbol, untyped]], Hash[Symbol, untyped]) -> void
+  def accumulate_reasoning_detail: (Hash[untyped, Hash[Symbol, untyped]], Hash[Symbol, untyped]) -> void
+
   # --
   # : (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
   def handle_tool_call_deltas: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
@@ -114,8 +129,12 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
   def convert_assistant_to_chat_completions_format: (Riffer::Messages::Assistant) -> Hash[Symbol, untyped]
 
   # --
-  # : (Riffer::Messages::FilePart) -> Hash[Symbol, untyped]
-  def convert_file_part_to_chat_completions_format: (Riffer::Messages::FilePart) -> Hash[Symbol, untyped]
+  # : (Riffer::Messages::Assistant::ReasoningPart) -> Hash[Symbol, untyped]
+  def convert_reasoning_part_to_detail: (Riffer::Messages::Assistant::ReasoningPart) -> Hash[Symbol, untyped]
+
+  # --
+  # : (Riffer::Messages::User::FilePart) -> Hash[Symbol, untyped]
+  def convert_file_part_to_chat_completions_format: (Riffer::Messages::User::FilePart) -> Hash[Symbol, untyped]
 
   # --
   # : (singleton(Riffer::Tool)) -> Hash[Symbol, untyped]

data/sig/generated/riffer/providers/repository.rbs

@@ -1,8 +1,5 @@
 # Generated from lib/riffer/providers/repository.rb with RBS::Inline
 
-# Resolves provider classes by identifier, combining the built-in REPO with
-# consumer registrations added through +register+. Registration is not
-# synchronized — register during boot, before concurrent generation begins.
 module Riffer::Providers::Repository
   @registrations: Hash[Symbol, ^() -> singleton(Riffer::Providers::Base)]
 
@@ -10,29 +7,20 @@ module Riffer::Providers::Repository
 
   REPO: Hash[Symbol, ^() -> singleton(Riffer::Providers::Base)]
 
-  # Registers a custom provider under +identifier+, resolved lazily by the block.
-  # Takes precedence over a built-in sharing the identifier.
-  #
-  #   Riffer::Providers::Repository.register(:jane) { MyApp::JaneProvider }
-  #
+  # Not synchronized — register during boot, before concurrent generation
+  # begins.
   # --
   # : ((String | Symbol)) { () -> singleton(Riffer::Providers::Base) } -> void
   def register: (String | Symbol) { () -> singleton(Riffer::Providers::Base) } -> void
 
-  # Removes a custom registration by identifier, leaving any built-in of the
-  # same name intact.
   # --
   # : ((String | Symbol)) -> void
   def unregister: (String | Symbol) -> void
 
-  # Finds a provider class by identifier, preferring a custom registration over
-  # a built-in of the same name.
-  #
   # --
   # : ((String | Symbol)) -> singleton(Riffer::Providers::Base)?
   def find: (String | Symbol) -> singleton(Riffer::Providers::Base)?
 
-  # Returns the registry identifier for a provider class, or nil when unregistered.
   # --
   # : (singleton(Riffer::Providers::Base)) -> Symbol?
   def key_for: (singleton(Riffer::Providers::Base)) -> Symbol?

data/sig/generated/riffer/providers/token_usage.rbs

@@ -1,40 +1,37 @@
 # Generated from lib/riffer/providers/token_usage.rb with RBS::Inline
 
-# Normalized token usage for an LLM API call. Buckets carry the same
-# meaning for every provider.
 class Riffer::Providers::TokenUsage
-  # Number of tokens entering the context window, including cache reads and writes.
+  # --
+  # : ((Hash[Symbol, untyped] | Riffer::Providers::TokenUsage)) -> Riffer::Providers::TokenUsage
+  def self.from_hash: (Hash[Symbol, untyped] | Riffer::Providers::TokenUsage) -> Riffer::Providers::TokenUsage
+
+  # Normalized across providers: includes cache reads and writes.
   attr_reader input_tokens: Integer
 
-  # Number of tokens generated by the model, including reasoning/thinking tokens.
+  # Includes reasoning/thinking tokens.
   attr_reader output_tokens: Integer
 
-  # Subset of +input_tokens+ written to the provider's prompt cache, when the provider reports it.
+  # Subset of +input_tokens+.
   attr_reader cache_write_tokens: Integer?
 
-  # Subset of +input_tokens+ read from the provider's prompt cache, when the provider reports it.
+  # Subset of +input_tokens+.
   attr_reader cache_read_tokens: Integer?
 
-  # Cost of the call, set when the model is priced. For observability, not billing.
+  # For observability, not billing.
   attr_reader cost: Float?
 
   # --
   # : (input_tokens: Integer, output_tokens: Integer, ?cache_write_tokens: Integer?, ?cache_read_tokens: Integer?, ?cost: Float?) -> void
   def initialize: (input_tokens: Integer, output_tokens: Integer, ?cache_write_tokens: Integer?, ?cache_read_tokens: Integer?, ?cost: Float?) -> void
 
-  # Returns the total number of tokens (input + output).
-  #
   # --
   # : () -> Integer
   def total_tokens: () -> Integer
 
-  # Combines two TokenUsage objects for cumulative tracking.
-  #
   # --
   # : (Riffer::Providers::TokenUsage) -> Riffer::Providers::TokenUsage
   def +: (Riffer::Providers::TokenUsage) -> Riffer::Providers::TokenUsage
 
-  # Converts the token usage to a hash; cache tokens and cost are omitted when nil.
   # --
   # : () -> Hash[Symbol, (Integer | Float)]
   def to_h: () -> Hash[Symbol, Integer | Float]

data/sig/generated/riffer/registrable.rbs

@@ -1,68 +1,29 @@
 # Generated from lib/riffer/registrable.rb with RBS::Inline
 
-# Registry of a class's direct subclasses, keyed by identifier. Extend it
-# onto a base class to look up subclasses in constant time via +find+ and +all+.
-# Subclasses join implicitly by inheriting; +register+ adds one explicitly, for
-# ephemeral classes a test suite builds and tears down. Registration is not
-# synchronized — register during boot or from a single-threaded test, before
-# concurrent lookups begin.
-#
-#   class Riffer::Tool
-#     extend Riffer::Registrable
-#   end
-#
-#   Riffer::Tool.find("weather_tool") # => WeatherTool
-#
 # @rbs module-self Class
 module Riffer::Registrable : Class
   @identifier_registry: Hash[String, Class]?
 
   @explicit_registrations: Hash[String, Class]?
 
-  # Finds a registered subclass by identifier, or +nil+ when none matches.
-  # Implicit registration covers only *named direct* subclasses: grandchildren
-  # are not visible to a grandparent's +find+ (call +find+ on their direct
-  # parent instead), anonymous classes are never registered implicitly, and a
-  # subclass whose name no longer resolves back to it is dropped at the next
-  # registry rebuild. Duplicate identifiers raise
-  # Riffer::DuplicateIdentifierError at first lookup.
-  #
   # --
   # : (String | Symbol) -> Class?
   def find: (String | Symbol) -> Class?
 
-  # Returns all registered subclasses, implicit and explicit. Carries the same
-  # registration rules as +find+.
-  #
   # --
   # : () -> Array[Class]
   def all: () -> Array[Class]
 
-  # Registers a direct subclass under its +identifier+, whether or not it is
-  # named — unlike implicit registration, it survives a name that no longer
-  # resolves, so an ephemeral class stays findable until +unregister+. Prefer
-  # Riffer::Testing for ordinary test setup, which stubs and cleans up
-  # automatically.
-  #
-  # Raises Riffer::ArgumentError when the identifier is blank or the class is
-  # not a direct subclass, and Riffer::DuplicateIdentifierError when the
-  # identifier is already taken — including by this same class.
-  #
   # --
   # : (Class) -> void
   def register: (Class) -> void
 
-  # Removes an explicit registration of +klass+, leaving implicit registrations
-  # untouched.
   # --
   # : (Class) -> void
   def unregister: (Class) -> void
 
   private
 
-  # Ruby invokes +inherited+ with +self+ bound to the direct superclass — the
-  # only registry the new subclass joins — so busting self's memo is exactly
-  # sufficient.
   # --
   # : (Class) -> void
   def inherited: (Class) -> void
@@ -79,12 +40,6 @@ module Riffer::Registrable : Class
   # : () -> Hash[String, Class]
   def build_identifier_registry: () -> Hash[String, Class]
 
-  # Class#subclasses keeps returning superseded generations of a reloaded or
-  # stubbed class, so a subclass counts only while its own name still resolves
-  # back to it. An anonymous class has no name to resolve and is skipped even
-  # with an explicit identifier — the MCP factory and serializer shells
-  # synthesize short-lived anonymous classes whose registration would flake
-  # with GC timing.
   # --
   # : (Class) -> bool
   def live?: (Class) -> bool

data/sig/generated/riffer/runner/fibers.rbs

@@ -1,11 +1,5 @@
 # Generated from lib/riffer/runner/fibers.rb with RBS::Inline
 
-# Processes items concurrently using fibers via the +async+ gem.
-# +max_concurrency+ caps simultaneous fibers via an <tt>Async::Semaphore</tt>.
-# If multiple fibers raise, only the first exception is re-raised after all
-# finish.
-# Joins the current reactor task when one is already running, and otherwise
-# starts its own.
 class Riffer::Runner::Fibers < Riffer::Runner
   @max_concurrency: Integer?
 

data/sig/generated/riffer/runner/sequential.rbs

@@ -1,6 +1,5 @@
 # Generated from lib/riffer/runner/sequential.rb with RBS::Inline
 
-# Processes items sequentially in the current thread — the default runner.
 class Riffer::Runner::Sequential < Riffer::Runner
   # --
   # : (Array[untyped], context: Riffer::Agent::Context?) { (untyped) -> untyped } -> Array[untyped]