riffer 0.47.1 → 0.48.0

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"]
@@ -218,6 +219,8 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
       tool_info: {},
     } #: Hash[Symbol, untyped]
 
+    stream_completed = false
+
     stream = client.responses.stream(params)
     begin
       stream.each do |event|
@@ -247,6 +250,7 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
         when :"response.output_item.done"
           handle_output_item_done_web_search(event, yielder: yielder) if event.item&.type == :web_search_call
         when :"response.completed", :"response.incomplete", :"response.failed"
+          stream_completed = true
           handle_response_finished(event, state: current_state, yielder: yielder)
         end
       end
@@ -256,6 +260,11 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
       # socket leaks until GC. close is idempotent and a no-op after EOF.
       stream.close
     end
+
+    return if stream_completed
+
+    raise Riffer::IncompleteStreamError,
+          "OpenAI Responses stream ended without a response.completed, response.incomplete, or response.failed event"
   end
 
   #--
@@ -288,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
 
   #--
@@ -394,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
@@ -402,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/repository.rb

@@ -27,13 +27,9 @@ module Riffer::Providers::Repository
   #
   #   Riffer::Providers::Repository.register(:jane) { MyApp::JaneProvider }
   #
-  # Raises Riffer::ArgumentError when called without a block.
-  #
   #--
   #: ((String | Symbol)) { () -> singleton(Riffer::Providers::Base) } -> void
   def register(identifier, &factory)
-    raise Riffer::ArgumentError, "register requires a block returning a provider class" unless factory
-
     @registrations[identifier.to_sym] = factory
     @key_for = nil
   end

data/lib/riffer/providers/token_usage.rb

@@ -4,20 +4,36 @@
 # 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
+  attr_reader :input_tokens #: Integer # @dynamic input_tokens
 
   # Number of tokens generated by the model, including reasoning/thinking tokens.
-  attr_reader :output_tokens #: Integer
+  attr_reader :output_tokens #: Integer # @dynamic output_tokens
 
   # Subset of +input_tokens+ written to the provider's prompt cache, when the provider reports it.
-  attr_reader :cache_write_tokens #: Integer?
+  attr_reader :cache_write_tokens #: Integer? # @dynamic cache_write_tokens
 
   # Subset of +input_tokens+ read from the provider's prompt cache, when the provider reports it.
-  attr_reader :cache_read_tokens #: Integer?
+  attr_reader :cache_read_tokens #: Integer? # @dynamic cache_read_tokens
 
   # Cost of the call, set when the model is priced. For observability, not billing.
-  attr_reader :cost #: Float?
+  attr_reader :cost #: Float? # @dynamic cost
 
   #--
   #: (input_tokens: Integer, output_tokens: Integer, ?cache_write_tokens: Integer?, ?cache_read_tokens: Integer?, ?cost: Float?) -> void

data/lib/riffer/skills/adapter.rb

@@ -7,7 +7,7 @@
 # for the rendered output.
 class Riffer::Skills::Adapter
   # The activation tool class for this adapter.
-  attr_reader :skill_activate_tool #: singleton(Riffer::Tool)
+  attr_reader :skill_activate_tool #: singleton(Riffer::Tool) # @dynamic skill_activate_tool
 
   #--
   #: (skill_activate_tool: singleton(Riffer::Tool)) -> void

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/skills/context.rb

@@ -11,13 +11,13 @@ class Riffer::Skills::Context
   # @rbs @preactivated: Array[String]
 
   # Skill catalog indexed by name.
-  attr_reader :skills #: Hash[String, Riffer::Skills::Frontmatter]
+  attr_reader :skills #: Hash[String, Riffer::Skills::Frontmatter] # @dynamic skills
 
   # The skill adapter used for this context.
-  attr_reader :adapter #: Riffer::Skills::Adapter
+  attr_reader :adapter #: Riffer::Skills::Adapter # @dynamic adapter
 
   # Optional callback invoked when a skill is first activated.
-  attr_accessor :on_activate #: (^(String) -> void)?
+  attr_accessor :on_activate #: (^(String) -> void)? # @dynamic on_activate, on_activate=
 
   #--
   #: (backend: Riffer::Skills::Backend, skills: Hash[String, Riffer::Skills::Frontmatter], adapter: Riffer::Skills::Adapter) -> void
@@ -106,10 +106,7 @@ class Riffer::Skills::Context
   #--
   #: (String) -> bool
   def model_invocable?(name)
-    skill = skills[name]
-    return false unless skill
-
-    !skill.disable_model_invocation
+    skills.key?(name) && !skills.fetch(name).disable_model_invocation
   end
 
   # Returns whether any skill is available for the model to activate.

data/lib/riffer/skills/filesystem_backend.rb

@@ -53,8 +53,7 @@ class Riffer::Skills::FilesystemBackend < Riffer::Skills::Backend
   def read_skill(name)
     list_skills unless @skills_cache
     cache = @skills_cache #: Hash[String, String]
-    dir = cache[name]
-    raise Riffer::ArgumentError, "Skill not found: '#{name}'" unless dir
+    dir = cache.fetch(name) { raise Riffer::ArgumentError, "Skill not found: '#{name}'" }
 
     _, body = Riffer::Skills::Frontmatter.parse(File.read(File.join(dir, SKILL_FILENAME)))
     body

data/lib/riffer/skills/frontmatter.rb

@@ -13,19 +13,19 @@ class Riffer::Skills::Frontmatter
   MAX_DESCRIPTION_LENGTH = 1024 #: Integer
 
   # The skill name (1-64 chars, lowercase alphanumeric and hyphens).
-  attr_reader :name #: String
+  attr_reader :name #: String # @dynamic name
 
   # The skill description (1-1024 chars).
-  attr_reader :description #: String
+  attr_reader :description #: String # @dynamic description
 
   # Whether the skill opts out of model-driven activation. Hidden from the
   # catalog and rejected at model activation; still reachable via programmatic
   # activation.
-  attr_reader :disable_model_invocation #: bool
+  attr_reader :disable_model_invocation #: bool # @dynamic disable_model_invocation
 
   # Metadata from the spec's +metadata+ field plus any unrecognized top-level
   # keys.
-  attr_reader :metadata #: Hash[Symbol, untyped]
+  attr_reader :metadata #: Hash[Symbol, untyped] # @dynamic metadata
 
   # Parses a raw SKILL.md string into a +[Frontmatter, body]+ pair — public so
   # custom backends needn't reimplement parsing. Raises Riffer::ArgumentError

data/lib/riffer/skills/xml_adapter.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-require "cgi"
+require "cgi/escape"
 
 # Renders a skill catalog as XML for the system prompt, optimized for
 # Anthropic/Claude.

data/lib/riffer/stream_events/base.rb

@@ -4,7 +4,7 @@
 # Base class for all streaming events. Subclasses must implement +to_h+.
 class Riffer::StreamEvents::Base
   # The message role (typically :assistant).
-  attr_reader :role #: Symbol
+  attr_reader :role #: Symbol # @dynamic role
 
   #--
   #: (?role: Symbol) -> void

data/lib/riffer/stream_events/finish_reason_done.rb

@@ -5,10 +5,10 @@
 # stream; no ordering guarantee relative to TokenUsageDone.
 class Riffer::StreamEvents::FinishReasonDone < Riffer::StreamEvents::Base
   # The normalized finish reason (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, when one exists on the wire.
-  attr_reader :raw_finish_reason #: String?
+  attr_reader :raw_finish_reason #: String? # @dynamic raw_finish_reason
 
   # Raises Riffer::ArgumentError when +finish_reason+ is outside the
   # normalized vocabulary.

data/lib/riffer/stream_events/guardrail_modification.rb

@@ -4,7 +4,7 @@
 # Emitted when a guardrail transforms data during streaming.
 class Riffer::StreamEvents::GuardrailModification < Riffer::StreamEvents::Base
   # The modification record.
-  attr_reader :modification #: Riffer::Guardrails::Modification
+  attr_reader :modification #: Riffer::Guardrails::Modification # @dynamic modification
 
   #--
   #: (Riffer::Guardrails::Modification, ?role: Symbol) -> void

data/lib/riffer/stream_events/guardrail_tripwire.rb

@@ -4,7 +4,7 @@
 # Emitted when a guardrail blocks execution during streaming.
 class Riffer::StreamEvents::GuardrailTripwire < Riffer::StreamEvents::Base
   # The tripwire containing block details.
-  attr_reader :tripwire #: Riffer::Guardrails::Tripwire
+  attr_reader :tripwire #: Riffer::Guardrails::Tripwire # @dynamic tripwire
 
   #--
   #: (Riffer::Guardrails::Tripwire, ?role: Symbol) -> void

data/lib/riffer/stream_events/interrupt.rb

@@ -5,11 +5,11 @@
 # +:riffer_interrupt+.
 class Riffer::StreamEvents::Interrupt < Riffer::StreamEvents::Base
   # The reason provided with the interrupt, if any.
-  attr_reader :reason #: (String | Symbol)?
+  attr_reader :reason #: (String | Symbol)? # @dynamic reason
 
   # Call ids of tool_use blocks riffer filled with placeholder results when the
   # interrupt fired (only when history healing is on).
-  attr_reader :healed_tool_call_ids #: Array[String]
+  attr_reader :healed_tool_call_ids #: Array[String] # @dynamic healed_tool_call_ids
 
   #--
   #: (?reason: (String | Symbol)?, ?healed_tool_call_ids: Array[String]) -> void

data/lib/riffer/stream_events/reasoning_delta.rb

@@ -5,7 +5,7 @@
 # providers that support reasoning (e.g. OpenAI with the reasoning option).
 class Riffer::StreamEvents::ReasoningDelta < Riffer::StreamEvents::Base
   # The incremental reasoning content.
-  attr_reader :content #: String
+  attr_reader :content #: String # @dynamic content
 
   #--
   #: (String, ?role: Symbol) -> void

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
+  # 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/stream_events/skill_activation.rb

@@ -5,7 +5,7 @@
 # callback when the LLM calls the activation tool.
 class Riffer::StreamEvents::SkillActivation < Riffer::StreamEvents::Base
   # The activated skill name.
-  attr_reader :name #: String
+  attr_reader :name #: String # @dynamic name
 
   #--
   #: (String, ?role: Symbol) -> void

data/lib/riffer/stream_events/text_delta.rb

@@ -4,7 +4,7 @@
 # Represents an incremental text chunk during streaming.
 class Riffer::StreamEvents::TextDelta < Riffer::StreamEvents::Base
   # The incremental text content.
-  attr_reader :content #: String
+  attr_reader :content #: String # @dynamic content
 
   #--
   #: (String, ?role: Symbol) -> void

data/lib/riffer/stream_events/text_done.rb

@@ -4,7 +4,7 @@
 # Represents completed text generation during streaming.
 class Riffer::StreamEvents::TextDone < Riffer::StreamEvents::Base
   # The complete text content.
-  attr_reader :content #: String
+  attr_reader :content #: String # @dynamic content
 
   #--
   #: (String, ?role: Symbol) -> void

data/lib/riffer/stream_events/token_usage_done.rb

@@ -4,7 +4,7 @@
 # Final token usage for the response, emitted when the LLM finishes.
 class Riffer::StreamEvents::TokenUsageDone < Riffer::StreamEvents::Base
   # The token usage data for this response.
-  attr_reader :token_usage #: Riffer::Providers::TokenUsage
+  attr_reader :token_usage #: Riffer::Providers::TokenUsage # @dynamic token_usage
 
   #--
   #: (token_usage: Riffer::Providers::TokenUsage, ?role: Symbol) -> void

data/lib/riffer/stream_events/tool_call_delta.rb

@@ -5,13 +5,13 @@
 # streaming.
 class Riffer::StreamEvents::ToolCallDelta < Riffer::StreamEvents::Base
   # The tool call item identifier.
-  attr_reader :item_id #: String
+  attr_reader :item_id #: String # @dynamic item_id
 
   # The tool name (may only be present in first delta).
-  attr_reader :name #: String?
+  attr_reader :name #: String? # @dynamic name
 
   # The incremental arguments JSON fragment.
-  attr_reader :arguments_delta #: String
+  attr_reader :arguments_delta #: String # @dynamic arguments_delta
 
   #--
   #: (item_id: String, arguments_delta: String, ?name: String?, ?role: Symbol) -> void

data/lib/riffer/stream_events/tool_call_done.rb

@@ -4,16 +4,16 @@
 # Represents a completed tool call during streaming.
 class Riffer::StreamEvents::ToolCallDone < Riffer::StreamEvents::Base
   # The tool call item identifier.
-  attr_reader :item_id #: String
+  attr_reader :item_id #: String # @dynamic item_id
 
   # The call identifier for response matching.
-  attr_reader :call_id #: String
+  attr_reader :call_id #: String # @dynamic call_id
 
   # The tool name.
-  attr_reader :name #: String
+  attr_reader :name #: String # @dynamic name
 
   # The complete arguments JSON string.
-  attr_reader :arguments #: String
+  attr_reader :arguments #: String # @dynamic arguments
 
   #--
   #: (item_id: String, call_id: String, name: String, arguments: String, ?role: Symbol) -> void

data/lib/riffer/stream_events/web_search_done.rb

@@ -4,10 +4,10 @@
 # The result of a completed server-side web search during streaming.
 class Riffer::StreamEvents::WebSearchDone < Riffer::StreamEvents::Base
   # The search query used.
-  attr_reader :query #: String
+  attr_reader :query #: String # @dynamic query
 
   # The search result sources with title and url.
-  attr_reader :sources #: Array[Hash[Symbol, String?]]
+  attr_reader :sources #: Array[Hash[Symbol, String?]] # @dynamic sources
 
   #--
   #: (String, ?sources: Array[Hash[Symbol, String?]], ?role: Symbol) -> void

data/lib/riffer/stream_events/web_search_status.rb

@@ -5,13 +5,13 @@
 # progresses.
 class Riffer::StreamEvents::WebSearchStatus < Riffer::StreamEvents::Base
   # The web search status ("in_progress", "searching", "completed", "open_page").
-  attr_reader :status #: String
+  attr_reader :status #: String # @dynamic status
 
   # The URL being fetched (present for "open_page" status).
-  attr_reader :url #: String?
+  attr_reader :url #: String? # @dynamic url
 
   # The search query (present when available during status changes).
-  attr_reader :query #: String?
+  attr_reader :query #: String? # @dynamic query
 
   #--
   #: (String, ?url: String?, ?query: String?, ?role: Symbol) -> void

data/lib/riffer/tools/response.rb

@@ -20,17 +20,17 @@ class Riffer::Tools::Response
   VALID_FORMATS = %i[text json].freeze #: Array[Symbol]
 
   # The response content.
-  attr_reader :content #: String
+  attr_reader :content #: String # @dynamic content
 
   # The error message, or +nil+ on success.
-  attr_reader :error_message #: String?
+  attr_reader :error_message #: String? # @dynamic error_message
 
   # The error type, or +nil+ on success.
-  attr_reader :error_type #: Symbol?
+  attr_reader :error_type #: Symbol? # @dynamic error_type
 
   # The exception an unhandled failure was folded from, or +nil+. Kept out of
   # every serialized form so it never reaches an LLM or a message payload.
-  attr_reader :exception #: Exception?
+  attr_reader :exception #: Exception? # @dynamic exception
 
   # Creates a success response.
   #

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/tracing/stream_recorder.rb

@@ -8,17 +8,17 @@ class Riffer::Tracing::StreamRecorder # :nodoc: all
   # @rbs @clock: ^() -> Float
   # @rbs @started_at: Float
 
-  attr_reader :token_usage #: Riffer::Providers::TokenUsage?
+  attr_reader :token_usage #: Riffer::Providers::TokenUsage? # @dynamic token_usage
 
-  attr_reader :time_to_first_chunk #: Float?
+  attr_reader :time_to_first_chunk #: Float? # @dynamic time_to_first_chunk
 
-  attr_reader :finish_reason #: Symbol?
+  attr_reader :finish_reason #: Symbol? # @dynamic finish_reason
 
-  attr_reader :raw_finish_reason #: String?
+  attr_reader :raw_finish_reason #: String? # @dynamic raw_finish_reason
 
-  attr_reader :content #: String?
+  attr_reader :content #: String? # @dynamic content
 
-  attr_reader :tool_calls #: Array[Riffer::Messages::Assistant::ToolCall]
+  attr_reader :tool_calls #: Array[Riffer::Messages::Assistant::ToolCall] # @dynamic tool_calls
 
   #--
   #: (Enumerator::Yielder, ?clock: ^() -> Float) -> void

data/lib/riffer/version.rb

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

data/lib/riffer.rb

@@ -41,6 +41,13 @@ module Riffer
   # Raised when a tool encounters an expected execution error.
   class ToolExecutionError < Error; end
 
+  # Raised when a provider's stream ends before its terminal event (Bedrock's
+  # messageStop, Anthropic's message_stop, OpenAI's response.completed /
+  # incomplete / failed), so a truncated or empty response is never returned
+  # as a complete message. Events already yielded were delivered; the
+  # request is safe to retry.
+  class IncompleteStreamError < Error; end
+
   # Base error for a file attachment that can't be resolved for the provider.
   class FileError < Error; end