riffer 0.48.0 → 0.50.0

data/lib/riffer/providers/azure_open_ai.rb

@@ -1,11 +1,7 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Azure OpenAI provider for GPT models hosted on Azure. Requires the +openai+
-# gem. Credentials resolve from config, then +AZURE_OPENAI_API_KEY+ /
-# +AZURE_OPENAI_ENDPOINT+.
 class Riffer::Providers::AzureOpenAI < Riffer::Providers::OpenAI
-  # The GenAI semconv well-known provider name.
   #--
   #: () -> String
   def self.semconv_provider_name
@@ -20,15 +16,21 @@ class Riffer::Providers::AzureOpenAI < Riffer::Providers::OpenAI
     Riffer.config.azure_openai.client
   end
 
-  # Deliberately not compacted: this borrows the OpenAI SDK to talk to Azure, so
-  # omitting an unset argument would let the SDK fall back to +OPENAI_API_KEY+
-  # and +OPENAI_BASE_URL+ — sending Azure traffic, and an OpenAI credential, to
-  # whatever those name. Passing nil raises in the SDK instead.
   #--
   #: () -> untyped
   def build_client
     api_key = Riffer.config.azure_openai.api_key || ENV.fetch("AZURE_OPENAI_API_KEY", nil)
     base_url = Riffer.config.azure_openai.endpoint || ENV.fetch("AZURE_OPENAI_ENDPOINT", nil)
+    # Pass nils rather than omitting them: an omitted argument lets the SDK fall
+    # back to OPENAI_API_KEY / OPENAI_BASE_URL, sending Azure traffic and an
+    # OpenAI credential elsewhere. A nil raises in the SDK instead.
     ::OpenAI::Client.new(api_key: api_key, base_url: base_url)
   end
+
+  # Azure resolves and decrypts reasoning items only within the resource that produced them.
+  #--
+  #: () -> String
+  def reasoning_format
+    "azure-openai-v1"
+  end
 end

data/lib/riffer/providers/base.rb

@@ -3,10 +3,6 @@
 
 require "json"
 
-# Base class for all LLM providers. A template-method flow: subclasses implement
-# the hooks (+build_request_params+, +execute_generate+, +execute_stream+,
-# +extract_token_usage+, +extract_content+, +extract_tool_calls+) and the base
-# class orchestrates them.
 class Riffer::Providers::Base
   # @rbs @current_tools: Array[singleton(Riffer::Tool)]
   # @rbs @current_model: String?
@@ -15,18 +11,12 @@ class Riffer::Providers::Base
 
   WIRE_SEPARATOR = "__" #: String
 
-  # Returns the preferred skill adapter for this provider; override in
-  # subclasses (optionally introspecting +model+) for provider-specific formats.
   #--
   #: (?String?) -> singleton(Riffer::Skills::Adapter)
   def self.skills_adapter(_model = nil)
     Riffer::Skills::MarkdownAdapter
   end
 
-  # Returns the provider name stamped as <tt>gen_ai.provider.name</tt> on trace
-  # spans, ideally a GenAI semconv well-known value. Defaults to the snake_cased
-  # class name rather than raising like the abstract provider methods, so
-  # enabling tracing never breaks an otherwise-working custom provider.
   #--
   #: () -> String
   def self.semconv_provider_name
@@ -34,11 +24,11 @@ class Riffer::Providers::Base
     # later must pick up its real name, not a frozen "unknown".
     class_name = name or return "unknown"
 
+    # A default rather than NotImplementedError, so enabling tracing never
+    # breaks an otherwise-working custom provider.
     @semconv_provider_name ||= Riffer::Helpers::Identifier.derive(class_name.split("::").last)
   end
 
-  # 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::User::FilePart]?, **untyped) -> Riffer::Messages::Assistant
   def generate_text(prompt: nil, system: nil, messages: nil, model: nil, files: nil, **options)
@@ -77,8 +67,6 @@ class Riffer::Providers::Base
     end
   end
 
-  # 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::User::FilePart]?, **untyped) -> Enumerator[Riffer::StreamEvents::Base, void]
   def stream_text(prompt: nil, system: nil, messages: nil, model: nil, files: nil, **options)
@@ -119,21 +107,17 @@ class Riffer::Providers::Base
     Riffer::Helpers::Dependencies.depends_on(gem_name)
   end
 
-  # Returns the client for the current LLM call. A configured client wins,
-  # resolved on every call so a Proc can vary the client by process or
-  # credential lifetime; otherwise the provider builds one from the configured
-  # credentials, memoized for the life of the provider.
   #--
   #: () -> untyped
   def client
     configured = global_client
+    # Resolved on every call, never memoized, so a Proc can vary the client by
+    # process or credential lifetime.
     return Riffer::Helpers::CallOrValue.resolve(configured) if configured
 
     @client ||= build_client
   end
 
-  # Returns the consumer-configured client for this provider; nil when none is
-  # configured, and for providers that take no configuration at all.
   #--
   #: () -> untyped
   def global_client
@@ -218,19 +202,17 @@ class Riffer::Providers::Base
     pricing.rates_for("#{key}/#{model}")
   end
 
-  # Defaults to nil rather than raising — finish reasons are optional, so
-  # providers that don't report one stay valid.
   #--
   #: (untyped) -> Riffer::Providers::FinishReason?
   def extract_finish_reason(_response)
+    # Optional hook, so providers that don't report a finish reason stay valid.
     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)
+    # Optional hook, so providers that don't expose replayable reasoning stay valid.
     []
   end
 
@@ -295,8 +277,6 @@ class Riffer::Providers::Base
     attributes.merge(tag_attributes(options[:tags] || {}))
   end
 
-  # Maps normalized tags to their namespaced span attribute form. An empty map
-  # yields an empty hash, so merging it is a no-op.
   #--
   #: (Hash[String, String]) -> Hash[String, String]
   def tag_attributes(tags)
@@ -358,11 +338,10 @@ 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)
+    # No +format+, so the reasoning persists for display but is never replayed.
     part = Riffer::Messages::Assistant::ReasoningPart.new(type: :text, text: text)
     yielder << Riffer::StreamEvents::ReasoningDone.new(part)
   end

data/lib/riffer/providers/finish_reason.rb

@@ -1,19 +1,13 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Normalized reason an LLM call finished, paired with the provider's raw
-# wire value. +reason+ carries the same meaning for every provider.
 class Riffer::Providers::FinishReason
-  # The normalized vocabulary every provider maps into.
   VALUES = %i[stop length tool_calls content_filter context_window malformed_output error other].freeze #: Array[Symbol]
 
-  # The normalized reason.
   attr_reader :reason #: Symbol # @dynamic reason
 
-  # The provider's raw finish-reason value, when one exists on the wire.
   attr_reader :raw #: String? # @dynamic raw
 
-  # Raises Riffer::ArgumentError when +reason+ is outside VALUES.
   #--
   #: (reason: Symbol, ?raw: String?) -> void
   def initialize(reason:, raw: nil)

data/lib/riffer/providers/gemini/client.rb

@@ -5,18 +5,8 @@ require "json"
 require "net/http"
 require "uri"
 
-# HTTP transport for the Gemini REST API. Riffer builds one from the
-# configured +api_key+ by default; construct your own to tune the HTTP knobs
-# and assign it to <tt>Riffer.config.gemini.client</tt>. Any object
-# implementing +post+ and +post_stream+ with these contracts works there —
-# the class is a default implementation, not a required base.
-#
-#   Riffer.configure do |config|
-#     config.gemini.client = Riffer::Providers::Gemini::Client.new(
-#       api_key: ENV["GEMINI_API_KEY"],
-#       read_timeout: 120
-#     )
-#   end
+# <tt>Riffer.config.gemini.client</tt> accepts any object implementing +post+ and +post_stream+
+# with these contracts; this class is the default, not a required base.
 class Riffer::Providers::Gemini::Client
   # @rbs @api_key: String?
   # @rbs @base_url: String
@@ -43,8 +33,7 @@ class Riffer::Providers::Gemini::Client
     @proxy_port = proxy_port
   end
 
-  # POSTs a JSON body to an API path and returns the parsed response hash.
-  # Raises Riffer::Error when the API responds with a non-success status.
+  # Raises Riffer::Error on a non-success status.
   #--
   #: (String, Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
   def post(path, body)
@@ -54,9 +43,7 @@ class Riffer::Providers::Gemini::Client
     JSON.parse(response.body, symbolize_names: true)
   end
 
-  # POSTs a JSON body to an API path, yielding raw response body chunks as
-  # they arrive. Raises Riffer::Error when the API responds with a
-  # non-success status.
+  # Raises Riffer::Error on a non-success status.
   #--
   #: (String, Hash[Symbol, untyped]) { (String) -> void } -> void
   def post_stream(path, body, &block)

data/lib/riffer/providers/gemini.rb

@@ -4,7 +4,6 @@
 require "json"
 require "securerandom"
 
-# Google Gemini provider for Gemini models via the Gemini REST API.
 class Riffer::Providers::Gemini < Riffer::Providers::Base
   VALID_MODEL_PATTERN = /\A[a-zA-Z0-9._-]+\z/ #: Regexp
 
@@ -29,7 +28,6 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
     "FINISH_REASON_UNSPECIFIED" => :other,
   }.freeze #: Hash[String, Symbol]
 
-  # The GenAI semconv well-known provider name.
   #--
   #: () -> String
   def self.semconv_provider_name
@@ -76,10 +74,8 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
       }]
     end
 
-    # tags propagate to observability only: the Gemini Developer API has no
-    # request labels field (unknown body fields are rejected), so :tags is
-    # stripped here rather than mapped. Native labels would arrive with a Vertex
-    # adapter. See docs/CONFIGURATION.md.
+    # The Gemini Developer API has no request labels field and rejects unknown
+    # body fields, so :tags reach observability only.
     generation_config = options.except(:tools, :structured_output, :tags)
 
     if structured_output
@@ -144,8 +140,6 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
     build_finish_reason(response.dig(:candidates, 0, :finishReason), tool_calls: has_function_call)
   end
 
-  # Gemini reports STOP even when the candidate carries functionCall parts,
-  # so tool-call presence overrides the raw value.
   #--
   #: (String?, tool_calls: bool) -> Riffer::Providers::FinishReason?
   def build_finish_reason(raw_reason, tool_calls:)
@@ -153,18 +147,18 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
 
     raw = raw_reason.to_s
     reason = FINISH_REASONS.fetch(raw, :other)
+    # Gemini reports STOP even when the candidate carries functionCall parts.
     reason = :tool_calls if reason == :stop && tool_calls
     Riffer::Providers::FinishReason.new(reason: reason, raw: raw)
   end
 
-  # Gemini reports thinking tokens outside +candidatesTokenCount+;
-  # TokenUsage's output includes them.
   #--
   #: (Hash[Symbol, untyped]) -> Riffer::Providers::TokenUsage
   def build_token_usage(usage)
     apply_pricing(
       Riffer::Providers::TokenUsage.new(
         input_tokens: usage[:promptTokenCount] || 0,
+        # Gemini reports thinking tokens outside candidatesTokenCount.
         output_tokens: (usage[:candidatesTokenCount] || 0) + (usage[:thoughtsTokenCount] || 0),
         cache_read_tokens: usage[:cachedContentTokenCount],
       ),

data/lib/riffer/providers/mock.rb

@@ -1,41 +1,28 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Mock provider for mocking LLM responses in tests; no external gems required.
 class Riffer::Providers::Mock < Riffer::Providers::Base
   # @rbs @responses: Array[Hash[Symbol, untyped]]
   # @rbs @current_index: Integer
   # @rbs @stubbed_responses: Array[Hash[Symbol, untyped]]
 
-  # Returns the skill adapter for the mock model — XML when the model name
-  # contains +claude+ (mirroring a real Claude provider), else Markdown.
   #--
   #: (?String?) -> singleton(Riffer::Skills::Adapter)
   def self.skills_adapter(model = nil)
+    # Mirrors the adapter a real Claude provider picks.
     return Riffer::Skills::XmlAdapter if model&.include?("claude")
 
     Riffer::Skills::MarkdownAdapter
   end
 
-  # The GenAI semconv well-known provider name.
   #--
   #: () -> String
   def self.semconv_provider_name
     "mock"
   end
 
-  # Array of recorded method calls for assertions.
   attr_reader :calls #: Array[Hash[Symbol, untyped]] # @dynamic calls
 
-  # +responses:+ pre-configures canned responses (same shape as
-  # +#stub_response+) for standalone use; agent tests queue responses on
-  # <tt>agent.provider</tt> via +#stub_response+ instead.
-  #
-  #   Riffer::Providers::Mock.new(responses: [
-  #     {content: "", tool_calls: [{name: "tool_a", arguments: "{}"}]},
-  #     {content: "Final answer"}
-  #   ])
-  #
   #--
   #: (?responses: Array[Hash[Symbol, untyped]]) -> void
   def initialize(responses: [])
@@ -46,16 +33,6 @@ class Riffer::Providers::Mock < Riffer::Providers::Base
     @stubbed_responses = []
   end
 
-  # Stubs the next response; call repeatedly to queue several. +finish_reason+
-  # defaults to +:tool_calls+ when tool calls are present, else +:stop+.
-  #
-  #   provider.stub_response("Hello")
-  #   provider.stub_response("", tool_calls: [{name: "my_tool", arguments: '{"key":"value"}'}])
-  #   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?, ?reasoning: Array[Hash[Symbol, untyped] | Riffer::Messages::Assistant::ReasoningPart]) -> void
   def stub_response(content, tool_calls: [], token_usage: nil, finish_reason: nil, reasoning: [])
@@ -68,8 +45,6 @@ class Riffer::Providers::Mock < Riffer::Providers::Base
     )
   end
 
-  # Clears all stubbed responses.
-  #
   #--
   #: () -> void
   def clear_stubs

data/lib/riffer/providers/open_ai.rb

@@ -1,13 +1,11 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# OpenAI provider for GPT models. Requires the +openai+ gem.
 class Riffer::Providers::OpenAI < Riffer::Providers::Base
   WEB_SEARCH_TOOL_TYPE = "web_search_preview" #: String
 
-  # The Responses API has no finish_reason field. The response +status+ is
-  # the primary signal; an +incomplete+ status is only meaningful together
-  # with <tt>incomplete_details.reason</tt>, so that branch nests one level.
+  # The Responses API has no finish_reason field, and an +incomplete+ status is only meaningful
+  # together with <tt>incomplete_details.reason</tt>.
   FINISH_REASONS = {
     "completed" => :stop,
     "incomplete" => {
@@ -20,7 +18,6 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
     "queued" => :other,
   }.freeze #: Hash[String, Symbol | Hash[String, Symbol]]
 
-  # The GenAI semconv well-known provider name.
   #--
   #: () -> String
   def self.semconv_provider_name
@@ -48,12 +45,11 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
     Riffer.config.openai.client
   end
 
-  # Compacted so an unset value stays absent: the SDK reads +OPENAI_API_KEY+ /
-  # +OPENAI_BASE_URL+ only for a missing argument, and an explicit nil would
-  # suppress that fallback.
   #--
   #: () -> untyped
   def build_client
+    # The SDK falls back to +OPENAI_API_KEY+ / +OPENAI_BASE_URL+ only for a missing argument; an
+    # explicit nil suppresses that fallback.
     ::OpenAI::Client.new(**{
       api_key: Riffer.config.openai.api_key,
       base_url: Riffer.config.openai.base_url,
@@ -80,10 +76,7 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
     } #: Hash[Symbol, untyped]
 
     unless tags.empty?
-      # 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"]
       params[:safety_identifier] = user_id if user_id
     end
@@ -165,7 +158,6 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
     Riffer::Providers::FinishReason.new(reason: reason, raw: detail || status)
   end
 
-  # The nested field that names the cause behind an ambiguous status.
   #--
   #: (untyped, String) -> String?
   def finish_detail(response, status)
@@ -181,16 +173,12 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
   #: (untyped) -> String
   def extract_content(response)
     typed_response = response #: OpenAI::Models::Responses::Response
-    text_content = ""
 
-    typed_response.output.each do |item|
-      next unless item.is_a?(::OpenAI::Models::Responses::ResponseOutputMessage)
-
-      text_block = item.content.find { |c| c.is_a?(::OpenAI::Models::Responses::ResponseOutputText) }
-      text_content = text_block.text if text_block.is_a?(::OpenAI::Models::Responses::ResponseOutputText)
-    end
+    typed_response.output.flat_map do |item|
+      next [] unless item.is_a?(::OpenAI::Models::Responses::ResponseOutputMessage)
 
-    text_content
+      item.content.filter_map { |c| c.text if c.is_a?(::OpenAI::Models::Responses::ResponseOutputText) }
+    end.join
   end
 
   #--
@@ -212,10 +200,47 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
     tool_calls
   end
 
+  #--
+  #: (untyped) -> Array[Riffer::Messages::Assistant::ReasoningPart]
+  def extract_reasoning(response)
+    typed_response = response #: OpenAI::Models::Responses::Response
+    typed_response.output.
+      grep(::OpenAI::Models::Responses::ResponseReasoningItem).
+      flat_map { |item| build_reasoning_parts(item) }
+  end
+
+  # The trailing +:encrypted+ part is always present, even without a payload, so the item's id
+  # survives for replay: with +store+ on, OpenAI resolves the item from the id alone.
+  #--
+  #: (untyped) -> Array[Riffer::Messages::Assistant::ReasoningPart]
+  def build_reasoning_parts(item)
+    typed_item = item #: OpenAI::Models::Responses::ResponseReasoningItem
+    id = typed_item.id
+    summaries = typed_item.summary.map { |summary| build_reasoning_part(type: :summary, id: id, text: summary.text) }
+    texts = (typed_item.content || []).map { |content| build_reasoning_part(type: :text, id: id, text: content.text) }
+
+    [*summaries, *texts, build_reasoning_part(type: :encrypted, id: id, data: typed_item.encrypted_content)]
+  end
+
+  #--
+  #: (type: Symbol, id: String, ?text: String?, ?data: String?) -> Riffer::Messages::Assistant::ReasoningPart
+  def build_reasoning_part(type:, id:, text: nil, data: nil)
+    Riffer::Messages::Assistant::ReasoningPart.new(type: type, text: text, data: data, id: id, format: reasoning_format)
+  end
+
+  # Distinct from OpenRouter's +openai-responses-v1+: reasoning relayed through OpenRouter is
+  # encrypted and stored under OpenRouter's organization, so neither side can replay the other's.
+  #--
+  #: () -> String
+  def reasoning_format
+    "openai-v1"
+  end
+
   #--
   #: (Hash[Symbol, untyped], Riffer::Providers::_EventSink) -> void
   def execute_stream(params, yielder)
     current_state = {
+      text: nil,
       tool_info: {},
     } #: Hash[Symbol, untyped]
 
@@ -231,12 +256,8 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
           end
         when :"response.output_text.delta"
           handle_output_text_delta(event, state: current_state, yielder: yielder)
-        when :"response.output_text.done"
-          handle_output_text_done(event, state: current_state, yielder: yielder)
         when :"response.reasoning_summary_text.delta"
           handle_reasoning_summary_text_delta(event, state: current_state, yielder: yielder)
-        when :"response.reasoning_summary_text.done"
-          handle_reasoning_summary_text_done(event, state: current_state, yielder: yielder)
         when :"response.function_call_arguments.delta"
           handle_function_call_arguments_delta(event, state: current_state, yielder: yielder)
         when :"response.function_call_arguments.done"
@@ -248,16 +269,18 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
         when :"response.web_search_call.completed"
           handle_web_search_status(event, status: "completed", yielder: yielder)
         when :"response.output_item.done"
-          handle_output_item_done_web_search(event, yielder: yielder) if event.item&.type == :web_search_call
+          case event.item&.type
+          when :web_search_call then handle_output_item_done_web_search(event, yielder: yielder)
+          when :reasoning then handle_output_item_done_reasoning(event, yielder: yielder)
+          end
         when :"response.completed", :"response.incomplete", :"response.failed"
           stream_completed = true
           handle_response_finished(event, state: current_state, yielder: yielder)
         end
       end
     ensure
-      # OpenAI SDK does not auto-close the underlying HTTP stream when
-      # iteration is interrupted (raise / fiber cancellation), so the SSE
-      # socket leaks until GC. close is idempotent and a no-op after EOF.
+      # The SDK doesn't close the SSE socket when iteration is interrupted (raise / fiber
+      # cancellation), so it leaks until GC. close is idempotent and a no-op after EOF.
       stream.close
     end
 
@@ -279,27 +302,19 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
   #--
   #: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
   def handle_output_text_delta(event, state:, yielder:)
+    # << avoids += copying the whole buffer per delta (O(n^2)); safe because
+    # nothing reads the buffer before the response finishes and TextDone takes it.
+    state[:text] ||= +""
+    state[:text] << event.delta
     yielder << Riffer::StreamEvents::TextDelta.new(event.delta)
   end
 
-  #--
-  #: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
-  def handle_output_text_done(event, state:, yielder:)
-    yielder << Riffer::StreamEvents::TextDone.new(event.text)
-  end
-
   #--
   #: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
   def handle_reasoning_summary_text_delta(event, state:, yielder:)
     yielder << Riffer::StreamEvents::ReasoningDelta.new(event.delta)
   end
 
-  #--
-  #: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
-  def handle_reasoning_summary_text_done(event, state:, yielder:)
-    yield_reasoning_done(yielder, event.text)
-  end
-
   #--
   #: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
   def handle_function_call_arguments_delta(event, state:, yielder:)
@@ -326,6 +341,8 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
   #--
   #: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
   def handle_response_finished(event, state:, yielder:)
+    yielder << Riffer::StreamEvents::TextDone.new(state[:text]) if state[:text]
+
     response = event.response
     return unless response
 
@@ -349,8 +366,7 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
     action = event.item.action
     case action
     when ::OpenAI::Models::Responses::ResponseFunctionWebSearch::Action::OpenPage
-      # OpenPage carries a url but no query or sources, so it doesn't fit
-      # WebSearchDone — emit as a status notification instead.
+      # OpenPage carries a url but no query or sources, so it doesn't fit WebSearchDone.
       yielder << Riffer::StreamEvents::WebSearchStatus.new("open_page", url: action.url)
     when ::OpenAI::Models::Responses::ResponseFunctionWebSearch::Action::Search
       sources = (action.sources || []).map { |s| { title: nil, url: s.url } }
@@ -358,6 +374,12 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
     end
   end
 
+  #--
+  #: (untyped, yielder: Riffer::Providers::_EventSink) -> void
+  def handle_output_item_done_reasoning(event, yielder:)
+    build_reasoning_parts(event.item).each { |part| yielder << Riffer::StreamEvents::ReasoningDone.new(part) }
+  end
+
   #--
   #: (Array[Riffer::Messages::Base]) -> Array[Hash[Symbol, untyped]]
   def convert_messages_to_openai_format(messages)
@@ -388,12 +410,13 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
   end
 
   #--
-  #: (Riffer::Messages::Assistant) -> (Hash[Symbol, untyped] | Array[Hash[Symbol, untyped]])
+  #: (Riffer::Messages::Assistant) -> Array[Hash[Symbol, untyped]]
   def convert_assistant_to_openai_format(message)
+    items = convert_reasoning_to_openai_format(message.reasoning)
+
     if message.tool_calls.empty?
-      { role: "assistant", content: message.content }
+      items << { role: "assistant", content: message.content }
     else
-      items = [] #: Array[Hash[Symbol, untyped]]
       if message.content && !message.content.empty?
         items << { type: "message", role: "assistant",
                    content: message.content, }
@@ -406,8 +429,33 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
           arguments: tc.arguments,
         }
       end
-      items
     end
+
+    items
+  end
+
+  #--
+  #: (Array[Riffer::Messages::Assistant::ReasoningPart]) -> Array[Hash[Symbol, untyped]]
+  def convert_reasoning_to_openai_format(reasoning)
+    reasoning.
+      select { |part| part.format == reasoning_format }.
+      chunk_while { |a, b| a.id == b.id }.
+      map { |parts| convert_reasoning_item_to_openai_format(parts) }
+  end
+
+  #--
+  #: (Array[Riffer::Messages::Assistant::ReasoningPart]) -> Hash[Symbol, untyped]
+  def convert_reasoning_item_to_openai_format(parts)
+    summary = parts.filter_map { |part| { type: "summary_text", text: part.text } if part.type == :summary }
+    content = parts.filter_map { |part| { type: "reasoning_text", text: part.text } if part.type == :text }
+
+    {
+      type: "reasoning",
+      id: parts.first&.id,
+      summary: summary,
+      content: content.empty? ? nil : content,
+      encrypted_content: parts.find { |part| part.type == :encrypted }&.data,
+    }.compact
   end
 
   #--