riffer 0.47.2 → 0.49.0

data/sig/generated/riffer/guardrails/modification.rbs

@@ -1,22 +1,16 @@
 # Generated from lib/riffer/guardrails/modification.rb with RBS::Inline
 
-# Records a guardrail transformation event.
 class Riffer::Guardrails::Modification
-  # The guardrail class that transformed data.
   attr_reader guardrail: singleton(Riffer::Guardrail)
 
-  # The phase when the transformation occurred (:before or :after).
   attr_reader phase: Symbol
 
-  # The indices of messages that were changed.
   attr_reader message_indices: Array[Integer]
 
   # --
   # : (guardrail: singleton(Riffer::Guardrail), phase: Symbol, message_indices: Array[Integer]) -> void
   def initialize: (guardrail: singleton(Riffer::Guardrail), phase: Symbol, message_indices: Array[Integer]) -> void
 
-  # Converts the modification to a hash.
-  #
   # --
   # : () -> Hash[Symbol, untyped]
   def to_h: () -> Hash[Symbol, untyped]

data/sig/generated/riffer/guardrails/result.rbs

@@ -1,53 +1,38 @@
 # Generated from lib/riffer/guardrails/result.rb with RBS::Inline
 
-# Represents the result of a guardrail execution: +pass+ (continue unchanged),
-# +transform+ (continue with changed data), or +block+ (halt with a reason).
 class Riffer::Guardrails::Result
   TYPES: Array[Symbol]
 
-  # The result type (:pass, :transform, or :block).
   attr_reader type: Symbol
 
-  # The data (for pass/transform) or reason (for block).
   attr_reader data: untyped
 
-  # Optional metadata for block results.
   attr_reader metadata: Hash[Symbol, untyped]?
 
-  # Creates a pass result that continues with unchanged data.
   # --
   # : (untyped) -> Riffer::Guardrails::Result
   def self.pass: (untyped) -> Riffer::Guardrails::Result
 
-  # Creates a transform result that continues with transformed data.
   # --
   # : (untyped) -> Riffer::Guardrails::Result
   def self.transform: (untyped) -> Riffer::Guardrails::Result
 
-  # Creates a block result that halts execution.
   # --
   # : (String, ?metadata: Hash[Symbol, untyped]?) -> Riffer::Guardrails::Result
   def self.block: (String, ?metadata: Hash[Symbol, untyped]?) -> Riffer::Guardrails::Result
 
-  # Raises Riffer::ArgumentError if +type+ is not :pass, :transform, or :block.
   # --
   # : (Symbol, untyped, ?metadata: Hash[Symbol, untyped]?) -> void
   def initialize: (Symbol, untyped, ?metadata: Hash[Symbol, untyped]?) -> void
 
-  # Returns true if this is a pass result.
-  #
   # --
   # : () -> bool
   def pass?: () -> bool
 
-  # Returns true if this is a transform result.
-  #
   # --
   # : () -> bool
   def transform?: () -> bool
 
-  # Returns true if this is a block result.
-  #
   # --
   # : () -> bool
   def block?: () -> bool

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

@@ -1,27 +1,18 @@
 # Generated from lib/riffer/guardrails/runner.rb with RBS::Inline
 
-# Executes guardrails sequentially, passing each one's output to the next; if
-# any blocks, execution stops and a tripwire is returned.
 class Riffer::Guardrails::Runner
-  # The guardrail configs to execute.
   attr_reader guardrail_configs: Array[Hash[Symbol, untyped]]
 
-  # The execution phase (:before or :after).
   attr_reader phase: Symbol
 
-  # The context passed to guardrails.
   attr_reader context: untyped
 
-  # The normalized per-call tags, stamped as +riffer.tag.*+ on guardrail spans.
   attr_reader tags: Hash[String, String]
 
   # --
   # : (Array[Hash[Symbol, untyped]], phase: Symbol, ?context: untyped, ?tags: Hash[String, String]) -> void
   def initialize: (Array[Hash[Symbol, untyped]], phase: Symbol, ?context: untyped, ?tags: Hash[String, String]) -> void
 
-  # Runs the guardrails sequentially. For the +:before+ phase +data+ is the
-  # messages array; for +:after+ it's the response (and +messages+ must be
-  # provided).
   # --
   # : (untyped, ?messages: Array[Riffer::Messages::Base]?) -> [untyped, Riffer::Guardrails::Tripwire?, Array[Riffer::Guardrails::Modification]]
   def run: (untyped, ?messages: Array[Riffer::Messages::Base]?) -> [ untyped, Riffer::Guardrails::Tripwire?, Array[Riffer::Guardrails::Modification] ]
@@ -48,8 +39,6 @@ class Riffer::Guardrails::Runner
   # : (Riffer::Guardrail) -> Hash[String, untyped]
   def guardrail_span_attributes: (Riffer::Guardrail) -> Hash[String, untyped]
 
-  # A block is a handled outcome, so its span status stays unset — an error
-  # span status is reserved for a raised exception.
   # --
   # : ((Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span), Riffer::Guardrails::Result) -> void
   def record_guardrail_outcome: (Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span, Riffer::Guardrails::Result) -> void

data/sig/generated/riffer/guardrails/tripwire.rbs

@@ -1,28 +1,20 @@
 # Generated from lib/riffer/guardrails/tripwire.rb with RBS::Inline
 
-# Captures information about a blocked guardrail execution.
 class Riffer::Guardrails::Tripwire
   PHASES: Array[Symbol]
 
-  # The reason for blocking.
   attr_reader reason: String
 
-  # The guardrail class that triggered the block.
   attr_reader guardrail: singleton(Riffer::Guardrail)
 
-  # The phase when the block occurred (:before or :after).
   attr_reader phase: Symbol
 
-  # Optional metadata about the block.
   attr_reader metadata: Hash[Symbol, untyped]?
 
-  # Raises Riffer::ArgumentError if +phase+ is invalid.
   # --
   # : (reason: String, guardrail: singleton(Riffer::Guardrail), phase: Symbol, ?metadata: Hash[Symbol, untyped]?) -> void
   def initialize: (reason: String, guardrail: singleton(Riffer::Guardrail), phase: Symbol, ?metadata: Hash[Symbol, untyped]?) -> void
 
-  # Converts the tripwire to a hash.
-  #
   # --
   # : () -> Hash[Symbol, untyped]
   def to_h: () -> Hash[Symbol, untyped]

data/sig/generated/riffer/guardrails.rbs

@@ -1,7 +1,5 @@
 # Generated from lib/riffer/guardrails.rb with RBS::Inline
 
-# Namespace for guardrail components that pre-process input and post-process
-# output in the agent pipeline.
 module Riffer::Guardrails
   PHASES: Array[Symbol]
 end

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

@@ -1,10 +1,6 @@
 # Generated from lib/riffer/helpers/boolean.rb with RBS::Inline
 
-# Coercion for boolean-ish configuration values.
 module Riffer::Helpers::Boolean
-  # Coerces +value+ to a boolean so an env-var +"false"+ (truthy in Ruby)
-  # doesn't silently read as +true+. Raises Riffer::ArgumentError on an
-  # unrecognized value, naming +attribute+ in the message.
   # --
   # : (untyped, attribute: String) -> bool
   def coerce: (untyped, attribute: String) -> bool

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

@@ -1,9 +1,6 @@
 # Generated from lib/riffer/helpers/call_or_value.rb with RBS::Inline
 
-# Resolves the Proc-or-value idiom.
 module Riffer::Helpers::CallOrValue
-  # Calls +thing+ when it's a Proc (passing +context+ if its arity is non-zero),
-  # returns it unchanged otherwise, or +default+ when +nil+.
   # --
   # : (untyped, ?context: untyped, ?default: untyped) -> untyped
   def resolve: (untyped, ?context: untyped, ?default: untyped) -> untyped

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

@@ -0,0 +1,13 @@
+# Generated from lib/riffer/helpers/deep_dup.rb with RBS::Inline
+
+module Riffer::Helpers::DeepDup
+  # --
+  # : (untyped) -> untyped
+  def call: (untyped) -> untyped
+
+  private
+
+  # --
+  # : (untyped, Hash[untyped, untyped]) -> untyped
+  def rebuild: (untyped, Hash[untyped, untyped]) -> untyped
+end

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

@@ -1,13 +1,9 @@
 # Generated from lib/riffer/helpers/dependencies.rb with RBS::Inline
 
-# Lazy-loads gem dependencies — used by providers to load required gems only
-# when needed.
 module Riffer::Helpers::Dependencies
-  # Raised when a required gem cannot be loaded.
   class LoadError < ::LoadError
   end
 
-  # Requires a gem by name; raises LoadError if it isn't installed.
   # --
   # : (String) -> true
   def depends_on: (String) -> true

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

@@ -1,26 +1,14 @@
 # Generated from lib/riffer/helpers/identifier.rb with RBS::Inline
 
-# Helper module for deriving snake_case identifiers from class names.
 module Riffer::Helpers::Identifier
-  # Derives a snake_case identifier from a class name string.
-  #
   # --
   # : (String?) -> String
   def derive: (String?) -> String
 
-  # Derives and memoizes the identifier for a class or module. Anonymous
-  # classes return "" without caching, so a class named later still derives its
-  # real identifier — a guard that must travel with the cache, so callers never
-  # memoize their own.
-  #
   # --
   # : (Module) -> String
   def for: (Module) -> String
 
-  # Returns the class-path name of a class or module, or +nil+ when anonymous.
-  # Tool classes shadow Module#name with the identifier DSL, so the real name
-  # must come from Module's own implementation.
-  #
   # --
   # : (Module) -> String?
   def real_name: (Module) -> String?

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

@@ -0,0 +1,21 @@
+# Generated from lib/riffer/helpers/validate.rb with RBS::Inline
+
+module Riffer::Helpers::Validate
+  # The error names the class, not the value, so a misassigned secret never
+  # lands in a log.
+  # --
+  # : (untyped, attribute: String) -> String?
+  def optional_string: (untyped, attribute: String) -> String?
+
+  # --
+  # : (untyped, attribute: String) -> Integer
+  def positive_integer: (untyped, attribute: String) -> Integer
+
+  # --
+  # : (untyped, attribute: String) -> Riffer::Runner
+  def runner: (untyped, attribute: String) -> Riffer::Runner
+
+  # --
+  # : (untyped, attribute: String) -> String
+  def model_id: (untyped, attribute: String) -> String
+end

data/sig/generated/riffer/mcp/authenticated_tool.rbs

@@ -1,11 +1,6 @@
 # Generated from lib/riffer/mcp/authenticated_tool.rb with RBS::Inline
 
-# Wraps MCP-generated tool classes so +tools/call+ resolves
-# +Riffer.config.mcp.credentials+ per invocation, copying metadata from the
-# inner class at wrap time.
 module Riffer::Mcp::AuthenticatedTool
-  # Returns one wrapper class per inner tool, sharing +manifest+ and +matched_tags+.
-  #
   # --
   # : (Array[singleton(Riffer::Mcp::Tool)], Riffer::Mcp::Manifest, Array[Symbol]) -> Array[singleton(Riffer::Mcp::Tool)]
   def wrap_all: (Array[singleton(Riffer::Mcp::Tool)], Riffer::Mcp::Manifest, Array[Symbol]) -> Array[singleton(Riffer::Mcp::Tool)]

data/sig/generated/riffer/mcp/client.rbs

@@ -1,8 +1,5 @@
 # Generated from lib/riffer/mcp/client.rb with RBS::Inline
 
-# Thin wrapper around the MCP Ruby SDK client (mcp gem v0.8+). Resolves headers
-# (if a Proc) once at init, then provides +tools_list+ / +tools_call+ — used for
-# discovery and for +tools/call+ when no +credentials+ proc is configured.
 class Riffer::Mcp::Client
   @client: untyped
 
@@ -10,14 +7,10 @@ class Riffer::Mcp::Client
   # : (endpoint: String, ?headers: (Hash[String, String] | Proc), ?client: untyped?) -> void
   def initialize: (endpoint: String, ?headers: Hash[String, String] | Proc, ?client: untyped?) -> void
 
-  # Returns tool definition hashes with +:name+, +:description+, and
-  # +:input_schema+ keys.
   # --
   # : () -> Array[Hash[Symbol, untyped]]
   def tools_list: () -> Array[Hash[Symbol, untyped]]
 
-  # Calls a tool on the MCP server and returns joined text content from the response.
-  #
   # --
   # : (String, ?Hash[untyped, untyped]) -> String
   def tools_call: (String, ?Hash[untyped, untyped]) -> String

data/sig/generated/riffer/mcp/manifest.rbs

@@ -1,21 +1,17 @@
 # Generated from lib/riffer/mcp/manifest.rb with RBS::Inline
 
-# Holds the configuration for a single MCP server.
 class Riffer::Mcp::Manifest
-  # Identifier used as the registration key and generated-agent identifier.
   attr_reader name: String
 
-  # Tags for matching +use_mcp+.
   attr_reader tags: Array[Symbol]
 
-  # HTTPS URL passed to the MCP transport.
   attr_reader endpoint: String
 
-  # Headers (or a Proc) resolved once when building the discovery client.
+  # Resolved once, when building the discovery client.
   attr_reader discovery_headers: (Hash[String, untyped] | ::Proc)?
 
-  # Optional hint (+:global+/+:tenant+/+:user+) for whether invocation
-  # credentials depend on tenant/user keys in +context+.
+  # +:global+, +:tenant+, or +:user+: whether invocation credentials depend on
+  # tenant/user keys in +context+.
   attr_reader credentials_scope: Symbol?
 
   # Raises Riffer::ArgumentError unless +name+ is present and +endpoint+ is a

data/sig/generated/riffer/mcp/registration.rbs

@@ -1,7 +1,5 @@
 # Generated from lib/riffer/mcp/registration.rb with RBS::Inline
 
-# Per-server state managed by Riffer::Mcp::Registry — discovers tools via
-# +tools/list+ and generates tool classes when a server is registered.
 class Riffer::Mcp::Registration
   @cancelled: bool
 
@@ -9,11 +7,8 @@ class Riffer::Mcp::Registration
 
   @mutex: Thread::Mutex
 
-  # The manifest that describes this server.
   attr_reader manifest: Riffer::Mcp::Manifest
 
-  # Generated Riffer::Mcp::Tool subclasses.
-  #
   # --
   # : () -> Array[singleton(Riffer::Mcp::Tool)]
   def tools: () -> Array[singleton(Riffer::Mcp::Tool)]
@@ -22,15 +17,10 @@ class Riffer::Mcp::Registration
   # : (Riffer::Mcp::Manifest) -> void
   def initialize: (Riffer::Mcp::Manifest) -> void
 
-  # Retires this registration, preventing in-flight discovery from publishing
-  # state.
-  #
   # --
   # : () -> void
   def retire!: () -> void
 
-  # Returns true if this registration has been retired.
-  #
   # --
   # : () -> bool
   def retired?: () -> bool

data/sig/generated/riffer/mcp/registry.rbs

@@ -1,31 +1,22 @@
 # Generated from lib/riffer/mcp/registry.rb with RBS::Inline
 
-# Thread-safe global store for MCP server registrations, keyed by manifest name.
 module Riffer::Mcp::Registry
   @mutex: Thread::Mutex
 
   @store: Hash[String, Riffer::Mcp::Registration]
 
-  # Registers an MCP server and starts async tool discovery, replacing any
-  # existing registration with the same name.
   # --
   # : ((Hash[Symbol, untyped] | Riffer::Mcp::Manifest)) -> Riffer::Mcp::Registration
   def register: (Hash[Symbol, untyped] | Riffer::Mcp::Manifest) -> Riffer::Mcp::Registration
 
-  # Removes a registration by name.
-  #
   # --
   # : ((String | Symbol)) -> void
   def unregister: (String | Symbol) -> void
 
-  # Returns a frozen snapshot of all current registrations.
-  #
   # --
   # : () -> Hash[String, Riffer::Mcp::Registration]
   def registrations: () -> Hash[String, Riffer::Mcp::Registration]
 
-  # Returns all registrations whose manifest tags intersect the given tags
-  # (normalized to symbols).
   # --
   # : (Array[Symbol]) -> Array[Riffer::Mcp::Registration]
   def find_by_tags: (Array[Symbol]) -> Array[Riffer::Mcp::Registration]

data/sig/generated/riffer/mcp/search_tool.rbs

@@ -1,12 +1,9 @@
 # Generated from lib/riffer/mcp/search_tool.rb with RBS::Inline
 
-# Searches available MCP tools by name or description.
 class Riffer::Mcp::SearchTool < Riffer::Tool
   IDENTIFIER: ::String
 
-  # Successful search response carrying the matched tool classes.
   class Result < Riffer::Tools::Response
-    # Tool classes that matched the search query.
     attr_reader discovered_tools: Array[singleton(Riffer::Tool)]
 
     # --
@@ -14,7 +11,6 @@ class Riffer::Mcp::SearchTool < Riffer::Tool
     def initialize: (String, Array[singleton(Riffer::Tool)]) -> void
   end
 
-  # Searches progressive MCP tools and returns a +Result+ with +discovered_tools+.
   # --
   # : (context: Riffer::Agent::Context?, query: String) -> Riffer::Tools::Response
   def call: (context: Riffer::Agent::Context?, query: String) -> Riffer::Tools::Response

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

@@ -1,18 +1,14 @@
 # Generated from lib/riffer/mcp/tool.rb with RBS::Inline
 
-# Base class for MCP-generated tools.
 class Riffer::Mcp::Tool < Riffer::Tool
   self.@mcp_server_tool_name: String?
 
   self.@input_schema: Hash[Symbol, untyped]?
 
-  # Returns the unprefixed tool name used for +tools/call+ on the MCP server.
   # --
   # : () -> String
   def self.mcp_server_tool_name: () -> String
 
-  # Returns the server-published input schema, falling back to the params DSL.
-  # MCP schemas are server-defined, so +strict+ is not applied to them.
   # --
   # : (?strict: bool) -> Hash[Symbol, untyped]
   def self.parameters_schema: (?strict: bool) -> Hash[Symbol, untyped]

data/sig/generated/riffer/mcp/tool_factory.rbs

@@ -1,12 +1,6 @@
 # Generated from lib/riffer/mcp/tool_factory.rb with RBS::Inline
 
-# Generates anonymous Riffer::Mcp::Tool subclasses from MCP tool definitions.
-# Generated tools delegate +#call+ to the MCP client and skip Riffer's param
-# validation — the MCP server validates inputs.
 module Riffer::Mcp::ToolFactory
-  # Builds one Riffer::Mcp::Tool subclass per tool definition, prefixing names
-  # with the manifest name to avoid cross-server collisions (e.g.
-  # +jira__search+); the server-side name stays on +.mcp_server_tool_name+.
   # --
   # : (String, Riffer::Mcp::Client, Array[Hash[Symbol, untyped]]) -> Array[singleton(Riffer::Mcp::Tool)]
   def build: (String, Riffer::Mcp::Client, Array[Hash[Symbol, untyped]]) -> Array[singleton(Riffer::Mcp::Tool)]

data/sig/generated/riffer/mcp.rbs

@@ -1,43 +1,23 @@
 # Generated from lib/riffer/mcp.rb with RBS::Inline
 
-# Integration with Model Context Protocol (MCP) servers. Register servers
-# globally; agents opt-in by tag via the +use_mcp+ DSL. Tags are
-# application-defined; see +docs/MCP.md+.
-#
-#   Riffer::Mcp.register(
-#     name: "github",
-#     tags: [:github],
-#     endpoint: "https://mcp.github.com",
-#     discovery_headers: -> { {"Authorization" => "Bearer #{ENV['GITHUB_TOKEN']}"} }
-#   )
-#
-#   class MyAgent < Riffer::Agent
-#     model "openai/gpt-4o"
-#     use_mcp :github
-#   end
 module Riffer::Mcp
-  # Base error for all MCP-related failures.
   class Error < Riffer::Error
   end
 
   # Raised when +Riffer.config.mcp.credentials+ returns +nil+ during +tools/call+
-  # after the server's tools were included for this run.
+  # after the server's tools were already included for this run.
   class CredentialsDeniedError < Error
   end
 
-  # Registers an MCP server, blocking until tool discovery completes. Raises
-  # on discovery failure.
+  # Blocks until tool discovery completes.
   # --
   # : ((Hash[Symbol, untyped] | Riffer::Mcp::Manifest)) -> Riffer::Mcp::Registration
   def register: (Hash[Symbol, untyped] | Riffer::Mcp::Manifest) -> Riffer::Mcp::Registration
 
-  # Removes a registration by name; subsequent agent runs won't see its tools.
   # --
   # : (String) -> void
   def unregister: (String) -> void
 
-  # Returns all current registrations keyed by name.
-  #
   # --
   # : () -> Hash[String, Riffer::Mcp::Registration]
   def registrations: () -> Hash[String, Riffer::Mcp::Registration]

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

@@ -0,0 +1,45 @@
+# Generated from lib/riffer/messages/assistant/reasoning_part.rb with RBS::Inline
+
+# Stored and replayed verbatim, never interpreted, so a provider that requires its own thinking
+# blocks back gets them unchanged.
+class Riffer::Messages::Assistant::ReasoningPart
+  TYPES: Array[Symbol]
+
+  attr_reader type: Symbol
+
+  attr_reader text: String?
+
+  attr_reader data: String?
+
+  attr_reader signature: String?
+
+  attr_reader id: String?
+
+  # Owned by the producing adapter (e.g. <tt>"anthropic-claude-v1"</tt>); adapters replay only the
+  # formats they recognize, so it is never validated here.
+  attr_reader format: String?
+
+  # --
+  # : ((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
+
+  # --
+  # : (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
+
+  # --
+  # : () -> 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,34 @@
+# Generated from lib/riffer/messages/assistant/tool_call.rb with RBS::Inline
+
+class Riffer::Messages::Assistant::ToolCall
+  attr_reader call_id: String
+
+  attr_reader name: String
+
+  # JSON-encoded, exactly as the provider emitted them.
+  attr_reader arguments: String
+
+  # --
+  # : ((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
+
+  # --
+  # : () -> 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

@@ -1,49 +1,37 @@
 # Generated from lib/riffer/messages/assistant.rb with RBS::Inline
 
-# 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 other reasoning part types 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
+  # --
+  # : ((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]
 
-  # Token usage data for this response.
+  attr_reader reasoning: Array[Riffer::Messages::Assistant::ReasoningPart]
+
   attr_reader token_usage: Riffer::Providers::TokenUsage?
 
-  # Parsed structured output hash, or nil when not applicable.
   attr_reader structured_output: Hash[Symbol, untyped]?
 
-  # Normalized reason the provider finished this response, when reported (see
-  # <tt>Riffer::Providers::FinishReason::VALUES</tt>).
   attr_reader finish_reason: Symbol?
 
-  # The provider's raw finish-reason value behind +finish_reason+, when one
-  # exists on the wire.
   attr_reader finish_reason_raw: String?
 
-  # Raises Riffer::ArgumentError when +finish_reason+ is outside the
-  # normalized vocabulary.
   # --
   # : (
-  #    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], ?token_usage: Riffer::Providers::TokenUsage?, ?structured_output: Hash[Symbol, untyped]?, ?finish_reason: Symbol?, ?finish_reason_raw: String?) -> void
+  #     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], ?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,12 +45,18 @@ class Riffer::Messages::Assistant < Riffer::Messages::Base
   # : () -> bool
   def has_tool_calls?: () -> bool
 
+  # --
+  # : () -> bool
+  def reasoning?: () -> bool
+
+  # --
+  # : () -> String?
+  def reasoning_text: () -> String?
+
   # --
   # : (Riffer::Messages::Assistant) -> Riffer::Messages::Assistant
   def +: (Riffer::Messages::Assistant) -> Riffer::Messages::Assistant
 
-  # Converts the message to a hash.
-  #
   # --
   # : () -> Hash[Symbol, untyped]
   def to_h: () -> Hash[Symbol, untyped]