riffer 0.32.1 → 0.34.0

data/lib/riffer/skills/context.rb

@@ -2,11 +2,13 @@
 # rbs_inline: enabled
 
 # Skills context for an agent generation cycle — coordinates discovery,
-# activation, and prompt rendering, caching activations to avoid redundant
+# activation, and prompt rendering, caching skill bodies to avoid redundant
 # backend reads. Exposed to tools via <tt>context.skills</tt>.
 class Riffer::Skills::Context
   # @rbs @backend: Riffer::Skills::Backend
-  # @rbs @activated: Hash[String, String]
+  # @rbs @bodies: Hash[String, String]
+  # @rbs @activated: Array[String]
+  # @rbs @preactivated: Array[String]
 
   # Skill catalog indexed by name.
   attr_reader :skills #: Hash[String, Riffer::Skills::Frontmatter]
@@ -15,7 +17,7 @@ class Riffer::Skills::Context
   attr_reader :adapter #: Riffer::Skills::Adapter
 
   # Optional callback invoked when a skill is first activated.
-  attr_writer :on_activate #: (^(String) -> void)?
+  attr_accessor :on_activate #: (^(String) -> void)?
 
   #--
   #: (backend: Riffer::Skills::Backend, skills: Hash[String, Riffer::Skills::Frontmatter], adapter: Riffer::Skills::Adapter) -> void
@@ -23,7 +25,20 @@ class Riffer::Skills::Context
     @backend = backend
     @skills = skills
     @adapter = adapter
-    @activated = {} #: Hash[String, String]
+    @bodies = {} #: Hash[String, String]
+    @activated = [] #: Array[String]
+    @preactivated = [] #: Array[String]
+  end
+
+  # Returns a skill's body without recording an activation.
+  #
+  # Raises Riffer::ArgumentError if the skill is not in the catalog.
+  #
+  #--
+  #: (String) -> String
+  def read(name)
+    raise Riffer::ArgumentError, "Unknown skill: '#{name}'" unless skills.key?(name)
+    @bodies[name] ||= @backend.read_skill(name)
   end
 
   # Activates a skill by name. Returns the cached body on re-activation.
@@ -33,11 +48,48 @@ class Riffer::Skills::Context
   #--
   #: (String) -> String
   def activate(name)
+    body = read(name)
+    unless @activated.include?(name)
+      @activated << name
+      @on_activate&.call(name)
+    end
+    body
+  end
+
+  # Activates a skill and returns its body wrapped for injection as a user
+  # message.
+  #
+  # Raises Riffer::ArgumentError if the skill is not in the catalog.
+  #
+  #--
+  #: (String) -> String
+  def activation_prompt(name)
+    body = activate(name)
+    @adapter.render_activation(skills.fetch(name), body)
+  end
+
+  # Activates a skill whose body renders in the system prompt rather than the
+  # conversation.
+  #
+  # Raises Riffer::ArgumentError if the skill is not in the catalog.
+  #
+  #--
+  #: (String) -> void
+  def preactivate(name)
+    activate(name)
+    @preactivated << name unless @preactivated.include?(name)
+  end
+
+  # Clears a skill's activation so the next activation is treated as the first.
+  #
+  # Raises Riffer::ArgumentError if the skill is not in the catalog.
+  #
+  #--
+  #: (String) -> void
+  def deactivate(name)
     raise Riffer::ArgumentError, "Unknown skill: '#{name}'" unless skills.key?(name)
-    return @activated[name] if @activated.key?(name)
-    @activated[name] = @backend.read_skill(name)
-    @on_activate&.call(name)
-    @activated[name]
+    @activated.delete(name)
+    nil
   end
 
   # Returns whether a skill has been activated.
@@ -45,7 +97,7 @@ class Riffer::Skills::Context
   #--
   #: (String) -> bool
   def activated?(name)
-    @activated.key?(name)
+    @activated.include?(name)
   end
 
   # Returns whether a skill exists and may be activated by the model.
@@ -71,7 +123,7 @@ class Riffer::Skills::Context
     available = available_skills
     parts = [] #: Array[String]
     parts << @adapter.render_catalog(available) unless available.empty?
-    @activated.each_value { |body| parts << body }
+    @preactivated.each { |name| parts << @adapter.render_activation(skills.fetch(name), @bodies.fetch(name)) }
     parts.join("\n\n")
   end
 
@@ -80,6 +132,6 @@ class Riffer::Skills::Context
   #--
   #: () -> Array[Riffer::Skills::Frontmatter]
   def available_skills
-    skills.values.reject { |skill| @activated.key?(skill.name) || skill.disable_model_invocation }
+    skills.values.reject { |skill| @preactivated.include?(skill.name) || skill.disable_model_invocation }
   end
 end

data/lib/riffer/skills/markdown_adapter.rb

@@ -11,7 +11,7 @@ class Riffer::Skills::MarkdownAdapter < Riffer::Skills::Adapter
     lines = [] #: Array[String]
     lines << "## Available Skills"
     lines << ""
-    lines << "When a user's request matches a skill description below, call the `#{skill_activate_tool.name}` tool with the skill name. After activation, follow the skill's instructions."
+    lines << catalog_instructions
     lines << ""
     skills.each do |skill|
       lines << "- **#{skill.name}**: #{skill.description}"

data/lib/riffer/skills/xml_adapter.rb

@@ -11,7 +11,7 @@ class Riffer::Skills::XmlAdapter < Riffer::Skills::Adapter
   #: (Array[Riffer::Skills::Frontmatter]) -> String
   def render_catalog(skills)
     lines = [] #: Array[String]
-    lines << "When a user's request matches a skill description below, call the `#{skill_activate_tool.name}` tool with the skill name. After activation, follow the skill's instructions."
+    lines << catalog_instructions
     lines << ""
     lines << "<available_skills>"
     skills.each do |skill|

data/lib/riffer/stream_events/finish_reason_done.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# Normalized reason the LLM finished, emitted once near the end of the
+# stream; no ordering guarantee relative to TokenUsageDone.
+class Riffer::StreamEvents::FinishReasonDone < Riffer::StreamEvents::Base
+  # The normalized finish reason (see <tt>Riffer::Providers::FinishReason::VALUES</tt>).
+  attr_reader :finish_reason #: Symbol
+
+  # The provider's raw finish-reason value, when one exists on the wire.
+  attr_reader :raw_finish_reason #: String?
+
+  # Raises Riffer::ArgumentError when +finish_reason+ is outside the
+  # normalized vocabulary.
+  #--
+  #: (finish_reason: Symbol, ?raw_finish_reason: String?, ?role: Symbol) -> void
+  def initialize(finish_reason:, raw_finish_reason: nil, role: :assistant)
+    unless Riffer::Providers::FinishReason::VALUES.include?(finish_reason)
+      raise Riffer::ArgumentError, "finish_reason must be one of #{Riffer::Providers::FinishReason::VALUES.inspect}, got #{finish_reason.inspect}"
+    end
+
+    super(role: role)
+    @finish_reason = finish_reason
+    @raw_finish_reason = raw_finish_reason
+  end
+
+  #--
+  #: () -> Hash[Symbol, untyped]
+  def to_h
+    hash = {role: @role, finish_reason: @finish_reason} #: Hash[Symbol, untyped]
+    hash[:raw_finish_reason] = @raw_finish_reason if @raw_finish_reason
+    hash
+  end
+end

data/lib/riffer/tools/runtime.rb

@@ -20,11 +20,17 @@ class Riffer::Tools::Runtime
   #--
   #: (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)
+    # Each Runner worker runs in its own thread/fiber, where the OTEL context
+    # starts empty — capture here so the execute_tool span parents correctly.
+    trace_context = Riffer::Tracing.current_context
     @runner.map(tool_calls, context: context) do |tool_call|
-      result = 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)
+      Riffer::Tracing.with_context(trace_context) do
+        instrument_tool_call(tool_call) 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
+        end
       end
-      [tool_call, result]
     end
   end
 
@@ -50,6 +56,27 @@ 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))
+    end
+  end
+
   #--
   #: (Riffer::Messages::Assistant::ToolCall, tools: Array[singleton(Riffer::Tool)], context: Riffer::Agent::Context?, ?assistant_message: Riffer::Messages::Assistant?) -> Riffer::Tools::Response
   def dispatch_tool_call(tool_call, tools:, context:, assistant_message: nil)
@@ -83,4 +110,73 @@ class Riffer::Tools::Runtime
 
     JSON.parse(arguments, symbolize_names: true)
   end
+
+  # 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|
+      capture_tool_arguments(span, tool_call)
+      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
+  end
+
+  #--
+  #: (Riffer::Messages::Assistant::ToolCall) -> Hash[String, untyped]
+  def tool_span_attributes(tool_call)
+    {
+      "gen_ai.operation.name" => "execute_tool",
+      "gen_ai.tool.name" => tool_call.name,
+      "gen_ai.tool.call.id" => tool_call.call_id
+    }
+  end
+
+  #--
+  #: (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
+  end
+
+  # A returned error Response is a handled outcome, so its status stays unset —
+  # an error span status is reserved for a raised exception.
+  #--
+  #: ((Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span), Riffer::Tools::Response) -> void
+  def record_tool_outcome(span, result)
+    error_type = result.error_type
+    span.set_attribute("error.type", error_type.to_s) if error_type
+    capture_tool_result(span, result)
+  end
+
+  #--
+  #: ((Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span), Riffer::Messages::Assistant::ToolCall) -> void
+  def capture_tool_arguments(span, tool_call)
+    return unless capture_tool_content?(span)
+
+    arguments = tool_call.arguments
+    span.set_attribute("gen_ai.tool.call.arguments", arguments) if arguments
+  end
+
+  #--
+  #: ((Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span), Riffer::Tools::Response) -> void
+  def capture_tool_result(span, result)
+    return unless capture_tool_content?(span)
+
+    span.set_attribute("gen_ai.tool.call.result", result.content)
+  end
+
+  #--
+  #: ((Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span)) -> bool
+  def capture_tool_content?(span)
+    Riffer.config.tracing.capture_messages && span.recording?
+  end
 end

data/lib/riffer/tracing/capture.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require "json"
+
+# Serializes riffer messages into the GenAI semconv JSON message structure
+# for opt-in span content capture. File parts become metadata-only stubs —
+# bytes and URLs never reach a span attribute.
+module Riffer::Tracing::Capture # :nodoc: all
+  extend self
+
+  #--
+  #: (Array[Riffer::Messages::Base]) -> String
+  def input_messages(messages)
+    JSON.generate(messages.filter_map { |message| convert_message(message) })
+  end
+
+  #--
+  #: (Array[Riffer::Messages::Base]) -> String?
+  def system_instructions(messages)
+    parts = messages.grep(Riffer::Messages::System).map { |message| text_part(message.content) }
+    return nil if parts.empty?
+
+    JSON.generate(parts)
+  end
+
+  #--
+  #: (content: String?, tool_calls: Array[Riffer::Messages::Assistant::ToolCall], finish_reason: Symbol?) -> String
+  def output_messages(content:, tool_calls:, finish_reason:)
+    message = {role: "assistant", parts: assistant_parts(content, tool_calls)} #: Hash[Symbol, untyped]
+    message[:finish_reason] = finish_reason if finish_reason
+    JSON.generate([message])
+  end
+
+  private
+
+  #--
+  #: (Riffer::Messages::Base) -> Hash[Symbol, untyped]?
+  def convert_message(message)
+    case message
+    when Riffer::Messages::User
+      parts = [text_part(message.content)] #: Array[Hash[Symbol, untyped]]
+      parts.concat(message.files.map { |file| file_part(file) })
+      {role: "user", parts: parts}
+    when Riffer::Messages::Assistant
+      {role: "assistant", parts: assistant_parts(message.content, message.tool_calls)}
+    when Riffer::Messages::Tool
+      {role: "tool", parts: [{type: "tool_call_response", id: message.tool_call_id, response: message.content}]}
+    end
+  end
+
+  #--
+  #: (String?, Array[Riffer::Messages::Assistant::ToolCall]) -> Array[Hash[Symbol, untyped]]
+  def assistant_parts(content, tool_calls)
+    parts = [] #: Array[Hash[Symbol, untyped]]
+    parts << text_part(content) if content && !content.empty?
+    parts.concat(tool_calls.map { |tool_call| tool_call_part(tool_call) })
+    parts
+  end
+
+  #--
+  #: (String?) -> Hash[Symbol, untyped]
+  def text_part(content)
+    {type: "text", content: content}
+  end
+
+  #--
+  #: (Riffer::Messages::Assistant::ToolCall) -> Hash[Symbol, untyped]
+  def tool_call_part(tool_call)
+    {type: "tool_call", id: tool_call.call_id, name: tool_call.name, arguments: parse_arguments(tool_call.arguments)}
+  end
+
+  #--
+  #: (Riffer::Messages::FilePart) -> Hash[Symbol, untyped]
+  def file_part(file)
+    part = {type: "file", media_type: file.media_type} #: Hash[Symbol, untyped]
+    part[:name] = file.filename if file.filename
+    part
+  end
+
+  # Semconv's tool_call part carries arguments as a JSON object; riffer holds
+  # them as a string — parse so the captured payload isn't double-encoded.
+  #--
+  #: (untyped) -> untyped
+  def parse_arguments(arguments)
+    return arguments unless arguments.is_a?(String)
+
+    JSON.parse(arguments)
+  rescue JSON::ParserError
+    arguments
+  end
+end

data/lib/riffer/tracing/no_op.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# No-op tracing backend, used when OTEL is unavailable or tracing is
+# disabled.
+module Riffer::Tracing::NoOp # :nodoc: all
+  extend self
+
+  # No-op stand-in for a span; answers <tt>recording?</tt> with +false+ so
+  # callers can skip expensive attribute serialization.
+  class Span
+    #--
+    #: (String, untyped) -> void
+    def set_attribute(key, value)
+    end
+
+    #--
+    #: (String, ?attributes: Hash[String, untyped]?) -> void
+    def add_event(name, attributes: nil)
+    end
+
+    #--
+    #: (Exception) -> void
+    def record_exception(exception)
+    end
+
+    #--
+    #: (?String) -> void
+    def error!(description = "")
+    end
+
+    #--
+    #: () -> bool
+    def recording?
+      false
+    end
+  end
+
+  SPAN = Span.new.freeze #: Riffer::Tracing::NoOp::Span
+
+  # Yields the no-op span, ignoring all span options.
+  #--
+  #: [R] (String, **untyped) { (Riffer::Tracing::NoOp::Span) -> R } -> R
+  def in_span(_name, **)
+    yield SPAN
+  end
+
+  # Returns +nil+; there is no trace context without OTEL.
+  #--
+  #: () -> nil
+  def current_context
+    nil
+  end
+
+  # Yields immediately; there is no context to attach.
+  #--
+  #: [R] (untyped) { () -> R } -> R
+  def with_context(_context)
+    yield
+  end
+end

data/lib/riffer/tracing/otel.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# OTEL-backed tracing backend. <tt>::OpenTelemetry</tt> constants appear only
+# inside method bodies here, so the gem loads and eager-loads cleanly when the
+# OpenTelemetry API is absent.
+class Riffer::Tracing::Otel # :nodoc: all
+  SUPPORTED_API_VERSIONS = Gem::Requirement.new(">= 1.1", "< 2") #: Gem::Requirement
+
+  # Wraps a live OTEL span behind the port's span surface, so callers never
+  # touch <tt>::OpenTelemetry</tt> constants (status objects in particular).
+  class Span
+    # @rbs @otel_span: untyped
+
+    #--
+    #: (untyped) -> void
+    def initialize(otel_span)
+      @otel_span = otel_span
+    end
+
+    #--
+    #: (String, untyped) -> void
+    def set_attribute(key, value)
+      @otel_span.set_attribute(key, value)
+    end
+
+    #--
+    #: (String, ?attributes: Hash[String, untyped]?) -> void
+    def add_event(name, attributes: nil)
+      @otel_span.add_event(name, attributes: attributes)
+    end
+
+    #--
+    #: (Exception) -> void
+    def record_exception(exception)
+      @otel_span.record_exception(exception)
+    end
+
+    # Marks the span status as error.
+    #--
+    #: (?String) -> void
+    def error!(description = "")
+      @otel_span.status = ::OpenTelemetry::Trace::Status.error(description)
+    end
+
+    #--
+    #: () -> bool
+    def recording?
+      @otel_span.recording?
+    end
+  end
+
+  class << self
+    # Builds a backend when the OpenTelemetry API is loadable at a supported
+    # version; returns +nil+ so resolution falls back to NoOp. +provider+
+    # defaults to the global <tt>OpenTelemetry.tracer_provider</tt>.
+    #--
+    #: (?provider: untyped) -> Riffer::Tracing::Otel?
+    def build(provider: nil)
+      version = api_version
+      return nil unless version
+
+      unless supported?(version)
+        Kernel.warn "riffer: opentelemetry-api #{version} is outside the supported range (#{SUPPORTED_API_VERSIONS}); tracing is disabled"
+        return nil
+      end
+
+      new(provider: provider || ::OpenTelemetry.tracer_provider)
+    end
+
+    # Whether the OpenTelemetry API gem is loadable at a supported version.
+    #--
+    #: () -> bool
+    def available?
+      version = api_version
+      !version.nil? && supported?(version)
+    end
+
+    # Whether the given opentelemetry-api version is one riffer codes
+    # against. The gem is undeclared, so this guard is the only protection
+    # against an incompatible API.
+    #--
+    #: (Gem::Version) -> bool
+    def supported?(version)
+      SUPPORTED_API_VERSIONS.satisfied_by?(version)
+    end
+
+    private
+
+    #--
+    #: () -> Gem::Version?
+    def api_version
+      require "opentelemetry"
+      spec = Gem.loaded_specs["opentelemetry-api"] #: untyped
+      spec&.version
+    rescue ::LoadError
+      nil
+    end
+  end
+
+  # @rbs @tracer: untyped
+
+  #--
+  #: (provider: untyped) -> void
+  def initialize(provider:)
+    @tracer = provider.tracer("riffer", Riffer::VERSION)
+  end
+
+  # Opens an OTEL span around the block, yielding the wrapped span.
+  #--
+  #: [R] (String, attributes: Hash[String, untyped]?, kind: Symbol) { (Riffer::Tracing::Otel::Span) -> R } -> R
+  def in_span(name, attributes:, kind:)
+    @tracer.in_span(name, attributes: attributes, kind: kind) do |otel_span, _context|
+      yield Span.new(otel_span)
+    end
+  end
+
+  # Returns the active OTEL context.
+  #--
+  #: () -> untyped
+  def current_context
+    ::OpenTelemetry::Context.current
+  end
+
+  # Runs the block with the given OTEL context active.
+  #--
+  #: [R] (untyped) { () -> R } -> R
+  def with_context(context)
+    return yield if context.nil?
+    ::OpenTelemetry::Context.with_current(context) { yield }
+  end
+end

data/lib/riffer/tracing/stream_recorder.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# Wraps a stream yielder to observe terminal events for span stamping while
+# forwarding every event downstream untouched.
+class Riffer::Tracing::StreamRecorder # :nodoc: all
+  # @rbs @yielder: Enumerator::Yielder
+
+  attr_reader :token_usage #: Riffer::Providers::TokenUsage?
+
+  attr_reader :finish_reason #: Symbol?
+
+  attr_reader :raw_finish_reason #: String?
+
+  attr_reader :content #: String?
+
+  attr_reader :tool_calls #: Array[Riffer::Messages::Assistant::ToolCall]
+
+  #--
+  #: (Enumerator::Yielder) -> void
+  def initialize(yielder)
+    @yielder = yielder
+    @tool_calls = [] #: Array[Riffer::Messages::Assistant::ToolCall]
+  end
+
+  #--
+  #: (Riffer::StreamEvents::Base) -> self
+  def <<(event)
+    record(event)
+    @yielder << event
+    self
+  end
+
+  private
+
+  #--
+  #: (Riffer::StreamEvents::Base) -> void
+  def record(event)
+    case event
+    when Riffer::StreamEvents::TextDone
+      @content = event.content
+    when Riffer::StreamEvents::ToolCallDone
+      @tool_calls << Riffer::Messages::Assistant::ToolCall.new(call_id: event.call_id, name: event.name, arguments: event.arguments)
+    when Riffer::StreamEvents::TokenUsageDone
+      @token_usage = event.token_usage
+    when Riffer::StreamEvents::FinishReasonDone
+      @finish_reason = event.finish_reason
+      @raw_finish_reason = event.raw_finish_reason
+    end
+  end
+end