riffer 0.47.2 → 0.49.0

data/lib/riffer/providers/token_usage.rb

@@ -1,22 +1,34 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Normalized token usage for an LLM API call. Buckets carry the same
-# meaning for every provider.
 class Riffer::Providers::TokenUsage
-  # Number of tokens entering the context window, including cache reads and writes.
+  #--
+  #: ((Hash[Symbol, untyped] | Riffer::Providers::TokenUsage)) -> Riffer::Providers::TokenUsage
+  def self.from_hash(usage)
+    return usage if usage.is_a?(Riffer::Providers::TokenUsage)
+
+    new(
+      input_tokens: usage[:input_tokens],
+      output_tokens: usage[:output_tokens],
+      cache_write_tokens: usage[:cache_write_tokens],
+      cache_read_tokens: usage[:cache_read_tokens],
+      cost: usage[:cost],
+    )
+  end
+
+  # Normalized across providers: includes cache reads and writes.
   attr_reader :input_tokens #: Integer # @dynamic input_tokens
 
-  # Number of tokens generated by the model, including reasoning/thinking tokens.
+  # Includes reasoning/thinking tokens.
   attr_reader :output_tokens #: Integer # @dynamic output_tokens
 
-  # Subset of +input_tokens+ written to the provider's prompt cache, when the provider reports it.
+  # Subset of +input_tokens+.
   attr_reader :cache_write_tokens #: Integer? # @dynamic cache_write_tokens
 
-  # Subset of +input_tokens+ read from the provider's prompt cache, when the provider reports it.
+  # Subset of +input_tokens+.
   attr_reader :cache_read_tokens #: Integer? # @dynamic cache_read_tokens
 
-  # Cost of the call, set when the model is priced. For observability, not billing.
+  # For observability, not billing.
   attr_reader :cost #: Float? # @dynamic cost
 
   #--
@@ -29,16 +41,12 @@ class Riffer::Providers::TokenUsage
     @cost = cost
   end
 
-  # Returns the total number of tokens (input + output).
-  #
   #--
   #: () -> Integer
   def total_tokens
     input_tokens + output_tokens
   end
 
-  # Combines two TokenUsage objects for cumulative tracking.
-  #
   #--
   #: (Riffer::Providers::TokenUsage) -> Riffer::Providers::TokenUsage
   def +(other)
@@ -51,7 +59,6 @@ class Riffer::Providers::TokenUsage
     )
   end
 
-  # Converts the token usage to a hash; cache tokens and cost are omitted when nil.
   #--
   #: () -> Hash[Symbol, (Integer | Float)]
   def to_h

data/lib/riffer/registrable.rb

@@ -1,57 +1,23 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Registry of a class's direct subclasses, keyed by identifier. Extend it
-# onto a base class to look up subclasses in constant time via +find+ and +all+.
-# Subclasses join implicitly by inheriting; +register+ adds one explicitly, for
-# ephemeral classes a test suite builds and tears down. Registration is not
-# synchronized — register during boot or from a single-threaded test, before
-# concurrent lookups begin.
-#
-#   class Riffer::Tool
-#     extend Riffer::Registrable
-#   end
-#
-#   Riffer::Tool.find("weather_tool") # => WeatherTool
-#
 # @rbs module-self Class
 module Riffer::Registrable
   # @rbs @identifier_registry: Hash[String, Class]?
   # @rbs @explicit_registrations: Hash[String, Class]?
 
-  # Finds a registered subclass by identifier, or +nil+ when none matches.
-  # Implicit registration covers only *named direct* subclasses: grandchildren
-  # are not visible to a grandparent's +find+ (call +find+ on their direct
-  # parent instead), anonymous classes are never registered implicitly, and a
-  # subclass whose name no longer resolves back to it is dropped at the next
-  # registry rebuild. Duplicate identifiers raise
-  # Riffer::DuplicateIdentifierError at first lookup.
-  #
   #--
   #: (String | Symbol) -> Class?
   def find(identifier)
     identifier_registry[identifier.to_s]
   end
 
-  # Returns all registered subclasses, implicit and explicit. Carries the same
-  # registration rules as +find+.
-  #
   #--
   #: () -> Array[Class]
   def all
     identifier_registry.values
   end
 
-  # Registers a direct subclass under its +identifier+, whether or not it is
-  # named — unlike implicit registration, it survives a name that no longer
-  # resolves, so an ephemeral class stays findable until +unregister+. Prefer
-  # Riffer::Testing for ordinary test setup, which stubs and cleans up
-  # automatically.
-  #
-  # Raises Riffer::ArgumentError when the identifier is blank or the class is
-  # not a direct subclass, and Riffer::DuplicateIdentifierError when the
-  # identifier is already taken — including by this same class.
-  #
   #--
   #: (Class) -> void
   def register(klass)
@@ -65,12 +31,12 @@ module Riffer::Registrable
     existing = identifier_registry[key]
     raise_duplicate_identifier!(key, existing, klass) if existing
 
+    # Not synchronized: register during boot or from a single-threaded test,
+    # before concurrent lookups begin.
     explicit_registrations[key] = klass
     @identifier_registry = nil
   end
 
-  # Removes an explicit registration of +klass+, leaving implicit registrations
-  # untouched.
   #--
   #: (Class) -> void
   def unregister(klass)
@@ -83,13 +49,12 @@ module Riffer::Registrable
 
   private
 
-  # Ruby invokes +inherited+ with +self+ bound to the direct superclass — the
-  # only registry the new subclass joins — so busting self's memo is exactly
-  # sufficient.
   #--
   #: (Class) -> void
   def inherited(subclass)
     super
+    # +self+ is the direct superclass — the only registry the new subclass
+    # joins — so busting self's memo is exactly sufficient.
     @identifier_registry = nil
   end
 
@@ -108,6 +73,8 @@ module Riffer::Registrable
   #--
   #: () -> Hash[String, Class]
   def build_identifier_registry
+    # Explicit entries skip +live?+ so an ephemeral class stays findable until
+    # +unregister+, even once its name no longer resolves.
     subclasses.each_with_object(explicit_registrations.dup) do |subclass, acc|
       next unless live?(subclass)
 
@@ -121,15 +88,14 @@ module Riffer::Registrable
     end.freeze
   end
 
-  # Class#subclasses keeps returning superseded generations of a reloaded or
-  # stubbed class, so a subclass counts only while its own name still resolves
-  # back to it. An anonymous class has no name to resolve and is skipped even
-  # with an explicit identifier — the MCP factory and serializer shells
-  # synthesize short-lived anonymous classes whose registration would flake
-  # with GC timing.
   #--
   #: (Class) -> bool
   def live?(subclass)
+    # Class#subclasses keeps returning superseded generations of a reloaded or
+    # stubbed class, so a subclass counts only while its own name still
+    # resolves back to it. Anonymous classes are skipped even with an
+    # identifier: the MCP factory and serializer shells synthesize short-lived
+    # anonymous classes whose registration would flake with GC timing.
     real_name = Riffer::Helpers::Identifier.real_name(subclass)
     return false if real_name.nil?
 

data/lib/riffer/runner/fibers.rb

@@ -1,12 +1,6 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Processes items concurrently using fibers via the +async+ gem.
-# +max_concurrency+ caps simultaneous fibers via an <tt>Async::Semaphore</tt>.
-# If multiple fibers raise, only the first exception is re-raised after all
-# finish.
-# Joins the current reactor task when one is already running, and otherwise
-# starts its own.
 class Riffer::Runner::Fibers < Riffer::Runner
   # @rbs @max_concurrency: Integer?
 
@@ -35,6 +29,7 @@ class Riffer::Runner::Fibers < Riffer::Runner
                barrier
              end
 
+    # Sync joins the running reactor task if there is one, otherwise starts its own.
     Sync do
       items.each_with_index do |item, index|
         parent.async do

data/lib/riffer/runner/sequential.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Processes items sequentially in the current thread — the default runner.
 class Riffer::Runner::Sequential < Riffer::Runner
   #--
   #: (Array[untyped], context: Riffer::Agent::Context?) { (untyped) -> untyped } -> Array[untyped]

data/lib/riffer/runner/threaded.rb

@@ -1,9 +1,6 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Processes items concurrently using a thread pool of up to +max_concurrency+
-# workers pulling from a shared queue, so a slow item doesn't block others. If
-# multiple workers raise, only the first exception is re-raised after all finish.
 class Riffer::Runner::Threaded < Riffer::Runner
   # @rbs @max_concurrency: Integer
 

data/lib/riffer/runner.rb

@@ -1,10 +1,7 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Generic concurrency primitive for batch execution. Subclasses implement
-# +map+ to control how items are processed.
 class Riffer::Runner
-  # Maps over items using the provided block.
   #--
   #: (Array[untyped], context: Riffer::Agent::Context?) { (untyped) -> untyped } -> Array[untyped]
   def map(items, context:, &block)

data/lib/riffer/skills/activate_tool.rb

@@ -1,8 +1,6 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Tool the LLM calls to activate a skill and receive its instructions;
-# registered automatically when an agent has skills configured.
 class Riffer::Skills::ActivateTool < Riffer::Tool
   identifier "skill_activate"
   description "Activates a skill and returns its instructions. " \
@@ -13,7 +11,6 @@ class Riffer::Skills::ActivateTool < Riffer::Tool
     required :name, String, description: "The skill name to activate"
   end
 
-  # Activates a skill by name and returns its wrapped body, or a short pointer when the skill is already active.
   #--
   #: (context: Riffer::Agent::Context?, name: String) -> Riffer::Tools::Response
   def call(context:, name:)

data/lib/riffer/skills/adapter.rb

@@ -1,12 +1,7 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Interface for skill adapters — provider-specific rendering of the
-# available-skills section in the system prompt. Subclass and override
-# +render_catalog+; the activation tool is exposed via +#skill_activate_tool+
-# for the rendered output.
 class Riffer::Skills::Adapter
-  # The activation tool class for this adapter.
   attr_reader :skill_activate_tool #: singleton(Riffer::Tool) # @dynamic skill_activate_tool
 
   #--
@@ -15,21 +10,18 @@ class Riffer::Skills::Adapter
     @skill_activate_tool = skill_activate_tool
   end
 
-  # Renders a skill catalog section for the system prompt.
   #--
   #: (Array[Riffer::Skills::Frontmatter]) -> String
   def render_catalog(skills)
     raise NotImplementedError, "#{self.class} must implement #render_catalog"
   end
 
-  # Renders an activated skill body wrapped in identifying tags.
   #--
   #: (Riffer::Skills::Frontmatter, String) -> String
   def render_activation(skill, body)
     %(<skill_content name="#{skill.name}">\n#{body}\n</skill_content>)
   end
 
-  # The behavioral instructions rendered alongside the catalog.
   #--
   #: () -> String
   def catalog_instructions

data/lib/riffer/skills/backend.rb

@@ -1,24 +1,19 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Interface for skill storage backends. Subclass and implement +list_skills+
-# and +read_skill+ for custom storage (database, S3, etc.); use
-# Riffer::Skills::Frontmatter.parse on raw SKILL.md content.
 class Riffer::Skills::Backend
   SKILL_FILENAME = "SKILL.md" #: String
 
   def initialize = nil
 
-  # Returns frontmatter for all available skills; called once at the start of
-  # generate/stream.
   #--
   #: () -> Array[Riffer::Skills::Frontmatter]
   def list_skills
     raise NotImplementedError, "#{self.class} must implement #list_skills"
   end
 
-  # Returns the full SKILL.md body (without frontmatter) for a skill. Raises
-  # Riffer::ArgumentError if the skill is not found.
+  # Returns the SKILL.md body without frontmatter. Raises Riffer::ArgumentError
+  # if the skill is not found.
   #--
   #: (String) -> String
   def read_skill(name)

data/lib/riffer/skills/config.rb

@@ -1,13 +1,6 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Configuration object for the skills block DSL.
-#
-#   skills do
-#     backend Riffer::Skills::FilesystemBackend.new(".skills")
-#     adapter Riffer::Skills::XmlAdapter
-#     activate ["code-review"]
-#   end
 class Riffer::Skills::Config
   # @rbs @backend: (Riffer::Skills::Backend | Proc)?
   # @rbs @adapter: singleton(Riffer::Skills::Adapter)?
@@ -23,7 +16,6 @@ class Riffer::Skills::Config
     @activate_tool = nil
   end
 
-  # Gets or sets the skills backend (a Backend or a +context+-resolved Proc).
   #--
   #: (?(Riffer::Skills::Backend | Proc)?) -> (Riffer::Skills::Backend | Proc)?
   def backend(value = nil)
@@ -32,8 +24,6 @@ class Riffer::Skills::Config
     @backend = value
   end
 
-  # Gets or sets a custom skill adapter class; defaults to the provider's
-  # preferred adapter.
   #--
   #: (?singleton(Riffer::Skills::Adapter)?) -> singleton(Riffer::Skills::Adapter)?
   def adapter(value = nil)
@@ -42,9 +32,6 @@ class Riffer::Skills::Config
     @adapter = value
   end
 
-  # Gets or sets skill names to activate at startup (an array or a
-  # +context+-resolved Proc); activated skills' bodies are included in the
-  # system prompt without a tool call.
   #--
   #: (?(Array[String] | Proc)?) -> (Array[String] | Proc)?
   def activate(value = nil)
@@ -53,13 +40,11 @@ class Riffer::Skills::Config
     @activate = value
   end
 
-  # Gets or sets the per-agent skill activation tool override, or +nil+ when
-  # unset — the global fallback to <tt>Riffer.config.skills.default_activate_tool</tt>
-  # is applied by the agent at resolution, not here. Raises Riffer::ArgumentError
-  # on an invalid value.
   #--
   #: (?singleton(Riffer::Tool)?) -> singleton(Riffer::Tool)?
   def activate_tool(value = nil)
+    # No fallback to <tt>Riffer.config.skills.default_activate_tool</tt> here;
+    # the agent applies it at resolution.
     return @activate_tool if value.nil?
     unless value.is_a?(Class) && value < Riffer::Tool
       raise Riffer::ArgumentError, "activate_tool must be a Riffer::Tool subclass"
@@ -67,4 +52,15 @@ class Riffer::Skills::Config
 
     @activate_tool = value
   end
+
+  private
+
+  #--
+  #: (Riffer::Skills::Config) -> void
+  def initialize_copy(source)
+    super
+    # A shallow copy would share the activation list, so activating a skill on
+    # either config would reach the other.
+    @activate = Riffer::Helpers::DeepDup.call(source.activate)
+  end
 end

data/lib/riffer/skills/context.rb

@@ -1,22 +1,16 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Skills context for an agent generation cycle — coordinates discovery,
-# 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 @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] # @dynamic skills
 
-  # The skill adapter used for this context.
   attr_reader :adapter #: Riffer::Skills::Adapter # @dynamic adapter
 
-  # Optional callback invoked when a skill is first activated.
   attr_accessor :on_activate #: (^(String) -> void)? # @dynamic on_activate, on_activate=
 
   #--
@@ -30,10 +24,7 @@ class Riffer::Skills::Context
     @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)
@@ -42,10 +33,7 @@ class Riffer::Skills::Context
     @bodies[name] ||= @backend.read_skill(name)
   end
 
-  # Activates a skill by name. Returns the cached body on re-activation.
-  #
   # Raises Riffer::ArgumentError if the skill is not in the catalog.
-  #
   #--
   #: (String) -> String
   def activate(name)
@@ -57,11 +45,7 @@ class Riffer::Skills::Context
     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)
@@ -69,11 +53,7 @@ class Riffer::Skills::Context
     @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)
@@ -81,10 +61,7 @@ class Riffer::Skills::Context
     @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)
@@ -94,30 +71,24 @@ class Riffer::Skills::Context
     nil
   end
 
-  # Returns whether a skill has been activated.
-  #
   #--
   #: (String) -> bool
   def activated?(name)
     @activated.include?(name)
   end
 
-  # Returns whether a skill exists and may be activated by the model.
   #--
   #: (String) -> bool
   def model_invocable?(name)
     skills.key?(name) && !skills.fetch(name).disable_model_invocation
   end
 
-  # Returns whether any skill is available for the model to activate.
   #--
   #: () -> bool
   def activatable?
     available_skills.any?
   end
 
-  # Returns the complete skills section for the system prompt — the catalog plus
-  # any pre-activated skill bodies.
   #--
   #: () -> String
   def system_prompt

data/lib/riffer/skills/filesystem_backend.rb

@@ -1,9 +1,6 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Built-in backend that reads skills from the filesystem. Scans configured
-# directories for immediate child directories containing +SKILL.md+; directory
-# names must match the skill +name+.
 class Riffer::Skills::FilesystemBackend < Riffer::Skills::Backend
   # @rbs @paths: Array[String]
   # @rbs @skills_cache: Hash[String, String]?
@@ -16,8 +13,6 @@ class Riffer::Skills::FilesystemBackend < Riffer::Skills::Backend
     @skills_cache = nil #: Hash[String, String]?
   end
 
-  # Returns frontmatter for all discovered skills; on a name collision across
-  # paths, first-path-wins.
   #--
   #: () -> Array[Riffer::Skills::Frontmatter]
   def list_skills
@@ -46,8 +41,6 @@ class Riffer::Skills::FilesystemBackend < Riffer::Skills::Backend
     frontmatters
   end
 
-  # Returns the full SKILL.md body (without frontmatter) for a skill. Raises
-  # Riffer::ArgumentError if the skill is not found.
   #--
   #: (String) -> String
   def read_skill(name)

data/lib/riffer/skills/frontmatter.rb

@@ -3,33 +3,21 @@
 
 require "yaml"
 
-# Immutable value object holding parsed SKILL.md YAML frontmatter. Required
-# fields: +name+ and +description+; the optional +disable-model-invocation+
-# flag is recognized, and any other unrecognized top-level keys are merged into
-# +metadata+.
 class Riffer::Skills::Frontmatter
   NAME_PATTERN = /\A[a-z0-9]+(-[a-z0-9]+)*\z/ #: Regexp
   MAX_NAME_LENGTH = 64 #: Integer
   MAX_DESCRIPTION_LENGTH = 1024 #: Integer
 
-  # The skill name (1-64 chars, lowercase alphanumeric and hyphens).
   attr_reader :name #: String # @dynamic name
 
-  # The skill description (1-1024 chars).
   attr_reader :description #: String # @dynamic description
 
-  # Whether the skill opts out of model-driven activation. Hidden from the
-  # catalog and rejected at model activation; still reachable via programmatic
-  # activation.
   attr_reader :disable_model_invocation #: bool # @dynamic disable_model_invocation
 
-  # Metadata from the spec's +metadata+ field plus any unrecognized top-level
-  # keys.
   attr_reader :metadata #: Hash[Symbol, untyped] # @dynamic metadata
 
-  # Parses a raw SKILL.md string into a +[Frontmatter, body]+ pair — public so
-  # custom backends needn't reimplement parsing. Raises Riffer::ArgumentError
-  # if the frontmatter is invalid.
+  # Public so custom backends needn't reimplement parsing. Raises
+  # Riffer::ArgumentError if the frontmatter is invalid.
   #--
   #: (String) -> [Riffer::Skills::Frontmatter, String]
   def self.parse(raw)
@@ -47,7 +35,6 @@ class Riffer::Skills::Frontmatter
     ]
   end
 
-  # Parses only the frontmatter from a raw SKILL.md string, ignoring the body.
   # Raises Riffer::ArgumentError if the frontmatter is invalid.
   #--
   #: (String) -> Riffer::Skills::Frontmatter
@@ -80,7 +67,6 @@ class Riffer::Skills::Frontmatter
   private_class_method :split_frontmatter
 
   # Raises Riffer::ArgumentError if +name+ or +description+ is invalid.
-  # +disable_model_invocation+ is treated as set only when literally +true+.
   #--
   #: (name: String, description: String, ?disable_model_invocation: bool, ?metadata: Hash[Symbol, untyped]) -> void
   def initialize(name:, description:, disable_model_invocation: false, metadata: {})

data/lib/riffer/skills/markdown_adapter.rb

@@ -1,10 +1,7 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Default skill adapter — renders a skill catalog as Markdown for the system
-# prompt.
 class Riffer::Skills::MarkdownAdapter < Riffer::Skills::Adapter
-  # Renders a skill catalog as Markdown.
   #--
   #: (Array[Riffer::Skills::Frontmatter]) -> String
   def render_catalog(skills)
@@ -21,12 +18,12 @@ class Riffer::Skills::MarkdownAdapter < Riffer::Skills::Adapter
 
   private
 
-  # Collapses whitespace so a multi-line (block scalar) description stays within
-  # its `-` list item instead of breaking out to column 0, where continuation
-  # lines would read as top-level prompt text or fabricated catalog entries.
   #--
   #: (String) -> String
   def single_line(description)
+    # A multi-line (block scalar) description must stay within its `-` list
+    # item; continuation lines at column 0 would read as top-level prompt text
+    # or fabricated catalog entries.
     description.gsub(/\s+/, " ").strip
   end
 end

data/lib/riffer/skills/xml_adapter.rb

@@ -3,10 +3,7 @@
 
 require "cgi/escape"
 
-# Renders a skill catalog as XML for the system prompt, optimized for
-# Anthropic/Claude.
 class Riffer::Skills::XmlAdapter < Riffer::Skills::Adapter
-  # Renders a skill catalog as XML.
   #--
   #: (Array[Riffer::Skills::Frontmatter]) -> String
   def render_catalog(skills)

data/lib/riffer/stream_events/base.rb

@@ -1,9 +1,7 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Base class for all streaming events. Subclasses must implement +to_h+.
 class Riffer::StreamEvents::Base
-  # The message role (typically :assistant).
   attr_reader :role #: Symbol # @dynamic role
 
   #--
@@ -12,7 +10,6 @@ class Riffer::StreamEvents::Base
     @role = role
   end
 
-  # Converts the event to a hash.
   #--
   #: () -> Hash[Symbol, untyped]
   def to_h

data/lib/riffer/stream_events/finish_reason_done.rb

@@ -1,17 +1,12 @@
 # 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.
+# 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 # @dynamic finish_reason
 
-  # The provider's raw finish-reason value, when one exists on the wire.
   attr_reader :raw_finish_reason #: String? # @dynamic raw_finish_reason
 
-  # 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)