riffer 0.47.1 → 0.48.0

data/sig/generated/riffer/files/resolver.rbs

@@ -20,17 +20,17 @@ class Riffer::Files::Resolver
   # : (Riffer::Messages::User) -> void
   def check_file_count!: (Riffer::Messages::User) -> void
 
-  # : (Riffer::Messages::FilePart) -> void
-  def resolve_file!: (Riffer::Messages::FilePart) -> void
+  # : (Riffer::Messages::User::FilePart) -> void
+  def resolve_file!: (Riffer::Messages::User::FilePart) -> void
 
-  # : (Riffer::Messages::FilePart) -> void
-  def verify_inline!: (Riffer::Messages::FilePart) -> void
+  # : (Riffer::Messages::User::FilePart) -> void
+  def verify_inline!: (Riffer::Messages::User::FilePart) -> void
 
   # +cache:+ is false for a :url-delivery provider verifying a sha256 — the
   # request still sends the URL, never the downloaded bytes, so caching them
   # would hold memory nothing reads and let later turns skip re-verifying.
-  # : (Riffer::Messages::FilePart, cache: (false | Symbol)) -> void
-  def download!: (Riffer::Messages::FilePart, cache: false | Symbol) -> void
+  # : (Riffer::Messages::User::FilePart, cache: (false | Symbol)) -> void
+  def download!: (Riffer::Messages::User::FilePart, cache: false | Symbol) -> void
 
   def verify_bytes!: (untyped bytes, untyped sha256) -> untyped
 end

data/sig/generated/riffer/helpers/deep_dup.rbs

@@ -0,0 +1,21 @@
+# Generated from lib/riffer/helpers/deep_dup.rb with RBS::Inline
+
+# Copying for the nested Hashes and Arrays a configuration object holds.
+module Riffer::Helpers::DeepDup
+  # Returns +value+ with every Hash and Array rebuilt, so a copy shares no
+  # collection with its source.
+  #
+  # Anything else is returned as-is, which a Class or a Proc needs: +Class#dup+
+  # answers a new anonymous class. One source collection maps to one copy, so
+  # references shared within +value+ stay shared in the result — an +:around+
+  # guardrail registered under two phases is still one registration afterwards.
+  # --
+  # : (untyped) -> untyped
+  def call: (untyped) -> untyped
+
+  private
+
+  # --
+  # : (untyped, Hash[untyped, untyped]) -> untyped
+  def rebuild: (untyped, Hash[untyped, untyped]) -> untyped
+end

data/sig/generated/riffer/messages/assistant/reasoning_part.rbs

@@ -0,0 +1,58 @@
+# Generated from lib/riffer/messages/assistant/reasoning_part.rb with RBS::Inline
+
+# Represents one block of model reasoning attached to an assistant message.
+# riffer stores and replays a part verbatim rather than interpreting it, so a
+# provider that requires its own thinking blocks back gets them unchanged.
+class Riffer::Messages::Assistant::ReasoningPart
+  TYPES: Array[Symbol]
+
+  # What the part carries: readable reasoning (+:text+), a provider-condensed
+  # digest (+:summary+), or an opaque payload (+:encrypted+).
+  attr_reader type: Symbol
+
+  # The reasoning prose, for +:text+ and +:summary+ parts.
+  attr_reader text: String?
+
+  # The opaque payload, for +:encrypted+ parts.
+  attr_reader data: String?
+
+  # The provider's signature over the part, when it issues one.
+  attr_reader signature: String?
+
+  # The provider's identifier for the part, when it issues one.
+  attr_reader id: String?
+
+  # The wire format of the part, owned by the provider adapter that produced it
+  # (e.g. <tt>"anthropic-claude-v1"</tt>). Adapters replay only the formats they
+  # recognize, so it is never validated here.
+  attr_reader format: String?
+
+  # Builds a ReasoningPart from a hash, or returns +part+ unchanged when it is
+  # already a ReasoningPart.
+  # --
+  # : ((Hash[Symbol, untyped] | Riffer::Messages::Assistant::ReasoningPart)) -> Riffer::Messages::Assistant::ReasoningPart
+  def self.from_hash: (Hash[Symbol, untyped] | Riffer::Messages::Assistant::ReasoningPart) -> Riffer::Messages::Assistant::ReasoningPart
+
+  # Raises Riffer::ArgumentError on a +type+ outside TYPES.
+  # --
+  # : (type: Symbol, ?text: String?, ?data: String?, ?signature: String?, ?id: String?, ?format: String?) -> void
+  def initialize: (type: Symbol, ?text: String?, ?data: String?, ?signature: String?, ?id: String?, ?format: String?) -> void
+
+  # Serializes the part to a hash, omitting the fields it doesn't carry.
+  #
+  # --
+  # : () -> Hash[Symbol, untyped]
+  def to_h: () -> Hash[Symbol, untyped]
+
+  # --
+  # : (untyped) -> bool
+  def ==: (untyped) -> bool
+
+  # --
+  # : (untyped) -> bool
+  def eql?: (untyped) -> bool
+
+  # --
+  # : () -> Integer
+  def hash: () -> Integer
+end

data/sig/generated/riffer/messages/assistant/tool_call.rbs

@@ -0,0 +1,42 @@
+# Generated from lib/riffer/messages/assistant/tool_call.rb with RBS::Inline
+
+# Represents one tool invocation the model requested on an assistant message.
+class Riffer::Messages::Assistant::ToolCall
+  # The provider's identifier for the call, echoed back on the tool result.
+  attr_reader call_id: String
+
+  # The name of the tool to invoke.
+  attr_reader name: String
+
+  # The JSON-encoded arguments, exactly as the provider emitted them.
+  attr_reader arguments: String
+
+  # Builds a ToolCall from a hash, or returns +call+ unchanged when it is
+  # already a ToolCall. Raises Riffer::ArgumentError when the hash is missing
+  # a field.
+  # --
+  # : ((Hash[Symbol, untyped] | Riffer::Messages::Assistant::ToolCall)) -> Riffer::Messages::Assistant::ToolCall
+  def self.from_hash: (Hash[Symbol, untyped] | Riffer::Messages::Assistant::ToolCall) -> Riffer::Messages::Assistant::ToolCall
+
+  # --
+  # : (call_id: String, name: String, arguments: String) -> void
+  def initialize: (call_id: String, name: String, arguments: String) -> void
+
+  # Serializes the call to a hash.
+  #
+  # --
+  # : () -> Hash[Symbol, untyped]
+  def to_h: () -> Hash[Symbol, untyped]
+
+  # --
+  # : (untyped) -> bool
+  def ==: (untyped) -> bool
+
+  # --
+  # : (untyped) -> bool
+  def eql?: (untyped) -> bool
+
+  # --
+  # : () -> Integer
+  def hash: () -> Integer
+end

data/sig/generated/riffer/messages/assistant.rbs

@@ -3,20 +3,23 @@
 # Represents an assistant (LLM) message in a conversation; may include tool
 # calls when the LLM requests tool execution.
 class Riffer::Messages::Assistant < Riffer::Messages::Base
-  class ToolCall < Struct[untyped]
-    attr_accessor call_id(): untyped
+  # The reasoning part types +reasoning_text+ reads; the rest carry no prose.
+  REASONING_TEXT_TYPES: Array[Symbol]
 
-    attr_accessor name(): untyped
-
-    attr_accessor arguments(): untyped
-
-    def self.new: (?untyped call_id, ?untyped name, ?untyped arguments) -> instance
-                | (?call_id: untyped, ?name: untyped, ?arguments: untyped) -> instance
-  end
+  # Builds an Assistant message from a hash, or returns +msg+ unchanged when it
+  # is already an Assistant message. Raises Riffer::ArgumentError on an invalid
+  # tool call, reasoning part, or +finish_reason+.
+  # --
+  # : ((Hash[Symbol, untyped] | Riffer::Messages::Assistant)) -> Riffer::Messages::Assistant
+  def self.from_hash: (Hash[Symbol, untyped] | Riffer::Messages::Assistant) -> Riffer::Messages::Assistant
 
   # Array of tool calls requested by the assistant.
   attr_reader tool_calls: Array[Riffer::Messages::Assistant::ToolCall]
 
+  # The model's reasoning blocks for this response, in the order the provider
+  # emitted them.
+  attr_reader reasoning: Array[Riffer::Messages::Assistant::ReasoningPart]
+
   # Token usage data for this response.
   attr_reader token_usage: Riffer::Providers::TokenUsage?
 
@@ -38,12 +41,13 @@ class Riffer::Messages::Assistant < Riffer::Messages::Base
   #    String,
   #    ?id: String?,
   #    ?tool_calls: Array[Riffer::Messages::Assistant::ToolCall],
+  #    ?reasoning: Array[Riffer::Messages::Assistant::ReasoningPart],
   #    ?token_usage: Riffer::Providers::TokenUsage?,
   #    ?structured_output: Hash[Symbol, untyped]?,
   #    ?finish_reason: Symbol?,
   #    ?finish_reason_raw: String?
   #  ) -> void
-  def initialize: (String, ?id: String?, ?tool_calls: Array[Riffer::Messages::Assistant::ToolCall], ?token_usage: Riffer::Providers::TokenUsage?, ?structured_output: Hash[Symbol, untyped]?, ?finish_reason: Symbol?, ?finish_reason_raw: String?) -> void
+  def initialize: (String, ?id: String?, ?tool_calls: Array[Riffer::Messages::Assistant::ToolCall], ?reasoning: Array[Riffer::Messages::Assistant::ReasoningPart], ?token_usage: Riffer::Providers::TokenUsage?, ?structured_output: Hash[Symbol, untyped]?, ?finish_reason: Symbol?, ?finish_reason_raw: String?) -> void
 
   # --
   # : () -> Symbol
@@ -57,6 +61,16 @@ class Riffer::Messages::Assistant < Riffer::Messages::Base
   # : () -> bool
   def has_tool_calls?: () -> bool
 
+  # --
+  # : () -> bool
+  def reasoning?: () -> bool
+
+  # The readable reasoning across this message's +:text+ and +:summary+ parts,
+  # joined by blank lines, or nil when it carries none.
+  # --
+  # : () -> String?
+  def reasoning_text: () -> String?
+
   # --
   # : (Riffer::Messages::Assistant) -> Riffer::Messages::Assistant
   def +: (Riffer::Messages::Assistant) -> Riffer::Messages::Assistant

data/sig/generated/riffer/messages/system.rbs

@@ -2,6 +2,12 @@
 
 # Represents a system message (instructions) in a conversation.
 class Riffer::Messages::System < Riffer::Messages::Base
+  # Builds a System message from a hash, or returns +msg+ unchanged when it is
+  # already a System message.
+  # --
+  # : ((Hash[Symbol, untyped] | Riffer::Messages::System)) -> Riffer::Messages::System
+  def self.from_hash: (Hash[Symbol, untyped] | Riffer::Messages::System) -> Riffer::Messages::System
+
   # --
   # : () -> Symbol
   def role: () -> Symbol

data/sig/generated/riffer/messages/tool.rbs

@@ -2,6 +2,12 @@
 
 # Represents a tool execution result in a conversation.
 class Riffer::Messages::Tool < Riffer::Messages::Base
+  # Builds a Tool message from a hash, or returns +msg+ unchanged when it is
+  # already a Tool message.
+  # --
+  # : ((Hash[Symbol, untyped] | Riffer::Messages::Tool)) -> Riffer::Messages::Tool
+  def self.from_hash: (Hash[Symbol, untyped] | Riffer::Messages::Tool) -> Riffer::Messages::Tool
+
   # The ID of the tool call this result responds to.
   attr_reader tool_call_id: String
 

data/sig/generated/riffer/messages/{file_part.rbs → user/file_part.rbs}

@@ -1,8 +1,8 @@
-# Generated from lib/riffer/messages/file_part.rb with RBS::Inline
+# Generated from lib/riffer/messages/user/file_part.rb with RBS::Inline
 
 # Represents a file attachment (image or document) — from a URL (+from_url+) or
 # raw base64 data (+new+).
-class Riffer::Messages::FilePart
+class Riffer::Messages::User::FilePart
   @data_bytes: String?
 
   @downloaded_data: String?
@@ -35,15 +35,20 @@ class Riffer::Messages::FilePart
   # Creates a FilePart from a URL, detecting +media_type+ from the path
   # extension when omitted. Raises Riffer::ArgumentError if it can't be detected.
   # --
-  # : (String, ?media_type: String?, ?filename: String?, ?sha256: String?) -> Riffer::Messages::FilePart
-  def self.from_url: (String, ?media_type: String?, ?filename: String?, ?sha256: String?) -> Riffer::Messages::FilePart
+  # : (String, ?media_type: String?, ?filename: String?, ?sha256: String?) -> Riffer::Messages::User::FilePart
+  def self.from_url: (String, ?media_type: String?, ?filename: String?, ?sha256: String?) -> Riffer::Messages::User::FilePart
 
   # Builds a FilePart from a +{url:, media_type:}+ or +{data:, media_type:}+ hash,
   # or returns +file+ unchanged when it is already a FilePart. Raises
   # Riffer::ArgumentError on an invalid hash.
   # --
-  # : ((Hash[Symbol, untyped] | Riffer::Messages::FilePart)) -> Riffer::Messages::FilePart
-  def self.from_hash: (Hash[Symbol, untyped] | Riffer::Messages::FilePart) -> Riffer::Messages::FilePart
+  # : ((Hash[Symbol, untyped] | Riffer::Messages::User::FilePart)) -> Riffer::Messages::User::FilePart
+  def self.from_hash: (Hash[Symbol, untyped] | Riffer::Messages::User::FilePart) -> Riffer::Messages::User::FilePart
+
+  # Raises Riffer::ArgumentError when the URL's extension isn't a known media type.
+  # --
+  # : (String) -> String
+  def self.detect_media_type: (String) -> String
 
   # The base64-encoded contents - caller-supplied, or filled in by the file
   # resolver after a download.  Nil for a URL source riffer hasn't fetched.

data/sig/generated/riffer/messages/user.rbs

@@ -2,12 +2,18 @@
 
 # Represents a user message in a conversation.
 class Riffer::Messages::User < Riffer::Messages::Base
+  # Builds a User message from a hash, or returns +msg+ unchanged when it is
+  # already a User message. Raises Riffer::ArgumentError on an invalid file.
+  # --
+  # : ((Hash[Symbol, untyped] | Riffer::Messages::User)) -> Riffer::Messages::User
+  def self.from_hash: (Hash[Symbol, untyped] | Riffer::Messages::User) -> Riffer::Messages::User
+
   # File attachments for this message.
-  attr_reader files: Array[Riffer::Messages::FilePart]
+  attr_reader files: Array[Riffer::Messages::User::FilePart]
 
   # --
-  # : (String, ?id: String?, ?files: Array[Riffer::Messages::FilePart]) -> void
-  def initialize: (String, ?id: String?, ?files: Array[Riffer::Messages::FilePart]) -> void
+  # : (String, ?id: String?, ?files: Array[Riffer::Messages::User::FilePart]) -> void
+  def initialize: (String, ?id: String?, ?files: Array[Riffer::Messages::User::FilePart]) -> void
 
   # --
   # : () -> Symbol

data/sig/generated/riffer/params/param.rbs

@@ -84,6 +84,13 @@ class Riffer::Params::Param
 
   private
 
+  # +dup+ would leave the copy sharing this one's nested Params, enum list and
+  # default, so defining a parameter or editing either value on one would reach
+  # the other.
+  # --
+  # : (Riffer::Params::Param) -> void
+  def initialize_copy: (Riffer::Params::Param) -> void
+
   # --
   # : () -> void
   def validate_strict_shape!: () -> void

data/sig/generated/riffer/params.rbs

@@ -62,6 +62,12 @@ class Riffer::Params
 
   private
 
+  # +dup+ would leave the copy sharing this one's parameters, so a caller
+  # defining a parameter on either would reach the other.
+  # --
+  # : (Riffer::Params) -> void
+  def initialize_copy: (Riffer::Params) -> void
+
   # --
   # : (Module, Module?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> Riffer::Params?
   def build_nested: (Module, Module?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> Riffer::Params?

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

@@ -25,8 +25,8 @@ class Riffer::Providers::AmazonBedrock < 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
 
@@ -91,10 +91,19 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
   # : (Hash[Symbol, untyped], Riffer::Providers::_EventSink) -> void
   def execute_stream: (Hash[Symbol, untyped], Riffer::Providers::_EventSink) -> void
 
+  # Re-raises an +Aws::Errors::EventError+ event with a message built from its
+  # error code and message. The SDK's own +#message+ is just the class name,
+  # so without this the failure would be unreadable.
+  # --
+  # : (untyped) -> void
+  def raise_stream_event_error!: (untyped) -> void
+
   # Re-raises a Bedrock stream-exception event as the matching
   # +Aws::BedrockRuntime::Errors+ class. ConverseStream delivers API errors on
   # the same channel as content, so without this a mid-stream failure would
-  # silently end the stream with no content.
+  # silently end the stream with no content. Non-exception events that we do
+  # not consume (including the SDK's +:unknown_event+ struct) are ignored for
+  # forward compatibility.
   # --
   # : (untyped) -> void
   def raise_if_stream_exception!: (untyped) -> void
@@ -136,8 +145,8 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
   def append_tool_result: (Array[Hash[Symbol, untyped]], Riffer::Messages::Tool) -> void
 
   # --
-  # : (Riffer::Messages::FilePart) -> Hash[Symbol, untyped]
-  def convert_file_part_to_bedrock_format: (Riffer::Messages::FilePart) -> Hash[Symbol, untyped]
+  # : (Riffer::Messages::User::FilePart) -> Hash[Symbol, untyped]
+  def convert_file_part_to_bedrock_format: (Riffer::Messages::User::FilePart) -> Hash[Symbol, untyped]
 
   BEDROCK_FORMAT_MAP: Hash[String, String]
 

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

@@ -126,8 +126,8 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
   def convert_assistant_to_anthropic_format: (Riffer::Messages::Assistant) -> Hash[Symbol, untyped]
 
   # --
-  # : (Riffer::Messages::FilePart) -> Hash[Symbol, untyped]
-  def convert_file_part_to_anthropic_format: (Riffer::Messages::FilePart) -> Hash[Symbol, untyped]
+  # : (Riffer::Messages::User::FilePart) -> Hash[Symbol, untyped]
+  def convert_file_part_to_anthropic_format: (Riffer::Messages::User::FilePart) -> Hash[Symbol, untyped]
 
   # --
   # : (singleton(Riffer::Tool)) -> Hash[Symbol, untyped]

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

@@ -32,18 +32,18 @@ class Riffer::Providers::Base
   # 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
 
@@ -105,6 +105,12 @@ class Riffer::Providers::Base
   # : (untyped) -> Riffer::Providers::FinishReason?
   def extract_finish_reason: (untyped) -> Riffer::Providers::FinishReason?
 
+  # Defaults to no parts rather than raising — reasoning parts are optional, so
+  # providers that don't expose replayable reasoning stay valid.
+  # --
+  # : (untyped) -> Array[Riffer::Messages::Assistant::ReasoningPart]
+  def extract_reasoning: (untyped) -> Array[Riffer::Messages::Assistant::ReasoningPart]
+
   # --
   # : (untyped) -> String
   def extract_content: (untyped) -> String
@@ -150,6 +156,12 @@ 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
 
+  # Wraps reasoning text that an adapter cannot yet replay in a +:text+ part
+  # with no +format+, so it persists for display but is never sent back.
+  # --
+  # : (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 +171,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 +183,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/gemini.rbs

@@ -12,8 +12,8 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
   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
 
@@ -74,8 +74,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

@@ -43,10 +43,11 @@ class Riffer::Providers::Mock < Riffer::Providers::Base
   #   provider.stub_response("Final response",
   #                          token_usage: Riffer::Providers::TokenUsage.new(input_tokens: 10, output_tokens: 5))
   #   provider.stub_response("Truncated...", finish_reason: :length)
+  #   provider.stub_response("Answer", reasoning: [{type: :text, text: "Thinking...", format: "mock-v1"}])
   #
   # --
-  # : (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.
   #
@@ -76,6 +77,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

@@ -19,8 +19,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
 
@@ -125,8 +125,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

@@ -19,8 +19,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
 
@@ -114,8 +114,8 @@ 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::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

@@ -15,8 +15,6 @@ module Riffer::Providers::Repository
   #
   #   Riffer::Providers::Repository.register(:jane) { MyApp::JaneProvider }
   #
-  # Raises Riffer::ArgumentError when called without a block.
-  #
   # --
   # : ((String | Symbol)) { () -> singleton(Riffer::Providers::Base) } -> void
   def register: (String | Symbol) { () -> singleton(Riffer::Providers::Base) } -> void

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

@@ -3,6 +3,12 @@
 # Normalized token usage for an LLM API call. Buckets carry the same
 # meaning for every provider.
 class Riffer::Providers::TokenUsage
+  # Builds a TokenUsage from a hash, or returns +usage+ unchanged when it is
+  # already a TokenUsage.
+  # --
+  # : ((Hash[Symbol, untyped] | Riffer::Providers::TokenUsage)) -> Riffer::Providers::TokenUsage
+  def self.from_hash: (Hash[Symbol, untyped] | Riffer::Providers::TokenUsage) -> Riffer::Providers::TokenUsage
+
   # Number of tokens entering the context window, including cache reads and writes.
   attr_reader input_tokens: Integer
 

data/sig/generated/riffer/skills/config.rbs

@@ -45,4 +45,13 @@ class Riffer::Skills::Config
   # --
   # : (?singleton(Riffer::Tool)?) -> singleton(Riffer::Tool)?
   def activate_tool: (?singleton(Riffer::Tool)?) -> singleton(Riffer::Tool)?
+
+  private
+
+  # +dup+ would leave the copy sharing this one's activation list, so activating
+  # a skill on either would reach the other. DeepDup rebuilds the list and
+  # returns a Proc as-is, which has nothing to alias.
+  # --
+  # : (Riffer::Skills::Config) -> void
+  def initialize_copy: (Riffer::Skills::Config) -> void
 end

data/sig/generated/riffer/stream_events/reasoning_done.rbs

@@ -1,14 +1,16 @@
 # Generated from lib/riffer/stream_events/reasoning_done.rb with RBS::Inline
 
-# Represents completed reasoning during streaming; only emitted by providers
-# that support reasoning (e.g. OpenAI with the reasoning option).
+# Represents one completed reasoning block during streaming; only emitted by
+# providers that support reasoning (e.g. OpenAI with the reasoning option).
 class Riffer::StreamEvents::ReasoningDone < Riffer::StreamEvents::Base
-  # The complete reasoning content.
-  attr_reader content: String
+  # The reasoning block, which the agent loop accumulates onto the assistant
+  # message. Its +text+ is the content the preceding ReasoningDelta events
+  # added up to.
+  attr_reader part: Riffer::Messages::Assistant::ReasoningPart
 
   # --
-  # : (String, ?role: Symbol) -> void
-  def initialize: (String, ?role: Symbol) -> void
+  # : (Riffer::Messages::Assistant::ReasoningPart, ?role: Symbol) -> void
+  def initialize: (Riffer::Messages::Assistant::ReasoningPart, ?role: Symbol) -> void
 
   # --
   # : () -> Hash[Symbol, untyped]

data/sig/generated/riffer/tools/runtime.rbs

@@ -44,8 +44,8 @@ class Riffer::Tools::Runtime
   def dispatch_tool_call: (Riffer::Messages::Assistant::ToolCall, tools: Array[singleton(Riffer::Tool)], context: Riffer::Agent::Context?, ?assistant_message: Riffer::Messages::Assistant?) -> Riffer::Tools::Response
 
   # --
-  # : (String?) -> untyped
-  def parse_arguments: (String?) -> untyped
+  # : (String) -> untyped
+  def parse_arguments: (String) -> untyped
 
   # Emitted outside +around_tool_call+ so host enrichment spans nest beneath it.
   # --

data/sig/generated/riffer/tracing/capture.rbs

@@ -35,12 +35,12 @@ module Riffer::Tracing::Capture
   def tool_call_part: (Riffer::Messages::Assistant::ToolCall) -> Hash[Symbol, untyped]
 
   # --
-  # : (Riffer::Messages::FilePart) -> Hash[Symbol, untyped]
-  def file_part: (Riffer::Messages::FilePart) -> Hash[Symbol, untyped]
+  # : (Riffer::Messages::User::FilePart) -> Hash[Symbol, untyped]
+  def file_part: (Riffer::Messages::User::FilePart) -> Hash[Symbol, untyped]
 
   # Semconv's tool_call part carries arguments as a JSON object; riffer holds
   # them as a string — parse so the captured payload isn't double-encoded.
   # --
-  # : (untyped) -> untyped
-  def parse_arguments: (untyped) -> untyped
+  # : (String) -> untyped
+  def parse_arguments: (String) -> untyped
 end