riffer 0.32.1 → 0.34.0

data/lib/riffer/agent/run.rb

@@ -23,7 +23,12 @@ module Riffer::Agent::Run
   #: (agent: Riffer::Agent, ?prompt: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?) -> Enumerator[Riffer::StreamEvents::Base, void]
   def stream(agent:, prompt: nil, files: nil)
     append_user_message(agent, prompt, files: files)
-    Enumerator.new { |stream_yielder| run_loop(agent, stream_yielder: stream_yielder) }
+    # The enumerator body runs in its own fiber, where the fiber-local OTEL
+    # context is empty — capture here so the run span parents to the caller's trace.
+    trace_context = Riffer::Tracing.current_context
+    Enumerator.new do |stream_yielder|
+      Riffer::Tracing.with_context(trace_context) { run_loop(agent, stream_yielder: stream_yielder) }
+    end
   end
 
   private
@@ -31,45 +36,89 @@ module Riffer::Agent::Run
   #--
   #: (Riffer::Agent, ?stream_yielder: Enumerator::Yielder?) -> Riffer::Agent::Response
   def run_loop(agent, stream_yielder: nil)
+    start = Riffer::Metrics.monotonic_now
+    error_type = nil #: String?
+    begin
+      Riffer::Tracing.in_span("invoke_agent #{agent.class.identifier}", attributes: run_span_attributes(agent), kind: :internal) do |span|
+        response = execute_run(agent, stream_yielder)
+        record_run_outcome(span, response)
+        response
+      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
+    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?
+      raise
+    ensure
+      Riffer::Metrics::Instruments::OPERATION_DURATION.record(Riffer::Metrics.monotonic_now - start, attributes: run_metric_attributes(agent, error_type))
+    end
+  end
+
+  #--
+  #: (Riffer::Agent, Enumerator::Yielder?) -> Riffer::Agent::Response
+  def execute_run(agent, stream_yielder)
     all_modifications = [] #: Array[Riffer::Guardrails::Modification]
+    run_usage = nil #: Riffer::Providers::TokenUsage?
+    run_steps = 0
 
-    run_before_guardrails(agent, stream_yielder, all_modifications) { |tripped| return tripped }
+    run_before_guardrails(agent, stream_yielder, all_modifications) do |tripwire|
+      return tripwire_response(agent, stream_yielder, tripwire, all_modifications, steps: run_steps)
+    end
 
     skills = agent.context.skills
+    consumer_on_activate = skills&.on_activate
 
     if stream_yielder && skills
-      skills.on_activate = ->(name) { stream_yielder << Riffer::StreamEvents::SkillActivation.new(name) }
+      skills.on_activate = ->(name) {
+        consumer_on_activate&.call(name)
+        stream_yielder << Riffer::StreamEvents::SkillActivation.new(name)
+      }
     end
 
-    step = agent.session.steps
+    begin
+      step = agent.session.steps
 
-    reason = catch(:riffer_interrupt) do
-      execute_pending_tool_calls(agent)
+      reason = catch(:riffer_interrupt) do
+        execute_pending_tool_calls(agent)
 
-      loop do
-        response = stream_yielder ? accumulate_streamed_response(agent, stream_yielder) : call_llm(agent)
-        step += 1
-        track_token_usage(agent, response.token_usage)
+        loop do
+          response = stream_yielder ? accumulate_streamed_response(agent, stream_yielder) : call_llm(agent)
+          step += 1
+          run_steps += 1
+          track_token_usage(agent, response.token_usage)
+          run_usage = sum_usage(run_usage, response.token_usage)
 
-        processed_response = run_after_guardrails(agent, response, stream_yielder, all_modifications) { |tripped| return tripped }
+          processed_response = run_after_guardrails(agent, response, stream_yielder, all_modifications) do |tripwire|
+            return tripwire_response(agent, stream_yielder, tripwire, all_modifications, token_usage: run_usage, steps: run_steps)
+          end
 
-        agent.session.add(processed_response)
+          agent.session.add(processed_response)
 
-        break unless processed_response.has_tool_calls?
+          break unless processed_response.has_tool_calls?
 
-        max_steps = agent.config.max_steps
-        throw :riffer_interrupt, Riffer::Agent::INTERRUPT_MAX_STEPS if max_steps && step >= max_steps
+          max_steps = agent.config.max_steps
+          throw :riffer_interrupt, Riffer::Agent::INTERRUPT_MAX_STEPS if max_steps && step >= max_steps
 
-        execute_tool_calls(agent, processed_response)
+          execute_tool_calls(agent, processed_response)
+        end
+
+        return final_response(agent, all_modifications, token_usage: run_usage, steps: run_steps)
       end
 
-      return final_response(agent, all_modifications)
+      new_messages, filled = Riffer::Agent::Session::Repair.fill_orphans(agent.session.messages)
+      agent.session.set(new_messages)
+      stream_yielder << Riffer::StreamEvents::Interrupt.new(reason: reason, healed_tool_call_ids: filled) if stream_yielder
+      final_response(agent, all_modifications, interrupted: true, interrupt_reason: reason, healed_tool_call_ids: filled, token_usage: run_usage, steps: run_steps)
+    ensure
+      # The stream wiring must not outlive the run — a leaked lambda would push
+      # later harness-side activations into a dead Enumerator::Yielder.
+      skills.on_activate = consumer_on_activate if stream_yielder && skills
     end
-
-    new_messages, filled = Riffer::Agent::Session::Repair.fill_orphans(agent.session.messages)
-    agent.session.set(new_messages)
-    stream_yielder << Riffer::StreamEvents::Interrupt.new(reason: reason, healed_tool_call_ids: filled) if stream_yielder
-    final_response(agent, all_modifications, interrupted: true, interrupt_reason: reason, healed_tool_call_ids: filled)
   end
 
   #--
@@ -78,6 +127,7 @@ module Riffer::Agent::Run
     accumulated_content = ""
     accumulated_tool_calls = [] #: Array[Riffer::Messages::Assistant::ToolCall]
     accumulated_token_usage = nil #: Riffer::Providers::TokenUsage?
+    accumulated_finish_reason = nil #: Symbol?
 
     call_llm_stream(agent).each do |event|
       stream_yielder << event
@@ -95,13 +145,16 @@ module Riffer::Agent::Run
         )
       when Riffer::StreamEvents::TokenUsageDone
         accumulated_token_usage = event.token_usage
+      when Riffer::StreamEvents::FinishReasonDone
+        accumulated_finish_reason = event.finish_reason
       end
     end
 
     Riffer::Messages::Assistant.new(
       accumulated_content,
       tool_calls: accumulated_tool_calls,
-      token_usage: accumulated_token_usage
+      token_usage: accumulated_token_usage,
+      finish_reason: accumulated_finish_reason
     )
   end
 
@@ -113,10 +166,10 @@ module Riffer::Agent::Run
   end
 
   #--
-  #: (Riffer::Agent, Enumerator::Yielder?, Riffer::Guardrails::Tripwire, Array[Riffer::Guardrails::Modification]) -> Riffer::Agent::Response
-  def tripwire_response(agent, stream_yielder, tripwire, all_modifications)
+  #: (Riffer::Agent, Enumerator::Yielder?, Riffer::Guardrails::Tripwire, Array[Riffer::Guardrails::Modification], ?token_usage: Riffer::Providers::TokenUsage?, ?steps: Integer) -> Riffer::Agent::Response
+  def tripwire_response(agent, stream_yielder, tripwire, all_modifications, token_usage: nil, steps: 0)
     stream_yielder << Riffer::StreamEvents::GuardrailTripwire.new(tripwire) if stream_yielder
-    build_response(agent, "", tripwire: tripwire, modifications: all_modifications)
+    build_response(agent, "", tripwire: tripwire, modifications: all_modifications, token_usage: token_usage, steps: steps)
   end
 
   #--
@@ -187,7 +240,7 @@ module Riffer::Agent::Run
   end
 
   #--
-  #: (Riffer::Agent, Enumerator::Yielder?, Array[Riffer::Guardrails::Modification]) { (Riffer::Agent::Response) -> void } -> void
+  #: (Riffer::Agent, Enumerator::Yielder?, Array[Riffer::Guardrails::Modification]) { (Riffer::Guardrails::Tripwire) -> void } -> void
   def run_before_guardrails(agent, stream_yielder, all_modifications)
     guardrails = agent.config.guardrails_for(:before)
     return if guardrails.empty?
@@ -196,11 +249,11 @@ module Riffer::Agent::Run
     processed_messages, tripwire, modifications = runner.run(agent.session.messages)
     agent.session.set(processed_messages) unless tripwire
     record_modifications!(stream_yielder, all_modifications, modifications)
-    yield tripwire_response(agent, stream_yielder, tripwire, all_modifications) if tripwire
+    yield tripwire if tripwire
   end
 
   #--
-  #: (Riffer::Agent, Riffer::Messages::Assistant, Enumerator::Yielder?, Array[Riffer::Guardrails::Modification]) { (Riffer::Agent::Response) -> void } -> untyped
+  #: (Riffer::Agent, Riffer::Messages::Assistant, Enumerator::Yielder?, Array[Riffer::Guardrails::Modification]) { (Riffer::Guardrails::Tripwire) -> void } -> untyped
   def run_after_guardrails(agent, response, stream_yielder, all_modifications)
     guardrails = agent.config.guardrails_for(:after)
     return response if guardrails.empty?
@@ -212,7 +265,7 @@ module Riffer::Agent::Run
     modifications.each { |m| m.message_indices.map! { response_index } }
 
     record_modifications!(stream_yielder, all_modifications, modifications)
-    yield tripwire_response(agent, stream_yielder, tripwire, all_modifications) if tripwire
+    yield tripwire if tripwire
 
     processed_response
   end
@@ -241,10 +294,10 @@ module Riffer::Agent::Run
   end
 
   #--
-  #: (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]) -> Riffer::Agent::Response
-  def build_response(agent, content, tripwire: nil, modifications: [], interrupted: false, interrupt_reason: nil, structured_output: nil, healed_tool_call_ids: [])
+  #: (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
+  def build_response(agent, content, tripwire: nil, modifications: [], interrupted: false, interrupt_reason: nil, structured_output: nil, healed_tool_call_ids: [], token_usage: nil, steps: 0)
     messages = agent.session.messages
-    Riffer::Agent::Response.new(content, tripwire: tripwire, modifications: modifications, interrupted: interrupted, interrupt_reason: interrupt_reason, structured_output: structured_output, messages: messages.frozen? ? messages : messages.dup.freeze, healed_tool_call_ids: healed_tool_call_ids)
+    Riffer::Agent::Response.new(content, tripwire: tripwire, modifications: modifications, interrupted: interrupted, interrupt_reason: interrupt_reason, structured_output: structured_output, messages: messages.frozen? ? messages : messages.dup.freeze, healed_tool_call_ids: healed_tool_call_ids, token_usage: token_usage, steps: steps)
   end
 
   # Raises when +files+ are supplied without a +prompt+ — the provider needs
@@ -264,7 +317,55 @@ module Riffer::Agent::Run
   def track_token_usage(agent, usage)
     return unless usage
 
-    current = agent.context.token_usage
-    agent.context.token_usage = current ? current + usage : usage
+    agent.context.token_usage = sum_usage(agent.context.token_usage, usage)
+  end
+
+  #--
+  #: (Riffer::Providers::TokenUsage?, Riffer::Providers::TokenUsage?) -> Riffer::Providers::TokenUsage?
+  def sum_usage(current, usage)
+    return current unless usage
+
+    current ? current + usage : usage
+  end
+
+  #--
+  #: (Riffer::Agent) -> Hash[String, untyped]
+  def run_span_attributes(agent)
+    {
+      "gen_ai.operation.name" => "invoke_agent",
+      "gen_ai.agent.name" => agent.class.identifier,
+      "gen_ai.provider.name" => agent.provider.class.semconv_provider_name,
+      "gen_ai.request.model" => agent.model_name
+    }
+  end
+
+  #--
+  #: (Riffer::Agent, String?) -> Hash[String, untyped]
+  def run_metric_attributes(agent, error_type)
+    attributes = {
+      "gen_ai.operation.name" => "invoke_agent",
+      "gen_ai.provider.name" => agent.provider.class.semconv_provider_name,
+      "gen_ai.request.model" => agent.model_name,
+      "gen_ai.agent.name" => agent.class.identifier
+    } #: Hash[String, untyped]
+    attributes["error.type"] = error_type if error_type
+    attributes
+  end
+
+  #--
+  #: (Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span, Riffer::Agent::Response) -> void
+  def record_run_outcome(span, response)
+    span.set_attribute("riffer.steps", response.steps)
+    Riffer::Tracing.record_usage(span, response.token_usage)
+
+    span.set_attribute("riffer.interrupt.reason", response.interrupt_reason.to_s) if response.interrupt_reason
+
+    tripwire = response.tripwire
+    return unless tripwire
+
+    class_name = tripwire.guardrail.name
+    span.set_attribute("riffer.tripwire.guardrail", Riffer::Helpers::ClassNameConverter.convert(class_name)) if class_name
+    span.set_attribute("riffer.tripwire.reason", tripwire.reason)
+    span.set_attribute("riffer.tripwire.phase", tripwire.phase.to_s)
   end
 end

data/lib/riffer/agent.rb

@@ -395,7 +395,7 @@ class Riffer::Agent
 
     if skills_config.activate
       names = Array(Riffer::Helpers::CallOrValue.resolve(skills_config.activate, context: @context))
-      names.each { |name| skills_context.activate(name) }
+      names.each { |name| skills_context.preactivate(name) }
     end
 
     skills_context

data/lib/riffer/config.rb

@@ -3,14 +3,14 @@
 
 # Configuration for the Riffer framework.
 class Riffer::Config
-  AmazonBedrock = Struct.new(:api_token, :region, keyword_init: true)
-  Anthropic = Struct.new(:api_key, keyword_init: true)
-  AzureOpenAI = Struct.new(:api_key, :endpoint, keyword_init: true)
-  Gemini = Struct.new(:api_key, :open_timeout, :read_timeout, keyword_init: true)
-  OpenAI = Struct.new(:api_key, keyword_init: true)
-  OpenRouter = Struct.new(:api_key, keyword_init: true)
-  Evals = Struct.new(:judge_model, keyword_init: true)
-  Mcp = Struct.new(:credentials, :discovery_runner, keyword_init: true)
+  AmazonBedrock = Struct.new(:api_token, :region)
+  Anthropic = Struct.new(:api_key)
+  AzureOpenAI = Struct.new(:api_key, :endpoint)
+  Gemini = Struct.new(:api_key, :open_timeout, :read_timeout)
+  OpenAI = Struct.new(:api_key)
+  OpenRouter = Struct.new(:api_key)
+  Evals = Struct.new(:judge_model)
+  Mcp = Struct.new(:credentials, :discovery_runner)
 
   # Skills-related global configuration.
   class Skills
@@ -49,6 +49,215 @@ class Riffer::Config
     end
   end
 
+  # Tracing-related global configuration.
+  class Tracing
+    # Whether riffer emits OTEL spans; defaults to +true+, a no-op until a
+    # host wires an OTEL SDK.
+    attr_reader :enabled #: bool
+
+    # Whether LLM-call spans capture full message content
+    # (<tt>gen_ai.input.messages</tt>, <tt>gen_ai.output.messages</tt>,
+    # <tt>gen_ai.system_instructions</tt>); defaults to +false+ — message
+    # content routinely carries sensitive data.
+    attr_reader :capture_messages #: bool
+
+    # 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
+    def initialize
+      @enabled = true
+      @capture_messages = false
+      @backend = nil
+    end
+
+    # Sets the enabled flag, coercing boolean-ish values so an env-var
+    # +"false"+ (truthy in Ruby) doesn't silently keep tracing on. Raises
+    # Riffer::ArgumentError on an unrecognized value.
+    #--
+    #: (untyped) -> void
+    def enabled=(value)
+      @enabled = Riffer::Helpers::Boolean.coerce(value, attribute: "enabled")
+    end
+
+    # Sets the capture_messages flag, coercing boolean-ish values so an
+    # env-var +"false"+ (truthy in Ruby) doesn't silently enable content
+    # capture. Raises Riffer::ArgumentError on an unrecognized value.
+    #--
+    #: (untyped) -> void
+    def capture_messages=(value)
+      @capture_messages = Riffer::Helpers::Boolean.coerce(value, attribute: "capture_messages")
+    end
+
+    # 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 backend=(value)
+      contract = %i[in_span current_context with_context]
+      unless value.nil? || contract.all? { |method| value.respond_to?(method) }
+        raise Riffer::ArgumentError, "tracing backend must respond to #in_span, #current_context, and #with_context"
+      end
+      @backend = value
+      Riffer::Tracing.reset!
+    end
+  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
+      @enabled = true
+      @backend = nil
+    end
+
+    # 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=(value)
+      @enabled = Riffer::Helpers::Boolean.coerce(value, attribute: "enabled")
+    end
+
+    # 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=(value)
+      unless value.nil? || value.respond_to?(:record_histogram)
+        raise Riffer::ArgumentError, "metrics backend must respond to #record_histogram"
+      end
+      @backend = value
+      Riffer::Metrics.reset!
+    end
+  end
+
+  # Consumer-configured token pricing, keyed by +provider/model+ id. Riffer
+  # ships no price table, so an unconfigured model carries no cost.
+  class Pricing
+    # @rbs @rates: Hash[String, Riffer::Config::Pricing::Rates]
+
+    # Per-million-token rates for one model's four token buckets. +cache_read+
+    # and +cache_write+ fall back to the +input+ rate when unset.
+    class Rates
+      # Input rate per million tokens.
+      attr_reader :input #: Float
+
+      # Output rate per million tokens.
+      attr_reader :output #: Float
+
+      # Cache-read rate per million tokens.
+      attr_reader :cache_read #: Float?
+
+      # Cache-write rate per million tokens.
+      attr_reader :cache_write #: Float?
+
+      #--
+      #: (input: Float, output: Float, ?cache_read: Float?, ?cache_write: Float?) -> void
+      def initialize(input:, output:, cache_read: nil, cache_write: nil)
+        @input = input
+        @output = output
+        @cache_read = cache_read
+        @cache_write = cache_write
+      end
+
+      # Returns the cost for the given token counts.
+      #--
+      #: (input_tokens: Integer, output_tokens: Integer, ?cache_read_tokens: Integer?, ?cache_write_tokens: Integer?) -> Float
+      def cost_for(input_tokens:, output_tokens:, cache_read_tokens: nil, cache_write_tokens: nil)
+        read = cache_read_tokens || 0
+        write = cache_write_tokens || 0
+        uncached = input_tokens - read - write
+        uncached = 0 if uncached.negative?
+
+        per_million = uncached * input +
+          read * (cache_read || input) +
+          write * (cache_write || input) +
+          output_tokens * output
+        per_million / 1_000_000.0
+      end
+    end
+
+    #--
+    #: () -> void
+    def initialize
+      @rates = {}
+    end
+
+    # Registers per-million-token rates for a +provider/model+ id/s. Raises
+    # Riffer::ArgumentError on a malformed id or a negative/non-numeric rate.
+    #--
+    #: ((String | Array[String]), input: Numeric, output: Numeric, ?cache_read: Numeric?, ?cache_write: Numeric?) -> void
+    def set(models, input:, output:, cache_read: nil, cache_write: nil)
+      ids = models.is_a?(Array) ? models : [models]
+      raise Riffer::ArgumentError, "at least one model id is required" if ids.empty?
+      ids.each { |id| validate_model!(id) }
+
+      rates = Rates.new(
+        input: coerce_rate(input, "input"),
+        output: coerce_rate(output, "output"),
+        cache_read: coerce_optional_rate(cache_read, "cache_read"),
+        cache_write: coerce_optional_rate(cache_write, "cache_write")
+      )
+      ids.each { |id| @rates[id] = rates }
+    end
+
+    # Returns the rates registered for a +provider/model+ id.
+    #--
+    #: (String) -> Riffer::Config::Pricing::Rates?
+    def rates_for(model)
+      @rates[model]
+    end
+
+    # Returns true when no rates are registered.
+    #--
+    #: () -> bool
+    def empty?
+      @rates.empty?
+    end
+
+    private
+
+    #--
+    #: (String) -> void
+    def validate_model!(model)
+      segments = model.to_s.split("/", 2)
+      valid = segments.length == 2 && segments.none? { |segment| segment.strip.empty? }
+      raise Riffer::ArgumentError, "pricing model id must be in \"provider/model\" form, got #{model.inspect}" unless valid
+    end
+
+    #--
+    #: (untyped, String) -> Float
+    def coerce_rate(value, attribute)
+      number = value
+      float = value.is_a?(Numeric) ? number.to_f : nil #: Float?
+      raise Riffer::ArgumentError, "#{attribute} rate must be a non-negative number, got #{value.inspect}" unless float&.finite? && float >= 0
+      float
+    end
+
+    #--
+    #: (untyped, String) -> Float?
+    def coerce_optional_rate(value, attribute)
+      return nil if value.nil?
+      coerce_rate(value, attribute)
+    end
+  end
+
   VALID_MESSAGE_ID_STRATEGIES = %i[none uuid uuidv7].freeze
 
   # Amazon Bedrock configuration.
@@ -94,6 +303,15 @@ class Riffer::Config
   # Skills-related global configuration.
   attr_reader :skills #: Riffer::Config::Skills
 
+  # 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
+
   # Strategy for auto-generating message ids: +:none+ (default), +:uuid+, or
   # +:uuidv7+. When not +:none+, messages get an +id+ at construction, and
   # seeded messages passed to +Riffer::Agent#generate+ must carry their own.
@@ -122,13 +340,7 @@ class Riffer::Config
   #--
   #: (untyped) -> void
   def experimental_history_healing=(value)
-    @experimental_history_healing = case value
-    when true, "true", 1, "1" then true
-    when false, "false", 0, "0", nil then false
-    else
-      raise Riffer::ArgumentError,
-        "experimental_history_healing must be a boolean (or 'true'/'false'/'1'/'0'/1/0), got #{value.inspect}"
-    end
+    @experimental_history_healing = Riffer::Helpers::Boolean.coerce(value, attribute: "experimental_history_healing")
   end
 
   #--
@@ -144,6 +356,9 @@ class Riffer::Config
     @mcp = Mcp.new(credentials: nil, discovery_runner: Riffer::Runner::Sequential.new)
     @tool_runtime = Riffer::Tools::Runtime::Inline.new
     @skills = Skills.new
+    @tracing = Tracing.new
+    @metrics = Metrics.new
+    @pricing = Pricing.new
     @message_id_strategy = :none
     @experimental_history_healing = false
   end

data/lib/riffer/guardrail.rb

@@ -31,6 +31,14 @@ class Riffer::Guardrail
     pass(response)
   end
 
+  # Returns the guardrail's identifier, used as the tracing span suffix and the
+  # <tt>riffer.guardrail.name</tt> attribute; override to label the span.
+  #--
+  #: () -> String
+  def name
+    Riffer::Helpers::ClassNameConverter.convert(self.class.name)
+  end
+
   protected
 
   # Creates a pass result that continues with unchanged data.

data/lib/riffer/guardrails/runner.rb

@@ -81,6 +81,38 @@ class Riffer::Guardrails::Runner
   #--
   #: (Riffer::Guardrail, untyped, messages: Array[Riffer::Messages::Base]?) -> Riffer::Guardrails::Result
   def execute_guardrail(guardrail, data, messages:)
+    instrument_guardrail(guardrail) do
+      Riffer::Tracing.in_span("execute_guardrail #{guardrail.name}", attributes: guardrail_span_attributes(guardrail), kind: :internal) do |span|
+        result = run_guardrail_phase(guardrail, data, messages: messages)
+        record_guardrail_outcome(span, result)
+        result
+      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
+    end
+  end
+
+  #--
+  #: (Riffer::Guardrail) { () -> Riffer::Guardrails::Result } -> Riffer::Guardrails::Result
+  def instrument_guardrail(guardrail)
+    start = Riffer::Metrics.monotonic_now
+    error_type = nil #: String?
+    begin
+      yield
+    rescue => error
+      error_type = error.class.name #: String?
+      raise
+    ensure
+      Riffer::Metrics::Instruments::GUARDRAIL_DURATION.record(Riffer::Metrics.monotonic_now - start, attributes: guardrail_metric_attributes(guardrail, error_type))
+    end
+  end
+
+  #--
+  #: (Riffer::Guardrail, untyped, messages: Array[Riffer::Messages::Base]?) -> Riffer::Guardrails::Result
+  def run_guardrail_phase(guardrail, data, messages:)
     case phase
     when :before
       guardrail.process_input(data, context: context)
@@ -90,4 +122,30 @@ class Riffer::Guardrails::Runner
       raise Riffer::Error, "Unexpected guardrail phase: #{phase}. Valid phases: #{Riffer::Guardrails::PHASES.join(", ")}"
     end
   end
+
+  #--
+  #: (Riffer::Guardrail) -> Hash[String, untyped]
+  def guardrail_span_attributes(guardrail)
+    {
+      "riffer.guardrail.name" => guardrail.name,
+      "riffer.guardrail.phase" => phase.to_s
+    }
+  end
+
+  #--
+  #: (Riffer::Guardrail, String?) -> Hash[String, untyped]
+  def guardrail_metric_attributes(guardrail, error_type)
+    attributes = guardrail_span_attributes(guardrail)
+    attributes["error.type"] = error_type if error_type
+    attributes
+  end
+
+  # 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::NoOp::Span), Riffer::Guardrails::Result) -> void
+  def record_guardrail_outcome(span, result)
+    span.set_attribute("riffer.guardrail.action", result.type.to_s)
+    span.set_attribute("riffer.tripwire.reason", result.data) if result.block?
+  end
 end

data/lib/riffer/helpers/boolean.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# Coercion for boolean-ish configuration values.
+module Riffer::Helpers::Boolean
+  extend self
+
+  # Coerces +value+ to a boolean so an env-var +"false"+ (truthy in Ruby)
+  # doesn't silently read as +true+. Raises Riffer::ArgumentError on an
+  # unrecognized value, naming +attribute+ in the message.
+  #--
+  #: (untyped, attribute: String) -> bool
+  def coerce(value, attribute:)
+    case value
+    when true, "true", 1, "1" then true
+    when false, "false", 0, "0", nil then false
+    else
+      raise Riffer::ArgumentError,
+        "#{attribute} must be a boolean (or 'true'/'false'/'1'/'0'/1/0), got #{value.inspect}"
+    end
+  end
+end