riffer 0.47.1 → 0.48.0

data/lib/riffer/evals/evaluator.rb

@@ -15,8 +15,12 @@ class Riffer::Evals::Evaluator
   # @rbs self.@instructions: String?
   # @rbs self.@higher_is_better: bool?
   # @rbs self.@judge_model: String?
+  # @rbs self.@identifier: String?
   # @rbs @judge: Riffer::Evals::Judge?
 
+  # The identifier for an anonymous evaluator class.
+  DEFAULT_IDENTIFIER = "riffer/judge" #: String
+
   class << self
     # Gets or sets the evaluation instructions (criteria and scoring rubric).
     #
@@ -51,6 +55,28 @@ class Riffer::Evals::Evaluator
 
       @judge_model = value.to_s
     end
+
+    # 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 identifier(value = nil)
+      return @identifier = value.to_s if value
+
+      @identifier || derived_identifier
+    end
+
+    private
+
+    # Anonymous classes derive an empty identifier.
+    #--
+    #: () -> String
+    def derived_identifier
+      derived = Riffer::Helpers::Identifier.for(self)
+      derived.empty? ? DEFAULT_IDENTIFIER : derived
+    end
   end
 
   # Evaluates an input/output pair. The default calls the judge with the
@@ -94,7 +120,8 @@ class Riffer::Evals::Evaluator
 
   protected
 
-  # 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
@@ -106,7 +133,7 @@ class Riffer::Evals::Evaluator
               "No judge model configured. Set judge_model on the evaluator or Riffer.config.evals.judge_model"
       end
 
-      Riffer::Evals::Judge.new(model: model)
+      Riffer::Evals::Judge.new(model: model, tags: { "kind" => "judge", "agent" => self.class.identifier })
     end
   end
 

data/lib/riffer/evals/judge.rb

@@ -28,18 +28,22 @@ class Riffer::Evals::Judge
   end
 
   # The model string (provider/model format).
-  attr_reader :model #: String
+  attr_reader :model #: String # @dynamic model
+
+  # The tags passed to the provider on every call.
+  attr_reader :tags #: Hash[String, String] # @dynamic tags
 
   # Raises Riffer::ArgumentError unless +model+ is "provider/model" format.
   #--
-  #: (model: String) -> void
-  def initialize(model:)
+  #: (model: String, ?tags: Hash[String, String]) -> void
+  def initialize(model:, tags: {})
     provider_name, model_name = model.split("/", 2)
     unless [provider_name, model_name].all? { |part| part.is_a?(String) && !part.strip.empty? }
       raise Riffer::ArgumentError, "Invalid model string: #{model}"
     end
 
     @model = model
+    @tags = tags
   end
 
   # Evaluates an input/output pair using the configured LLM.
@@ -49,12 +53,14 @@ class Riffer::Evals::Judge
     system_message = build_system_message(instructions)
     user_message = build_user_message(input: input, output: output, ground_truth: ground_truth)
 
-    response = provider_instance.generate_text(
+    options = {
       system: system_message,
       prompt: user_message,
       model: model_name,
       tools: [EvaluationTool],
-    )
+    } #: Hash[Symbol, untyped]
+    options[:tags] = tags unless tags.empty?
+    response = provider_instance.generate_text(**options)
 
     parse_tool_response(response)
   end
@@ -109,10 +115,9 @@ class Riffer::Evals::Judge
   #--
   #: (Riffer::Messages::Assistant) -> Hash[Symbol, untyped]
   def parse_tool_response(response)
-    tool_call = response.tool_calls.first
-    raise Riffer::Error, "Invalid judge response: no tool call found" unless tool_call
+    tool_call = response.tool_calls.fetch(0) { raise Riffer::Error, "Invalid judge response: no tool call found" }
 
-    parsed = JSON.parse(tool_call[:arguments], symbolize_names: true)
+    parsed = JSON.parse(tool_call.arguments, symbolize_names: true)
     score = parsed[:score]
     reason = parsed[:reason]
 

data/lib/riffer/evals/result.rb

@@ -4,23 +4,23 @@
 # Represents the result of a single evaluation.
 class Riffer::Evals::Result
   # The evaluator class that produced this result.
-  attr_reader :evaluator #: singleton(Riffer::Evals::Evaluator)
+  attr_reader :evaluator #: singleton(Riffer::Evals::Evaluator) # @dynamic evaluator
 
   # The evaluation score (0.0 to 1.0).
-  attr_reader :score #: Float
+  attr_reader :score #: Float # @dynamic score
 
   # Human-readable explanation of the score.
-  attr_reader :reason #: String?
+  attr_reader :reason #: String? # @dynamic reason
 
   # Additional metadata from the evaluation.
-  attr_reader :metadata #: Hash[Symbol, untyped]
+  attr_reader :metadata #: Hash[Symbol, untyped] # @dynamic metadata
 
   # Whether higher scores are better for this evaluator.
-  attr_reader :higher_is_better #: bool
+  attr_reader :higher_is_better #: bool # @dynamic higher_is_better
 
   # Token usage for the judge call that produced this result, when the
   # evaluator used an LLM. Nil for rule-based evaluators.
-  attr_reader :token_usage #: Riffer::Providers::TokenUsage?
+  attr_reader :token_usage #: Riffer::Providers::TokenUsage? # @dynamic token_usage
 
   # Raises Riffer::ArgumentError if +score+ is not between 0.0 and 1.0.
   #--

data/lib/riffer/evals/run_result.rb

@@ -4,7 +4,7 @@
 # Represents the complete result of an evaluation run across multiple scenarios.
 class Riffer::Evals::RunResult
   # Per-scenario evaluation results.
-  attr_reader :scenario_results #: Array[Riffer::Evals::ScenarioResult]
+  attr_reader :scenario_results #: Array[Riffer::Evals::ScenarioResult] # @dynamic scenario_results
 
   #--
   #: (scenario_results: Array[Riffer::Evals::ScenarioResult]) -> void

data/lib/riffer/evals/scenario_result.rb

@@ -4,22 +4,22 @@
 # Represents the result of evaluating a single scenario.
 class Riffer::Evals::ScenarioResult
   # The input that was evaluated.
-  attr_reader :input #: String
+  attr_reader :input #: String # @dynamic input
 
   # The agent output for this scenario.
-  attr_reader :output #: String
+  attr_reader :output #: String # @dynamic output
 
   # The ground truth used during evaluation.
-  attr_reader :ground_truth #: String?
+  attr_reader :ground_truth #: String? # @dynamic ground_truth
 
   # Individual evaluation results.
-  attr_reader :results #: Array[Riffer::Evals::Result]
+  attr_reader :results #: Array[Riffer::Evals::Result] # @dynamic results
 
   # The full message history from the agent conversation.
-  attr_reader :messages #: Array[Riffer::Messages::Base]
+  attr_reader :messages #: Array[Riffer::Messages::Base] # @dynamic messages
 
   # Token usage the agent under test spent generating this scenario's output.
-  attr_reader :token_usage #: Riffer::Providers::TokenUsage?
+  attr_reader :token_usage #: Riffer::Providers::TokenUsage? # @dynamic token_usage
 
   #--
   #: (input: String, output: String, ground_truth: String?, results: Array[Riffer::Evals::Result], ?messages: Array[Riffer::Messages::Base], ?token_usage: Riffer::Providers::TokenUsage?) -> void

data/lib/riffer/files/resolver.rb

@@ -40,7 +40,7 @@ class Riffer::Files::Resolver
     raise Riffer::TooManyFilesError, "Too many files specified in user message"
   end
 
-  #: (Riffer::Messages::FilePart) -> void
+  #: (Riffer::Messages::User::FilePart) -> void
   def resolve_file!(file)
     delivery = @provider.file_delivery(file)
     if delivery == :unsupported
@@ -62,7 +62,7 @@ class Riffer::Files::Resolver
     end
   end
 
-  #: (Riffer::Messages::FilePart) -> void
+  #: (Riffer::Messages::User::FilePart) -> void
   def verify_inline!(file)
     return unless file.sha256
 
@@ -72,7 +72,7 @@ class Riffer::Files::Resolver
   # +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
+  #: (Riffer::Messages::User::FilePart, cache: (false | Symbol)) -> void
   def download!(file, cache:)
     raise Riffer::FileDownloadsDisabledError, "File attachments are disabled" unless @config.allow_downloads
 

data/lib/riffer/guardrails/modification.rb

@@ -4,13 +4,13 @@
 # Records a guardrail transformation event.
 class Riffer::Guardrails::Modification
   # The guardrail class that transformed data.
-  attr_reader :guardrail #: singleton(Riffer::Guardrail)
+  attr_reader :guardrail #: singleton(Riffer::Guardrail) # @dynamic guardrail
 
   # The phase when the transformation occurred (:before or :after).
-  attr_reader :phase #: Symbol
+  attr_reader :phase #: Symbol # @dynamic phase
 
   # The indices of messages that were changed.
-  attr_reader :message_indices #: Array[Integer]
+  attr_reader :message_indices #: Array[Integer] # @dynamic message_indices
 
   #--
   #: (guardrail: singleton(Riffer::Guardrail), phase: Symbol, message_indices: Array[Integer]) -> void

data/lib/riffer/guardrails/result.rb

@@ -7,13 +7,13 @@ class Riffer::Guardrails::Result
   TYPES = %i[pass transform block].freeze #: Array[Symbol]
 
   # The result type (:pass, :transform, or :block).
-  attr_reader :type #: Symbol
+  attr_reader :type #: Symbol # @dynamic type
 
   # The data (for pass/transform) or reason (for block).
-  attr_reader :data #: untyped
+  attr_reader :data #: untyped # @dynamic data
 
   # Optional metadata for block results.
-  attr_reader :metadata #: Hash[Symbol, untyped]?
+  attr_reader :metadata #: Hash[Symbol, untyped]? # @dynamic metadata
 
   class << self
     # Creates a pass result that continues with unchanged data.

data/lib/riffer/guardrails/runner.rb

@@ -5,16 +5,16 @@
 # 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]]
+  attr_reader :guardrail_configs #: Array[Hash[Symbol, untyped]] # @dynamic guardrail_configs
 
   # The execution phase (:before or :after).
-  attr_reader :phase #: Symbol
+  attr_reader :phase #: Symbol # @dynamic phase
 
   # The context passed to guardrails.
-  attr_reader :context #: untyped
+  attr_reader :context #: untyped # @dynamic context
 
   # The normalized per-call tags, stamped as +riffer.tag.*+ on guardrail spans.
-  attr_reader :tags #: Hash[String, String]
+  attr_reader :tags #: Hash[String, String] # @dynamic tags
 
   #--
   #: (Array[Hash[Symbol, untyped]], phase: Symbol, ?context: untyped, ?tags: Hash[String, String]) -> void

data/lib/riffer/guardrails/tripwire.rb

@@ -6,16 +6,16 @@ class Riffer::Guardrails::Tripwire
   PHASES = Riffer::Guardrails::PHASES #: Array[Symbol]
 
   # The reason for blocking.
-  attr_reader :reason #: String
+  attr_reader :reason #: String # @dynamic reason
 
   # The guardrail class that triggered the block.
-  attr_reader :guardrail #: singleton(Riffer::Guardrail)
+  attr_reader :guardrail #: singleton(Riffer::Guardrail) # @dynamic guardrail
 
   # The phase when the block occurred (:before or :after).
-  attr_reader :phase #: Symbol
+  attr_reader :phase #: Symbol # @dynamic phase
 
   # Optional metadata about the block.
-  attr_reader :metadata #: Hash[Symbol, untyped]?
+  attr_reader :metadata #: Hash[Symbol, untyped]? # @dynamic metadata
 
   # Raises Riffer::ArgumentError if +phase+ is invalid.
   #--

data/lib/riffer/helpers/deep_dup.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# Copying for the nested Hashes and Arrays a configuration object holds.
+module Riffer::Helpers::DeepDup
+  extend self
+
+  # 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(value)
+    seen = {} #: Hash[untyped, untyped]
+
+    rebuild(value, seen.compare_by_identity)
+  end
+
+  private
+
+  #--
+  #: (untyped, Hash[untyped, untyped]) -> untyped
+  def rebuild(value, seen)
+    return seen[value] if seen.key?(value)
+
+    case value
+    when Hash
+      copy = seen[value] = {}
+      value.each { |key, entry| copy[key] = rebuild(entry, seen) }
+      copy
+    when Array
+      copy = seen[value] = []
+      value.each { |entry| copy << rebuild(entry, seen) }
+      copy
+    else value
+    end
+  end
+end

data/lib/riffer/mcp/manifest.rb

@@ -6,20 +6,20 @@ require "uri"
 # 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
+  attr_reader :name #: String # @dynamic name
 
   # Tags for matching +use_mcp+.
-  attr_reader :tags #: Array[Symbol]
+  attr_reader :tags #: Array[Symbol] # @dynamic tags
 
   # HTTPS URL passed to the MCP transport.
-  attr_reader :endpoint #: String
+  attr_reader :endpoint #: String # @dynamic endpoint
 
   # Headers (or a Proc) resolved once when building the discovery client.
-  attr_reader :discovery_headers #: (Hash[String, untyped] | ::Proc)?
+  attr_reader :discovery_headers #: (Hash[String, untyped] | ::Proc)? # @dynamic discovery_headers
 
   # Optional hint (+:global+/+:tenant+/+:user+) for whether invocation
   # credentials depend on tenant/user keys in +context+.
-  attr_reader :credentials_scope #: Symbol?
+  attr_reader :credentials_scope #: Symbol? # @dynamic credentials_scope
 
   # Raises Riffer::ArgumentError unless +name+ is present and +endpoint+ is a
   # valid HTTPS URL.

data/lib/riffer/mcp/registration.rb

@@ -9,7 +9,7 @@ class Riffer::Mcp::Registration
   # @rbs @mutex: Thread::Mutex
 
   # The manifest that describes this server.
-  attr_reader :manifest #: Riffer::Mcp::Manifest
+  attr_reader :manifest #: Riffer::Mcp::Manifest # @dynamic manifest
 
   # Generated Riffer::Mcp::Tool subclasses.
   #

data/lib/riffer/mcp/search_tool.rb

@@ -8,7 +8,7 @@ class Riffer::Mcp::SearchTool < Riffer::Tool
   # 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)]
+    attr_reader :discovered_tools #: Array[singleton(Riffer::Tool)] # @dynamic discovered_tools
 
     #--
     #: (String, Array[singleton(Riffer::Tool)]) -> void

data/lib/riffer/messages/assistant/reasoning_part.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# 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 = %i[text summary encrypted].freeze #: Array[Symbol]
+
+  # What the part carries: readable reasoning (+:text+), a provider-condensed
+  # digest (+:summary+), or an opaque payload (+:encrypted+).
+  attr_reader :type #: Symbol # @dynamic type
+
+  # The reasoning prose, for +:text+ and +:summary+ parts.
+  attr_reader :text #: String? # @dynamic text
+
+  # The opaque payload, for +:encrypted+ parts.
+  attr_reader :data #: String? # @dynamic data
+
+  # The provider's signature over the part, when it issues one.
+  attr_reader :signature #: String? # @dynamic signature
+
+  # The provider's identifier for the part, when it issues one.
+  attr_reader :id #: String? # @dynamic id
+
+  # 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? # @dynamic format
+
+  # 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(part)
+    return part if part.is_a?(Riffer::Messages::Assistant::ReasoningPart)
+
+    new(
+      type: part[:type].to_sym,
+      text: part[:text],
+      data: part[:data],
+      signature: part[:signature],
+      id: part[:id],
+      format: part[:format],
+    )
+  end
+
+  # Raises Riffer::ArgumentError on a +type+ outside TYPES.
+  #--
+  #: (type: Symbol, ?text: String?, ?data: String?, ?signature: String?, ?id: String?, ?format: String?) -> void
+  def initialize(type:, text: nil, data: nil, signature: nil, id: nil, format: nil)
+    unless TYPES.include?(type)
+      raise Riffer::ArgumentError,
+            "type must be one of #{TYPES.inspect}, got #{type.inspect}"
+    end
+
+    @type = type
+    @text = text
+    @data = data
+    @signature = signature
+    @id = id
+    @format = format
+  end
+
+  # Serializes the part to a hash, omitting the fields it doesn't carry.
+  #
+  #--
+  #: () -> Hash[Symbol, untyped]
+  def to_h
+    { type: type, text: text, data: data, signature: signature, id: id, format: format }.compact
+  end
+
+  #--
+  #: (untyped) -> bool
+  def ==(other)
+    other.is_a?(Riffer::Messages::Assistant::ReasoningPart) && to_h == other.to_h
+  end
+
+  #--
+  #: (untyped) -> bool
+  def eql?(other)
+    self == other
+  end
+
+  #--
+  #: () -> Integer
+  def hash
+    to_h.hash
+  end
+end

data/lib/riffer/messages/assistant/tool_call.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# 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 # @dynamic call_id
+
+  # The name of the tool to invoke.
+  attr_reader :name #: String # @dynamic name
+
+  # The JSON-encoded arguments, exactly as the provider emitted them.
+  attr_reader :arguments #: String # @dynamic arguments
+
+  # 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(call)
+    return call if call.is_a?(Riffer::Messages::Assistant::ToolCall)
+
+    if call.values_at(:call_id, :name, :arguments).any?(&:nil?)
+      raise Riffer::ArgumentError, "Tool call hash must include :call_id, :name, and :arguments"
+    end
+
+    new(call_id: call[:call_id], name: call[:name], arguments: call[:arguments])
+  end
+
+  #--
+  #: (call_id: String, name: String, arguments: String) -> void
+  def initialize(call_id:, name:, arguments:)
+    @call_id = call_id
+    @name = name
+    @arguments = arguments
+  end
+
+  # Serializes the call to a hash.
+  #
+  #--
+  #: () -> Hash[Symbol, untyped]
+  def to_h
+    { call_id: call_id, name: name, arguments: arguments }
+  end
+
+  #--
+  #: (untyped) -> bool
+  def ==(other)
+    other.is_a?(Riffer::Messages::Assistant::ToolCall) && to_h == other.to_h
+  end
+
+  #--
+  #: (untyped) -> bool
+  def eql?(other)
+    self == other
+  end
+
+  #--
+  #: () -> Integer
+  def hash
+    to_h.hash
+  end
+end

data/lib/riffer/messages/assistant.rb

@@ -4,24 +4,49 @@
 # 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
-  ToolCall = Struct.new(:call_id, :name, :arguments)
+  # The reasoning part types +reasoning_text+ reads; the rest carry no prose.
+  REASONING_TEXT_TYPES = %i[text summary].freeze #: Array[Symbol]
+
+  # 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(msg)
+    return msg if msg.is_a?(Riffer::Messages::Assistant)
+
+    new(
+      msg[:content],
+      id: msg[:id],
+      tool_calls: (msg[:tool_calls] || []).map { |tc| Riffer::Messages::Assistant::ToolCall.from_hash(tc) },
+      reasoning: (msg[:reasoning] || []).map { |part| Riffer::Messages::Assistant::ReasoningPart.from_hash(part) },
+      token_usage: msg[:token_usage] && Riffer::Providers::TokenUsage.from_hash(msg[:token_usage]),
+      structured_output: msg[:structured_output],
+      finish_reason: msg[:finish_reason]&.to_sym,
+      finish_reason_raw: msg[:finish_reason_raw],
+    )
+  end
 
   # Array of tool calls requested by the assistant.
-  attr_reader :tool_calls #: Array[Riffer::Messages::Assistant::ToolCall]
+  attr_reader :tool_calls #: Array[Riffer::Messages::Assistant::ToolCall] # @dynamic tool_calls
+
+  # The model's reasoning blocks for this response, in the order the provider
+  # emitted them.
+  attr_reader :reasoning #: Array[Riffer::Messages::Assistant::ReasoningPart] # @dynamic reasoning
 
   # Token usage data for this response.
-  attr_reader :token_usage #: Riffer::Providers::TokenUsage?
+  attr_reader :token_usage #: Riffer::Providers::TokenUsage? # @dynamic token_usage
 
   # Parsed structured output hash, or nil when not applicable.
-  attr_reader :structured_output #: Hash[Symbol, untyped]?
+  attr_reader :structured_output #: Hash[Symbol, untyped]? # @dynamic structured_output
 
   # Normalized reason the provider finished this response, when reported (see
   # <tt>Riffer::Providers::FinishReason::VALUES</tt>).
-  attr_reader :finish_reason #: Symbol?
+  attr_reader :finish_reason #: Symbol? # @dynamic finish_reason
 
   # The provider's raw finish-reason value behind +finish_reason+, when one
   # exists on the wire.
-  attr_reader :finish_reason_raw #: String?
+  attr_reader :finish_reason_raw #: String? # @dynamic finish_reason_raw
 
   # Raises Riffer::ArgumentError when +finish_reason+ is outside the
   # normalized vocabulary.
@@ -30,6 +55,7 @@ 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?,
@@ -39,6 +65,7 @@ class Riffer::Messages::Assistant < Riffer::Messages::Base
     content,
     id: nil,
     tool_calls: [],
+    reasoning: [],
     token_usage: nil,
     structured_output: nil,
     finish_reason: nil,
@@ -51,6 +78,7 @@ class Riffer::Messages::Assistant < Riffer::Messages::Base
 
     super(content, id: id)
     @tool_calls = tool_calls
+    @reasoning = reasoning
     @token_usage = token_usage
     @structured_output = structured_output
     @finish_reason = finish_reason
@@ -75,10 +103,29 @@ class Riffer::Messages::Assistant < Riffer::Messages::Base
     !@tool_calls.empty?
   end
 
+  #--
+  #: () -> bool
+  def reasoning?
+    !@reasoning.empty?
+  end
+
+  # 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
+    texts = reasoning.filter_map { |part| part.text if REASONING_TEXT_TYPES.include?(part.type) }
+    texts.empty? ? nil : texts.join("\n\n")
+  end
+
   #--
   #: (Riffer::Messages::Assistant) -> Riffer::Messages::Assistant
   def +(other)
-    self.class.new("#{content}\n\n#{other.content}", tool_calls: tool_calls + other.tool_calls)
+    self.class.new(
+      "#{content}\n\n#{other.content}",
+      tool_calls: tool_calls + other.tool_calls,
+      reasoning: reasoning + other.reasoning,
+    )
   end
 
   # Converts the message to a hash.
@@ -89,6 +136,7 @@ class Riffer::Messages::Assistant < Riffer::Messages::Base
     hash = { role: role, content: content } #: Hash[Symbol, untyped]
     hash[:id] = id if id
     hash[:tool_calls] = tool_calls.map(&:to_h) unless tool_calls.empty?
+    hash[:reasoning] = reasoning.map(&:to_h) if reasoning?
     hash[:token_usage] = token_usage.to_h if token_usage
     hash[:structured_output] = structured_output if structured_output?
     hash[:finish_reason] = finish_reason if finish_reason