riffer 0.48.0 → 0.49.0

data/lib/riffer/tools/toolable.rb

@@ -1,20 +1,6 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Shared class-level DSL for anything that presents as a tool to an LLM. Extend
-# it to make a class discoverable as a tool; instance-level execution (+call+,
-# +call_with_validation+) lives on Riffer::Tool instead.
-#
-#   class MyTool
-#     extend Riffer::Tools::Toolable
-#
-#     description "Does something useful"
-#
-#     params do
-#       required :input, String
-#     end
-#   end
-#
 # @rbs module-self Module
 module Riffer::Tools::Toolable
   # @rbs self.@extenders: Array[Module]?
@@ -26,8 +12,6 @@ module Riffer::Tools::Toolable
 
   DEFAULT_TIMEOUT = 10 #: Integer
 
-  # Tracks all classes that extend Toolable.
-  #
   #--
   #: (Module) -> void
   def self.extended(base)
@@ -35,16 +19,12 @@ module Riffer::Tools::Toolable
     extenders << base
   end
 
-  # Returns all classes that have extended Toolable.
-  #
   #--
   #: () -> Array[Module]
   def self.all
     @extenders || []
   end
 
-  # Gets or sets the tool description.
-  #
   #--
   #: (?String?) -> String?
   def description(value = nil)
@@ -53,8 +33,6 @@ module Riffer::Tools::Toolable
     @description = value.to_s
   end
 
-  # Gets or sets the tool identifier/name.
-  #
   #--
   #: (?String?) -> String
   def identifier(value = nil)
@@ -63,8 +41,6 @@ module Riffer::Tools::Toolable
     @identifier = value.to_s
   end
 
-  # Alias for identifier — used by providers.
-  #
   #--
   #: (?String?) -> String
   def name(value = nil)
@@ -73,8 +49,6 @@ module Riffer::Tools::Toolable
     identifier
   end
 
-  # Gets or sets the tool timeout in seconds.
-  #
   #--
   #: (?(Integer | Float)?) -> (Integer | Float)
   def timeout(value = nil)
@@ -83,8 +57,6 @@ module Riffer::Tools::Toolable
     @timeout = value.to_f
   end
 
-  # Defines parameters using the Params DSL.
-  #
   #--
   #: () ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> Riffer::Params?
   def params(&block)
@@ -95,15 +67,12 @@ module Riffer::Tools::Toolable
     @params_builder = builder
   end
 
-  # Returns the JSON Schema for the tool's parameters.
-  #
   #--
   #: (?strict: bool) -> Hash[Symbol, untyped]
   def parameters_schema(strict: false)
     @params_builder&.to_json_schema(strict: strict) || empty_schema
   end
 
-  # Returns the kind of toolable entity; defaults to +:tool+.
   #--
   #: (?Symbol?) -> Symbol
   def kind(value = nil)
@@ -112,8 +81,6 @@ module Riffer::Tools::Toolable
     @kind = value.to_sym
   end
 
-  # Returns a provider-agnostic tool schema hash.
-  #
   #--
   #: (?strict: bool) -> Hash[Symbol, untyped]
   def to_tool_schema(strict: false)
@@ -124,10 +91,6 @@ module Riffer::Tools::Toolable
     }
   end
 
-  # Validates that the minimum required metadata is present for LLM tool use.
-  #
-  # Raises Riffer::ArgumentError if validation fails.
-  #
   #--
   #: () -> true
   def validate_as_tool!

data/lib/riffer/tracing/capture.rb

@@ -3,9 +3,6 @@
 
 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
 
@@ -73,13 +70,14 @@ module Riffer::Tracing::Capture # :nodoc: all
   #--
   #: (Riffer::Messages::User::FilePart) -> Hash[Symbol, untyped]
   def file_part(file)
+    # Metadata only: file bytes and URLs must never reach a span attribute.
     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.
+  # Semconv's tool_call part carries arguments as a JSON object, so a string
+  # would be double-encoded.
   #--
   #: (String) -> untyped
   def parse_arguments(arguments)

data/lib/riffer/tracing/no_op.rb

@@ -1,13 +1,9 @@
 # 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
@@ -34,21 +30,18 @@ module Riffer::Tracing::NoOp # :nodoc: all
 
   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)

data/lib/riffer/tracing/otel.rb

@@ -1,14 +1,13 @@
 # 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.
+# <tt>::OpenTelemetry</tt> constants must appear only inside method bodies, so
+# the gem 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).
+  # Keeps callers from touching <tt>::OpenTelemetry</tt> constants (status
+  # objects in particular).
   class Span
     # @rbs @otel_span: untyped
 
@@ -36,7 +35,6 @@ class Riffer::Tracing::Otel # :nodoc: all
       @otel_span.record_exception(exception)
     end
 
-    # Marks the span status as error.
     #--
     #: (?String) -> void
     def error!(description = "")
@@ -51,9 +49,7 @@ class Riffer::Tracing::Otel # :nodoc: all
   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>.
+    # Returns +nil+ so resolution falls back to NoOp.
     #--
     #: (?provider: untyped) -> Riffer::Tracing::Otel?
     def build(provider: nil)
@@ -69,7 +65,6 @@ class Riffer::Tracing::Otel # :nodoc: all
       new(provider: provider || ::OpenTelemetry.tracer_provider)
     end
 
-    # Whether the OpenTelemetry API gem is loadable at a supported version.
     #--
     #: () -> bool
     def available?
@@ -79,9 +74,8 @@ class Riffer::Tracing::Otel # :nodoc: all
       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.
+    # opentelemetry-api is undeclared, so this is the only protection against
+    # an incompatible API.
     #--
     #: (Gem::Version) -> bool
     def supported?(version)
@@ -109,7 +103,6 @@ class Riffer::Tracing::Otel # :nodoc: all
     @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:)
@@ -118,14 +111,12 @@ class Riffer::Tracing::Otel # :nodoc: all
     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, &)

data/lib/riffer/tracing/stream_recorder.rb

@@ -1,23 +1,16 @@
 # 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
   # @rbs @clock: ^() -> Float
   # @rbs @started_at: Float
 
   attr_reader :token_usage #: Riffer::Providers::TokenUsage? # @dynamic token_usage
-
   attr_reader :time_to_first_chunk #: Float? # @dynamic time_to_first_chunk
-
   attr_reader :finish_reason #: Symbol? # @dynamic finish_reason
-
   attr_reader :raw_finish_reason #: String? # @dynamic raw_finish_reason
-
   attr_reader :content #: String? # @dynamic content
-
   attr_reader :tool_calls #: Array[Riffer::Messages::Assistant::ToolCall] # @dynamic tool_calls
 
   #--

data/lib/riffer/tracing.rb

@@ -1,21 +1,15 @@
 # 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.
+# No-ops unless the host bundles the OpenTelemetry API, 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, &)
@@ -24,8 +18,7 @@ module Riffer::Tracing # :nodoc: all
     backend.in_span(name, attributes: attributes, kind: kind, &)
   end
 
-  # Returns the active trace context, for re-attachment across fiber or
-  # thread boundaries.
+  # For re-attachment across fiber or thread boundaries.
   #--
   #: () -> untyped
   def current_context
@@ -34,8 +27,7 @@ module Riffer::Tracing # :nodoc: all
     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.
+  # +nil+ passes through so captures taken while tracing was off stay harmless.
   #--
   #: [R] (untyped) { () -> R } -> R
   def with_context(context, &)
@@ -44,8 +36,6 @@ module Riffer::Tracing # :nodoc: all
     backend.with_context(context, &)
   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)
@@ -58,24 +48,11 @@ module Riffer::Tracing # :nodoc: all
     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.48.0" #: String
+  VERSION = "0.49.0" #: String
 end

data/lib/riffer.rb

@@ -3,7 +3,6 @@
 
 require "zeitwerk"
 
-# Riffer is the main module for the Riffer AI framework.
 loader = Zeitwerk::Loader.for_gem
 loader.inflector.inflect(
   "open_ai" => "OpenAI",
@@ -24,78 +23,51 @@ module Riffer
 
   # @rbs @config: Riffer::Config?
 
-  # Base error class for Riffer.
   class Error < StandardError; end
 
-  # Raised when invalid arguments are provided.
   class ArgumentError < ::ArgumentError; end
 
-  # Raised when tool parameter validation fails.
   class ValidationError < Error; end
 
-  # Raised inside a tool's +call+ when execution exceeds the configured
-  # timeout. Rescue it in the tool to clean up; otherwise it becomes a
+  # Rescue it in the tool to clean up; otherwise it becomes a
   # +:timeout_error+ response.
   class TimeoutError < Error; end
 
-  # Raised when a tool encounters an expected execution error.
   class ToolExecutionError < Error; end
 
-  # Raised when a provider's stream ends before its terminal event (Bedrock's
-  # messageStop, Anthropic's message_stop, OpenAI's response.completed /
-  # incomplete / failed), so a truncated or empty response is never returned
-  # as a complete message. Events already yielded were delivered; the
-  # request is safe to retry.
+  # Events already yielded were delivered; the request is safe to retry.
   class IncompleteStreamError < Error; end
 
-  # Base error for a file attachment that can't be resolved for the provider.
   class FileError < Error; end
 
-  # Raised when the provider can't accept the file at all.
   class FileUnsupportedError < FileError; end
 
-  # Raised when a download is required but Riffer.config.files.allow_downloads is false.
   class FileDownloadsDisabledError < FileError; end
 
-  # Raised when a message carries more files than Riffer.config.files.max_per_message allows.
   class TooManyFilesError < FileError; end
 
-  # Raised when there's an issue downloading a file
   class FileDownloadError < FileError; end
 
-  # Raised when a file size exceeds Riffer.config.files.max_bytes
   class FileTooLargeError < FileError; end
 
-  # Raised when a downloaded or inline file's sha256 doesn't match.
   class FileChecksumMismatchError < FileError; end
 
-  # Raised when a FilePart's data isn't valid base64
   class FileEncodingError < FileError; end
 
-  # Raised when two registered subclasses share the same identifier.
   class DuplicateIdentifierError < Error; end
 
-  # Returns the Riffer configuration.
-  #
   #--
   #: () -> Riffer::Config
   def config
     @config ||= Config.new
   end
 
-  # Yields the configuration for block-based setup.
-  #
-  #   Riffer.configure do |config|
-  #     config.openai.api_key = ENV['OPENAI_API_KEY']
-  #   end
-  #
   #--
   #: () ?{ (Riffer::Config) -> void } -> void
   def configure(&)
     yield config if block_given?
   end
 
-  # Returns the gem version.
   #--
   #: () -> String
   def version

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

@@ -1,120 +1,84 @@
 # Generated from lib/riffer/agent/config.rb with RBS::Inline
 
-# Typed configuration object holding every class-level DSL setting on a
-# Riffer::Agent subclass. Procs are stored unresolved and resolved per-instance
-# later.
 class Riffer::Agent::Config
   DEFAULT_MAX_STEPS: Integer
 
   @tool_runtime: (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)?
 
-  # The configured agent identifier.
   attr_reader identifier: String?
 
-  # The configured model.
   attr_reader model: (String | Proc)?
 
-  # The configured instructions.
   attr_reader instructions: (String | Proc)?
 
-  # Options passed to generate_text/stream_text.
   attr_accessor model_options: Hash[Symbol, untyped]
 
-  # The configured structured-output schema.
   attr_reader structured_output: Riffer::Params?
 
-  # The maximum number of LLM call steps in the tool-use loop.
   attr_accessor max_steps: Numeric?
 
-  # The configured tools.
   attr_accessor tools_config: (Array[singleton(Riffer::Tool)] | Proc)?
 
-  # The accumulated +use_mcp+ tag configurations.
   attr_reader mcp_configs: Array[Hash[Symbol, untyped]]
 
-  # The configured skills.
   attr_accessor skills_config: Riffer::Skills::Config?
 
-  # Registered guardrail entries keyed by phase.
   attr_reader guardrails: Hash[Symbol, Array[Hash[Symbol, untyped]]]
 
-  # Builds a new Config. Raises Riffer::ArgumentError if +model+ or
-  # +instructions+ is invalid (e.g. an empty string).
   # --
   # : (
-  #    ?identifier: String?,
-  #    ?model: (String | Proc)?,
-  #    ?instructions: (String | Proc)?,
-  #    ?model_options: Hash[Symbol, untyped],
-  #    ?structured_output: Riffer::Params?,
-  #    ?max_steps: Numeric?,
-  #    ?tools_config: (Array[singleton(Riffer::Tool)] | Proc)?,
-  #    ?mcp_configs: Array[Hash[Symbol, untyped]],
-  #    ?tool_runtime: (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)?,
-  #    ?skills_config: Riffer::Skills::Config?,
-  #    ?guardrails: Hash[Symbol, Array[Hash[Symbol, untyped]]]
-  #  ) -> void
+  #     ?identifier: String?,
+  #     ?model: (String | Proc)?,
+  #     ?instructions: (String | Proc)?,
+  #     ?model_options: Hash[Symbol, untyped],
+  #     ?structured_output: Riffer::Params?,
+  #     ?max_steps: Numeric?,
+  #     ?tools_config: (Array[singleton(Riffer::Tool)] | Proc)?,
+  #     ?mcp_configs: Array[Hash[Symbol, untyped]],
+  #     ?tool_runtime: (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)?,
+  #     ?skills_config: Riffer::Skills::Config?,
+  #     ?guardrails: Hash[Symbol, Array[Hash[Symbol, untyped]]]
+  #   ) -> void
   def initialize: (?identifier: String?, ?model: (String | Proc)?, ?instructions: (String | Proc)?, ?model_options: Hash[Symbol, untyped], ?structured_output: Riffer::Params?, ?max_steps: Numeric?, ?tools_config: (Array[singleton(Riffer::Tool)] | Proc)?, ?mcp_configs: Array[Hash[Symbol, untyped]], ?tool_runtime: (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)?, ?skills_config: Riffer::Skills::Config?, ?guardrails: Hash[Symbol, Array[Hash[Symbol, untyped]]]) -> void
 
-  # Sets +identifier+, coercing the value to String.
   # --
   # : (untyped) -> String?
   def identifier=: (untyped) -> String?
 
-  # Sets +structured_output+. Raises Riffer::ArgumentError on an invalid value.
   # --
   # : (Riffer::Params?) -> Riffer::Params?
   def structured_output=: (Riffer::Params?) -> Riffer::Params?
 
-  # Returns the declared tool runtime, or +Riffer.config.tool_runtime+ when none
-  # was declared. Resolving the global here rather than at construction is what
-  # lets a copy tell an inherited runtime from a defaulted one.
   # --
   # : () -> (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)
   def tool_runtime: () -> (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)
 
-  # Sets +tool_runtime+. Raises Riffer::ArgumentError on an invalid value.
   # --
   # : ((singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)) -> (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)
   def tool_runtime=: (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc) -> (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)
 
-  # Sets +model+. Raises Riffer::ArgumentError on an invalid value (e.g. an
-  # empty string).
   # --
   # : ((String | Proc)?) -> (String | Proc)?
   def model=: ((String | Proc)?) -> (String | Proc)?
 
-  # Sets +instructions+. Raises Riffer::ArgumentError on an invalid value (e.g.
-  # an empty string).
   # --
   # : ((String | Proc)?) -> (String | Proc)?
   def instructions=: ((String | Proc)?) -> (String | Proc)?
 
-  # Appends an MCP tag entry to +mcp_configs+.
-  #
   # --
   # : (String | Symbol, ?progressive: bool) -> Array[Hash[Symbol, untyped]]
   def add_mcp: (String | Symbol, ?progressive: bool) -> Array[Hash[Symbol, untyped]]
 
-  # Appends a guardrail entry to +guardrails+ for the given phase; +:around+
-  # appends to both +:before+ and +:after+. Raises Riffer::ArgumentError unless
-  # +phase+ is :before, :after, or :around.
   # --
   # : (Symbol, klass: singleton(Riffer::Guardrail), ?options: Hash[Symbol, untyped]) -> void
   def add_guardrail: (Symbol, klass: singleton(Riffer::Guardrail), ?options: Hash[Symbol, untyped]) -> void
 
-  # Returns the guardrail entries for the given phase, or +[]+ if none.
-  #
   # --
   # : (Symbol) -> Array[Hash[Symbol, untyped]]
   def guardrails_for: (Symbol) -> Array[Hash[Symbol, untyped]]
 
   private
 
-  # +dup+ would leave the copy sharing every collection with this one, so a
-  # declaration on either would reach the other. The nesting runs deeper than one
-  # level: an mcp entry holds its own +:tags+ array, a guardrail entry its own
-  # +:options+ hash, and +model_options+ is arbitrary.
   # --
   # : (Riffer::Agent::Config) -> void
   def initialize_copy: (Riffer::Agent::Config) -> void

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

@@ -1,74 +1,52 @@
 # Generated from lib/riffer/agent/context.rb with RBS::Inline
 
-# Typed value object wrapping the runtime context Hash held by a Riffer::Agent.
-# Exposes typed +skills+, +token_usage+, +mcp_progressive_tools+, and
-# +discovered_tools+ accessors while preserving +#[]+ / +#dig+ for caller-provided keys.
 class Riffer::Agent::Context
   @data: Hash[Symbol, untyped]
 
   RESERVED_KEYS: Array[Symbol]
 
-  # Builds a new context. The caller Hash is duped so later caller mutations
-  # don't leak in. Raises Riffer::ArgumentError if it contains a reserved key.
+  # Raises Riffer::ArgumentError if +data+ contains a reserved key.
   # --
   # : (?Hash[Symbol, untyped]) -> void
   def initialize: (?Hash[Symbol, untyped]) -> void
 
-  # The agent's resolved +Riffer::Skills::Context+, or +nil+ when skills
-  # are not configured.
-  #
   # --
   # : () -> Riffer::Skills::Context?
   def skills: () -> Riffer::Skills::Context?
 
-  # Sets the resolved skills context. Raises Riffer::ArgumentError on an
-  # invalid value.
   # --
   # : (Riffer::Skills::Context?) -> Riffer::Skills::Context?
   def skills=: (Riffer::Skills::Context?) -> Riffer::Skills::Context?
 
-  # The cumulative +Riffer::Providers::TokenUsage+ across every Run on this agent,
-  # or +nil+ before the first response is recorded.
-  #
+  # Cumulative across every run on this agent.
   # --
   # : () -> Riffer::Providers::TokenUsage?
   def token_usage: () -> Riffer::Providers::TokenUsage?
 
-  # Sets the cumulative token usage. Raises Riffer::ArgumentError on an invalid
-  # value.
   # --
   # : (Riffer::Providers::TokenUsage?) -> Riffer::Providers::TokenUsage?
   def token_usage=: (Riffer::Providers::TokenUsage?) -> Riffer::Providers::TokenUsage?
 
-  # Hash-style read, preserved so tools can pull caller-provided keys via
-  # <tt>context[:agent]</tt>.
   # --
   # : (Symbol) -> untyped
   def []: (Symbol) -> untyped
 
-  # Auth-wrapped MCP tool classes for progressive discovery, or +nil+.
   # --
   # : () -> Array[singleton(Riffer::Tool)]?
   def mcp_progressive_tools: () -> Array[singleton(Riffer::Tool)]?
 
-  # Sets progressive MCP tools. Raises Riffer::ArgumentError on an invalid value.
   # --
   # : (Array[singleton(Riffer::Tool)]?) -> Array[singleton(Riffer::Tool)]?
   def mcp_progressive_tools=: (Array[singleton(Riffer::Tool)]?) -> Array[singleton(Riffer::Tool)]?
 
-  # MCP tool classes discovered during progressive search. Accumulates across
-  # +generate+ calls and is merged into the active tool list on every LLM call.
   # --
   # : () -> Array[singleton(Riffer::Tool)]?
   def discovered_tools: () -> Array[singleton(Riffer::Tool)]?
 
-  # Sets the discovered tools array. Raises Riffer::ArgumentError on an invalid value.
   # --
   # : (Array[singleton(Riffer::Tool)]?) -> Array[singleton(Riffer::Tool)]?
   def discovered_tools=: (Array[singleton(Riffer::Tool)]?) -> Array[singleton(Riffer::Tool)]?
 
-  # Accumulates newly discovered MCP tool classes, deduplicating by name.
-  # Each call extends the existing set; calling multiple times is safe.
   # --
   # : (Array[singleton(Riffer::Tool)]) -> Array[singleton(Riffer::Tool)]
   def discover_tools: (Array[singleton(Riffer::Tool)]) -> Array[singleton(Riffer::Tool)]
@@ -77,8 +55,6 @@ class Riffer::Agent::Context
   # : (*Symbol) -> untyped
   def dig: (*Symbol) -> untyped
 
-  # Returns a copy of the underlying Hash; mutating it does not affect this
-  # context.
   # --
   # : () -> Hash[Symbol, untyped]
   def to_h: () -> Hash[Symbol, untyped]