riffer 0.34.0 → 0.36.0

data/lib/riffer/providers/amazon_bedrock.rb

@@ -64,14 +64,20 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
     tools = options[:tools]
     structured_output = options[:structured_output]
     cache_control = options[:cache_control]
+    tags = options[:tags] || {}
 
     params = {
       model_id: model,
       system: partitioned_messages[:system],
       messages: partitioned_messages[:conversation],
-      **options.except(:tools, :structured_output, :cache_control)
+      **options.except(:tools, :structured_output, :cache_control, :tags)
     } #: Hash[Symbol, untyped]
 
+    # requestMetadata is a flat String=>String map used to filter invocation
+    # logs; every tag (including the reserved user_id) rides along, since
+    # Converse has no dedicated end-user field.
+    params[:request_metadata] = tags unless tags.empty?
+
     if tools && !tools.empty?
       params[:tool_config] = {
         tools: tools.map { |t| convert_tool_to_bedrock_format(t) }

data/lib/riffer/providers/anthropic.rb

@@ -48,6 +48,7 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
     tools = options[:tools]
     structured_output = options[:structured_output]
     web_search = options[:web_search]
+    tags = options[:tags] || {}
 
     max_tokens = options.fetch(:max_tokens, 4096)
 
@@ -55,11 +56,17 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
       model: model,
       messages: partitioned_messages[:conversation],
       max_tokens: max_tokens,
-      **options.except(:tools, :max_tokens, :structured_output, :web_search)
+      **options.except(:tools, :max_tokens, :structured_output, :web_search, :tags)
     } #: Hash[Symbol, untyped]
 
     params[:system] = partitioned_messages[:system] if partitioned_messages[:system]
 
+    # Anthropic's only request-metadata field is metadata.user_id (opaque, no
+    # PII). It carries the reserved user_id tag; all other tags are dropped
+    # here and survive only on spans.
+    user_id = tags["user_id"]
+    params[:metadata] = {user_id: user_id} if user_id
+
     anthropic_tools = [] #: Array[Hash[Symbol, untyped]]
     anthropic_tools.concat(tools.map { |t| convert_tool_to_anthropic_format(t) }) if tools && !tools.empty?
 

data/lib/riffer/providers/base.rb

@@ -57,8 +57,6 @@ class Riffer::Providers::Base
       structured_output = parse_structured_output(content) if options[:structured_output] && tool_calls.empty?
 
       Riffer::Tracing.record_usage(span, token_usage)
-      record_token_usage_metric(model, token_usage)
-      record_cost_metric(model, token_usage)
       record_finish_reason(span, finish_reason&.reason, finish_reason&.raw)
       capture_output(span, content: content, tool_calls: tool_calls, finish_reason: finish_reason&.reason)
 
@@ -86,22 +84,15 @@ class Riffer::Providers::Base
     params = build_request_params(messages, model, options)
 
     # The enumerator body runs in its own fiber, where the fiber-local OTEL
-    # context is empty — capture here so the chat span parents to the
-    # caller's trace.
+    # context is empty — capture here so the chat span parents to the caller's
+    # trace.
     trace_context = Riffer::Tracing.current_context
     Enumerator.new do |yielder|
       Riffer::Tracing.with_context(trace_context) do
         in_chat_span(model, messages, options) do |span|
-          # The recorder feeds both the span and the token-usage metric, so build
-          # it whenever either is live — metrics fire even with tracing off.
-          observe = span.recording? || Riffer::Metrics.recording?
-          sink = observe ? Riffer::Tracing::StreamRecorder.new(yielder) : yielder
+          sink = span.recording? ? Riffer::Tracing::StreamRecorder.new(yielder) : yielder
           execute_stream(params, sink)
-          if sink.is_a?(Riffer::Tracing::StreamRecorder)
-            record_stream_outcome(span, sink)
-            record_token_usage_metric(model, sink.token_usage)
-            record_cost_metric(model, sink.token_usage)
-          end
+          record_stream_outcome(span, sink) if sink.is_a?(Riffer::Tracing::StreamRecorder)
         end
       end
     end
@@ -222,25 +213,14 @@ class Riffer::Providers::Base
   #--
   #: [R] (String?, Array[Riffer::Messages::Base], Hash[Symbol, untyped]) { (Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span) -> R } -> R
   def in_chat_span(model, messages, options)
-    start = Riffer::Metrics.monotonic_now
-    error_type = nil #: String?
-    begin
-      Riffer::Tracing.in_span(model ? "chat #{model}" : "chat", attributes: chat_span_attributes(model, options), kind: :client) do |span|
-        capture_input(span, messages)
-        yield span
-      rescue => error
-        # The backend records the exception and error status on the re-raise;
-        # error.type is the one semconv attribute it doesn't set.
-        span.set_attribute("error.type", error.class.name)
-        raise
-      end
+    Riffer::Tracing.in_span(model ? "chat #{model}" : "chat", attributes: chat_span_attributes(model, options), kind: :client) do |span|
+      capture_input(span, messages)
+      yield span
     rescue => error
-      # The inner rescue tags the span; capture error.type here too, at method
-      # scope, where the ensure can read it onto the metric.
-      error_type = error.class.name #: String?
+      # The backend records the exception and error status on the re-raise;
+      # error.type is the one semconv attribute it doesn't set.
+      span.set_attribute("error.type", error.class.name)
       raise
-    ensure
-      Riffer::Metrics::Instruments::OPERATION_DURATION.record(Riffer::Metrics.monotonic_now - start, attributes: chat_metric_attributes(model, error_type))
     end
   end
 
@@ -258,47 +238,15 @@ class Riffer::Providers::Base
       attributes[attribute] = value unless value.nil?
     end
 
-    attributes
-  end
-
-  #--
-  #: (String?) -> Hash[String, untyped]
-  def chat_metric_base_attributes(model)
-    attributes = {
-      "gen_ai.operation.name" => "chat",
-      "gen_ai.provider.name" => self.class.semconv_provider_name
-    } #: Hash[String, untyped]
-    attributes["gen_ai.request.model"] = model if model
-    attributes
+    attributes.merge(tag_attributes(options[:tags] || {}))
   end
 
+  # Maps normalized tags to their namespaced span attribute form. An empty map
+  # yields an empty hash, so merging it is a no-op.
   #--
-  #: (String?, String?) -> Hash[String, untyped]
-  def chat_metric_attributes(model, error_type)
-    attributes = chat_metric_base_attributes(model)
-    attributes["error.type"] = error_type if error_type
-    attributes
-  end
-
-  # Per-call only — the run level would double-count an aggregate.
-  #--
-  #: (String?, Riffer::Providers::TokenUsage?) -> void
-  def record_token_usage_metric(model, usage)
-    return unless usage
-
-    base = chat_metric_base_attributes(model)
-    Riffer::Metrics::Instruments::TOKEN_USAGE.record(usage.input_tokens, attributes: base.merge("gen_ai.token.type" => "input"))
-    Riffer::Metrics::Instruments::TOKEN_USAGE.record(usage.output_tokens, attributes: base.merge("gen_ai.token.type" => "output"))
-  end
-
-  # Per-call only — the run level would double-count an aggregate.
-  #--
-  #: (String?, Riffer::Providers::TokenUsage?) -> void
-  def record_cost_metric(model, usage)
-    cost = usage&.cost
-    return unless cost
-
-    Riffer::Metrics::Instruments::COST.record(cost, attributes: chat_metric_base_attributes(model))
+  #: (Hash[String, String]) -> Hash[String, String]
+  def tag_attributes(tags)
+    tags.transform_keys { |key| "riffer.tag.#{key}" }
   end
 
   #--

data/lib/riffer/providers/gemini.rb

@@ -67,7 +67,11 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
       }]
     end
 
-    generation_config = options.except(:tools, :structured_output)
+    # tags propagate to observability only: the Gemini Developer API has no
+    # request labels field (unknown body fields are rejected), so :tags is
+    # stripped here rather than mapped. Native labels would arrive with a Vertex
+    # adapter. See docs/10_CONFIGURATION.md.
+    generation_config = options.except(:tools, :structured_output, :tags)
 
     if structured_output
       generation_config[:responseMimeType] = "application/json"

data/lib/riffer/providers/open_ai.rb

@@ -30,6 +30,7 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
     tools = options[:tools]
     structured_output = options[:structured_output]
     web_search = options[:web_search]
+    tags = options[:tags] || {}
 
     params = {
       input: convert_messages_to_openai_format(messages),
@@ -38,9 +39,17 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
         effort: reasoning,
         summary: "auto"
       },
-      **options.except(:reasoning, :tools, :structured_output, :web_search)
+      **options.except(:reasoning, :tools, :structured_output, :web_search, :tags)
     } #: Hash[Symbol, untyped]
 
+    unless tags.empty?
+      params[:metadata] = tags
+      # The reserved user_id also maps to the native safety identifier while
+      # staying in metadata as an ordinary tag.
+      user_id = tags["user_id"]
+      params[:safety_identifier] = user_id if user_id
+    end
+
     openai_tools = [] #: Array[Hash[Symbol, untyped]]
     openai_tools.concat(tools.map { |t| convert_tool_to_openai_format(t) }) if tools && !tools.empty?
 

data/lib/riffer/providers/open_router.rb

@@ -44,13 +44,22 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
     reasoning = options[:reasoning]
     tools = options[:tools]
     structured_output = options[:structured_output]
+    tags = options[:tags] || {}
 
     params = {
       model: model,
       messages: convert_messages_to_chat_completions_format(messages),
-      **options.except(:reasoning, :tools, :structured_output)
+      **options.except(:reasoning, :tools, :structured_output, :tags)
     } #: Hash[Symbol, untyped]
 
+    unless tags.empty?
+      params[:metadata] = 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"]
+      params[:user] = user if user
+    end
+
     if reasoning
       params[:reasoning] = reasoning.is_a?(String) ? {effort: reasoning} : reasoning
     end

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 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,24 +59,14 @@ 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)
-    start = Riffer::Metrics.monotonic_now
-    error_type = nil #: String?
-    begin
-      result = in_tool_span(tool_call) do |span|
-        response = yield
-        record_tool_outcome(span, response)
-        response
-      end
-      error_type = result.error_type&.to_s
-      [tool_call, result] #: [Riffer::Messages::Assistant::ToolCall, Riffer::Tools::Response]
-    rescue => error
-      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::Messages::Assistant::ToolCall, ?Hash[String, String]) { () -> Riffer::Tools::Response } -> [Riffer::Messages::Assistant::ToolCall, Riffer::Tools::Response]
+  def instrument_tool_call(tool_call, tags = {})
+    result = in_tool_span(tool_call, tags) do |span|
+      response = yield
+      record_tool_outcome(span, response)
+      response
     end
+    [tool_call, result] #: [Riffer::Messages::Assistant::ToolCall, Riffer::Tools::Response]
   end
 
   #--
@@ -113,9 +105,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::NoOp::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,24 +119,21 @@ 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
 
+  # Maps normalized tags to their namespaced span attribute form. An empty map
+  # yields an empty hash, so merging it is a no-op.
   #--
-  #: (Riffer::Messages::Assistant::ToolCall, String?) -> Hash[String, untyped]
-  def tool_metric_attributes(tool_call, error_type)
-    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
+  #: (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 —

data/lib/riffer/version.rb

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

data/sig/_private/opentelemetry.rbs

@@ -1,13 +1,10 @@
-# Minimal signatures for the `opentelemetry-api` and `opentelemetry-metrics-api`
-# gems (undeclared, runtime detected), which ship no RBS.
+# Minimal signatures for the `opentelemetry-api` gem (undeclared, runtime
+# detected), which ships no RBS.
 #
-# Only the surface used by Riffer::Tracing::Otel and Riffer::Metrics::Otel is
-# declared.
+# Only the surface used by Riffer::Tracing::Otel is declared.
 module OpenTelemetry
   def self.tracer_provider: () -> untyped
 
-  def self.meter_provider: () -> untyped
-
   class Context
     def self.current: () -> OpenTelemetry::Context
 

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 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 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,12 +111,16 @@ 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]
+  # : (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

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 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

@@ -137,36 +137,6 @@ class Riffer::Config
     def backend=: (untyped) -> void
   end
 
-  # Metrics-related global configuration, independent of +config.tracing+ so a
-  # host can run one signal without the other.
-  class Metrics
-    # Whether riffer records OTEL metric instruments; defaults to +true+, a
-    # no-op until a host wires an OTEL metrics SDK.
-    attr_reader enabled: bool
-
-    # 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
-    def initialize: () -> void
-
-    # Sets the enabled flag, coercing boolean-ish values so an env-var
-    # +"false"+ (truthy in Ruby) doesn't silently keep metrics on. Raises
-    # Riffer::ArgumentError on an unrecognized value.
-    # --
-    # : (untyped) -> void
-    def enabled=: (untyped) -> void
-
-    # Sets the metrics backend riffer routes measurements through. Raises
-    # Riffer::ArgumentError unless the value is +nil+ or responds to
-    # +record_histogram+.
-    # --
-    # : (untyped) -> void
-    def backend=: (untyped) -> void
-  end
-
   # Consumer-configured token pricing, keyed by +provider/model+ id. Riffer
   # ships no price table, so an unconfigured model carries no cost.
   class Pricing
@@ -276,9 +246,6 @@ class Riffer::Config
   # Tracing-related global configuration.
   attr_reader tracing: Riffer::Config::Tracing
 
-  # Metrics-related global configuration.
-  attr_reader metrics: Riffer::Config::Metrics
-
   # Consumer-configured per-model token pricing.
   attr_reader pricing: Riffer::Config::Pricing
 

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,10 +40,6 @@ 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
@@ -49,10 +48,6 @@ 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.
   # --