riffer 0.47.2 → 0.48.0

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

@@ -6,6 +6,8 @@
 class Riffer::Agent::Config
   DEFAULT_MAX_STEPS: Integer
 
+  @tool_runtime: (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)?
+
   # The configured agent identifier.
   attr_reader identifier: String?
 
@@ -30,9 +32,6 @@ class Riffer::Agent::Config
   # The accumulated +use_mcp+ tag configurations.
   attr_reader mcp_configs: Array[Hash[Symbol, untyped]]
 
-  # The configured tool runtime.
-  attr_reader tool_runtime: singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc
-
   # The configured skills.
   attr_accessor skills_config: Riffer::Skills::Config?
 
@@ -51,11 +50,11 @@ class Riffer::Agent::Config
   #    ?max_steps: Numeric?,
   #    ?tools_config: (Array[singleton(Riffer::Tool)] | Proc)?,
   #    ?mcp_configs: Array[Hash[Symbol, untyped]],
-  #    ?tool_runtime: (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc),
+  #    ?tool_runtime: (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)?,
   #    ?skills_config: Riffer::Skills::Config?,
   #    ?guardrails: Hash[Symbol, Array[Hash[Symbol, untyped]]]
   #  ) -> void
-  def initialize: (?identifier: String?, ?model: (String | Proc)?, ?instructions: (String | Proc)?, ?model_options: Hash[Symbol, untyped], ?structured_output: Riffer::Params?, ?max_steps: Numeric?, ?tools_config: (Array[singleton(Riffer::Tool)] | Proc)?, ?mcp_configs: Array[Hash[Symbol, untyped]], ?tool_runtime: singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc, ?skills_config: Riffer::Skills::Config?, ?guardrails: Hash[Symbol, Array[Hash[Symbol, untyped]]]) -> void
+  def initialize: (?identifier: String?, ?model: (String | Proc)?, ?instructions: (String | Proc)?, ?model_options: Hash[Symbol, untyped], ?structured_output: Riffer::Params?, ?max_steps: Numeric?, ?tools_config: (Array[singleton(Riffer::Tool)] | Proc)?, ?mcp_configs: Array[Hash[Symbol, untyped]], ?tool_runtime: (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)?, ?skills_config: Riffer::Skills::Config?, ?guardrails: Hash[Symbol, Array[Hash[Symbol, untyped]]]) -> void
 
   # Sets +identifier+, coercing the value to String.
   # --
@@ -67,6 +66,13 @@ class Riffer::Agent::Config
   # : (Riffer::Params?) -> Riffer::Params?
   def structured_output=: (Riffer::Params?) -> Riffer::Params?
 
+  # Returns the declared tool runtime, or +Riffer.config.tool_runtime+ when none
+  # was declared. Resolving the global here rather than at construction is what
+  # lets a copy tell an inherited runtime from a defaulted one.
+  # --
+  # : () -> (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)
+  def tool_runtime: () -> (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)
+
   # Sets +tool_runtime+. Raises Riffer::ArgumentError on an invalid value.
   # --
   # : ((singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)) -> (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)
@@ -105,6 +111,14 @@ class Riffer::Agent::Config
 
   private
 
+  # +dup+ would leave the copy sharing every collection with this one, so a
+  # declaration on either would reach the other. The nesting runs deeper than one
+  # level: an mcp entry holds its own +:tags+ array, a guardrail entry its own
+  # +:options+ hash, and +model_options+ is arbitrary.
+  # --
+  # : (Riffer::Agent::Config) -> void
+  def initialize_copy: (Riffer::Agent::Config) -> void
+
   # --
   # : (untyped, String) -> void
   def validate_string_or_proc!: (untyped, String) -> void

data/sig/generated/riffer/agent/response.rbs

@@ -23,6 +23,10 @@ class Riffer::Agent::Response
   # The modifications made by guardrails during processing.
   attr_reader modifications: Array[Riffer::Guardrails::Modification]
 
+  # The reasoning parts on the final assistant message, if the provider
+  # produced any.
+  attr_reader reasoning: Array[Riffer::Messages::Assistant::ReasoningPart]
+
   # The parsed structured output, if structured output was configured.
   attr_reader structured_output: Hash[Symbol, untyped]?
 
@@ -46,13 +50,14 @@ class Riffer::Agent::Response
   #     outcome: Riffer::Agent::Outcome,
   #     ?tripwire: Riffer::Guardrails::Tripwire?,
   #     ?modifications: Array[Riffer::Guardrails::Modification],
+  #     ?reasoning: Array[Riffer::Messages::Assistant::ReasoningPart],
   #     ?structured_output: Hash[Symbol, untyped]?,
   #     ?messages: Array[Riffer::Messages::Base],
   #     ?healed_tool_call_ids: Array[String],
   #     ?token_usage: Riffer::Providers::TokenUsage?,
   #     ?steps: Integer
   #   ) -> void
-  def initialize: (String, outcome: Riffer::Agent::Outcome, ?tripwire: Riffer::Guardrails::Tripwire?, ?modifications: Array[Riffer::Guardrails::Modification], ?structured_output: Hash[Symbol, untyped]?, ?messages: Array[Riffer::Messages::Base], ?healed_tool_call_ids: Array[String], ?token_usage: Riffer::Providers::TokenUsage?, ?steps: Integer) -> void
+  def initialize: (String, outcome: Riffer::Agent::Outcome, ?tripwire: Riffer::Guardrails::Tripwire?, ?modifications: Array[Riffer::Guardrails::Modification], ?reasoning: Array[Riffer::Messages::Assistant::ReasoningPart], ?structured_output: Hash[Symbol, untyped]?, ?messages: Array[Riffer::Messages::Base], ?healed_tool_call_ids: Array[String], ?token_usage: Riffer::Providers::TokenUsage?, ?steps: Integer) -> void
 
   # Returns true if any guardrail modified data during processing.
   #

data/sig/generated/riffer/agent/run.rbs

@@ -7,20 +7,21 @@ module Riffer::Agent::Run
   # for prompt/files semantics.
   #
   # --
-  # : (agent: Riffer::Agent, ?prompt: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?tags: Hash[(String | Symbol), untyped]) -> Riffer::Agent::Response
-  def generate: (agent: Riffer::Agent, ?prompt: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?tags: Hash[String | Symbol, untyped]) -> Riffer::Agent::Response
+  # : (agent: Riffer::Agent, ?prompt: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::User::FilePart]?, ?tags: Hash[(String | Symbol), untyped]) -> Riffer::Agent::Response
+  def generate: (agent: Riffer::Agent, ?prompt: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::User::FilePart]?, ?tags: Hash[String | Symbol, untyped]) -> Riffer::Agent::Response
 
   # Runs the streaming loop for the given agent. See Riffer::Agent#stream
   # for prompt/files semantics.
   #
   # --
-  # : (agent: Riffer::Agent, ?prompt: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?tags: Hash[(String | Symbol), untyped]) -> Enumerator[Riffer::StreamEvents::Base, Riffer::Agent::Response]
-  def stream: (agent: Riffer::Agent, ?prompt: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?tags: Hash[String | Symbol, untyped]) -> Enumerator[Riffer::StreamEvents::Base, Riffer::Agent::Response]
+  # : (agent: Riffer::Agent, ?prompt: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::User::FilePart]?, ?tags: Hash[(String | Symbol), untyped]) -> Enumerator[Riffer::StreamEvents::Base, Riffer::Agent::Response]
+  def stream: (agent: Riffer::Agent, ?prompt: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::User::FilePart]?, ?tags: Hash[String | Symbol, untyped]) -> Enumerator[Riffer::StreamEvents::Base, Riffer::Agent::Response]
 
   private
 
   # Both +generate+ and +stream+ funnel here, so this is the single place raw
-  # +tags+ are normalized. The clean <tt>String => String</tt> map is then
+  # +tags+ are normalized and merged over the default tags (a caller tag wins
+  # on a shared key). The clean <tt>String => String</tt> map is then
   # threaded to every span builder in the run as +riffer.tag.*+ and to each
   # provider call (via +merged_model_options+) for native request-metadata
   # mapping.
@@ -100,6 +101,11 @@ module Riffer::Agent::Run
   # : (Riffer::Agent, ?Hash[String, String]) -> Hash[Symbol, untyped]
   def merged_model_options: (Riffer::Agent, ?Hash[String, String]) -> Hash[Symbol, untyped]
 
+  # The tags riffer adds to every run, identifying the agent it's on behalf of.
+  # --
+  # : (Riffer::Agent) -> Hash[String, String]
+  def default_tags: (Riffer::Agent) -> Hash[String, String]
+
   # --
   # : (
   #     Riffer::Agent,
@@ -107,18 +113,19 @@ module Riffer::Agent::Run
   #     outcome: Riffer::Agent::Outcome,
   #     ?tripwire: Riffer::Guardrails::Tripwire?,
   #     ?modifications: Array[Riffer::Guardrails::Modification],
+  #     ?reasoning: Array[Riffer::Messages::Assistant::ReasoningPart],
   #     ?structured_output: Hash[Symbol, untyped]?,
   #     ?healed_tool_call_ids: Array[String],
   #     ?token_usage: Riffer::Providers::TokenUsage?,
   #     ?steps: Integer
   #   ) -> Riffer::Agent::Response
-  def build_response: (Riffer::Agent, String, outcome: Riffer::Agent::Outcome, ?tripwire: Riffer::Guardrails::Tripwire?, ?modifications: Array[Riffer::Guardrails::Modification], ?structured_output: Hash[Symbol, untyped]?, ?healed_tool_call_ids: Array[String], ?token_usage: Riffer::Providers::TokenUsage?, ?steps: Integer) -> Riffer::Agent::Response
+  def build_response: (Riffer::Agent, String, outcome: Riffer::Agent::Outcome, ?tripwire: Riffer::Guardrails::Tripwire?, ?modifications: Array[Riffer::Guardrails::Modification], ?reasoning: Array[Riffer::Messages::Assistant::ReasoningPart], ?structured_output: Hash[Symbol, untyped]?, ?healed_tool_call_ids: Array[String], ?token_usage: Riffer::Providers::TokenUsage?, ?steps: Integer) -> Riffer::Agent::Response
 
   # Raises when +files+ are supplied without a +prompt+ — the provider needs
   # text to anchor the attachments.
   # --
-  # : (Riffer::Agent, String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?) -> void
-  def append_user_message: (Riffer::Agent, String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?) -> void
+  # : (Riffer::Agent, String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::User::FilePart]?) -> void
+  def append_user_message: (Riffer::Agent, String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::User::FilePart]?) -> void
 
   # --
   # : (Riffer::Agent, Riffer::Providers::TokenUsage?) -> void

data/sig/generated/riffer/agent.rbs

@@ -22,6 +22,13 @@ class Riffer::Agent
   # : () -> Riffer::Agent::Config
   def self.config: () -> Riffer::Agent::Config
 
+  # +identifier+ is cleared because it is configuration here but identity on the
+  # subclass; two classes claiming one raise Riffer::DuplicateIdentifierError at
+  # the next registry lookup.
+  # --
+  # : (Class) -> void
+  def self.inherited: (Class) -> void
+
   # Gets or sets the agent identifier.
   #
   # --
@@ -108,13 +115,13 @@ class Riffer::Agent
 
   # Generates a response using a new agent instance.
   # --
-  # : (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?context: Hash[Symbol, untyped]?, ?tags: Hash[(String | Symbol), untyped]) -> Riffer::Agent::Response
-  def self.generate: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?context: Hash[Symbol, untyped]?, ?tags: Hash[String | Symbol, untyped]) -> Riffer::Agent::Response
+  # : (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::User::FilePart]?, ?context: Hash[Symbol, untyped]?, ?tags: Hash[(String | Symbol), untyped]) -> Riffer::Agent::Response
+  def self.generate: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::User::FilePart]?, ?context: Hash[Symbol, untyped]?, ?tags: Hash[String | Symbol, untyped]) -> Riffer::Agent::Response
 
   # Streams a response using a new agent instance.
   # --
-  # : (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?context: Hash[Symbol, untyped]?, ?tags: Hash[(String | Symbol), untyped]) -> Enumerator[Riffer::StreamEvents::Base, Riffer::Agent::Response]
-  def self.stream: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?context: Hash[Symbol, untyped]?, ?tags: Hash[String | Symbol, untyped]) -> Enumerator[Riffer::StreamEvents::Base, Riffer::Agent::Response]
+  # : (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::User::FilePart]?, ?context: Hash[Symbol, untyped]?, ?tags: Hash[(String | Symbol), untyped]) -> Enumerator[Riffer::StreamEvents::Base, Riffer::Agent::Response]
+  def self.stream: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::User::FilePart]?, ?context: Hash[Symbol, untyped]?, ?tags: Hash[String | Symbol, untyped]) -> Enumerator[Riffer::StreamEvents::Base, Riffer::Agent::Response]
 
   # Reconstructs a runnable agent from a wire hash produced by +#to_h+.
   # --
@@ -190,6 +197,14 @@ class Riffer::Agent
   # : (?session: Riffer::Agent::Session?, ?context: Hash[Symbol, untyped]?, ?config: Riffer::Agent::Config?) -> void
   def initialize: (?session: Riffer::Agent::Session?, ?context: Hash[Symbol, untyped]?, ?config: Riffer::Agent::Config?) -> void
 
+  # The identifier for this agent: the instance config's identifier when set
+  # (e.g. an agent restored with +Riffer::Agent.from_h+), otherwise the class
+  # identifier.
+  #
+  # --
+  # : () -> String
+  def identifier: () -> String
+
   # Generates a response from the agent.
   #
   # With +prompt+, a new user message is appended (silently — +on_message+ does
@@ -202,11 +217,12 @@ class Riffer::Agent
   # are stamped as +riffer.tag.*+ on every span the call emits. See
   # +docs/AGENTS.md+ for the per-provider mapping. The reserved key
   # +user_id+ also maps to the provider's native user identifier where one
-  # exists.
+  # exists. Riffer adds the default tags +kind+ (+"agent"+) and +agent+ (the
+  # agent identifier); a caller tag with the same key wins.
   #
   # --
-  # : (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?tags: Hash[(String | Symbol), untyped]) -> Riffer::Agent::Response
-  def generate: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?tags: Hash[String | Symbol, untyped]) -> Riffer::Agent::Response
+  # : (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::User::FilePart]?, ?tags: Hash[(String | Symbol), untyped]) -> Riffer::Agent::Response
+  def generate: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::User::FilePart]?, ?tags: Hash[String | Symbol, untyped]) -> Riffer::Agent::Response
 
   # Streams a response from the agent as an +Enumerator+ of
   # +Riffer::StreamEvents+ whose block-form +each+ returns the final
@@ -215,8 +231,8 @@ class Riffer::Agent
   # Raises Riffer::ArgumentError if structured output is configured.
   #
   # --
-  # : (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?tags: Hash[(String | Symbol), untyped]) -> Enumerator[Riffer::StreamEvents::Base, Riffer::Agent::Response]
-  def stream: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?tags: Hash[String | Symbol, untyped]) -> Enumerator[Riffer::StreamEvents::Base, Riffer::Agent::Response]
+  # : (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::User::FilePart]?, ?tags: Hash[(String | Symbol), untyped]) -> Enumerator[Riffer::StreamEvents::Base, Riffer::Agent::Response]
+  def stream: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::User::FilePart]?, ?tags: Hash[String | Symbol, untyped]) -> Enumerator[Riffer::StreamEvents::Base, Riffer::Agent::Response]
 
   # Interrupts the agent loop from an +on_message+ callback. Equivalent to
   # <tt>throw :riffer_interrupt, reason</tt>.

data/sig/generated/riffer/config.rbs

@@ -147,7 +147,7 @@ class Riffer::Config
     def backend=: (untyped) -> void
   end
 
-  # File-attachment-download policy for +Riffer::Messages::FilePart+ URL sources
+  # File-attachment-download policy for +Riffer::Messages::User::FilePart+ URL sources
   class Files
     # Allow file attachments to be downloaded to send to providers.
     attr_reader allow_downloads: bool

data/sig/generated/riffer/evals/evaluator.rbs

@@ -16,8 +16,13 @@ class Riffer::Evals::Evaluator
 
   self.@judge_model: String?
 
+  self.@identifier: String?
+
   @judge: Riffer::Evals::Judge?
 
+  # The identifier for an anonymous evaluator class.
+  DEFAULT_IDENTIFIER: String
+
   # Gets or sets the evaluation instructions (criteria and scoring rubric).
   #
   # --
@@ -36,6 +41,19 @@ class Riffer::Evals::Evaluator
   # : (?String?) -> String?
   def self.judge_model: (?String?) -> String?
 
+  # Gets or sets the evaluator identifier, sent as the +agent+ tag on judge
+  # calls. Defaults to the snake_cased class name, or DEFAULT_IDENTIFIER for
+  # an anonymous class.
+  #
+  # --
+  # : (?String?) -> String
+  def self.identifier: (?String?) -> String
+
+  # Anonymous classes derive an empty identifier.
+  # --
+  # : () -> String
+  private def self.derived_identifier: () -> String
+
   # Evaluates an input/output pair. The default calls the judge with the
   # class-level +instructions+; override for custom logic (e.g. rule-based
   # evaluators).
@@ -49,7 +67,8 @@ class Riffer::Evals::Evaluator
   # : (String | Array[Hash[Symbol, untyped] | Riffer::Messages::Base]) -> String
   def format_input: (String | Array[Hash[Symbol, untyped] | Riffer::Messages::Base]) -> String
 
-  # Returns a Judge instance configured for this evaluator.
+  # Returns a Judge instance configured for this evaluator. Its calls carry
+  # the +kind+ (+"judge"+) and +agent+ (the evaluator identifier) tags.
   #
   # --
   # : () -> Riffer::Evals::Judge

data/sig/generated/riffer/evals/judge.rbs

@@ -19,10 +19,13 @@ class Riffer::Evals::Judge
   # The model string (provider/model format).
   attr_reader model: String
 
+  # The tags passed to the provider on every call.
+  attr_reader tags: Hash[String, String]
+
   # Raises Riffer::ArgumentError unless +model+ is "provider/model" format.
   # --
-  # : (model: String) -> void
-  def initialize: (model: String) -> void
+  # : (model: String, ?tags: Hash[String, String]) -> void
+  def initialize: (model: String, ?tags: Hash[String, String]) -> void
 
   # Evaluates an input/output pair using the configured LLM.
   # --

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
 
@@ -145,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]