riffer 0.33.0 → 0.35.0

data/lib/riffer/tools/runtime.rb

@@ -18,14 +18,16 @@ class Riffer::Tools::Runtime
 
   # Executes a batch of tool calls, returning <tt>[tool_call, response]</tt> pairs.
   #--
-  #: (Array[Riffer::Messages::Assistant::ToolCall], tools: Array[singleton(Riffer::Tool)], context: Riffer::Agent::Context?, ?assistant_message: Riffer::Messages::Assistant?) -> Array[[Riffer::Messages::Assistant::ToolCall, Riffer::Tools::Response]]
-  def execute(tool_calls, tools:, context:, assistant_message: nil)
+  #: (Array[Riffer::Messages::Assistant::ToolCall], tools: Array[singleton(Riffer::Tool)], context: Riffer::Agent::Context?, ?assistant_message: Riffer::Messages::Assistant?, ?tags: Hash[String, String]) -> Array[[Riffer::Messages::Assistant::ToolCall, Riffer::Tools::Response]]
+  def execute(tool_calls, tools:, context:, assistant_message: nil, tags: {})
     # Each Runner worker runs in its own thread/fiber, where the OTEL context
     # starts empty — capture here so the execute_tool span parents correctly.
+    # tags are an ordinary local captured in the block, so they reach the
+    # worker's span/metric without re-propagation.
     trace_context = Riffer::Tracing.current_context
     @runner.map(tool_calls, context: context) do |tool_call|
       Riffer::Tracing.with_context(trace_context) do
-        instrument_tool_call(tool_call) do
+        instrument_tool_call(tool_call, tags) do
           around_tool_call(tool_call, context: context, assistant_message: assistant_message) do
             dispatch_tool_call(tool_call, tools: tools, context: context, assistant_message: assistant_message)
           end
@@ -57,12 +59,12 @@ class Riffer::Tools::Runtime
   private
 
   #--
-  #: (Riffer::Messages::Assistant::ToolCall) { () -> Riffer::Tools::Response } -> [Riffer::Messages::Assistant::ToolCall, Riffer::Tools::Response]
-  def instrument_tool_call(tool_call)
+  #: (Riffer::Messages::Assistant::ToolCall, ?Hash[String, String]) { () -> Riffer::Tools::Response } -> [Riffer::Messages::Assistant::ToolCall, Riffer::Tools::Response]
+  def instrument_tool_call(tool_call, tags = {})
     start = Riffer::Metrics.monotonic_now
     error_type = nil #: String?
     begin
-      result = in_tool_span(tool_call) do |span|
+      result = in_tool_span(tool_call, tags) do |span|
         response = yield
         record_tool_outcome(span, response)
         response
@@ -73,7 +75,7 @@ class Riffer::Tools::Runtime
       error_type = error.class.name #: String?
       raise
     ensure
-      Riffer::Metrics::Instruments::OPERATION_DURATION.record(Riffer::Metrics.monotonic_now - start, attributes: tool_metric_attributes(tool_call, error_type))
+      Riffer::Metrics::Instruments::OPERATION_DURATION.record(Riffer::Metrics.monotonic_now - start, attributes: tool_metric_attributes(tool_call, error_type, tags))
     end
   end
 
@@ -113,9 +115,9 @@ class Riffer::Tools::Runtime
 
   # Emitted outside +around_tool_call+ so host enrichment spans nest beneath it.
   #--
-  #: [R] (Riffer::Messages::Assistant::ToolCall) { ((Riffer::Tracing::Otel::Span | Riffer::Tracing::Null::Span)) -> R } -> R
-  def in_tool_span(tool_call)
-    Riffer::Tracing.in_span("execute_tool #{tool_call.name}", attributes: tool_span_attributes(tool_call), kind: :internal) do |span|
+  #: [R] (Riffer::Messages::Assistant::ToolCall, ?Hash[String, String]) { ((Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span)) -> R } -> R
+  def in_tool_span(tool_call, tags = {})
+    Riffer::Tracing.in_span("execute_tool #{tool_call.name}", attributes: tool_span_attributes(tool_call, tags), kind: :internal) do |span|
       capture_tool_arguments(span, tool_call)
       yield span
     rescue => error
@@ -127,30 +129,38 @@ class Riffer::Tools::Runtime
   end
 
   #--
-  #: (Riffer::Messages::Assistant::ToolCall) -> Hash[String, untyped]
-  def tool_span_attributes(tool_call)
+  #: (Riffer::Messages::Assistant::ToolCall, ?Hash[String, String]) -> Hash[String, untyped]
+  def tool_span_attributes(tool_call, tags = {})
     {
       "gen_ai.operation.name" => "execute_tool",
       "gen_ai.tool.name" => tool_call.name,
       "gen_ai.tool.call.id" => tool_call.call_id
-    }
+    }.merge(tag_attributes(tags))
   end
 
   #--
-  #: (Riffer::Messages::Assistant::ToolCall, String?) -> Hash[String, untyped]
-  def tool_metric_attributes(tool_call, error_type)
+  #: (Riffer::Messages::Assistant::ToolCall, String?, ?Hash[String, String]) -> Hash[String, untyped]
+  def tool_metric_attributes(tool_call, error_type, tags = {})
     attributes = {
       "gen_ai.operation.name" => "execute_tool",
       "gen_ai.tool.name" => tool_call.name
     } #: Hash[String, untyped]
     attributes["error.type"] = error_type if error_type
-    attributes
+    attributes.merge(tag_attributes(tags))
+  end
+
+  # Maps normalized tags to their namespaced span/metric 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)
+    tags.transform_keys { |key| "riffer.tag.#{key}" }
   end
 
   # 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::Null::Span), Riffer::Tools::Response) -> void
+  #: ((Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span), Riffer::Tools::Response) -> void
   def record_tool_outcome(span, result)
     error_type = result.error_type
     span.set_attribute("error.type", error_type.to_s) if error_type
@@ -158,7 +168,7 @@ class Riffer::Tools::Runtime
   end
 
   #--
-  #: ((Riffer::Tracing::Otel::Span | Riffer::Tracing::Null::Span), Riffer::Messages::Assistant::ToolCall) -> void
+  #: ((Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span), Riffer::Messages::Assistant::ToolCall) -> void
   def capture_tool_arguments(span, tool_call)
     return unless capture_tool_content?(span)
 
@@ -167,7 +177,7 @@ class Riffer::Tools::Runtime
   end
 
   #--
-  #: ((Riffer::Tracing::Otel::Span | Riffer::Tracing::Null::Span), Riffer::Tools::Response) -> void
+  #: ((Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span), Riffer::Tools::Response) -> void
   def capture_tool_result(span, result)
     return unless capture_tool_content?(span)
 
@@ -175,7 +185,7 @@ class Riffer::Tools::Runtime
   end
 
   #--
-  #: ((Riffer::Tracing::Otel::Span | Riffer::Tracing::Null::Span)) -> bool
+  #: ((Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span)) -> bool
   def capture_tool_content?(span)
     Riffer.config.tracing.capture_messages && span.recording?
   end

data/lib/riffer/tracing/{null.rb → no_op.rb}

@@ -3,7 +3,7 @@
 
 # No-op tracing backend, used when OTEL is unavailable or tracing is
 # disabled.
-module Riffer::Tracing::Null # :nodoc: all
+module Riffer::Tracing::NoOp # :nodoc: all
   extend self
 
   # No-op stand-in for a span; answers <tt>recording?</tt> with +false+ so
@@ -36,11 +36,11 @@ module Riffer::Tracing::Null # :nodoc: all
     end
   end
 
-  SPAN = Span.new.freeze #: Riffer::Tracing::Null::Span
+  SPAN = Span.new.freeze #: Riffer::Tracing::NoOp::Span
 
   # Yields the no-op span, ignoring all span options.
   #--
-  #: [R] (String, **untyped) { (Riffer::Tracing::Null::Span) -> R } -> R
+  #: [R] (String, **untyped) { (Riffer::Tracing::NoOp::Span) -> R } -> R
   def in_span(_name, **)
     yield SPAN
   end

data/lib/riffer/tracing/otel.rb

@@ -52,10 +52,11 @@ class Riffer::Tracing::Otel # :nodoc: all
 
   class << self
     # Builds a backend when the OpenTelemetry API is loadable at a supported
-    # version; returns +nil+ so resolution falls back to Null.
+    # 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 build(provider:)
+    #: (?provider: untyped) -> Riffer::Tracing::Otel?
+    def build(provider: nil)
       version = api_version
       return nil unless version
 

data/lib/riffer/tracing.rb

@@ -7,7 +7,7 @@
 module Riffer::Tracing # :nodoc: all
   extend self
 
-  # @rbs @backend: (Riffer::Tracing::Otel | singleton(Riffer::Tracing::Null))?
+  # @rbs @backend: untyped
 
   MUTEX = Mutex.new #: Mutex
 
@@ -17,9 +17,9 @@ module Riffer::Tracing # :nodoc: all
 
   # Opens a span around the block, yielding the span.
   #--
-  #: [R] (String, ?attributes: Hash[String, untyped]?, ?kind: Symbol) { (Riffer::Tracing::Otel::Span | Riffer::Tracing::Null::Span) -> R } -> R
+  #: [R] (String, ?attributes: Hash[String, untyped]?, ?kind: Symbol) { (Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span) -> R } -> R
   def in_span(name, attributes: nil, kind: :internal, &block)
-    return Null.in_span(name, &block) unless Riffer.config.tracing.enabled
+    return NoOp.in_span(name, &block) unless Riffer.config.tracing.enabled
     backend.in_span(name, attributes: attributes, kind: kind, &block)
   end
 
@@ -28,7 +28,7 @@ module Riffer::Tracing # :nodoc: all
   #--
   #: () -> untyped
   def current_context
-    return Null.current_context unless Riffer.config.tracing.enabled
+    return NoOp.current_context unless Riffer.config.tracing.enabled
     backend.current_context
   end
 
@@ -37,14 +37,14 @@ module Riffer::Tracing # :nodoc: all
   #--
   #: [R] (untyped) { () -> R } -> R
   def with_context(context, &block)
-    return Null.with_context(context, &block) unless Riffer.config.tracing.enabled
+    return NoOp.with_context(context, &block) unless Riffer.config.tracing.enabled
     backend.with_context(context, &block)
   end
 
   # Stamps token usage onto the span — the <tt>gen_ai.usage.*</tt> counts and,
   # when the model was priced, <tt>riffer.cost</tt>.
   #--
-  #: ((Riffer::Tracing::Otel::Span | Riffer::Tracing::Null::Span), Riffer::Providers::TokenUsage?) -> void
+  #: ((Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span), Riffer::Providers::TokenUsage?) -> void
   def record_usage(span, usage)
     return unless usage
 
@@ -65,14 +65,14 @@ module Riffer::Tracing # :nodoc: all
   private
 
   #--
-  #: () -> (Riffer::Tracing::Otel | singleton(Riffer::Tracing::Null))
+  #: () -> untyped
   def backend
     @backend || MUTEX.synchronize { @backend ||= resolve_backend }
   end
 
   #--
-  #: () -> (Riffer::Tracing::Otel | singleton(Riffer::Tracing::Null))
+  #: () -> untyped
   def resolve_backend
-    Otel.build(provider: Riffer.config.tracing.tracer_provider) || Null
+    Riffer.config.tracing.backend || NoOp
   end
 end

data/lib/riffer/version.rb

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

data/sig/generated/riffer/agent/run.rbs

@@ -7,29 +7,34 @@ module Riffer::Agent::Run
   # for prompt/files semantics.
   #
   # --
-  # : (agent: Riffer::Agent, ?prompt: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?) -> Riffer::Agent::Response
-  def generate: (agent: Riffer::Agent, ?prompt: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?) -> Riffer::Agent::Response
+  # : (agent: Riffer::Agent, ?prompt: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?tags: Hash[(String | Symbol), untyped]) -> Riffer::Agent::Response
+  def generate: (agent: Riffer::Agent, ?prompt: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?tags: Hash[String | Symbol, untyped]) -> Riffer::Agent::Response
 
   # Runs the streaming loop for the given agent. See Riffer::Agent#stream
   # for prompt/files semantics.
   #
   # --
-  # : (agent: Riffer::Agent, ?prompt: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?) -> Enumerator[Riffer::StreamEvents::Base, void]
-  def stream: (agent: Riffer::Agent, ?prompt: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?) -> Enumerator[Riffer::StreamEvents::Base, void]
+  # : (agent: Riffer::Agent, ?prompt: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?tags: Hash[(String | Symbol), untyped]) -> Enumerator[Riffer::StreamEvents::Base, void]
+  def stream: (agent: Riffer::Agent, ?prompt: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?tags: Hash[String | Symbol, untyped]) -> Enumerator[Riffer::StreamEvents::Base, void]
 
   private
 
+  # Both +generate+ and +stream+ funnel here, so this is the single place raw
+  # +tags+ are normalized. The clean <tt>String => String</tt> map is then
+  # threaded to every span/metric builder in the run as +riffer.tag.*+ and to
+  # each provider call (via +merged_model_options+) for native request-metadata
+  # mapping.
   # --
-  # : (Riffer::Agent, ?stream_yielder: Enumerator::Yielder?) -> Riffer::Agent::Response
-  def run_loop: (Riffer::Agent, ?stream_yielder: Enumerator::Yielder?) -> Riffer::Agent::Response
+  # : (Riffer::Agent, ?tags: Hash[(String | Symbol), untyped]?, ?stream_yielder: Enumerator::Yielder?) -> Riffer::Agent::Response
+  def run_loop: (Riffer::Agent, ?tags: Hash[String | Symbol, untyped]?, ?stream_yielder: Enumerator::Yielder?) -> Riffer::Agent::Response
 
   # --
-  # : (Riffer::Agent, Enumerator::Yielder?) -> Riffer::Agent::Response
-  def execute_run: (Riffer::Agent, Enumerator::Yielder?) -> Riffer::Agent::Response
+  # : (Riffer::Agent, Enumerator::Yielder?, ?Hash[String, String]) -> Riffer::Agent::Response
+  def execute_run: (Riffer::Agent, Enumerator::Yielder?, ?Hash[String, String]) -> Riffer::Agent::Response
 
   # --
-  # : (Riffer::Agent, Enumerator::Yielder) -> Riffer::Messages::Assistant
-  def accumulate_streamed_response: (Riffer::Agent, Enumerator::Yielder) -> Riffer::Messages::Assistant
+  # : (Riffer::Agent, Enumerator::Yielder, ?Hash[String, String]) -> Riffer::Messages::Assistant
+  def accumulate_streamed_response: (Riffer::Agent, Enumerator::Yielder, ?Hash[String, String]) -> Riffer::Messages::Assistant
 
   # --
   # : (Enumerator::Yielder?, Array[Riffer::Guardrails::Modification], Array[Riffer::Guardrails::Modification]) -> void
@@ -44,32 +49,32 @@ module Riffer::Agent::Run
   def final_response: (Riffer::Agent, Array[Riffer::Guardrails::Modification], **untyped) -> Riffer::Agent::Response
 
   # --
-  # : (Riffer::Agent) -> Riffer::Messages::Assistant
-  def call_llm: (Riffer::Agent) -> Riffer::Messages::Assistant
+  # : (Riffer::Agent, ?Hash[String, String]) -> Riffer::Messages::Assistant
+  def call_llm: (Riffer::Agent, ?Hash[String, String]) -> Riffer::Messages::Assistant
 
   # --
-  # : (Riffer::Agent) -> Enumerator[Riffer::StreamEvents::Base, void]
-  def call_llm_stream: (Riffer::Agent) -> Enumerator[Riffer::StreamEvents::Base, void]
+  # : (Riffer::Agent, ?Hash[String, String]) -> Enumerator[Riffer::StreamEvents::Base, void]
+  def call_llm_stream: (Riffer::Agent, ?Hash[String, String]) -> Enumerator[Riffer::StreamEvents::Base, void]
 
   # --
-  # : (Riffer::Agent, Riffer::Messages::Assistant, ?tool_calls: Array[Riffer::Messages::Assistant::ToolCall]) -> void
-  def execute_tool_calls: (Riffer::Agent, Riffer::Messages::Assistant, ?tool_calls: Array[Riffer::Messages::Assistant::ToolCall]) -> void
+  # : (Riffer::Agent, Riffer::Messages::Assistant, ?tool_calls: Array[Riffer::Messages::Assistant::ToolCall], ?tags: Hash[String, String]) -> void
+  def execute_tool_calls: (Riffer::Agent, Riffer::Messages::Assistant, ?tool_calls: Array[Riffer::Messages::Assistant::ToolCall], ?tags: Hash[String, String]) -> void
 
   # --
   # : (Riffer::Agent, Array[[Riffer::Messages::Assistant::ToolCall, Riffer::Tools::Response]]) -> void
   def inject_discovered_tools: (Riffer::Agent, Array[[ Riffer::Messages::Assistant::ToolCall, Riffer::Tools::Response ]]) -> void
 
   # --
-  # : (Riffer::Agent) -> void
-  def execute_pending_tool_calls: (Riffer::Agent) -> void
+  # : (Riffer::Agent, ?Hash[String, String]) -> void
+  def execute_pending_tool_calls: (Riffer::Agent, ?Hash[String, String]) -> void
 
   # --
-  # : (Riffer::Agent, Enumerator::Yielder?, Array[Riffer::Guardrails::Modification]) { (Riffer::Guardrails::Tripwire) -> void } -> void
-  def run_before_guardrails: (Riffer::Agent, Enumerator::Yielder?, Array[Riffer::Guardrails::Modification]) { (Riffer::Guardrails::Tripwire) -> void } -> void
+  # : (Riffer::Agent, Enumerator::Yielder?, Array[Riffer::Guardrails::Modification], ?Hash[String, String]) { (Riffer::Guardrails::Tripwire) -> void } -> void
+  def run_before_guardrails: (Riffer::Agent, Enumerator::Yielder?, Array[Riffer::Guardrails::Modification], ?Hash[String, String]) { (Riffer::Guardrails::Tripwire) -> void } -> void
 
   # --
-  # : (Riffer::Agent, Riffer::Messages::Assistant, Enumerator::Yielder?, Array[Riffer::Guardrails::Modification]) { (Riffer::Guardrails::Tripwire) -> void } -> untyped
-  def run_after_guardrails: (Riffer::Agent, Riffer::Messages::Assistant, Enumerator::Yielder?, Array[Riffer::Guardrails::Modification]) { (Riffer::Guardrails::Tripwire) -> void } -> untyped
+  # : (Riffer::Agent, Riffer::Messages::Assistant, Enumerator::Yielder?, Array[Riffer::Guardrails::Modification], ?Hash[String, String]) { (Riffer::Guardrails::Tripwire) -> void } -> untyped
+  def run_after_guardrails: (Riffer::Agent, Riffer::Messages::Assistant, Enumerator::Yielder?, Array[Riffer::Guardrails::Modification], ?Hash[String, String]) { (Riffer::Guardrails::Tripwire) -> void } -> untyped
 
   # --
   # : (Riffer::Agent, Riffer::Messages::Assistant?) -> Hash[Symbol, untyped]?
@@ -79,9 +84,13 @@ module Riffer::Agent::Run
   # : (Riffer::Agent) -> Array[singleton(Riffer::Tool)]
   def effective_tools: (Riffer::Agent) -> Array[singleton(Riffer::Tool)]
 
+  # +tags+ rides in the options hash as a curated key the providers extract for
+  # native request-metadata mapping (alongside +:structured_output+); it never
+  # reaches an SDK call verbatim. Span/metric tagging is threaded separately to
+  # each builder.
   # --
-  # : (Riffer::Agent) -> Hash[Symbol, untyped]
-  def merged_model_options: (Riffer::Agent) -> Hash[Symbol, untyped]
+  # : (Riffer::Agent, ?Hash[String, String]) -> Hash[Symbol, untyped]
+  def merged_model_options: (Riffer::Agent, ?Hash[String, String]) -> Hash[Symbol, untyped]
 
   # --
   # : (Riffer::Agent, String, ?tripwire: Riffer::Guardrails::Tripwire?, ?modifications: Array[Riffer::Guardrails::Modification], ?interrupted: bool, ?interrupt_reason: (String | Symbol)?, ?structured_output: Hash[Symbol, untyped]?, ?healed_tool_call_ids: Array[String], ?token_usage: Riffer::Providers::TokenUsage?, ?steps: Integer) -> Riffer::Agent::Response
@@ -102,14 +111,22 @@ module Riffer::Agent::Run
   def sum_usage: (Riffer::Providers::TokenUsage?, Riffer::Providers::TokenUsage?) -> Riffer::Providers::TokenUsage?
 
   # --
-  # : (Riffer::Agent) -> Hash[String, untyped]
-  def run_span_attributes: (Riffer::Agent) -> Hash[String, untyped]
+  # : (Riffer::Agent, ?Hash[String, String]) -> Hash[String, untyped]
+  def run_span_attributes: (Riffer::Agent, ?Hash[String, String]) -> Hash[String, untyped]
 
   # --
-  # : (Riffer::Agent, String?) -> Hash[String, untyped]
-  def run_metric_attributes: (Riffer::Agent, String?) -> Hash[String, untyped]
+  # : (Riffer::Agent, String?, ?Hash[String, String]) -> Hash[String, untyped]
+  def run_metric_attributes: (Riffer::Agent, String?, ?Hash[String, String]) -> Hash[String, untyped]
 
   # --
-  # : (Riffer::Tracing::Otel::Span | Riffer::Tracing::Null::Span, Riffer::Agent::Response) -> void
-  def record_run_outcome: (Riffer::Tracing::Otel::Span | Riffer::Tracing::Null::Span, Riffer::Agent::Response) -> void
+  # : (Hash[(String | Symbol), untyped]?) -> Hash[String, String]
+  def normalize_tags: (Hash[String | Symbol, untyped]?) -> Hash[String, String]
+
+  # --
+  # : (Hash[String, String]) -> Hash[String, String]
+  def tag_attributes: (Hash[String, String]) -> Hash[String, String]
+
+  # --
+  # : (Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span, Riffer::Agent::Response) -> void
+  def record_run_outcome: (Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span, Riffer::Agent::Response) -> void
 end

data/sig/generated/riffer/agent.rbs

@@ -124,13 +124,13 @@ class Riffer::Agent
 
   # Generates a response using a new agent instance.
   # --
-  # : (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?context: Hash[Symbol, untyped]?) -> Riffer::Agent::Response
-  def self.generate: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?context: Hash[Symbol, untyped]?) -> Riffer::Agent::Response
+  # : (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?context: Hash[Symbol, untyped]?, ?tags: Hash[(String | Symbol), untyped]) -> Riffer::Agent::Response
+  def self.generate: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?context: Hash[Symbol, untyped]?, ?tags: Hash[String | Symbol, untyped]) -> Riffer::Agent::Response
 
   # Streams a response using a new agent instance.
   # --
-  # : (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?context: Hash[Symbol, untyped]?) -> Enumerator[Riffer::StreamEvents::Base, void]
-  def self.stream: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?context: Hash[Symbol, untyped]?) -> Enumerator[Riffer::StreamEvents::Base, void]
+  # : (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?context: Hash[Symbol, untyped]?, ?tags: Hash[(String | Symbol), untyped]) -> Enumerator[Riffer::StreamEvents::Base, void]
+  def self.stream: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?context: Hash[Symbol, untyped]?, ?tags: Hash[String | Symbol, untyped]) -> Enumerator[Riffer::StreamEvents::Base, void]
 
   # Reconstructs a runnable agent from a wire hash produced by +#to_h+.
   # --
@@ -213,18 +213,25 @@ class Riffer::Agent
   # against the current session, resuming a persisted conversation or pending
   # tool calls. +files:+ requires +prompt+.
   #
+  # +tags:+ is an optional flat hash of attribution tags applied to this single
+  # call: they propagate to the provider's native request-metadata field, and
+  # are stamped as +riffer.tag.*+ on every span and metric the call emits. See
+  # +docs/03_AGENTS.md+ for the per-provider mapping. The reserved key
+  # +user_id+ also maps to the provider's native user identifier where one
+  # exists.
+  #
   # --
-  # : (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?) -> Riffer::Agent::Response
-  def generate: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?) -> Riffer::Agent::Response
+  # : (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?tags: Hash[(String | Symbol), untyped]) -> Riffer::Agent::Response
+  def generate: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?tags: Hash[String | Symbol, untyped]) -> Riffer::Agent::Response
 
   # Streams a response from the agent, returning an +Enumerator+ of
-  # +Riffer::StreamEvents+. See +#generate+ for prompt/files semantics.
+  # +Riffer::StreamEvents+. See +#generate+ for prompt/files/tags semantics.
   #
   # Raises Riffer::ArgumentError if structured output is configured.
   #
   # --
-  # : (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?) -> Enumerator[Riffer::StreamEvents::Base, void]
-  def stream: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?) -> Enumerator[Riffer::StreamEvents::Base, void]
+  # : (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?tags: Hash[(String | Symbol), untyped]) -> Enumerator[Riffer::StreamEvents::Base, void]
+  def stream: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?tags: Hash[String | Symbol, untyped]) -> Enumerator[Riffer::StreamEvents::Base, void]
 
   # Interrupts the agent loop from an +on_message+ callback. Equivalent to
   # <tt>throw :riffer_interrupt, reason</tt>.

data/sig/generated/riffer/config.rbs

@@ -107,9 +107,9 @@ class Riffer::Config
     # content routinely carries sensitive data.
     attr_reader capture_messages: bool
 
-    # Explicit OTEL tracer provider; defaults to +nil+, which resolves the
-    # global <tt>OpenTelemetry.tracer_provider</tt> at first span.
-    attr_reader tracer_provider: untyped
+    # The backend riffer routes spans through; defaults to +nil+, a no-op.
+    # Riffer auto-detects no backend; assigning one is opt-in.
+    attr_reader backend: untyped
 
     # --
     # : () -> void
@@ -129,12 +129,12 @@ class Riffer::Config
     # : (untyped) -> void
     def capture_messages=: (untyped) -> void
 
-    # Sets an explicit tracer provider, forcing the OTEL backend. Raises
-    # Riffer::ArgumentError when the OpenTelemetry API gem isn't available
-    # at a supported version.
+    # Sets the tracing backend riffer routes spans through. Raises
+    # Riffer::ArgumentError unless the value is +nil+ or responds to the full
+    # delegated contract: +in_span+, +current_context+, and +with_context+.
     # --
     # : (untyped) -> void
-    def tracer_provider=: (untyped) -> void
+    def backend=: (untyped) -> void
   end
 
   # Metrics-related global configuration, independent of +config.tracing+ so a
@@ -144,9 +144,9 @@ class Riffer::Config
     # no-op until a host wires an OTEL metrics SDK.
     attr_reader enabled: bool
 
-    # Explicit OTEL meter provider; defaults to +nil+, which resolves the
-    # global <tt>OpenTelemetry.meter_provider</tt> at first record.
-    attr_reader meter_provider: untyped
+    # The backend riffer routes measurements through; defaults to +nil+, a no-op.
+    # Riffer auto-detects no backend; assigning one is opt-in.
+    attr_reader backend: untyped
 
     # --
     # : () -> void
@@ -159,12 +159,12 @@ class Riffer::Config
     # : (untyped) -> void
     def enabled=: (untyped) -> void
 
-    # Sets an explicit meter provider, forcing the OTEL backend. Raises
-    # Riffer::ArgumentError when the OpenTelemetry metrics API gem isn't
-    # available at a supported version.
+    # Sets the metrics backend riffer routes measurements through. Raises
+    # Riffer::ArgumentError unless the value is +nil+ or responds to
+    # +record_histogram+.
     # --
     # : (untyped) -> void
-    def meter_provider=: (untyped) -> void
+    def backend=: (untyped) -> void
   end
 
   # Consumer-configured token pricing, keyed by +provider/model+ id. Riffer

data/sig/generated/riffer/guardrails/runner.rbs

@@ -12,9 +12,12 @@ class Riffer::Guardrails::Runner
   # The context passed to guardrails.
   attr_reader context: untyped
 
+  # The normalized per-call tags, stamped as +riffer.tag.*+ on guardrail spans.
+  attr_reader tags: Hash[String, String]
+
   # --
-  # : (Array[Hash[Symbol, untyped]], phase: Symbol, ?context: untyped) -> void
-  def initialize: (Array[Hash[Symbol, untyped]], phase: Symbol, ?context: untyped) -> void
+  # : (Array[Hash[Symbol, untyped]], phase: Symbol, ?context: untyped, ?tags: Hash[String, String]) -> void
+  def initialize: (Array[Hash[Symbol, untyped]], phase: Symbol, ?context: untyped, ?tags: Hash[String, String]) -> void
 
   # Runs the guardrails sequentially. For the +:before+ phase +data+ is the
   # messages array; for +:after+ it's the response (and +messages+ must be
@@ -37,6 +40,10 @@ class Riffer::Guardrails::Runner
   # : (Riffer::Guardrail, untyped, messages: Array[Riffer::Messages::Base]?) -> Riffer::Guardrails::Result
   def execute_guardrail: (Riffer::Guardrail, untyped, messages: Array[Riffer::Messages::Base]?) -> Riffer::Guardrails::Result
 
+  # --
+  # : (Riffer::Guardrail) { () -> Riffer::Guardrails::Result } -> Riffer::Guardrails::Result
+  def instrument_guardrail: (Riffer::Guardrail) { () -> Riffer::Guardrails::Result } -> Riffer::Guardrails::Result
+
   # --
   # : (Riffer::Guardrail, untyped, messages: Array[Riffer::Messages::Base]?) -> Riffer::Guardrails::Result
   def run_guardrail_phase: (Riffer::Guardrail, untyped, messages: Array[Riffer::Messages::Base]?) -> Riffer::Guardrails::Result
@@ -45,9 +52,13 @@ class Riffer::Guardrails::Runner
   # : (Riffer::Guardrail) -> Hash[String, untyped]
   def guardrail_span_attributes: (Riffer::Guardrail) -> Hash[String, untyped]
 
+  # --
+  # : (Riffer::Guardrail, String?) -> Hash[String, untyped]
+  def guardrail_metric_attributes: (Riffer::Guardrail, String?) -> Hash[String, untyped]
+
   # A block is a handled outcome, so its span status stays unset — an error
   # span status is reserved for a raised exception.
   # --
-  # : ((Riffer::Tracing::Otel::Span | Riffer::Tracing::Null::Span), Riffer::Guardrails::Result) -> void
-  def record_guardrail_outcome: (Riffer::Tracing::Otel::Span | Riffer::Tracing::Null::Span, Riffer::Guardrails::Result) -> void
+  # : ((Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span), Riffer::Guardrails::Result) -> void
+  def record_guardrail_outcome: (Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span, Riffer::Guardrails::Result) -> void
 end

data/sig/generated/riffer/metrics/instruments.rbs

@@ -10,4 +10,6 @@ module Riffer::Metrics::Instruments
   TOKEN_USAGE: Riffer::Metrics::Histogram
 
   COST: Riffer::Metrics::Histogram
+
+  GUARDRAIL_DURATION: Riffer::Metrics::Histogram
 end

data/sig/generated/riffer/metrics/{null.rbs → no_op.rbs}

@@ -1,8 +1,8 @@
-# Generated from lib/riffer/metrics/null.rb with RBS::Inline
+# Generated from lib/riffer/metrics/no_op.rb with RBS::Inline
 
 # No-op metrics backend, used when the OpenTelemetry metrics API is unavailable
 # or metrics are disabled.
-module Riffer::Metrics::Null
+module Riffer::Metrics::NoOp
   # Ignores the measurement; there is no meter without the OTEL metrics API.
   # --
   # : (String, Numeric, unit: String?, description: String?, attributes: Hash[String, untyped]?) -> void

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

@@ -8,10 +8,11 @@ class Riffer::Metrics::Otel
   SUPPORTED_API_VERSIONS: Gem::Requirement
 
   # Builds a backend when the OpenTelemetry metrics API is loadable at a
-  # supported version; returns +nil+ so resolution falls back to Null.
+  # supported version; returns +nil+ so resolution falls back to NoOp.
+  # +provider+ defaults to the global <tt>OpenTelemetry.meter_provider</tt>.
   # --
-  # : (provider: untyped) -> Riffer::Metrics::Otel?
-  def self.build: (provider: untyped) -> Riffer::Metrics::Otel?
+  # : (?provider: untyped) -> Riffer::Metrics::Otel?
+  def self.build: (?provider: untyped) -> Riffer::Metrics::Otel?
 
   # Whether the OpenTelemetry metrics API gem is loadable at a supported
   # version.

data/sig/generated/riffer/metrics.rbs

@@ -4,7 +4,7 @@
 # the OpenTelemetry metrics API and no-ops otherwise, so riffer never declares
 # an OTEL dependency.
 module Riffer::Metrics
-  @backend: (Riffer::Metrics::Otel | singleton(Riffer::Metrics::Null))?
+  @backend: untyped
 
   MUTEX: Mutex
 
@@ -42,7 +42,8 @@ module Riffer::Metrics
   def record_histogram: (String, Numeric, ?unit: String?, ?description: String?, ?attributes: Hash[String, untyped]?) -> void
 
   # Mirrors a span's +recording?+ so a caller can skip work that exists only to
-  # feed a metric.
+  # feed a metric. True for any live backend — the OTEL backend or a
+  # consumer-supplied one — so a custom metrics sink still gets fed.
   # --
   # : () -> bool
   def recording?: () -> bool
@@ -62,10 +63,10 @@ module Riffer::Metrics
   private
 
   # --
-  # : () -> (Riffer::Metrics::Otel | singleton(Riffer::Metrics::Null))
-  def backend: () -> (Riffer::Metrics::Otel | singleton(Riffer::Metrics::Null))
+  # : () -> untyped
+  def backend: () -> untyped
 
   # --
-  # : () -> (Riffer::Metrics::Otel | singleton(Riffer::Metrics::Null))
-  def resolve_backend: () -> (Riffer::Metrics::Otel | singleton(Riffer::Metrics::Null))
+  # : () -> untyped
+  def resolve_backend: () -> untyped
 end