riffer 0.32.0 → 0.33.0

data/lib/riffer/mcp/authenticated_tool.rb

@@ -2,38 +2,35 @@
 # rbs_inline: enabled
 
 # Wraps MCP-generated tool classes so +tools/call+ resolves
-# +Riffer.config.mcp.credentials+ per invocation, delegating metadata to the
-# inner class.
+# +Riffer.config.mcp.credentials+ per invocation, copying metadata from the
+# inner class at wrap time.
 module Riffer::Mcp::AuthenticatedTool
   extend self
 
   # Returns one wrapper class per inner tool, sharing +manifest+ and +matched_tags+.
   #
   #--
-  #: (Array[singleton(Riffer::Tool)], Riffer::Mcp::Manifest, Array[Symbol]) -> Array[singleton(Riffer::Tool)]
+  #: (Array[singleton(Riffer::Mcp::Tool)], Riffer::Mcp::Manifest, Array[Symbol]) -> Array[singleton(Riffer::Mcp::Tool)]
   def wrap_all(tool_classes, manifest, matched_tags)
     tool_classes.map { |tc| wrap_one(tc, manifest, matched_tags) }
   end
 
   #--
-  #: (singleton(Riffer::Tool), Riffer::Mcp::Manifest, Array[Symbol]) -> singleton(Riffer::Tool)
-  # Class.new(Riffer::Tool) is typed as ::Class by steep — it cannot verify the subtype
-  # relationship for dynamically created anonymous classes, so the ignore is required.
-  def wrap_one(inner_class, manifest, matched_tags) # steep:ignore MethodBodyTypeMismatch
+  #: (singleton(Riffer::Mcp::Tool), Riffer::Mcp::Manifest, Array[Symbol]) -> singleton(Riffer::Mcp::Tool)
+  def wrap_one(inner_class, manifest, matched_tags)
     inner = inner_class
     man = manifest
     tags = matched_tags
 
-    Class.new(Riffer::Tool) do
-      # steep cannot type the body of a dynamically created anonymous class:
-      # its ivars and `self` inside define_method are unresolvable.
+    # steep does not model Class.new's class_eval semantics — the block body
+    # typechecks against the enclosing module, so the ivar assignments and the
+    # define_method bodies are unresolvable.
+    Class.new(Riffer::Mcp::Tool) do
       # steep:ignore:start
       @identifier = inner.identifier
-
-      define_singleton_method(:name) { inner.name }
-      define_singleton_method(:mcp_server_tool_name) { inner.mcp_server_tool_name }
-      define_singleton_method(:description) { inner.description }
-      define_singleton_method(:parameters_schema) { |strict: false| inner.parameters_schema(strict: strict) }
+      @description = inner.description
+      @input_schema = inner.parameters_schema
+      @mcp_server_tool_name = inner.mcp_server_tool_name
 
       # Creates a fresh client per +tools/call+ so headers from the credentials
       # proc stay current.
@@ -48,9 +45,6 @@ module Riffer::Mcp::AuthenticatedTool
       define_method(:call) do |context:, **kwargs|
         cred = Riffer.config.mcp.credentials
         unless cred
-          # `next` rather than `return`: inside define_method the block IS the method
-          # body, so both exit :call identically at runtime. `next` avoids a false
-          # steep ReturnTypeMismatch that would otherwise need a steep:ignore.
           next inner.new.call(context: context, **kwargs)
         end
 
@@ -61,9 +55,9 @@ module Riffer::Mcp::AuthenticatedTool
         end
 
         client = build_call_client(man.endpoint, headers)
-        text(client.tools_call(inner.mcp_server_tool_name, kwargs))
+        text(client.tools_call(self.class.mcp_server_tool_name, kwargs))
       end
       # steep:ignore:end
-    end
+    end #: singleton(Riffer::Mcp::Tool)
   end
 end

data/lib/riffer/mcp/registration.rb

@@ -5,16 +5,16 @@
 # +tools/list+ and generates tool classes when a server is registered.
 class Riffer::Mcp::Registration
   # @rbs @cancelled: bool
-  # @rbs @tools: Array[singleton(Riffer::Tool)]
+  # @rbs @tools: Array[singleton(Riffer::Mcp::Tool)]
   # @rbs @mutex: Thread::Mutex
 
   # The manifest that describes this server.
   attr_reader :manifest #: Riffer::Mcp::Manifest
 
-  # Generated Riffer::Tool subclasses.
+  # Generated Riffer::Mcp::Tool subclasses.
   #
   #--
-  #: () -> Array[singleton(Riffer::Tool)]
+  #: () -> Array[singleton(Riffer::Mcp::Tool)]
   def tools
     @mutex.synchronize { @tools }
   end
@@ -24,7 +24,7 @@ class Riffer::Mcp::Registration
   def initialize(manifest)
     @manifest = manifest
     @cancelled = false
-    @tools = [] #: Array[singleton(Riffer::Tool)]
+    @tools = [] #: Array[singleton(Riffer::Mcp::Tool)]
     @mutex = Mutex.new
     run_discovery
   end

data/lib/riffer/mcp/tool.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# Base class for MCP-generated tools.
+class Riffer::Mcp::Tool < Riffer::Tool
+  # @rbs self.@mcp_server_tool_name: String?
+  # @rbs self.@input_schema: Hash[Symbol, untyped]?
+
+  # Returns the unprefixed tool name used for +tools/call+ on the MCP server.
+  #--
+  #: () -> String
+  def self.mcp_server_tool_name
+    @mcp_server_tool_name || raise(NotImplementedError, "#{self} must set @mcp_server_tool_name")
+  end
+
+  # Returns the server-published input schema, falling back to the params DSL.
+  # MCP schemas are server-defined, so +strict+ is not applied to them.
+  #--
+  #: (?strict: bool) -> Hash[Symbol, untyped]
+  def self.parameters_schema(strict: false)
+    @input_schema || super
+  end
+end

data/lib/riffer/mcp/tool_factory.rb

@@ -1,17 +1,17 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Generates anonymous Riffer::Tool subclasses from MCP tool definitions.
+# Generates anonymous Riffer::Mcp::Tool subclasses from MCP tool definitions.
 # Generated tools delegate +#call+ to the MCP client and skip Riffer's param
 # validation — the MCP server validates inputs.
 module Riffer::Mcp::ToolFactory
   extend self
 
-  # Builds one Riffer::Tool subclass per tool definition, prefixing names with
-  # the manifest name to avoid cross-server collisions (e.g. +jira__search+);
-  # the server-side name stays on +.mcp_server_tool_name+.
+  # Builds one Riffer::Mcp::Tool subclass per tool definition, prefixing names
+  # with the manifest name to avoid cross-server collisions (e.g.
+  # +jira__search+); the server-side name stays on +.mcp_server_tool_name+.
   #--
-  #: (String, Riffer::Mcp::Client, Array[Hash[Symbol, untyped]]) -> Array[singleton(Riffer::Tool)]
+  #: (String, Riffer::Mcp::Client, Array[Hash[Symbol, untyped]]) -> Array[singleton(Riffer::Mcp::Tool)]
   def build(manifest_name, client, tool_defs)
     tool_defs.map { |td| build_tool_class(manifest_name, client, td) }
   end
@@ -23,32 +23,24 @@ module Riffer::Mcp::ToolFactory
     str.gsub(/[^a-zA-Z0-9_-]/, "_")
   end
 
+  #: (String, Riffer::Mcp::Client, Hash[Symbol, untyped]) -> singleton(Riffer::Mcp::Tool)
   def build_tool_class(manifest_name, client, td)
     prefixed = "#{sanitize_name_component(manifest_name)}__#{sanitize_name_component(td[:name])}"
 
-    # steep cannot type the body of a dynamically created anonymous class:
-    # its ivars and `self` inside define_method are unresolvable, so the
-    # block is ignored wholesale (cf. AuthenticatedTool.wrap_one).
-    Class.new(Riffer::Tool) do
+    # steep does not model Class.new's class_eval semantics — the block body
+    # typechecks against the enclosing module, so the ivar assignments and the
+    # define_method body are unresolvable.
+    Class.new(Riffer::Mcp::Tool) do
       # steep:ignore:start
-      @mcp_client = client
       @mcp_server_tool_name = td[:name]
-      # Set @identifier directly so .identifier does not fall back to
-      # Riffer::Helpers::ClassNameConverter.convert(nil) on this anonymous class.
       @identifier = prefixed
-
-      define_singleton_method(:name) { prefixed }
-      define_singleton_method(:mcp_server_tool_name) { td[:name] }
-      define_singleton_method(:description) { td[:description] }
-      define_singleton_method(:parameters_schema) { |strict: false| td[:input_schema] || Riffer::Tool.send(:empty_schema) }
+      @description = td[:description]
+      @input_schema = td[:input_schema]
 
       define_method(:call) do |context:, **kwargs|
-        result = self.class.instance_variable_get(:@mcp_client).tools_call(
-          self.class.instance_variable_get(:@mcp_server_tool_name), kwargs
-        )
-        text(result)
+        text(client.tools_call(self.class.mcp_server_tool_name, kwargs))
       end
       # steep:ignore:end
-    end
+    end #: singleton(Riffer::Mcp::Tool)
   end
 end

data/lib/riffer/messages/assistant.rb

@@ -4,7 +4,7 @@
 # Represents an assistant (LLM) message in a conversation; may include tool
 # calls when the LLM requests tool execution.
 class Riffer::Messages::Assistant < Riffer::Messages::Base
-  ToolCall = Struct.new(:call_id, :name, :arguments, keyword_init: true)
+  ToolCall = Struct.new(:call_id, :name, :arguments)
 
   # Array of tool calls requested by the assistant.
   attr_reader :tool_calls #: Array[Riffer::Messages::Assistant::ToolCall]
@@ -15,13 +15,24 @@ class Riffer::Messages::Assistant < Riffer::Messages::Base
   # Parsed structured output hash, or nil when not applicable.
   attr_reader :structured_output #: Hash[Symbol, untyped]?
 
+  # Normalized reason the provider finished this response, when reported (see
+  # <tt>Riffer::Providers::FinishReason::VALUES</tt>).
+  attr_reader :finish_reason #: Symbol?
+
+  # Raises Riffer::ArgumentError when +finish_reason+ is outside the
+  # normalized vocabulary.
   #--
-  #: (String, ?id: String?, ?tool_calls: Array[Riffer::Messages::Assistant::ToolCall], ?token_usage: Riffer::Providers::TokenUsage?, ?structured_output: Hash[Symbol, untyped]?) -> void
-  def initialize(content, id: nil, tool_calls: [], token_usage: nil, structured_output: nil)
+  #: (String, ?id: String?, ?tool_calls: Array[Riffer::Messages::Assistant::ToolCall], ?token_usage: Riffer::Providers::TokenUsage?, ?structured_output: Hash[Symbol, untyped]?, ?finish_reason: Symbol?) -> void
+  def initialize(content, id: nil, tool_calls: [], token_usage: nil, structured_output: nil, finish_reason: nil)
+    if finish_reason && !Riffer::Providers::FinishReason::VALUES.include?(finish_reason)
+      raise Riffer::ArgumentError, "finish_reason must be one of #{Riffer::Providers::FinishReason::VALUES.inspect}, got #{finish_reason.inspect}"
+    end
+
     super(content, id: id)
     @tool_calls = tool_calls
     @token_usage = token_usage
     @structured_output = structured_output
+    @finish_reason = finish_reason
   end
 
   #--
@@ -58,6 +69,7 @@ class Riffer::Messages::Assistant < Riffer::Messages::Base
     hash[:tool_calls] = tool_calls.map(&:to_h) unless tool_calls.empty?
     hash[:token_usage] = token_usage.to_h if token_usage
     hash[:structured_output] = structured_output if structured_output?
+    hash[:finish_reason] = finish_reason if finish_reason
     hash
   end
 end

data/lib/riffer/messages/base.rb

@@ -34,7 +34,8 @@ class Riffer::Messages::Base
         tc.is_a?(Riffer::Messages::Assistant::ToolCall) ? tc : Riffer::Messages::Assistant::ToolCall.new(**tc)
       }
       structured_output = msg[:structured_output]
-      Riffer::Messages::Assistant.new(content, id: id, tool_calls: tool_calls, structured_output: structured_output)
+      finish_reason = msg[:finish_reason]&.to_sym
+      Riffer::Messages::Assistant.new(content, id: id, tool_calls: tool_calls, structured_output: structured_output, finish_reason: finish_reason)
     when :system
       Riffer::Messages::System.new(content, id: id)
     when :tool

data/lib/riffer/metrics/instruments.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# The catalog of metric instruments riffer records. Each handle is a constant
+# that resolves its backend at record time, so it survives a meter-provider swap
+# or a runtime +enabled+ flip.
+module Riffer::Metrics::Instruments # :nodoc: all
+  OPERATION_DURATION = Riffer::Metrics.create_histogram(
+    "gen_ai.client.operation.duration",
+    unit: "s",
+    description: "Duration of GenAI client operations"
+  ) #: Riffer::Metrics::Histogram
+
+  TOKEN_USAGE = Riffer::Metrics.create_histogram(
+    "gen_ai.client.token.usage",
+    unit: "{token}",
+    description: "Number of input and output tokens used in GenAI operations"
+  ) #: Riffer::Metrics::Histogram
+
+  COST = Riffer::Metrics.create_histogram(
+    "riffer.gen_ai.cost",
+    unit: "USD",
+    description: "Cost of GenAI client operations in USD"
+  ) #: Riffer::Metrics::Histogram
+end

data/lib/riffer/metrics/null.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# No-op metrics backend, used when the OpenTelemetry metrics API is unavailable
+# or metrics are disabled.
+module Riffer::Metrics::Null # :nodoc: all
+  extend self
+
+  # Ignores the measurement; there is no meter without the OTEL metrics API.
+  #--
+  #: (String, Numeric, unit: String?, description: String?, attributes: Hash[String, untyped]?) -> void
+  def record_histogram(name, value, unit:, description:, attributes:)
+  end
+end

data/lib/riffer/metrics/otel.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# OTEL-backed metrics backend. <tt>::OpenTelemetry</tt> constants appear only
+# inside method bodies here, so the gem loads and eager-loads cleanly when the
+# OpenTelemetry metrics API is absent.
+class Riffer::Metrics::Otel # :nodoc: all
+  SUPPORTED_API_VERSIONS = Gem::Requirement.new(">= 0.2", "< 1.0") #: Gem::Requirement
+
+  class << self
+    # Builds a backend when the OpenTelemetry metrics API is loadable at a
+    # supported version; returns +nil+ so resolution falls back to Null.
+    #--
+    #: (provider: untyped) -> Riffer::Metrics::Otel?
+    def build(provider:)
+      version = api_version
+      return nil unless version
+
+      unless supported?(version)
+        Kernel.warn "riffer: opentelemetry-metrics-api #{version} is outside the supported range (#{SUPPORTED_API_VERSIONS}); metrics are disabled"
+        return nil
+      end
+
+      new(provider: provider || ::OpenTelemetry.meter_provider)
+    end
+
+    # Whether the OpenTelemetry metrics API gem is loadable at a supported
+    # version.
+    #--
+    #: () -> bool
+    def available?
+      version = api_version
+      !version.nil? && supported?(version)
+    end
+
+    # Whether the given opentelemetry-metrics-api version is one riffer codes
+    # against. The gem is undeclared, so this guard is the only protection
+    # against an incompatible, still-pre-1.0 API.
+    #--
+    #: (Gem::Version) -> bool
+    def supported?(version)
+      SUPPORTED_API_VERSIONS.satisfied_by?(version)
+    end
+
+    private
+
+    #--
+    #: () -> Gem::Version?
+    def api_version
+      require "opentelemetry-metrics-api"
+      spec = Gem.loaded_specs["opentelemetry-metrics-api"] #: untyped
+      spec&.version
+    rescue ::LoadError
+      nil
+    end
+  end
+
+  # @rbs @meter: untyped
+  # @rbs @instruments: Hash[String, untyped]
+  # @rbs @mutex: Mutex
+
+  #--
+  #: (provider: untyped) -> void
+  def initialize(provider:)
+    @meter = provider.meter("riffer", version: Riffer::VERSION)
+    @instruments = {}
+    @mutex = Mutex.new
+  end
+
+  # Records a value onto the named histogram.
+  #--
+  #: (String, Numeric, unit: String?, description: String?, attributes: Hash[String, untyped]?) -> void
+  def record_histogram(name, value, unit:, description:, attributes:)
+    histogram = @mutex.synchronize do
+      @instruments[name] ||= @meter.create_histogram(name, unit: unit, description: description)
+    end
+    histogram.record(value, attributes: attributes)
+  end
+end

data/lib/riffer/metrics.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# Internal metrics port — records OTEL metric instruments when the host bundles
+# the OpenTelemetry metrics API and no-ops otherwise, so riffer never declares
+# an OTEL dependency.
+module Riffer::Metrics # :nodoc: all
+  extend self
+
+  # @rbs @backend: (Riffer::Metrics::Otel | singleton(Riffer::Metrics::Null))?
+
+  MUTEX = Mutex.new #: Mutex
+
+  # The Ruby API cannot attach a schema URL to a meter, so the semconv pin
+  # lives here as the documented contract version.
+  SCHEMA_URL = "https://opentelemetry.io/schemas/1.37.0" #: String
+
+  # A handle to a named histogram, safe to hold as a constant: it defers backend
+  # resolution to record time, so it survives a meter-provider swap or a runtime
+  # +enabled+ flip.
+  class Histogram
+    # @rbs @name: String
+    # @rbs @unit: String?
+    # @rbs @description: String?
+
+    #--
+    #: (String, ?unit: String?, ?description: String?) -> void
+    def initialize(name, unit: nil, description: nil)
+      @name = name
+      @unit = unit
+      @description = description
+    end
+
+    #--
+    #: (Numeric, ?attributes: Hash[String, untyped]?) -> void
+    def record(value, attributes: nil)
+      Riffer::Metrics.record_histogram(@name, value, unit: @unit, description: @description, attributes: attributes)
+    end
+  end
+
+  # Returns a handle to the named histogram.
+  #--
+  #: (String, ?unit: String?, ?description: String?) -> Riffer::Metrics::Histogram
+  def create_histogram(name, unit: nil, description: nil)
+    Histogram.new(name, unit: unit, description: description)
+  end
+
+  # Records a value onto the named histogram.
+  #--
+  #: (String, Numeric, ?unit: String?, ?description: String?, ?attributes: Hash[String, untyped]?) -> void
+  def record_histogram(name, value, unit: nil, description: nil, attributes: nil)
+    return unless Riffer.config.metrics.enabled
+    backend.record_histogram(name, value, unit: unit, description: description, attributes: attributes)
+  end
+
+  # Mirrors a span's +recording?+ so a caller can skip work that exists only to
+  # feed a metric.
+  #--
+  #: () -> bool
+  def recording?
+    Riffer.config.metrics.enabled && backend.is_a?(Otel)
+  end
+
+  # Reads the monotonic clock in seconds — the time source for duration metrics,
+  # immune to wall-clock adjustments.
+  #--
+  #: () -> Float
+  def monotonic_now
+    Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  end
+
+  # Discards the resolved backend so the next record re-resolves it; cached
+  # instruments live on that backend, so this clears them too.
+  #--
+  #: () -> void
+  def reset!
+    MUTEX.synchronize { @backend = nil }
+  end
+
+  private
+
+  #--
+  #: () -> (Riffer::Metrics::Otel | singleton(Riffer::Metrics::Null))
+  def backend
+    @backend || MUTEX.synchronize { @backend ||= resolve_backend }
+  end
+
+  #--
+  #: () -> (Riffer::Metrics::Otel | singleton(Riffer::Metrics::Null))
+  def resolve_backend
+    Otel.build(provider: Riffer.config.metrics.meter_provider) || Null
+  end
+end

data/lib/riffer/providers/amazon_bedrock.rb

@@ -10,6 +10,15 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
   # cross-region (+us.anthropic.claude-...+) ids.
   ANTHROPIC_MODEL_PATTERN = /(?:^|\.)anthropic\./ #: Regexp
 
+  FINISH_REASONS = {
+    "end_turn" => :stop,
+    "stop_sequence" => :stop,
+    "max_tokens" => :length,
+    "tool_use" => :tool_calls,
+    "guardrail_intervened" => :content_filter,
+    "content_filtered" => :content_filter
+  }.freeze #: Hash[String, Symbol]
+
   # Returns the skill adapter for the Bedrock model — XML for Anthropic models
   # (which Bedrock hosts alongside other vendors'), else Markdown.
   #--
@@ -19,6 +28,13 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
     Riffer::Skills::MarkdownAdapter
   end
 
+  # The GenAI semconv well-known provider name.
+  #--
+  #: () -> String
+  def self.semconv_provider_name
+    "aws.bedrock"
+  end
+
   #--
   #: (?api_token: String?, ?region: String?, **untyped) -> void
   def initialize(api_token: nil, region: nil, **options)
@@ -120,14 +136,39 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
   #: (untyped) -> Riffer::Providers::TokenUsage?
   def extract_token_usage(response)
     typed_response = response #: Aws::BedrockRuntime::Client::_ConverseResponseSuccess
-    usage = typed_response.usage
+    build_token_usage(typed_response.usage)
+  end
 
-    Riffer::Providers::TokenUsage.new(
-      input_tokens: usage.input_tokens,
+  # Converse's +input_tokens+ excludes the cache buckets; TokenUsage's
+  # input includes them.
+  #--
+  #: (untyped) -> Riffer::Providers::TokenUsage
+  def build_token_usage(usage)
+    cache_write = usage.cache_write_input_tokens
+    cache_read = usage.cache_read_input_tokens
+
+    apply_pricing(Riffer::Providers::TokenUsage.new(
+      input_tokens: usage.input_tokens + (cache_write || 0) + (cache_read || 0),
       output_tokens: usage.output_tokens,
-      cache_write_tokens: usage.cache_write_input_tokens,
-      cache_read_tokens: usage.cache_read_input_tokens
-    )
+      cache_write_tokens: cache_write,
+      cache_read_tokens: cache_read
+    ))
+  end
+
+  #--
+  #: (untyped) -> Riffer::Providers::FinishReason?
+  def extract_finish_reason(response)
+    typed_response = response #: Aws::BedrockRuntime::Client::_ConverseResponseSuccess
+    build_finish_reason(typed_response.stop_reason)
+  end
+
+  #--
+  #: (untyped) -> Riffer::Providers::FinishReason?
+  def build_finish_reason(stop_reason)
+    return nil unless stop_reason
+
+    raw = stop_reason.to_s
+    Riffer::Providers::FinishReason.new(reason: FINISH_REASONS.fetch(raw, :other), raw: raw)
   end
 
   #--
@@ -169,7 +210,7 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
   end
 
   #--
-  #: (Hash[Symbol, untyped], Enumerator::Yielder) -> void
+  #: (Hash[Symbol, untyped], Riffer::Providers::_EventSink) -> void
   def execute_stream(params, yielder)
     current_state = {
       text: nil,
@@ -187,6 +228,8 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
         when Aws::BedrockRuntime::Types::ContentBlockStopEvent
           handle_content_block_stop_text_delta(event, state: current_state, yielder: yielder) if current_state[:text]
           handle_content_block_stop_tool_use(event, state: current_state, yielder: yielder) if current_state[:tool_call]
+        when Aws::BedrockRuntime::Types::MessageStopEvent
+          yield_finish_reason(yielder, build_finish_reason(event.stop_reason))
         when Aws::BedrockRuntime::Types::ConverseStreamMetadataEvent
           handle_metadata_usage(event, state: current_state, yielder: yielder) if event.usage
         else
@@ -212,7 +255,7 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
   end
 
   #--
-  #: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  #: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
   def handle_content_block_start_tool_use(event, state:, yielder:)
     typed_event = event #: Aws::BedrockRuntime::Types::ContentBlockStartEvent
     state[:tool_call] = {
@@ -223,7 +266,7 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
   end
 
   #--
-  #: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  #: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
   def handle_content_block_delta_text_delta(event, state:, yielder:)
     typed_event = event #: Aws::BedrockRuntime::Types::ContentBlockDeltaEvent
     delta_text = typed_event.delta.text
@@ -233,7 +276,7 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
   end
 
   #--
-  #: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  #: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
   def handle_content_block_delta_tool_use(event, state:, yielder:)
     typed_event = event #: Aws::BedrockRuntime::Types::ContentBlockDeltaEvent
     input_delta = typed_event.delta.tool_use.input
@@ -248,14 +291,14 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
   end
 
   #--
-  #: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  #: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
   def handle_content_block_stop_text_delta(_event, state:, yielder:)
     yielder << Riffer::StreamEvents::TextDone.new(state[:text])
     state[:text] = nil
   end
 
   #--
-  #: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  #: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
   def handle_content_block_stop_tool_use(_event, state:, yielder:)
     tool_call = state[:tool_call]
     yielder << Riffer::StreamEvents::ToolCallDone.new(
@@ -268,17 +311,10 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
   end
 
   #--
-  #: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  #: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
   def handle_metadata_usage(event, state:, yielder:)
     typed_event = event #: Aws::BedrockRuntime::Types::ConverseStreamMetadataEvent
-    yielder << Riffer::StreamEvents::TokenUsageDone.new(
-      token_usage: Riffer::Providers::TokenUsage.new(
-        input_tokens: typed_event.usage.input_tokens,
-        output_tokens: typed_event.usage.output_tokens,
-        cache_write_tokens: typed_event.usage.cache_write_input_tokens,
-        cache_read_tokens: typed_event.usage.cache_read_input_tokens
-      )
-    )
+    yielder << Riffer::StreamEvents::TokenUsageDone.new(token_usage: build_token_usage(typed_event.usage))
   end
 
   #--