riffer 0.47.2 → 0.48.0

data/lib/riffer/messages/base.rb

@@ -15,27 +15,11 @@ class Riffer::Messages::Base
     raise Riffer::ArgumentError, "Message hash must include a 'role' key" if msg[:role].nil? || msg[:role].empty?
 
     case msg[:role].to_sym
-    when :user
-      files = (msg[:files] || []).map { |f| Riffer::Messages::FilePart.from_hash(f) }
-      Riffer::Messages::User.new(msg[:content], id: msg[:id], files: files)
-    when :assistant
-      tool_calls = (msg[:tool_calls] || []).map do |tc|
-        tc.is_a?(Riffer::Messages::Assistant::ToolCall) ? tc : Riffer::Messages::Assistant::ToolCall.new(**tc)
-      end
-      Riffer::Messages::Assistant.new(
-        msg[:content],
-        id: msg[:id],
-        tool_calls: tool_calls,
-        structured_output: msg[:structured_output],
-        finish_reason: msg[:finish_reason]&.to_sym,
-        finish_reason_raw: msg[:finish_reason_raw],
-      )
-    when :system
-      Riffer::Messages::System.new(msg[:content], id: msg[:id])
-    when :tool
-      Riffer::Messages::Tool.new(msg[:content], id: msg[:id], tool_call_id: msg[:tool_call_id], name: msg[:name])
-    else
-      raise Riffer::ArgumentError, "Unknown message role: #{msg[:role]}"
+    when :user then Riffer::Messages::User.from_hash(msg)
+    when :assistant then Riffer::Messages::Assistant.from_hash(msg)
+    when :system then Riffer::Messages::System.from_hash(msg)
+    when :tool then Riffer::Messages::Tool.from_hash(msg)
+    else raise Riffer::ArgumentError, "Unknown message role: #{msg[:role]}"
     end
   end
 

data/lib/riffer/messages/system.rb

@@ -3,6 +3,16 @@
 
 # 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(msg)
+    return msg if msg.is_a?(Riffer::Messages::System)
+
+    new(msg[:content], id: msg[:id])
+  end
+
   #--
   #: () -> Symbol
   def role

data/lib/riffer/messages/tool.rb

@@ -3,6 +3,23 @@
 
 # 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(msg)
+    return msg if msg.is_a?(Riffer::Messages::Tool)
+
+    new(
+      msg[:content],
+      id: msg[:id],
+      tool_call_id: msg[:tool_call_id],
+      name: msg[:name],
+      error: msg[:error],
+      error_type: msg[:error_type]&.to_sym,
+    )
+  end
+
   # The ID of the tool call this result responds to.
   attr_reader :tool_call_id #: String # @dynamic tool_call_id
 

data/lib/riffer/messages/{file_part.rb → user/file_part.rb}

@@ -6,7 +6,7 @@ require "uri"
 
 # 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
   # @rbs @url_string: String?
   # @rbs @data: String?
   # @rbs @downloaded_data: String?
@@ -62,23 +62,18 @@ 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
+  #: (String, ?media_type: String?, ?filename: String?, ?sha256: String?) -> Riffer::Messages::User::FilePart
   def self.from_url(url, media_type: nil, filename: nil, sha256: nil)
-    unless media_type
-      ext = ::File.extname(URI.parse(url).path.to_s).downcase
-      media_type = MEDIA_TYPES.fetch(ext) { raise Riffer::ArgumentError, "Cannot detect media type from URL; provide media_type explicitly" }
-    end
-
-    new(url: url, media_type: media_type, filename: filename, sha256: sha256)
+    new(url: url, media_type: media_type || detect_media_type(url), filename: filename, sha256: sha256)
   end
 
   # 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
+  #: ((Hash[Symbol, untyped] | Riffer::Messages::User::FilePart)) -> Riffer::Messages::User::FilePart
   def self.from_hash(file)
-    return file if file.is_a?(Riffer::Messages::FilePart)
+    return file if file.is_a?(Riffer::Messages::User::FilePart)
 
     url = file[:url]
     data = file[:data]
@@ -87,7 +82,7 @@ class Riffer::Messages::FilePart
     sha256 = file[:sha256]
 
     if url
-      from_url(url, media_type: media_type, filename: filename, sha256: sha256)
+      new(url: url, data: data, media_type: media_type || detect_media_type(url), filename: filename, sha256: sha256)
     elsif data && media_type
       new(data: data, media_type: media_type, filename: filename, sha256: sha256)
     else
@@ -95,6 +90,15 @@ class Riffer::Messages::FilePart
     end
   end
 
+  # Raises Riffer::ArgumentError when the URL's extension isn't a known media type.
+  #--
+  #: (String) -> String
+  def self.detect_media_type(url)
+    ext = ::File.extname(URI.parse(url).path.to_s).downcase
+    MEDIA_TYPES.fetch(ext) { raise Riffer::ArgumentError, "Cannot detect media type from URL; provide media_type explicitly" }
+  end
+  private_class_method :detect_media_type
+
   # 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/lib/riffer/messages/user.rb

@@ -3,11 +3,22 @@
 
 # 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(msg)
+    return msg if msg.is_a?(Riffer::Messages::User)
+
+    files = (msg[:files] || []).map { |f| Riffer::Messages::User::FilePart.from_hash(f) }
+    new(msg[:content], id: msg[:id], files: files)
+  end
+
   # File attachments for this message.
-  attr_reader :files #: Array[Riffer::Messages::FilePart] # @dynamic files
+  attr_reader :files #: Array[Riffer::Messages::User::FilePart] # @dynamic files
 
   #--
-  #: (String, ?id: String?, ?files: Array[Riffer::Messages::FilePart]) -> void
+  #: (String, ?id: String?, ?files: Array[Riffer::Messages::User::FilePart]) -> void
   def initialize(content, id: nil, files: [])
     super(content, id: id)
     @files = files

data/lib/riffer/params/param.rb

@@ -181,6 +181,18 @@ 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(source)
+    super
+    @nested_params = source.nested_params&.dup
+    @enum = Riffer::Helpers::DeepDup.call(source.enum)
+    @default = Riffer::Helpers::DeepDup.call(source.default)
+  end
+
   #--
   #: () -> void
   def validate_strict_shape!

data/lib/riffer/params.rb

@@ -151,6 +151,15 @@ 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(source)
+    super
+    @parameters = source.parameters.map(&:dup)
+  end
+
   #--
   #: (Module, Module?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> Riffer::Params?
   def build_nested(type, of, &block)

data/lib/riffer/providers/amazon_bedrock.rb

@@ -47,7 +47,7 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
   end
 
   #--
-  #: (Riffer::Messages::FilePart) -> Symbol
+  #: (Riffer::Messages::User::FilePart) -> Symbol
   def file_delivery(file)
     file.url&.start_with?("s3://") ? :url : :bytes
   end
@@ -98,8 +98,9 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
 
     # requestMetadata is a flat String=>String map used to filter invocation
     # logs; every tag (including the reserved user_id) rides along, since
-    # Converse has no dedicated end-user field.
-    params[:request_metadata] = tags unless tags.empty?
+    # Converse has no dedicated end-user field. Merged over any request_metadata
+    # set in model_options; a tag wins on a shared key.
+    params[:request_metadata] = (params[:request_metadata] || {}).merge(tags) unless tags.empty?
 
     if tools && !tools.empty?
       params[:tool_config] = {
@@ -449,7 +450,7 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
   end
 
   #--
-  #: (Riffer::Messages::FilePart) -> Hash[Symbol, untyped]
+  #: (Riffer::Messages::User::FilePart) -> Hash[Symbol, untyped]
   def convert_file_part_to_bedrock_format(file)
     format = bedrock_format(file.media_type)
 

data/lib/riffer/providers/anthropic.rb

@@ -338,7 +338,7 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
   #--
   #: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
   def handle_content_block_stop_thinking(_event, state:, yielder:)
-    yielder << Riffer::StreamEvents::ReasoningDone.new(state[:reasoning])
+    yield_reasoning_done(yielder, state[:reasoning])
     state[:reasoning] = nil
   end
 
@@ -444,7 +444,7 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
   end
 
   #--
-  #: (Riffer::Messages::FilePart) -> Hash[Symbol, untyped]
+  #: (Riffer::Messages::User::FilePart) -> Hash[Symbol, untyped]
   def convert_file_part_to_anthropic_format(file)
     type = file.image? ? "image" : "document"
 

data/lib/riffer/providers/base.rb

@@ -40,7 +40,7 @@ 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
+  #: (?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: nil, system: nil, messages: nil, model: nil, files: nil, **options)
     validate_input!(prompt: prompt, system: system, messages: messages)
     @current_tools = options[:tools] || [] #: Array[singleton(Riffer::Tool)]
@@ -56,6 +56,7 @@ class Riffer::Providers::Base
 
       content = extract_content(response)
       tool_calls = extract_tool_calls(response)
+      reasoning = extract_reasoning(response)
       token_usage = extract_token_usage(response)
       finish_reason = extract_finish_reason(response)
       structured_output = parse_structured_output(content) if options[:structured_output] && tool_calls.empty?
@@ -67,6 +68,7 @@ class Riffer::Providers::Base
       Riffer::Messages::Assistant.new(
         content,
         tool_calls: tool_calls,
+        reasoning: reasoning,
         token_usage: token_usage,
         structured_output: structured_output,
         finish_reason: finish_reason&.reason,
@@ -78,7 +80,7 @@ class Riffer::Providers::Base
   # 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]
+  #: (?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: nil, system: nil, messages: nil, model: nil, files: nil, **options)
     validate_input!(prompt: prompt, system: system, messages: messages)
     @current_tools = options[:tools] || [] #: Array[singleton(Riffer::Tool)]
@@ -105,7 +107,7 @@ class Riffer::Providers::Base
   end
 
   #--
-  #: (Riffer::Messages::FilePart) -> Symbol
+  #: (Riffer::Messages::User::FilePart) -> Symbol
   def file_delivery(_file)
     :url
   end
@@ -224,6 +226,14 @@ class Riffer::Providers::Base
     nil
   end
 
+  # 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(_response)
+    []
+  end
+
   #--
   #: (untyped) -> String
   def extract_content(response)
@@ -348,6 +358,15 @@ class Riffer::Providers::Base
     Riffer.config.tracing.capture_messages && span.recording?
   end
 
+  # 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(yielder, text)
+    part = Riffer::Messages::Assistant::ReasoningPart.new(type: :text, text: text)
+    yielder << Riffer::StreamEvents::ReasoningDone.new(part)
+  end
+
   #--
   #: (Riffer::Providers::_EventSink, Riffer::Providers::FinishReason?) -> void
   def yield_finish_reason(yielder, finish_reason)
@@ -368,11 +387,11 @@ class Riffer::Providers::Base
   end
 
   #--
-  #: ((String | Hash[String, untyped])?) -> Hash[String, untyped]
+  #: (String) -> Hash[String, untyped]
   def parse_tool_arguments(arguments)
-    return {} if arguments.nil? || arguments.empty?
+    return {} if arguments.empty?
 
-    arguments.is_a?(String) ? JSON.parse(arguments) : arguments
+    JSON.parse(arguments)
   end
 
   #--
@@ -397,7 +416,7 @@ class Riffer::Providers::Base
   end
 
   #--
-  #: (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:, system:, messages:, files: nil)
     if messages && files && !files.empty?
       raise Riffer::ArgumentError, "cannot provide both files and messages; attach files to individual messages instead"
@@ -407,7 +426,7 @@ class Riffer::Providers::Base
 
     result = [] #: Array[Riffer::Messages::Base]
     result << Riffer::Messages::System.new(system) if system
-    file_parts = (files || []).map { |f| Riffer::Messages::FilePart.from_hash(f) }
+    file_parts = (files || []).map { |f| Riffer::Messages::User::FilePart.from_hash(f) }
     prompt_text = prompt #: String
     result << Riffer::Messages::User.new(prompt_text, files: file_parts)
     result

data/lib/riffer/providers/gemini.rb

@@ -37,7 +37,7 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
   end
 
   #--
-  #: (Riffer::Messages::FilePart) -> Symbol
+  #: (Riffer::Messages::User::FilePart) -> Symbol
   def file_delivery(_file)
     :base64
   end
@@ -287,7 +287,7 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
   end
 
   #--
-  #: (Riffer::Messages::FilePart) -> Hash[Symbol, untyped]
+  #: (Riffer::Messages::User::FilePart) -> Hash[Symbol, untyped]
   def convert_file_part_to_gemini_format(file)
     { inlineData: { mimeType: file.media_type, data: file.data } }
   end

data/lib/riffer/providers/mock.rb

@@ -54,15 +54,17 @@ 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(content, tool_calls: [], token_usage: nil, finish_reason: nil)
+  #: (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(content, tool_calls: [], token_usage: nil, finish_reason: nil, reasoning: [])
     @stubbed_responses << normalize_response(
       content: content,
       tool_calls: tool_calls,
       token_usage: token_usage,
       finish_reason: finish_reason,
+      reasoning: reasoning,
     )
   end
 
@@ -92,6 +94,7 @@ class Riffer::Providers::Mock < Riffer::Providers::Base
       role: response[:role] || "assistant",
       content: response[:content] || "",
       tool_calls: formatted_tool_calls,
+      reasoning: (response[:reasoning] || []).map { |part| Riffer::Messages::Assistant::ReasoningPart.from_hash(part) },
       token_usage: response[:token_usage],
       finish_reason: response[:finish_reason] || (formatted_tool_calls.empty? ? :stop : :tool_calls),
     }
@@ -129,6 +132,12 @@ class Riffer::Providers::Mock < Riffer::Providers::Base
     reason ? Riffer::Providers::FinishReason.new(reason: reason) : nil
   end
 
+  #--
+  #: (untyped) -> Array[Riffer::Messages::Assistant::ReasoningPart]
+  def extract_reasoning(response)
+    response[:reasoning] || []
+  end
+
   #--
   #: (untyped) -> String
   def extract_content(response)
@@ -149,6 +158,7 @@ class Riffer::Providers::Mock < Riffer::Providers::Base
     tool_calls = response[:tool_calls] || []
     token_usage = response[:token_usage]
     web_search = response[:web_search]
+    reasoning = response[:reasoning] || []
 
     if web_search
       yielder << Riffer::StreamEvents::WebSearchStatus.new("in_progress")
@@ -161,6 +171,12 @@ class Riffer::Providers::Mock < Riffer::Providers::Base
       )
     end
 
+    reasoning.each do |part|
+      text = part.text
+      yielder << Riffer::StreamEvents::ReasoningDelta.new(text) if text
+      yielder << Riffer::StreamEvents::ReasoningDone.new(part)
+    end
+
     unless full_content.empty?
       content_parts = full_content.split(". ").map { |part| part + (part.end_with?(".") ? "" : ".") }
       content_parts.each do |part|

data/lib/riffer/providers/open_ai.rb

@@ -35,7 +35,7 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
   end
 
   #--
-  #: (Riffer::Messages::FilePart) -> Symbol
+  #: (Riffer::Messages::User::FilePart) -> Symbol
   def file_delivery(file)
     file.image? ? :url : :base64
   end
@@ -80,7 +80,8 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
     } #: Hash[Symbol, untyped]
 
     unless tags.empty?
-      params[:metadata] = tags
+      # Merged over any metadata set in model_options; a tag wins on a shared key.
+      params[:metadata] = (params[:metadata] || {}).merge(tags)
       # The reserved user_id also maps to the native safety identifier while
       # staying in metadata as an ordinary tag.
       user_id = tags["user_id"]
@@ -296,7 +297,7 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
   #--
   #: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
   def handle_reasoning_summary_text_done(event, state:, yielder:)
-    yielder << Riffer::StreamEvents::ReasoningDone.new(event.text)
+    yield_reasoning_done(yielder, event.text)
   end
 
   #--
@@ -402,7 +403,7 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
           type: "function_call",
           call_id: tc.call_id,
           name: encode_tool_name(tc.name),
-          arguments: tc.arguments.is_a?(String) ? tc.arguments : tc.arguments.to_json,
+          arguments: tc.arguments,
         }
       end
       items
@@ -410,7 +411,7 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
   end
 
   #--
-  #: (Riffer::Messages::FilePart) -> Hash[Symbol, untyped]
+  #: (Riffer::Messages::User::FilePart) -> Hash[Symbol, untyped]
   def convert_file_part_to_openai_format(file)
     if file.image?
       image_url = file.url? ? file.url : "data:#{file.media_type};base64,#{file.data}"

data/lib/riffer/providers/open_router.rb

@@ -34,7 +34,7 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
   end
 
   #--
-  #: (Riffer::Messages::FilePart) -> Symbol
+  #: (Riffer::Messages::User::FilePart) -> Symbol
   def file_delivery(file)
     file.image? ? :url : :base64
   end
@@ -74,7 +74,8 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
     } #: Hash[Symbol, untyped]
 
     unless tags.empty?
-      params[:metadata] = tags
+      # Merged over any metadata set in model_options; a tag wins on a shared key.
+      params[:metadata] = (params[:metadata] || {}).merge(tags)
       # OpenRouter exposes the legacy Chat Completions user field rather than
       # safety_identifier; the reserved user_id maps there and stays in metadata.
       user = tags["user_id"]
@@ -223,7 +224,7 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
     emit_tool_call_done_events(state: state, yielder: yielder) unless state[:tool_calls].empty?
 
     yielder << Riffer::StreamEvents::TextDone.new(state[:text]) unless state[:text].empty?
-    yielder << Riffer::StreamEvents::ReasoningDone.new(state[:reasoning]) unless state[:reasoning].empty?
+    yield_reasoning_done(yielder, state[:reasoning]) unless state[:reasoning].empty?
     yield_finish_reason(yielder, build_finish_reason(state[:finish_reason], native: state[:native_finish_reason]))
   end
 
@@ -362,7 +363,7 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
           type: "function",
           function: {
             name: encode_tool_name(tc.name),
-            arguments: tc.arguments.is_a?(String) ? tc.arguments : tc.arguments.to_json,
+            arguments: tc.arguments,
           },
         }
       end
@@ -372,7 +373,7 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
   end
 
   #--
-  #: (Riffer::Messages::FilePart) -> Hash[Symbol, untyped]
+  #: (Riffer::Messages::User::FilePart) -> Hash[Symbol, untyped]
   def convert_file_part_to_chat_completions_format(file)
     if file.image?
       image_url = file.url? ? file.url : "data:#{file.media_type};base64,#{file.data}"

data/lib/riffer/providers/token_usage.rb

@@ -4,6 +4,22 @@
 # 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(usage)
+    return usage if usage.is_a?(Riffer::Providers::TokenUsage)
+
+    new(
+      input_tokens: usage[:input_tokens],
+      output_tokens: usage[:output_tokens],
+      cache_write_tokens: usage[:cache_write_tokens],
+      cache_read_tokens: usage[:cache_read_tokens],
+      cost: usage[:cost],
+    )
+  end
+
   # Number of tokens entering the context window, including cache reads and writes.
   attr_reader :input_tokens #: Integer # @dynamic input_tokens
 

data/lib/riffer/skills/config.rb

@@ -67,4 +67,16 @@ class Riffer::Skills::Config
 
     @activate_tool = value
   end
+
+  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(source)
+    super
+    @activate = Riffer::Helpers::DeepDup.call(source.activate)
+  end
 end

data/lib/riffer/stream_events/reasoning_done.rb

@@ -1,22 +1,24 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# 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 # @dynamic content
+  # 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 # @dynamic part
 
   #--
-  #: (String, ?role: Symbol) -> void
-  def initialize(content, role: :assistant)
+  #: (Riffer::Messages::Assistant::ReasoningPart, ?role: Symbol) -> void
+  def initialize(part, role: :assistant)
     super(role: role)
-    @content = content
+    @part = part
   end
 
   #--
   #: () -> Hash[Symbol, untyped]
   def to_h
-    { role: @role, content: @content }
+    { role: @role, part: part.to_h }
   end
 end

data/lib/riffer/tools/runtime.rb

@@ -101,9 +101,9 @@ class Riffer::Tools::Runtime
   end
 
   #--
-  #: (String?) -> untyped
+  #: (String) -> untyped
   def parse_arguments(arguments)
-    return {} if arguments.nil? || arguments.empty?
+    return {} if arguments.empty?
 
     JSON.parse(arguments, symbolize_names: true)
   end
@@ -168,8 +168,7 @@ class Riffer::Tools::Runtime
   def capture_tool_arguments(span, tool_call)
     return unless capture_tool_content?(span)
 
-    arguments = tool_call.arguments
-    span.set_attribute("gen_ai.tool.call.arguments", arguments) if arguments
+    span.set_attribute("gen_ai.tool.call.arguments", tool_call.arguments)
   end
 
   #--

data/lib/riffer/tracing/capture.rb

@@ -71,7 +71,7 @@ module Riffer::Tracing::Capture # :nodoc: all
   end
 
   #--
-  #: (Riffer::Messages::FilePart) -> Hash[Symbol, untyped]
+  #: (Riffer::Messages::User::FilePart) -> Hash[Symbol, untyped]
   def file_part(file)
     part = { type: "file", media_type: file.media_type } #: Hash[Symbol, untyped]
     part[:name] = file.filename if file.filename
@@ -81,10 +81,8 @@ module Riffer::Tracing::Capture # :nodoc: all
   # 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
+  #: (String) -> untyped
   def parse_arguments(arguments)
-    return arguments unless arguments.is_a?(String)
-
     JSON.parse(arguments)
   rescue JSON::ParserError
     arguments

data/lib/riffer/version.rb

@@ -2,5 +2,5 @@
 # rbs_inline: enabled
 
 module Riffer
-  VERSION = "0.47.2" #: String
+  VERSION = "0.48.0" #: String
 end