riffer 0.32.1 → 0.34.0

data/sig/generated/riffer/providers/open_ai.rbs

@@ -4,6 +4,11 @@
 class Riffer::Providers::OpenAI < Riffer::Providers::Base
   WEB_SEARCH_TOOL_TYPE: String
 
+  # The GenAI semconv well-known provider name.
+  # --
+  # : () -> String
+  def self.semconv_provider_name: () -> String
+
   # --
   # : (**untyped) -> void
   def initialize: (**untyped) -> void
@@ -22,6 +27,23 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
   # : (untyped) -> Riffer::Providers::TokenUsage?
   def extract_token_usage: (untyped) -> Riffer::Providers::TokenUsage?
 
+  # --
+  # : (untyped) -> Riffer::Providers::TokenUsage
+  def build_token_usage: (untyped) -> Riffer::Providers::TokenUsage
+
+  # --
+  # : (untyped) -> Riffer::Providers::FinishReason?
+  def extract_finish_reason: (untyped) -> Riffer::Providers::FinishReason?
+
+  # The Responses API reports no finish_reason field, so one is derived.
+  # --
+  # : (untyped) -> Riffer::Providers::FinishReason?
+  def build_finish_reason: (untyped) -> Riffer::Providers::FinishReason?
+
+  # --
+  # : (untyped) -> Riffer::Providers::FinishReason
+  def incomplete_finish_reason: (untyped) -> Riffer::Providers::FinishReason
+
   # --
   # : (untyped) -> String
   def extract_content: (untyped) -> String
@@ -31,48 +53,48 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
   def extract_tool_calls: (untyped) -> Array[Riffer::Messages::Assistant::ToolCall]
 
   # --
-  # : (Hash[Symbol, untyped], Enumerator::Yielder) -> void
-  def execute_stream: (Hash[Symbol, untyped], Enumerator::Yielder) -> void
+  # : (Hash[Symbol, untyped], Riffer::Providers::_EventSink) -> void
+  def execute_stream: (Hash[Symbol, untyped], Riffer::Providers::_EventSink) -> void
 
   # --
-  # : (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
-  def handle_output_item_added_function_call: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  # : (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
+  def handle_output_item_added_function_call: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
 
   # --
-  # : (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
-  def handle_output_text_delta: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  # : (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
+  def handle_output_text_delta: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
 
   # --
-  # : (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
-  def handle_output_text_done: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  # : (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
+  def handle_output_text_done: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
 
   # --
-  # : (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
-  def handle_reasoning_summary_text_delta: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  # : (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
+  def handle_reasoning_summary_text_delta: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
 
   # --
-  # : (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
-  def handle_reasoning_summary_text_done: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  # : (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
+  def handle_reasoning_summary_text_done: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
 
   # --
-  # : (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
-  def handle_function_call_arguments_delta: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  # : (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
+  def handle_function_call_arguments_delta: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
 
   # --
-  # : (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
-  def handle_function_call_arguments_done: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  # : (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
+  def handle_function_call_arguments_done: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
 
   # --
-  # : (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
-  def handle_response_completed: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  # : (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
+  def handle_response_finished: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
 
   # --
-  # : (untyped, status: String, yielder: Enumerator::Yielder) -> void
-  def handle_web_search_status: (untyped, status: String, yielder: Enumerator::Yielder) -> void
+  # : (untyped, status: String, yielder: Riffer::Providers::_EventSink) -> void
+  def handle_web_search_status: (untyped, status: String, yielder: Riffer::Providers::_EventSink) -> void
 
   # --
-  # : (untyped, yielder: Enumerator::Yielder) -> void
-  def handle_output_item_done_web_search: (untyped, yielder: Enumerator::Yielder) -> void
+  # : (untyped, yielder: Riffer::Providers::_EventSink) -> void
+  def handle_output_item_done_web_search: (untyped, yielder: Riffer::Providers::_EventSink) -> void
 
   # --
   # : (Array[Riffer::Messages::Base]) -> Array[Hash[Symbol, untyped]]

data/sig/generated/riffer/providers/open_router.rbs

@@ -7,6 +7,13 @@
 class Riffer::Providers::OpenRouter < Riffer::Providers::Base
   BASE_URL: String
 
+  FINISH_REASONS: Hash[String, Symbol]
+
+  # The GenAI semconv well-known provider name.
+  # --
+  # : () -> String
+  def self.semconv_provider_name: () -> String
+
   # --
   # : (?api_key: String?, **untyped) -> void
   def initialize: (?api_key: String?, **untyped) -> void
@@ -25,6 +32,18 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
   # : (untyped) -> Riffer::Providers::TokenUsage?
   def extract_token_usage: (untyped) -> Riffer::Providers::TokenUsage?
 
+  # --
+  # : (untyped) -> Riffer::Providers::TokenUsage
+  def build_token_usage: (untyped) -> Riffer::Providers::TokenUsage
+
+  # --
+  # : (untyped) -> Riffer::Providers::FinishReason?
+  def extract_finish_reason: (untyped) -> Riffer::Providers::FinishReason?
+
+  # --
+  # : (untyped) -> Riffer::Providers::FinishReason?
+  def build_finish_reason: (untyped) -> Riffer::Providers::FinishReason?
+
   # --
   # : (untyped) -> String
   def extract_content: (untyped) -> String
@@ -34,28 +53,28 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
   def extract_tool_calls: (untyped) -> Array[Riffer::Messages::Assistant::ToolCall]
 
   # --
-  # : (Hash[Symbol, untyped], Enumerator::Yielder) -> void
-  def execute_stream: (Hash[Symbol, untyped], Enumerator::Yielder) -> void
+  # : (Hash[Symbol, untyped], Riffer::Providers::_EventSink) -> void
+  def execute_stream: (Hash[Symbol, untyped], Riffer::Providers::_EventSink) -> void
 
   # --
-  # : (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
-  def handle_stream_chunk: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  # : (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
+  def handle_stream_chunk: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
 
   # --
-  # : (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
-  def handle_text_delta: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  # : (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
+  def handle_text_delta: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
 
   # --
-  # : (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
-  def handle_reasoning_delta: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  # : (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
+  def handle_reasoning_delta: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
 
   # --
-  # : (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
-  def handle_tool_call_deltas: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  # : (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
+  def handle_tool_call_deltas: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
 
   # --
-  # : (state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
-  def emit_tool_call_done_events: (state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  # : (state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
+  def emit_tool_call_done_events: (state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
 
   # --
   # : (untyped) -> bool

data/sig/generated/riffer/providers/repository.rbs

@@ -2,6 +2,8 @@
 
 # Registry for finding provider classes by identifier.
 module Riffer::Providers::Repository
+  @key_for: Hash[singleton(Riffer::Providers::Base), Symbol]?
+
   REPO: Hash[Symbol, ^() -> singleton(Riffer::Providers::Base)]
 
   # Finds a provider class by identifier.
@@ -9,4 +11,9 @@ module Riffer::Providers::Repository
   # --
   # : ((String | Symbol)) -> singleton(Riffer::Providers::Base)?
   def find: (String | Symbol) -> singleton(Riffer::Providers::Base)?
+
+  # Returns the registry identifier for a provider class, or nil when unregistered.
+  # --
+  # : (singleton(Riffer::Providers::Base)) -> Symbol?
+  def key_for: (singleton(Riffer::Providers::Base)) -> Symbol?
 end

data/sig/generated/riffer/providers/token_usage.rbs

@@ -1,22 +1,26 @@
 # Generated from lib/riffer/providers/token_usage.rb with RBS::Inline
 
-# Represents token usage data from an LLM API call.
+# Normalized token usage for an LLM API call. Buckets carry the same
+# meaning for every provider.
 class Riffer::Providers::TokenUsage
-  # Number of tokens in the input/prompt.
+  # Number of tokens entering the context window, including cache reads and writes.
   attr_reader input_tokens: Integer
 
-  # Number of tokens in the output/response.
+  # Number of tokens generated by the model, including reasoning/thinking tokens.
   attr_reader output_tokens: Integer
 
-  # Number of tokens written to cache, when the provider reports it.
+  # Subset of +input_tokens+ written to the provider's prompt cache, when the provider reports it.
   attr_reader cache_write_tokens: Integer?
 
-  # Number of tokens read from cache, when the provider reports it.
+  # Subset of +input_tokens+ read from the provider's prompt cache, when the provider reports it.
   attr_reader cache_read_tokens: Integer?
 
+  # Cost of the call, set when the model is priced. For observability, not billing.
+  attr_reader cost: Float?
+
   # --
-  # : (input_tokens: Integer, output_tokens: Integer, ?cache_write_tokens: Integer?, ?cache_read_tokens: Integer?) -> void
-  def initialize: (input_tokens: Integer, output_tokens: Integer, ?cache_write_tokens: Integer?, ?cache_read_tokens: Integer?) -> void
+  # : (input_tokens: Integer, output_tokens: Integer, ?cache_write_tokens: Integer?, ?cache_read_tokens: Integer?, ?cost: Float?) -> void
+  def initialize: (input_tokens: Integer, output_tokens: Integer, ?cache_write_tokens: Integer?, ?cache_read_tokens: Integer?, ?cost: Float?) -> void
 
   # Returns the total number of tokens (input + output).
   #
@@ -30,14 +34,20 @@ class Riffer::Providers::TokenUsage
   # : (Riffer::Providers::TokenUsage) -> Riffer::Providers::TokenUsage
   def +: (Riffer::Providers::TokenUsage) -> Riffer::Providers::TokenUsage
 
-  # Converts the token usage to a hash; cache tokens are omitted when nil.
+  # Converts the token usage to a hash; cache tokens and cost are omitted when nil.
   # --
-  # : () -> Hash[Symbol, Integer]
-  def to_h: () -> Hash[Symbol, Integer]
+  # : () -> Hash[Symbol, (Integer | Float)]
+  def to_h: () -> Hash[Symbol, Integer | Float]
 
   private
 
   # --
   # : (Integer?, Integer?) -> Integer?
   def add_nullable: (Integer?, Integer?) -> Integer?
+
+  # nil is absorbing, not zero: one unpriced call makes the run total nil
+  # rather than silently under-reporting.
+  # --
+  # : (Float?, Float?) -> Float?
+  def add_cost: (Float?, Float?) -> Float?
 end

data/sig/generated/riffer/skills/activate_tool.rbs

@@ -3,8 +3,14 @@
 # Tool the LLM calls to activate a skill and receive its instructions;
 # registered automatically when an agent has skills configured.
 class Riffer::Skills::ActivateTool < Riffer::Tool
-  # Activates a skill by name and returns its body.
+  # Activates a skill by name and returns its wrapped body, or a short pointer when the skill is already active.
   # --
   # : (context: Riffer::Agent::Context?, name: String) -> Riffer::Tools::Response
   def call: (context: Riffer::Agent::Context?, name: String) -> Riffer::Tools::Response
+
+  private
+
+  # --
+  # : (String) -> String
+  def already_active_message: (String) -> String
 end

data/sig/generated/riffer/skills/adapter.rbs

@@ -16,4 +16,14 @@ class Riffer::Skills::Adapter
   # --
   # : (Array[Riffer::Skills::Frontmatter]) -> String
   def render_catalog: (Array[Riffer::Skills::Frontmatter]) -> String
+
+  # Renders an activated skill body wrapped in identifying tags.
+  # --
+  # : (Riffer::Skills::Frontmatter, String) -> String
+  def render_activation: (Riffer::Skills::Frontmatter, String) -> String
+
+  # The behavioral instructions rendered alongside the catalog.
+  # --
+  # : () -> String
+  def catalog_instructions: () -> String
 end

data/sig/generated/riffer/skills/context.rbs

@@ -1,12 +1,16 @@
 # Generated from lib/riffer/skills/context.rb with RBS::Inline
 
 # Skills context for an agent generation cycle — coordinates discovery,
-# activation, and prompt rendering, caching activations to avoid redundant
+# activation, and prompt rendering, caching skill bodies to avoid redundant
 # backend reads. Exposed to tools via <tt>context.skills</tt>.
 class Riffer::Skills::Context
-  @backend: Riffer::Skills::Backend
+  @preactivated: Array[String]
+
+  @activated: Array[String]
 
-  @activated: Hash[String, String]
+  @bodies: Hash[String, String]
+
+  @backend: Riffer::Skills::Backend
 
   # Skill catalog indexed by name.
   attr_reader skills: Hash[String, Riffer::Skills::Frontmatter]
@@ -15,12 +19,20 @@ class Riffer::Skills::Context
   attr_reader adapter: Riffer::Skills::Adapter
 
   # Optional callback invoked when a skill is first activated.
-  attr_writer on_activate: (^(String) -> void)?
+  attr_accessor on_activate: (^(String) -> void)?
 
   # --
   # : (backend: Riffer::Skills::Backend, skills: Hash[String, Riffer::Skills::Frontmatter], adapter: Riffer::Skills::Adapter) -> void
   def initialize: (backend: Riffer::Skills::Backend, skills: Hash[String, Riffer::Skills::Frontmatter], adapter: Riffer::Skills::Adapter) -> void
 
+  # Returns a skill's body without recording an activation.
+  #
+  # Raises Riffer::ArgumentError if the skill is not in the catalog.
+  #
+  # --
+  # : (String) -> String
+  def read: (String) -> String
+
   # Activates a skill by name. Returns the cached body on re-activation.
   #
   # Raises Riffer::ArgumentError if the skill is not in the catalog.
@@ -29,6 +41,32 @@ class Riffer::Skills::Context
   # : (String) -> String
   def activate: (String) -> String
 
+  # Activates a skill and returns its body wrapped for injection as a user
+  # message.
+  #
+  # Raises Riffer::ArgumentError if the skill is not in the catalog.
+  #
+  # --
+  # : (String) -> String
+  def activation_prompt: (String) -> String
+
+  # Activates a skill whose body renders in the system prompt rather than the
+  # conversation.
+  #
+  # Raises Riffer::ArgumentError if the skill is not in the catalog.
+  #
+  # --
+  # : (String) -> void
+  def preactivate: (String) -> void
+
+  # Clears a skill's activation so the next activation is treated as the first.
+  #
+  # Raises Riffer::ArgumentError if the skill is not in the catalog.
+  #
+  # --
+  # : (String) -> void
+  def deactivate: (String) -> void
+
   # Returns whether a skill has been activated.
   #
   # --

data/sig/generated/riffer/stream_events/finish_reason_done.rbs

@@ -0,0 +1,21 @@
+# Generated from lib/riffer/stream_events/finish_reason_done.rb with RBS::Inline
+
+# Normalized reason the LLM finished, emitted once near the end of the
+# 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
+
+  # The provider's raw finish-reason value, when one exists on the wire.
+  attr_reader raw_finish_reason: String?
+
+  # Raises Riffer::ArgumentError when +finish_reason+ is outside the
+  # normalized vocabulary.
+  # --
+  # : (finish_reason: Symbol, ?raw_finish_reason: String?, ?role: Symbol) -> void
+  def initialize: (finish_reason: Symbol, ?raw_finish_reason: String?, ?role: Symbol) -> void
+
+  # --
+  # : () -> Hash[Symbol, untyped]
+  def to_h: () -> Hash[Symbol, untyped]
+end

data/sig/generated/riffer/tools/runtime.rbs

@@ -35,6 +35,10 @@ class Riffer::Tools::Runtime
 
   private
 
+  # --
+  # : (Riffer::Messages::Assistant::ToolCall) { () -> Riffer::Tools::Response } -> [Riffer::Messages::Assistant::ToolCall, Riffer::Tools::Response]
+  def instrument_tool_call: (Riffer::Messages::Assistant::ToolCall) { () -> Riffer::Tools::Response } -> [ Riffer::Messages::Assistant::ToolCall, Riffer::Tools::Response ]
+
   # --
   # : (Riffer::Messages::Assistant::ToolCall, tools: Array[singleton(Riffer::Tool)], context: Riffer::Agent::Context?, ?assistant_message: Riffer::Messages::Assistant?) -> Riffer::Tools::Response
   def dispatch_tool_call: (Riffer::Messages::Assistant::ToolCall, tools: Array[singleton(Riffer::Tool)], context: Riffer::Agent::Context?, ?assistant_message: Riffer::Messages::Assistant?) -> Riffer::Tools::Response
@@ -42,4 +46,35 @@ class Riffer::Tools::Runtime
   # --
   # : (String?) -> Hash[Symbol, untyped]
   def parse_arguments: (String?) -> Hash[Symbol, untyped]
+
+  # Emitted outside +around_tool_call+ so host enrichment spans nest beneath it.
+  # --
+  # : [R] (Riffer::Messages::Assistant::ToolCall) { ((Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span)) -> R } -> R
+  def in_tool_span: [R] (Riffer::Messages::Assistant::ToolCall) { (Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span) -> R } -> R
+
+  # --
+  # : (Riffer::Messages::Assistant::ToolCall) -> Hash[String, untyped]
+  def tool_span_attributes: (Riffer::Messages::Assistant::ToolCall) -> Hash[String, untyped]
+
+  # --
+  # : (Riffer::Messages::Assistant::ToolCall, String?) -> Hash[String, untyped]
+  def tool_metric_attributes: (Riffer::Messages::Assistant::ToolCall, String?) -> Hash[String, untyped]
+
+  # A returned error Response is a handled outcome, so its status stays unset —
+  # an error span status is reserved for a raised exception.
+  # --
+  # : ((Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span), Riffer::Tools::Response) -> void
+  def record_tool_outcome: (Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span, Riffer::Tools::Response) -> void
+
+  # --
+  # : ((Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span), Riffer::Messages::Assistant::ToolCall) -> void
+  def capture_tool_arguments: (Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span, Riffer::Messages::Assistant::ToolCall) -> void
+
+  # --
+  # : ((Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span), Riffer::Tools::Response) -> void
+  def capture_tool_result: (Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span, Riffer::Tools::Response) -> void
+
+  # --
+  # : ((Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span)) -> bool
+  def capture_tool_content?: (Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span) -> bool
 end

data/sig/generated/riffer/tracing/capture.rbs

@@ -0,0 +1,46 @@
+# Generated from lib/riffer/tracing/capture.rb with RBS::Inline
+
+# Serializes riffer messages into the GenAI semconv JSON message structure
+# for opt-in span content capture. File parts become metadata-only stubs —
+# bytes and URLs never reach a span attribute.
+module Riffer::Tracing::Capture
+  # --
+  # : (Array[Riffer::Messages::Base]) -> String
+  def input_messages: (Array[Riffer::Messages::Base]) -> String
+
+  # --
+  # : (Array[Riffer::Messages::Base]) -> String?
+  def system_instructions: (Array[Riffer::Messages::Base]) -> String?
+
+  # --
+  # : (content: String?, tool_calls: Array[Riffer::Messages::Assistant::ToolCall], finish_reason: Symbol?) -> String
+  def output_messages: (content: String?, tool_calls: Array[Riffer::Messages::Assistant::ToolCall], finish_reason: Symbol?) -> String
+
+  private
+
+  # --
+  # : (Riffer::Messages::Base) -> Hash[Symbol, untyped]?
+  def convert_message: (Riffer::Messages::Base) -> Hash[Symbol, untyped]?
+
+  # --
+  # : (String?, Array[Riffer::Messages::Assistant::ToolCall]) -> Array[Hash[Symbol, untyped]]
+  def assistant_parts: (String?, Array[Riffer::Messages::Assistant::ToolCall]) -> Array[Hash[Symbol, untyped]]
+
+  # --
+  # : (String?) -> Hash[Symbol, untyped]
+  def text_part: (String?) -> Hash[Symbol, untyped]
+
+  # --
+  # : (Riffer::Messages::Assistant::ToolCall) -> Hash[Symbol, untyped]
+  def tool_call_part: (Riffer::Messages::Assistant::ToolCall) -> Hash[Symbol, untyped]
+
+  # --
+  # : (Riffer::Messages::FilePart) -> Hash[Symbol, untyped]
+  def file_part: (Riffer::Messages::FilePart) -> Hash[Symbol, untyped]
+
+  # 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
+  def parse_arguments: (untyped) -> untyped
+end

data/sig/generated/riffer/tracing/no_op.rbs

@@ -0,0 +1,46 @@
+# Generated from lib/riffer/tracing/no_op.rb with RBS::Inline
+
+# No-op tracing backend, used when OTEL is unavailable or tracing is
+# disabled.
+module Riffer::Tracing::NoOp
+  # No-op stand-in for a span; answers <tt>recording?</tt> with +false+ so
+  # callers can skip expensive attribute serialization.
+  class Span
+    # --
+    # : (String, untyped) -> void
+    def set_attribute: (String, untyped) -> void
+
+    # --
+    # : (String, ?attributes: Hash[String, untyped]?) -> void
+    def add_event: (String, ?attributes: Hash[String, untyped]?) -> void
+
+    # --
+    # : (Exception) -> void
+    def record_exception: (Exception) -> void
+
+    # --
+    # : (?String) -> void
+    def error!: (?String) -> void
+
+    # --
+    # : () -> bool
+    def recording?: () -> bool
+  end
+
+  SPAN: Riffer::Tracing::NoOp::Span
+
+  # Yields the no-op span, ignoring all span options.
+  # --
+  # : [R] (String, **untyped) { (Riffer::Tracing::NoOp::Span) -> R } -> R
+  def in_span: [R] (String, **untyped) { (Riffer::Tracing::NoOp::Span) -> R } -> R
+
+  # Returns +nil+; there is no trace context without OTEL.
+  # --
+  # : () -> nil
+  def current_context: () -> nil
+
+  # Yields immediately; there is no context to attach.
+  # --
+  # : [R] (untyped) { () -> R } -> R
+  def with_context: [R] (untyped) { () -> R } -> R
+end

data/sig/generated/riffer/tracing/otel.rbs

@@ -0,0 +1,84 @@
+# Generated from lib/riffer/tracing/otel.rb with RBS::Inline
+
+# OTEL-backed tracing backend. <tt>::OpenTelemetry</tt> constants appear only
+# inside method bodies here, so the gem loads and eager-loads cleanly when the
+# OpenTelemetry API is absent.
+class Riffer::Tracing::Otel
+  # :nodoc: all
+  SUPPORTED_API_VERSIONS: Gem::Requirement
+
+  # Wraps a live OTEL span behind the port's span surface, so callers never
+  # touch <tt>::OpenTelemetry</tt> constants (status objects in particular).
+  class Span
+    @otel_span: untyped
+
+    # --
+    # : (untyped) -> void
+    def initialize: (untyped) -> void
+
+    # --
+    # : (String, untyped) -> void
+    def set_attribute: (String, untyped) -> void
+
+    # --
+    # : (String, ?attributes: Hash[String, untyped]?) -> void
+    def add_event: (String, ?attributes: Hash[String, untyped]?) -> void
+
+    # --
+    # : (Exception) -> void
+    def record_exception: (Exception) -> void
+
+    # Marks the span status as error.
+    # --
+    # : (?String) -> void
+    def error!: (?String) -> void
+
+    # --
+    # : () -> bool
+    def recording?: () -> bool
+  end
+
+  # Builds a backend when the OpenTelemetry API is loadable at a supported
+  # version; returns +nil+ so resolution falls back to NoOp. +provider+
+  # defaults to the global <tt>OpenTelemetry.tracer_provider</tt>.
+  # --
+  # : (?provider: untyped) -> Riffer::Tracing::Otel?
+  def self.build: (?provider: untyped) -> Riffer::Tracing::Otel?
+
+  # Whether the OpenTelemetry API gem is loadable at a supported version.
+  # --
+  # : () -> bool
+  def self.available?: () -> bool
+
+  # Whether the given opentelemetry-api version is one riffer codes
+  # against. The gem is undeclared, so this guard is the only protection
+  # against an incompatible API.
+  # --
+  # : (Gem::Version) -> bool
+  def self.supported?: (Gem::Version) -> bool
+
+  # --
+  # : () -> Gem::Version?
+  private def self.api_version: () -> Gem::Version?
+
+  @tracer: untyped
+
+  # --
+  # : (provider: untyped) -> void
+  def initialize: (provider: untyped) -> void
+
+  # Opens an OTEL span around the block, yielding the wrapped span.
+  # --
+  # : [R] (String, attributes: Hash[String, untyped]?, kind: Symbol) { (Riffer::Tracing::Otel::Span) -> R } -> R
+  def in_span: [R] (String, attributes: Hash[String, untyped]?, kind: Symbol) { (Riffer::Tracing::Otel::Span) -> R } -> R
+
+  # Returns the active OTEL context.
+  # --
+  # : () -> untyped
+  def current_context: () -> untyped
+
+  # Runs the block with the given OTEL context active.
+  # --
+  # : [R] (untyped) { () -> R } -> R
+  def with_context: [R] (untyped) { () -> R } -> R
+end

data/sig/generated/riffer/tracing/stream_recorder.rbs

@@ -0,0 +1,31 @@
+# Generated from lib/riffer/tracing/stream_recorder.rb with RBS::Inline
+
+# Wraps a stream yielder to observe terminal events for span stamping while
+# forwarding every event downstream untouched.
+class Riffer::Tracing::StreamRecorder
+  @yielder: Enumerator::Yielder
+
+  attr_reader token_usage: Riffer::Providers::TokenUsage?
+
+  attr_reader finish_reason: Symbol?
+
+  attr_reader raw_finish_reason: String?
+
+  attr_reader content: String?
+
+  attr_reader tool_calls: Array[Riffer::Messages::Assistant::ToolCall]
+
+  # --
+  # : (Enumerator::Yielder) -> void
+  def initialize: (Enumerator::Yielder) -> void
+
+  # --
+  # : (Riffer::StreamEvents::Base) -> self
+  def <<: (Riffer::StreamEvents::Base) -> self
+
+  private
+
+  # --
+  # : (Riffer::StreamEvents::Base) -> void
+  def record: (Riffer::StreamEvents::Base) -> void
+end