riffer 0.31.0 → 0.32.0

data/lib/riffer/guardrails/runner.rb

@@ -1,14 +1,8 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Executes guardrails sequentially and manages the processing pipeline.
-#
-# The runner processes guardrails in order, passing the output of each
-# to the next. If any guardrail blocks, execution stops and a tripwire
-# is returned.
-#
-#   runner = Runner.new(guardrail_configs, phase: :before, context: context)
-#   data, tripwire, modifications = runner.run(messages)
+# Executes guardrails sequentially, passing each one's output to the next; if
+# any blocks, execution stops and a tripwire is returned.
 class Riffer::Guardrails::Runner
   # The guardrail configs to execute.
   attr_reader :guardrail_configs #: Array[Hash[Symbol, untyped]]
@@ -19,12 +13,6 @@ class Riffer::Guardrails::Runner
   # The context passed to guardrails.
   attr_reader :context #: untyped
 
-  # Creates a new runner.
-  #
-  # [guardrail_configs] configs with :class and :options keys.
-  # [phase] :before or :after.
-  # [context] optional context to pass to guardrails.
-  #
   #--
   #: (Array[Hash[Symbol, untyped]], phase: Symbol, ?context: untyped) -> void
   def initialize(guardrail_configs, phase:, context: nil)
@@ -33,14 +21,9 @@ class Riffer::Guardrails::Runner
     @context = context
   end
 
-  # Runs the guardrails sequentially.
-  #
-  # For before phase, data should be an array of messages.
-  # For after phase, data should be a response and messages must be provided.
-  #
-  # [data] the data to process (messages for before, response for after).
-  # [messages] the conversation messages (required for after phase).
-  #
+  # Runs the guardrails sequentially. For the +:before+ phase +data+ is the
+  # messages array; for +:after+ it's the response (and +messages+ must be
+  # provided).
   #--
   #: (untyped, ?messages: Array[Riffer::Messages::Base]?) -> [untyped, Riffer::Guardrails::Tripwire?, Array[Riffer::Guardrails::Modification]]
   def run(data, messages: nil)

data/lib/riffer/guardrails/tripwire.rb

@@ -2,16 +2,6 @@
 # rbs_inline: enabled
 
 # Captures information about a blocked guardrail execution.
-#
-# When a guardrail blocks execution, a Tripwire is created to record
-# the reason, which guardrail triggered it, and which phase it occurred in.
-#
-#   tripwire = Tripwire.new(
-#     reason: "PII detected in input",
-#     guardrail: PiiRedactor,
-#     phase: :before,
-#     metadata: { detected_types: [:email, :phone] }
-#   )
 class Riffer::Guardrails::Tripwire
   PHASES = Riffer::Guardrails::PHASES #: Array[Symbol]
 
@@ -27,15 +17,7 @@ class Riffer::Guardrails::Tripwire
   # Optional metadata about the block.
   attr_reader :metadata #: Hash[Symbol, untyped]?
 
-  # Creates a new tripwire.
-  #
-  # [reason] the reason for blocking.
-  # [guardrail] the guardrail class that blocked.
-  # [phase] :before or :after.
-  # [metadata] optional additional information.
-  #
-  # Raises Riffer::ArgumentError if the phase is invalid.
-  #
+  # Raises Riffer::ArgumentError if +phase+ is invalid.
   #--
   #: (reason: String, guardrail: singleton(Riffer::Guardrail), phase: Symbol, ?metadata: Hash[Symbol, untyped]?) -> void
   def initialize(reason:, guardrail:, phase:, metadata: nil)

data/lib/riffer/guardrails.rb

@@ -1,10 +1,8 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Namespace module for guardrail components.
-#
-# Guardrails provide pre-processing of input messages and post-processing
-# of output responses in the agent pipeline.
+# Namespace for guardrail components that pre-process input and post-process
+# output in the agent pipeline.
 module Riffer::Guardrails
   PHASES = %i[before after].freeze #: Array[Symbol]
 end

data/lib/riffer/helpers/call_or_value.rb

@@ -1,12 +1,13 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Resolves the "Proc-or-value" idiom: if +thing+ is a Proc, calls it
-# (passing +context+ when its arity is non-zero); otherwise returns
-# +thing+ unchanged. When +thing+ is +nil+, returns +default+.
+# Resolves the Proc-or-value idiom.
 module Riffer::Helpers::CallOrValue
   extend self
 
+  # Calls +thing+ when it's a Proc (passing +context+ if its arity is non-zero),
+  # returns it unchanged otherwise, or +default+ when +nil+.
+  #--
   #: (untyped, ?context: untyped, ?default: untyped) -> untyped
   def resolve(thing, context: nil, default: nil)
     return default if thing.nil?

data/lib/riffer/helpers/class_name_converter.rb

@@ -3,13 +3,15 @@
 
 # Helper module for converting class names.
 module Riffer::Helpers::ClassNameConverter
+  extend self
+
   DEFAULT_SEPARATOR = "/" #: String
 
   # Converts a class name to snake_case identifier format.
   #
   #--
   #: (String, ?separator: String) -> String
-  def class_name_to_path(class_name, separator: DEFAULT_SEPARATOR)
+  def convert(class_name, separator: DEFAULT_SEPARATOR)
     class_name
       .to_s
       .gsub("::", separator)

data/lib/riffer/helpers/dependencies.rb

@@ -1,17 +1,15 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Helper module for lazy loading gem dependencies.
-#
-# Used by providers to load their required gems only when needed.
+# Lazy-loads gem dependencies — used by providers to load required gems only
+# when needed.
 module Riffer::Helpers::Dependencies
+  extend self
+
   # Raised when a required gem cannot be loaded.
   class LoadError < ::LoadError; end
 
-  # Requires a gem by name, raising a helpful error if it is not installed.
-  #
-  # Raises LoadError if the gem cannot be required.
-  #
+  # Requires a gem by name; raises LoadError if it isn't installed.
   #--
   #: (String) -> true
   def depends_on(gem_name)

data/lib/riffer/helpers.rb

@@ -1,10 +1,5 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Namespace for shared helper modules in the Riffer framework.
-#
-# Helpers provide reusable functionality across the library:
-# - Riffer::Helpers::ClassNameConverter - Class name to path conversion
-# - Riffer::Helpers::Dependencies - Lazy gem dependency loading
 module Riffer::Helpers
 end

data/lib/riffer/mcp/authenticated_tool.rb

@@ -1,15 +1,17 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Wraps MCP-generated tool classes so +tools/call+ uses +Riffer.config.mcp.credentials+
-# per invocation while delegating metadata to the inner class.
-#
+# Wraps MCP-generated tool classes so +tools/call+ resolves
+# +Riffer.config.mcp.credentials+ per invocation, delegating metadata to the
+# inner class.
 module Riffer::Mcp::AuthenticatedTool
+  extend self
+
   # 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 self.wrap_all(tool_classes, manifest, matched_tags)
+  def wrap_all(tool_classes, manifest, matched_tags)
     tool_classes.map { |tc| wrap_one(tc, manifest, matched_tags) }
   end
 
@@ -17,7 +19,7 @@ module Riffer::Mcp::AuthenticatedTool
   #: (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 self.wrap_one(inner_class, manifest, matched_tags) # steep:ignore MethodBodyTypeMismatch
+  def wrap_one(inner_class, manifest, matched_tags) # steep:ignore MethodBodyTypeMismatch
     inner = inner_class
     man = manifest
     tags = matched_tags
@@ -33,10 +35,8 @@ module Riffer::Mcp::AuthenticatedTool
       define_singleton_method(:description) { inner.description }
       define_singleton_method(:parameters_schema) { |strict: false| inner.parameters_schema(strict: strict) }
 
-      # Builds a client for a single +tools/call+ invocation.
-      #
-      # Creates a fresh client per call so headers from the credentials proc stay
-      # current.
+      # Creates a fresh client per +tools/call+ so headers from the credentials
+      # proc stay current.
       # TODO: A per-headers cache would reduce connection churn under load, and
       # requires a follow-up investigation to determine how to invalidate failing
       # clients.

data/lib/riffer/mcp/client.rb

@@ -1,21 +1,10 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Thin wrapper around the MCP Ruby SDK client (mcp gem v0.8+).
-#
-# Resolves headers (if a Proc) once at initialization, then provides
-# +tools_list+ and +tools_call+. Used for discovery (+Manifest#discovery_headers+)
-# and for +tools/call+ when no +credentials+ proc is configured.
-#
-# MCP gem API used:
-#   MCP::Client::HTTP.new(url:, headers:)  — HTTP transport (requires faraday)
-#   MCP::Client.new(transport:)            — client
-#   client.tools                           — Array<MCP::Client::Tool>
-#   client.call_tool(tool:, arguments:)    — raw JSON-RPC response Hash
-#
+# Thin wrapper around the MCP Ruby SDK client (mcp gem v0.8+). Resolves headers
+# (if a Proc) once at init, then provides +tools_list+ / +tools_call+ — used for
+# discovery and for +tools/call+ when no +credentials+ proc is configured.
 class Riffer::Mcp::Client
-  include Riffer::Helpers::Dependencies
-
   # @rbs @client: untyped
 
   #--
@@ -31,9 +20,8 @@ class Riffer::Mcp::Client
     end
   end
 
-  # Returns an array of tool definition hashes, each with +:name+, +:description+,
-  # and +:input_schema+ keys.
-  #
+  # Returns tool definition hashes with +:name+, +:description+, and
+  # +:input_schema+ keys.
   #--
   #: () -> Array[Hash[Symbol, untyped]]
   def tools_list
@@ -66,4 +54,11 @@ class Riffer::Mcp::Client
     content = response.dig("result", "content") || []
     content.filter_map { |item| item["text"] }.join
   end
+
+  private
+
+  #: (String) -> true
+  def depends_on(gem_name)
+    Riffer::Helpers::Dependencies.depends_on(gem_name)
+  end
 end

data/lib/riffer/mcp/manifest.rb

@@ -3,23 +3,26 @@
 
 require "uri"
 
-# Riffer::Mcp::Manifest holds the configuration for a single MCP server.
-#
-# +name+                - String identifier used as the registration key and generated-agent identifier.
-# +tags+                - Array[Symbol]; normalized to symbols at construction time.
-# +endpoint+            - String HTTPS URL passed to the MCP transport.
-# +discovery_headers+   - Hash or Proc; resolved once when building the discovery client for +tools/list+.
-# +credentials_scope+  - Optional symbol hint: +:global+, +:tenant+, +:user+ — documents whether
-#   invocation credentials are expected to depend on tenant and/or user keys in +context+ (no ids stored).
-#   Apps may treat +:user+ as "user in tenant" and pass both keys in +context+.
-#
+# Holds the configuration for a single MCP server.
 class Riffer::Mcp::Manifest
+  # Identifier used as the registration key and generated-agent identifier.
   attr_reader :name #: String
+
+  # Tags for matching +use_mcp+.
   attr_reader :tags #: Array[Symbol]
+
+  # HTTPS URL passed to the MCP transport.
   attr_reader :endpoint #: String
+
+  # Headers (or a Proc) resolved once when building the discovery client.
   attr_reader :discovery_headers #: (Hash[String, untyped] | ::Proc)?
+
+  # Optional hint (+:global+/+:tenant+/+:user+) for whether invocation
+  # credentials depend on tenant/user keys in +context+.
   attr_reader :credentials_scope #: Symbol?
 
+  # Raises Riffer::ArgumentError unless +name+ is present and +endpoint+ is a
+  # valid HTTPS URL.
   #--
   #: (name: String, endpoint: String, ?tags: Array[untyped]?, ?discovery_headers: (Hash[String, untyped] | ::Proc)?, ?credentials_scope: (String | Symbol)?) -> void
   def initialize(name:, endpoint:, tags: nil, discovery_headers: nil, credentials_scope: nil)

data/lib/riffer/mcp/registration.rb

@@ -1,11 +1,8 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Per-server state managed by Riffer::Mcp::Registry.
-#
-# Created when a server is registered. Discovers tools via the MCP
-# +tools/list+ call, then generates tool classes.
-#
+# Per-server state managed by Riffer::Mcp::Registry — discovers tools via
+# +tools/list+ and generates tool classes when a server is registered.
 class Riffer::Mcp::Registration
   # @rbs @cancelled: bool
   # @rbs @tools: Array[singleton(Riffer::Tool)]
@@ -51,12 +48,6 @@ class Riffer::Mcp::Registration
 
   private
 
-  # Runs tool discovery using the configured Runner.
-  #
-  # With +Runner::Sequential+ (default) discovery blocks inline. With
-  # +Runner::Threaded+ discovery runs on a pool thread but +map+ still
-  # blocks the caller — useful for Rails connection-pool isolation.
-  #
   #--
   #: () -> void
   def run_discovery

data/lib/riffer/mcp/registry.rb

@@ -1,67 +1,59 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Thread-safe global store for MCP server registrations.
-#
-# Keyed by manifest name. All public methods are mutex-guarded.
-#
+# Thread-safe global store for MCP server registrations, keyed by manifest name.
 module Riffer::Mcp::Registry
-  # @rbs self.@mutex: Thread::Mutex
-  # @rbs self.@store: Hash[String, Riffer::Mcp::Registration]
+  extend self
+
+  # @rbs @mutex: Thread::Mutex
+  # @rbs @store: Hash[String, Riffer::Mcp::Registration]
 
   @mutex = Mutex.new
   @store = {} #: Hash[String, Riffer::Mcp::Registration]
 
-  class << self
-    # Registers an MCP server and starts async tool discovery.
-    #
-    # Accepts a Manifest instance or a hash of manifest keyword arguments.
-    # Replaces any existing registration with the same name.
-    #
-    #--
-    #: ((Hash[Symbol, untyped] | Riffer::Mcp::Manifest)) -> Riffer::Mcp::Registration
-    def register(manifest_or_hash)
-      # steep cannot verify that an untyped Hash splat supplies Manifest's
-      # required name:/endpoint: keywords; Manifest validates them at runtime.
-      manifest = manifest_or_hash.is_a?(Riffer::Mcp::Manifest) ? manifest_or_hash : Riffer::Mcp::Manifest.new(**manifest_or_hash) # steep:ignore InsufficientKeywordArguments
-      registration = Riffer::Mcp::Registration.new(manifest)
-      old = @mutex.synchronize do
-        previous = @store[manifest.name]
-        @store[manifest.name] = registration
-        previous
-      end
-      old&.retire!
-      registration
+  # Registers an MCP server and starts async tool discovery, replacing any
+  # existing registration with the same name.
+  #--
+  #: ((Hash[Symbol, untyped] | Riffer::Mcp::Manifest)) -> Riffer::Mcp::Registration
+  def register(manifest_or_hash)
+    # steep cannot verify that an untyped Hash splat supplies Manifest's
+    # required name:/endpoint: keywords; Manifest validates them at runtime.
+    manifest = manifest_or_hash.is_a?(Riffer::Mcp::Manifest) ? manifest_or_hash : Riffer::Mcp::Manifest.new(**manifest_or_hash) # steep:ignore InsufficientKeywordArguments
+    registration = Riffer::Mcp::Registration.new(manifest)
+    old = @mutex.synchronize do
+      previous = @store[manifest.name]
+      @store[manifest.name] = registration
+      previous
     end
+    old&.retire!
+    registration
+  end
 
-    # Removes a registration by name.
-    #
-    #--
-    #: ((String | Symbol)) -> void
-    def unregister(name)
-      removed = @mutex.synchronize { @store.delete(name.to_s) }
-      removed&.retire!
-    end
+  # Removes a registration by name.
+  #
+  #--
+  #: ((String | Symbol)) -> void
+  def unregister(name)
+    removed = @mutex.synchronize { @store.delete(name.to_s) }
+    removed&.retire!
+  end
 
-    # Returns a frozen snapshot of all current registrations.
-    #
-    #--
-    #: () -> Hash[String, Riffer::Mcp::Registration]
-    def registrations
-      @mutex.synchronize { @store.dup.freeze }
-    end
+  # Returns a frozen snapshot of all current registrations.
+  #
+  #--
+  #: () -> Hash[String, Riffer::Mcp::Registration]
+  def registrations
+    @mutex.synchronize { @store.dup.freeze }
+  end
 
-    # Returns all registrations whose manifest tags intersect with the given tags.
-    #
-    # Tags are normalized to symbols before matching.
-    #
-    #--
-    #: (Array[Symbol]) -> Array[Riffer::Mcp::Registration]
-    def find_by_tags(tags)
-      normalized = tags.map(&:to_sym)
-      @mutex.synchronize do
-        @store.values.select { |reg| (reg.manifest.tags & normalized).any? }
-      end
+  # Returns all registrations whose manifest tags intersect the given tags
+  # (normalized to symbols).
+  #--
+  #: (Array[Symbol]) -> Array[Riffer::Mcp::Registration]
+  def find_by_tags(tags)
+    normalized = tags.map(&:to_sym)
+    @mutex.synchronize do
+      @store.values.select { |reg| (reg.manifest.tags & normalized).any? }
     end
   end
 end

data/lib/riffer/mcp/search_tool.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# Searches available MCP tools by name or description.
+class Riffer::Mcp::SearchTool < Riffer::Tool
+  IDENTIFIER = "mcp_search"
+
+  # Successful search response carrying the matched tool classes.
+  class Result < Riffer::Tools::Response
+    # Tool classes that matched the search query.
+    attr_reader :discovered_tools #: Array[singleton(Riffer::Tool)]
+
+    #--
+    #: (String, Array[singleton(Riffer::Tool)]) -> void
+    def initialize(content, discovered_tools)
+      super(content: content, success: true)
+      @discovered_tools = discovered_tools
+    end
+  end
+
+  identifier IDENTIFIER
+  description "Search for available MCP tools by name or description."
+
+  params do
+    required :query, String, description: "Non-empty substring to filter tools by name or description."
+  end
+
+  # Searches progressive MCP tools and returns a +Result+ with +discovered_tools+.
+  #--
+  #: (context: Riffer::Agent::Context?, query: String) -> Riffer::Tools::Response
+  def call(context:, query:)
+    return error("Provide a search query to find MCP tools by name or description.") if query.strip.empty?
+
+    tools = context&.mcp_progressive_tools || []
+    matches = filter(tools, query)
+
+    return text("No tools found matching '#{query}'.") if matches.empty?
+
+    names = matches.map(&:name).join(", ")
+    Result.new(
+      "Found #{matches.length} tool(s): #{names}. They are now available — call them directly.",
+      matches
+    )
+  end
+
+  private
+
+  #: (Array[singleton(Riffer::Tool)], String) -> Array[singleton(Riffer::Tool)]
+  def filter(tools, query)
+    q = query.downcase
+    tools.select { |t| t.name.downcase.include?(q) || t.description.to_s.downcase.include?(q) }
+  end
+end

data/lib/riffer/mcp/tool_factory.rb

@@ -2,33 +2,28 @@
 # rbs_inline: enabled
 
 # Generates anonymous Riffer::Tool subclasses from MCP tool definitions.
-#
-# Each generated class:
-# - Has +.name+, +.description+, and +.parameters_schema+ derived from the MCP tool definition.
-# - Delegates +#call+ to the MCP client's +tools_call+ method.
-# - Skips Riffer's param validation — the MCP server validates inputs.
-#
+# 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.
-  #
-  # Tool names are prefixed with the manifest name to avoid collisions
-  # across MCP servers (e.g. +"jira__search"+). The original server-side
-  # name is available via +.mcp_server_tool_name+.
-  #
+  extend self
+
+  # 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+.
   #--
   #: (String, Riffer::Mcp::Client, Array[Hash[Symbol, untyped]]) -> Array[singleton(Riffer::Tool)]
-  def self.build(manifest_name, client, tool_defs)
+  def build(manifest_name, client, tool_defs)
     tool_defs.map { |td| build_tool_class(manifest_name, client, td) }
   end
 
-  # Replaces characters that are unsafe in LLM tool names.
+  private
+
   #: (String) -> String
-  def self.sanitize_name_component(str)
+  def sanitize_name_component(str)
     str.gsub(/[^a-zA-Z0-9_-]/, "_")
   end
-  private_class_method :sanitize_name_component
 
-  private_class_method def self.build_tool_class(manifest_name, client, td)
+  def build_tool_class(manifest_name, client, td)
     prefixed = "#{sanitize_name_component(manifest_name)}__#{sanitize_name_component(td[:name])}"
 
     # steep cannot type the body of a dynamically created anonymous class:
@@ -39,7 +34,7 @@ module Riffer::Mcp::ToolFactory
       @mcp_client = client
       @mcp_server_tool_name = td[:name]
       # Set @identifier directly so .identifier does not fall back to
-      # class_name_to_path(nil) on this anonymous class.
+      # Riffer::Helpers::ClassNameConverter.convert(nil) on this anonymous class.
       @identifier = prefixed
 
       define_singleton_method(:name) { prefixed }

data/lib/riffer/mcp.rb

@@ -1,10 +1,9 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Riffer::Mcp provides integration with Model Context Protocol (MCP) servers.
-#
-# Register MCP servers globally; agents opt-in by tag via the +use_mcp+ DSL.
-# Tags are application-defined; see +docs/14_MCP.md+ (Tags section).
+# Integration with Model Context Protocol (MCP) servers. Register servers
+# globally; agents opt-in by tag via the +use_mcp+ DSL. Tags are
+# application-defined; see +docs/14_MCP.md+.
 #
 #   Riffer::Mcp.register(
 #     name: "github",
@@ -19,6 +18,8 @@
 #   end
 #
 module Riffer::Mcp
+  extend self
+
   # Base error for all MCP-related failures.
   class Error < Riffer::Error; end
 
@@ -26,32 +27,26 @@ module Riffer::Mcp
   # after the server's tools were included for this run.
   class CredentialsDeniedError < Error; end
 
-  # Registers an MCP server, blocking until tool discovery completes.
-  #
-  # Raises on discovery failure. Pass a +Manifest+ instance or a hash with
-  # the same keys.
-  #
+  # Registers an MCP server, blocking until tool discovery completes. Raises
+  # on discovery failure.
   #--
   #: ((Hash[Symbol, untyped] | Riffer::Mcp::Manifest)) -> Riffer::Mcp::Registration
-  def self.register(manifest_or_hash)
+  def register(manifest_or_hash)
     Registry.register(manifest_or_hash)
   end
 
-  # Removes a registration by name.
-  #
-  # Subsequent agent runs will not see tools from this server.
-  #
+  # Removes a registration by name; subsequent agent runs won't see its tools.
   #--
   #: (String) -> void
-  def self.unregister(name)
+  def unregister(name)
     Registry.unregister(name)
   end
 
-  # Returns all current registrations keyed by name (for introspection).
+  # Returns all current registrations keyed by name.
   #
   #--
   #: () -> Hash[String, Riffer::Mcp::Registration]
-  def self.registrations
+  def registrations
     Registry.registrations
   end
 end

data/lib/riffer/messages/assistant.rb

@@ -1,15 +1,8 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Represents an assistant (LLM) message in a conversation.
-#
-# May include tool calls when the LLM requests tool execution.
-#
-#   msg = Riffer::Messages::Assistant.new("Hello!")
-#   msg.role        # => :assistant
-#   msg.content     # => "Hello!"
-#   msg.tool_calls  # => []
-#
+# Represents an assistant (LLM) message in a conversation; may include tool
+# calls when the LLM requests tool execution.
 class Riffer::Messages::Assistant < Riffer::Messages::Base
   ToolCall = Struct.new(:call_id, :name, :arguments, keyword_init: true)