riffer 0.32.1 → 0.34.0

data/lib/riffer/tracing.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# Internal tracing port — emits OTEL spans when the host bundles the
+# OpenTelemetry API and no-ops otherwise, so riffer never declares an OTEL
+# dependency.
+module Riffer::Tracing # :nodoc: all
+  extend self
+
+  # @rbs @backend: untyped
+
+  MUTEX = Mutex.new #: Mutex
+
+  # The Ruby API cannot attach a schema URL to a tracer, so the semconv pin
+  # lives here as the documented contract version.
+  SCHEMA_URL = "https://opentelemetry.io/schemas/1.37.0" #: String
+
+  # Opens a span around the block, yielding the span.
+  #--
+  #: [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 NoOp.in_span(name, &block) unless Riffer.config.tracing.enabled
+    backend.in_span(name, attributes: attributes, kind: kind, &block)
+  end
+
+  # Returns the active trace context, for re-attachment across fiber or
+  # thread boundaries.
+  #--
+  #: () -> untyped
+  def current_context
+    return NoOp.current_context unless Riffer.config.tracing.enabled
+    backend.current_context
+  end
+
+  # Runs the block with the given trace context active; +nil+ passes through
+  # so captures taken while tracing was dark stay harmless.
+  #--
+  #: [R] (untyped) { () -> R } -> R
+  def with_context(context, &block)
+    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::NoOp::Span), Riffer::Providers::TokenUsage?) -> void
+  def record_usage(span, usage)
+    return unless usage
+
+    span.set_attribute("gen_ai.usage.input_tokens", usage.input_tokens)
+    span.set_attribute("gen_ai.usage.output_tokens", usage.output_tokens)
+    span.set_attribute("gen_ai.usage.cache_read.input_tokens", usage.cache_read_tokens) if usage.cache_read_tokens
+    span.set_attribute("gen_ai.usage.cache_creation.input_tokens", usage.cache_write_tokens) if usage.cache_write_tokens
+    span.set_attribute("riffer.cost", usage.cost) if usage.cost
+  end
+
+  # Discards the resolved backend so the next span re-resolves it.
+  #--
+  #: () -> void
+  def reset!
+    MUTEX.synchronize { @backend = nil }
+  end
+
+  private
+
+  #--
+  #: () -> untyped
+  def backend
+    @backend || MUTEX.synchronize { @backend ||= resolve_backend }
+  end
+
+  #--
+  #: () -> untyped
+  def resolve_backend
+    Riffer.config.tracing.backend || NoOp
+  end
+end

data/lib/riffer/version.rb

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

data/sig/_private/opentelemetry.rbs

@@ -0,0 +1,22 @@
+# Minimal signatures for the `opentelemetry-api` and `opentelemetry-metrics-api`
+# gems (undeclared, runtime detected), which ship no RBS.
+#
+# Only the surface used by Riffer::Tracing::Otel and Riffer::Metrics::Otel is
+# declared.
+module OpenTelemetry
+  def self.tracer_provider: () -> untyped
+
+  def self.meter_provider: () -> untyped
+
+  class Context
+    def self.current: () -> OpenTelemetry::Context
+
+    def self.with_current: [R] (OpenTelemetry::Context) { () -> R } -> R
+  end
+
+  module Trace
+    class Status
+      def self.error: (?String) -> OpenTelemetry::Trace::Status
+    end
+  end
+end

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

@@ -27,6 +27,13 @@ class Riffer::Agent::Response
   # The parsed structured output, if structured output was configured.
   attr_reader structured_output: Hash[Symbol, untyped]?
 
+  # The aggregate token usage across this run's LLM calls, if any was reported.
+  attr_reader token_usage: Riffer::Providers::TokenUsage?
+
+  # The number of LLM calls made during this run (0 when a before-guardrail
+  # blocks before any call). Distinct from the session's cumulative step count.
+  attr_reader steps: Integer
+
   # The full message history from the agent conversation.
   attr_reader messages: Array[Riffer::Messages::Base]
 
@@ -35,8 +42,8 @@ class Riffer::Agent::Response
   attr_reader healed_tool_call_ids: Array[String]
 
   # --
-  # : (String, ?tripwire: Riffer::Guardrails::Tripwire?, ?modifications: Array[Riffer::Guardrails::Modification], ?interrupted: bool, ?interrupt_reason: (String | Symbol)?, ?structured_output: Hash[Symbol, untyped]?, ?messages: Array[Riffer::Messages::Base], ?healed_tool_call_ids: Array[String]) -> void
-  def initialize: (String, ?tripwire: Riffer::Guardrails::Tripwire?, ?modifications: Array[Riffer::Guardrails::Modification], ?interrupted: bool, ?interrupt_reason: (String | Symbol)?, ?structured_output: Hash[Symbol, untyped]?, ?messages: Array[Riffer::Messages::Base], ?healed_tool_call_ids: Array[String]) -> void
+  # : (String, ?tripwire: Riffer::Guardrails::Tripwire?, ?modifications: Array[Riffer::Guardrails::Modification], ?interrupted: bool, ?interrupt_reason: (String | Symbol)?, ?structured_output: Hash[Symbol, untyped]?, ?messages: Array[Riffer::Messages::Base], ?healed_tool_call_ids: Array[String], ?token_usage: Riffer::Providers::TokenUsage?, ?steps: Integer) -> void
+  def initialize: (String, ?tripwire: Riffer::Guardrails::Tripwire?, ?modifications: Array[Riffer::Guardrails::Modification], ?interrupted: bool, ?interrupt_reason: (String | Symbol)?, ?structured_output: Hash[Symbol, untyped]?, ?messages: Array[Riffer::Messages::Base], ?healed_tool_call_ids: Array[String], ?token_usage: Riffer::Providers::TokenUsage?, ?steps: Integer) -> void
 
   # Returns true if the response was blocked by a guardrail.
   #

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

@@ -23,6 +23,10 @@ module Riffer::Agent::Run
   # : (Riffer::Agent, ?stream_yielder: Enumerator::Yielder?) -> Riffer::Agent::Response
   def run_loop: (Riffer::Agent, ?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) -> Riffer::Messages::Assistant
   def accumulate_streamed_response: (Riffer::Agent, Enumerator::Yielder) -> Riffer::Messages::Assistant
@@ -32,8 +36,8 @@ module Riffer::Agent::Run
   def record_modifications!: (Enumerator::Yielder?, Array[Riffer::Guardrails::Modification], Array[Riffer::Guardrails::Modification]) -> void
 
   # --
-  # : (Riffer::Agent, Enumerator::Yielder?, Riffer::Guardrails::Tripwire, Array[Riffer::Guardrails::Modification]) -> Riffer::Agent::Response
-  def tripwire_response: (Riffer::Agent, Enumerator::Yielder?, Riffer::Guardrails::Tripwire, Array[Riffer::Guardrails::Modification]) -> Riffer::Agent::Response
+  # : (Riffer::Agent, Enumerator::Yielder?, Riffer::Guardrails::Tripwire, Array[Riffer::Guardrails::Modification], ?token_usage: Riffer::Providers::TokenUsage?, ?steps: Integer) -> Riffer::Agent::Response
+  def tripwire_response: (Riffer::Agent, Enumerator::Yielder?, Riffer::Guardrails::Tripwire, Array[Riffer::Guardrails::Modification], ?token_usage: Riffer::Providers::TokenUsage?, ?steps: Integer) -> Riffer::Agent::Response
 
   # --
   # : (Riffer::Agent, Array[Riffer::Guardrails::Modification], **untyped) -> Riffer::Agent::Response
@@ -60,12 +64,12 @@ module Riffer::Agent::Run
   def execute_pending_tool_calls: (Riffer::Agent) -> void
 
   # --
-  # : (Riffer::Agent, Enumerator::Yielder?, Array[Riffer::Guardrails::Modification]) { (Riffer::Agent::Response) -> void } -> void
-  def run_before_guardrails: (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: (Riffer::Agent, Enumerator::Yielder?, Array[Riffer::Guardrails::Modification]) { (Riffer::Guardrails::Tripwire) -> void } -> void
 
   # --
-  # : (Riffer::Agent, Riffer::Messages::Assistant, Enumerator::Yielder?, Array[Riffer::Guardrails::Modification]) { (Riffer::Agent::Response) -> void } -> untyped
-  def run_after_guardrails: (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: (Riffer::Agent, Riffer::Messages::Assistant, Enumerator::Yielder?, Array[Riffer::Guardrails::Modification]) { (Riffer::Guardrails::Tripwire) -> void } -> untyped
 
   # --
   # : (Riffer::Agent, Riffer::Messages::Assistant?) -> Hash[Symbol, untyped]?
@@ -80,8 +84,8 @@ module Riffer::Agent::Run
   def merged_model_options: (Riffer::Agent) -> 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]) -> Riffer::Agent::Response
-  def build_response: (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
+  # : (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: (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
 
   # Raises when +files+ are supplied without a +prompt+ — the provider needs
   # text to anchor the attachments.
@@ -92,4 +96,20 @@ module Riffer::Agent::Run
   # --
   # : (Riffer::Agent, Riffer::Providers::TokenUsage?) -> void
   def track_token_usage: (Riffer::Agent, Riffer::Providers::TokenUsage?) -> void
+
+  # --
+  # : (Riffer::Providers::TokenUsage?, Riffer::Providers::TokenUsage?) -> Riffer::Providers::TokenUsage?
+  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, String?) -> Hash[String, untyped]
+  def run_metric_attributes: (Riffer::Agent, String?) -> Hash[String, untyped]
+
+  # --
+  # : (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/config.rbs

@@ -7,15 +7,15 @@ class Riffer::Config
 
     attr_accessor region(): untyped
 
-    def self.new: (?api_token: untyped, ?region: untyped) -> instance
-                | ({ ?api_token: untyped, ?region: untyped }) -> instance
+    def self.new: (?untyped api_token, ?untyped region) -> instance
+                | (?api_token: untyped, ?region: untyped) -> instance
   end
 
   class Anthropic < Struct[untyped]
     attr_accessor api_key(): untyped
 
-    def self.new: (?api_key: untyped) -> instance
-                | ({ ?api_key: untyped }) -> instance
+    def self.new: (?untyped api_key) -> instance
+                | (?api_key: untyped) -> instance
   end
 
   class AzureOpenAI < Struct[untyped]
@@ -23,8 +23,8 @@ class Riffer::Config
 
     attr_accessor endpoint(): untyped
 
-    def self.new: (?api_key: untyped, ?endpoint: untyped) -> instance
-                | ({ ?api_key: untyped, ?endpoint: untyped }) -> instance
+    def self.new: (?untyped api_key, ?untyped endpoint) -> instance
+                | (?api_key: untyped, ?endpoint: untyped) -> instance
   end
 
   class Gemini < Struct[untyped]
@@ -34,29 +34,29 @@ class Riffer::Config
 
     attr_accessor read_timeout(): untyped
 
-    def self.new: (?api_key: untyped, ?open_timeout: untyped, ?read_timeout: untyped) -> instance
-                | ({ ?api_key: untyped, ?open_timeout: untyped, ?read_timeout: untyped }) -> instance
+    def self.new: (?untyped api_key, ?untyped open_timeout, ?untyped read_timeout) -> instance
+                | (?api_key: untyped, ?open_timeout: untyped, ?read_timeout: untyped) -> instance
   end
 
   class OpenAI < Struct[untyped]
     attr_accessor api_key(): untyped
 
-    def self.new: (?api_key: untyped) -> instance
-                | ({ ?api_key: untyped }) -> instance
+    def self.new: (?untyped api_key) -> instance
+                | (?api_key: untyped) -> instance
   end
 
   class OpenRouter < Struct[untyped]
     attr_accessor api_key(): untyped
 
-    def self.new: (?api_key: untyped) -> instance
-                | ({ ?api_key: untyped }) -> instance
+    def self.new: (?untyped api_key) -> instance
+                | (?api_key: untyped) -> instance
   end
 
   class Evals < Struct[untyped]
     attr_accessor judge_model(): untyped
 
-    def self.new: (?judge_model: untyped) -> instance
-                | ({ ?judge_model: untyped }) -> instance
+    def self.new: (?untyped judge_model) -> instance
+                | (?judge_model: untyped) -> instance
   end
 
   class Mcp < Struct[untyped]
@@ -64,8 +64,8 @@ class Riffer::Config
 
     attr_accessor discovery_runner(): untyped
 
-    def self.new: (?credentials: untyped, ?discovery_runner: untyped) -> instance
-                | ({ ?credentials: untyped, ?discovery_runner: untyped }) -> instance
+    def self.new: (?untyped credentials, ?untyped discovery_runner) -> instance
+                | (?credentials: untyped, ?discovery_runner: untyped) -> instance
   end
 
   # Skills-related global configuration.
@@ -95,6 +95,143 @@ class Riffer::Config
     def default_backend=: ((Riffer::Skills::Backend | Proc)?) -> void
   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: () -> void
+
+    # 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=: (untyped) -> void
+
+    # 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=: (untyped) -> void
+
+    # 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=: (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
+    @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: Float, output: Float, ?cache_read: Float?, ?cache_write: Float?) -> void
+
+      # 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: Integer, output_tokens: Integer, ?cache_read_tokens: Integer?, ?cache_write_tokens: Integer?) -> Float
+    end
+
+    # --
+    # : () -> void
+    def initialize: () -> void
+
+    # 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: (String | Array[String], input: Numeric, output: Numeric, ?cache_read: Numeric?, ?cache_write: Numeric?) -> void
+
+    # Returns the rates registered for a +provider/model+ id.
+    # --
+    # : (String) -> Riffer::Config::Pricing::Rates?
+    def rates_for: (String) -> Riffer::Config::Pricing::Rates?
+
+    # Returns true when no rates are registered.
+    # --
+    # : () -> bool
+    def empty?: () -> bool
+
+    private
+
+    # --
+    # : (String) -> void
+    def validate_model!: (String) -> void
+
+    # --
+    # : (untyped, String) -> Float
+    def coerce_rate: (untyped, String) -> Float
+
+    # --
+    # : (untyped, String) -> Float?
+    def coerce_optional_rate: (untyped, String) -> Float?
+  end
+
   VALID_MESSAGE_ID_STRATEGIES: untyped
 
   # Amazon Bedrock configuration.
@@ -136,6 +273,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.

data/sig/generated/riffer/guardrail.rbs

@@ -26,6 +26,12 @@ class Riffer::Guardrail
   # : (Riffer::Messages::Assistant, messages: Array[Riffer::Messages::Base], context: untyped) -> Riffer::Guardrails::Result
   def process_output: (Riffer::Messages::Assistant, messages: Array[Riffer::Messages::Base], context: untyped) -> Riffer::Guardrails::Result
 
+  # 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: () -> String
+
   # Creates a pass result that continues with unchanged data.
   # --
   # : (untyped) -> Riffer::Guardrails::Result

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

@@ -36,4 +36,26 @@ 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
+
+  # --
+  # : (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::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/helpers/boolean.rbs

@@ -0,0 +1,11 @@
+# Generated from lib/riffer/helpers/boolean.rb with RBS::Inline
+
+# Coercion for boolean-ish configuration values.
+module Riffer::Helpers::Boolean
+  # 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: (untyped, attribute: String) -> bool
+end

data/sig/generated/riffer/mcp/authenticated_tool.rbs

@@ -1,18 +1,16 @@
 # Generated from lib/riffer/mcp/authenticated_tool.rb with RBS::Inline
 
 # Wraps MCP-generated tool classes so +tools/call+ resolves
-# +Riffer.config.mcp.credentials+ per invocation, delegating metadata to the
-# inner class.
+# +Riffer.config.mcp.credentials+ per invocation, copying metadata from the
+# inner class at wrap time.
 module Riffer::Mcp::AuthenticatedTool
   # Returns one wrapper class per inner tool, sharing +manifest+ and +matched_tags+.
   #
   # --
-  # : (Array[singleton(Riffer::Tool)], Riffer::Mcp::Manifest, Array[Symbol]) -> Array[singleton(Riffer::Tool)]
-  def wrap_all: (Array[singleton(Riffer::Tool)], Riffer::Mcp::Manifest, Array[Symbol]) -> Array[singleton(Riffer::Tool)]
+  # : (Array[singleton(Riffer::Mcp::Tool)], Riffer::Mcp::Manifest, Array[Symbol]) -> Array[singleton(Riffer::Mcp::Tool)]
+  def wrap_all: (Array[singleton(Riffer::Mcp::Tool)], Riffer::Mcp::Manifest, Array[Symbol]) -> Array[singleton(Riffer::Mcp::Tool)]
 
   # --
-  # : (singleton(Riffer::Tool), Riffer::Mcp::Manifest, Array[Symbol]) -> singleton(Riffer::Tool)
-  #  Class.new(Riffer::Tool) is typed as ::Class by steep — it cannot verify the subtype
-  #  relationship for dynamically created anonymous classes, so the ignore is required.
-  def wrap_one: (singleton(Riffer::Tool), Riffer::Mcp::Manifest, Array[Symbol]) -> singleton(Riffer::Tool)
+  # : (singleton(Riffer::Mcp::Tool), Riffer::Mcp::Manifest, Array[Symbol]) -> singleton(Riffer::Mcp::Tool)
+  def wrap_one: (singleton(Riffer::Mcp::Tool), Riffer::Mcp::Manifest, Array[Symbol]) -> singleton(Riffer::Mcp::Tool)
 end

data/sig/generated/riffer/mcp/registration.rbs

@@ -5,18 +5,18 @@
 class Riffer::Mcp::Registration
   @cancelled: bool
 
-  @tools: Array[singleton(Riffer::Tool)]
+  @tools: Array[singleton(Riffer::Mcp::Tool)]
 
   @mutex: Thread::Mutex
 
   # The manifest that describes this server.
   attr_reader manifest: Riffer::Mcp::Manifest
 
-  # Generated Riffer::Tool subclasses.
+  # Generated Riffer::Mcp::Tool subclasses.
   #
   # --
-  # : () -> Array[singleton(Riffer::Tool)]
-  def tools: () -> Array[singleton(Riffer::Tool)]
+  # : () -> Array[singleton(Riffer::Mcp::Tool)]
+  def tools: () -> Array[singleton(Riffer::Mcp::Tool)]
 
   # --
   # : (Riffer::Mcp::Manifest) -> void

data/sig/generated/riffer/mcp/tool.rbs

@@ -0,0 +1,19 @@
+# Generated from lib/riffer/mcp/tool.rb with RBS::Inline
+
+# Base class for MCP-generated tools.
+class Riffer::Mcp::Tool < Riffer::Tool
+  self.@mcp_server_tool_name: String?
+
+  self.@input_schema: Hash[Symbol, untyped]?
+
+  # Returns the unprefixed tool name used for +tools/call+ on the MCP server.
+  # --
+  # : () -> String
+  def self.mcp_server_tool_name: () -> String
+
+  # Returns the server-published input schema, falling back to the params DSL.
+  # MCP schemas are server-defined, so +strict+ is not applied to them.
+  # --
+  # : (?strict: bool) -> Hash[Symbol, untyped]
+  def self.parameters_schema: (?strict: bool) -> Hash[Symbol, untyped]
+end

data/sig/generated/riffer/mcp/tool_factory.rbs

@@ -1,20 +1,21 @@
 # Generated from lib/riffer/mcp/tool_factory.rb with RBS::Inline
 
-# Generates anonymous Riffer::Tool subclasses from MCP tool definitions.
+# Generates anonymous Riffer::Mcp::Tool subclasses from MCP tool definitions.
 # Generated tools delegate +#call+ to the MCP client and skip Riffer's param
 # validation — the MCP server validates inputs.
 module Riffer::Mcp::ToolFactory
-  # Builds one Riffer::Tool subclass per tool definition, prefixing names with
-  # the manifest name to avoid cross-server collisions (e.g. +jira__search+);
-  # the server-side name stays on +.mcp_server_tool_name+.
+  # Builds one Riffer::Mcp::Tool subclass per tool definition, prefixing names
+  # with the manifest name to avoid cross-server collisions (e.g.
+  # +jira__search+); the server-side name stays on +.mcp_server_tool_name+.
   # --
-  # : (String, Riffer::Mcp::Client, Array[Hash[Symbol, untyped]]) -> Array[singleton(Riffer::Tool)]
-  def build: (String, Riffer::Mcp::Client, Array[Hash[Symbol, untyped]]) -> Array[singleton(Riffer::Tool)]
+  # : (String, Riffer::Mcp::Client, Array[Hash[Symbol, untyped]]) -> Array[singleton(Riffer::Mcp::Tool)]
+  def build: (String, Riffer::Mcp::Client, Array[Hash[Symbol, untyped]]) -> Array[singleton(Riffer::Mcp::Tool)]
 
   private
 
   # : (String) -> String
   def sanitize_name_component: (String) -> String
 
-  def build_tool_class: (untyped manifest_name, untyped client, untyped td) -> untyped
+  # : (String, Riffer::Mcp::Client, Hash[Symbol, untyped]) -> singleton(Riffer::Mcp::Tool)
+  def build_tool_class: (String, Riffer::Mcp::Client, Hash[Symbol, untyped]) -> singleton(Riffer::Mcp::Tool)
 end

data/sig/generated/riffer/messages/assistant.rbs

@@ -10,8 +10,8 @@ class Riffer::Messages::Assistant < Riffer::Messages::Base
 
     attr_accessor arguments(): untyped
 
-    def self.new: (?call_id: untyped, ?name: untyped, ?arguments: untyped) -> instance
-                | ({ ?call_id: untyped, ?name: untyped, ?arguments: untyped }) -> instance
+    def self.new: (?untyped call_id, ?untyped name, ?untyped arguments) -> instance
+                | (?call_id: untyped, ?name: untyped, ?arguments: untyped) -> instance
   end
 
   # Array of tool calls requested by the assistant.
@@ -23,9 +23,15 @@ class Riffer::Messages::Assistant < Riffer::Messages::Base
   # Parsed structured output hash, or nil when not applicable.
   attr_reader structured_output: Hash[Symbol, untyped]?
 
+  # Normalized reason the provider finished this response, when reported (see
+  # <tt>Riffer::Providers::FinishReason::VALUES</tt>).
+  attr_reader finish_reason: Symbol?
+
+  # Raises Riffer::ArgumentError when +finish_reason+ is outside the
+  # normalized vocabulary.
   # --
-  # : (String, ?id: String?, ?tool_calls: Array[Riffer::Messages::Assistant::ToolCall], ?token_usage: Riffer::Providers::TokenUsage?, ?structured_output: Hash[Symbol, untyped]?) -> void
-  def initialize: (String, ?id: String?, ?tool_calls: Array[Riffer::Messages::Assistant::ToolCall], ?token_usage: Riffer::Providers::TokenUsage?, ?structured_output: Hash[Symbol, untyped]?) -> void
+  # : (String, ?id: String?, ?tool_calls: Array[Riffer::Messages::Assistant::ToolCall], ?token_usage: Riffer::Providers::TokenUsage?, ?structured_output: Hash[Symbol, untyped]?, ?finish_reason: Symbol?) -> void
+  def initialize: (String, ?id: String?, ?tool_calls: Array[Riffer::Messages::Assistant::ToolCall], ?token_usage: Riffer::Providers::TokenUsage?, ?structured_output: Hash[Symbol, untyped]?, ?finish_reason: Symbol?) -> void
 
   # --
   # : () -> Symbol

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

@@ -0,0 +1,15 @@
+# Generated from lib/riffer/metrics/instruments.rb with RBS::Inline
+
+# The catalog of metric instruments riffer records. Each handle is a constant
+# that resolves its backend at record time, so it survives a meter-provider swap
+# or a runtime +enabled+ flip.
+module Riffer::Metrics::Instruments
+  # :nodoc: all
+  OPERATION_DURATION: Riffer::Metrics::Histogram
+
+  TOKEN_USAGE: Riffer::Metrics::Histogram
+
+  COST: Riffer::Metrics::Histogram
+
+  GUARDRAIL_DURATION: Riffer::Metrics::Histogram
+end

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

@@ -0,0 +1,10 @@
+# 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::NoOp
+  # Ignores the measurement; there is no meter without the OTEL metrics API.
+  # --
+  # : (String, Numeric, unit: String?, description: String?, attributes: Hash[String, untyped]?) -> void
+  def record_histogram: (String, Numeric, unit: String?, description: String?, attributes: Hash[String, untyped]?) -> void
+end