riffer 0.30.0 → 0.32.0

data/lib/riffer/tools/toolable.rb

@@ -1,16 +1,9 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Riffer::Tools::Toolable provides the shared class-level DSL for anything that can
-# present as a tool to an LLM — tools today, and subagents/workflows in the
-# future.
-#
-# Extend this module to make a class discoverable as a tool by LLM providers.
-# Provides identifier, description, params, timeout, and JSON schema
-# generation.
-#
-# Instance-level execution concerns (+call+, +call_with_validation+, etc.)
-# are NOT part of Toolable — those belong on Riffer::Tool.
+# 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
@@ -37,7 +30,6 @@ module Riffer::Tools::Toolable
   #--
   #: (Module) -> void
   def self.extended(base)
-    base.extend Riffer::Helpers::ClassNameConverter
     extenders = (@extenders ||= []) #: Array[Module]
     extenders << base
   end
@@ -64,7 +56,7 @@ module Riffer::Tools::Toolable
   #--
   #: (?String?) -> String
   def identifier(value = nil)
-    return @identifier || class_name_to_path(Module.instance_method(:name).bind_call(self)) if value.nil?
+    return @identifier || Riffer::Helpers::ClassNameConverter.convert(Module.instance_method(:name).bind_call(self)) if value.nil?
     @identifier = value.to_s
   end
 
@@ -105,10 +97,7 @@ module Riffer::Tools::Toolable
     @params_builder&.to_json_schema(strict: strict) || empty_schema
   end
 
-  # Returns the kind of toolable entity.
-  #
-  # Defaults to +:tool+. Extensible to +:agent+, +:workflow+, etc.
-  #
+  # Returns the kind of toolable entity; defaults to +:tool+.
   #--
   #: (?Symbol?) -> Symbol
   def kind(value = nil)

data/lib/riffer/tools.rb

@@ -1,9 +1,5 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Namespace for tool-related classes in the Riffer framework.
-#
-# Contains:
-# - Riffer::Tools::Response - Required return type for tool execution
 module Riffer::Tools
 end

data/lib/riffer/version.rb

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

data/lib/riffer.rb

@@ -4,10 +4,6 @@
 require "zeitwerk"
 
 # Riffer is the main module for the Riffer AI framework.
-#
-# Provides configuration, error classes, and versioning for the gem.
-#
-# See Riffer::Config, Riffer::Agent, Riffer::Providers, and Riffer::Messages.
 loader = Zeitwerk::Loader.for_gem
 loader.inflector.inflect(
   "open_ai" => "OpenAI",
@@ -17,7 +13,9 @@ loader.inflector.inflect(
 loader.setup
 
 module Riffer
-  # @rbs self.@config: Riffer::Config?
+  extend self
+
+  # @rbs @config: Riffer::Config?
 
   # Base error class for Riffer.
   class Error < StandardError; end
@@ -38,7 +36,7 @@ module Riffer
   #
   #--
   #: () -> Riffer::Config
-  def self.config
+  def config
     @config ||= Config.new
   end
 
@@ -50,13 +48,14 @@ module Riffer
   #
   #--
   #: () ?{ (Riffer::Config) -> void } -> void
-  def self.configure(&block)
+  def configure(&block)
     yield config if block_given?
   end
 
+  # Returns the gem version.
   #--
   #: () -> String
-  def self.version
+  def version
     VERSION
   end
 end

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

@@ -1,88 +1,76 @@
 # Generated from lib/riffer/agent/config.rb with RBS::Inline
 
 # Typed configuration object holding every class-level DSL setting on a
-# Riffer::Agent subclass.
-#
-# Each subclass of Riffer::Agent owns one Config, accessible via the class
-# method <tt>config</tt>. The class-level DSL (+model+, +instructions+, +uses_tools+,
-# etc.) reads and mutates this Config in place. Append-style DSL methods
-# (+use_mcp+, +guardrail+) are handled by the +add_mcp+ and +add_guardrail+
-# helpers below.
-#
-# Config stores Procs unresolved. Per-instance resolution happens elsewhere
-# (instructions, model, tools, tool runtime, skills).
+# Riffer::Agent subclass. Procs are stored unresolved and resolved per-instance
+# later.
 class Riffer::Agent::Config
   DEFAULT_MAX_STEPS: Integer
 
+  # 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 the provider client.
   attr_accessor provider_options: Hash[Symbol, untyped]
 
+  # 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 tool runtime.
   attr_reader tool_runtime: singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc
 
+  # 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. All fields are optional; unset fields take the
-  # documented defaults.
-  #
-  # Raises Riffer::ArgumentError if +model+ or +instructions+ is provided
-  # as a non-String, non-Proc value (or as an empty String).
-  #
+  # 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)?, ?provider_options: Hash[Symbol, untyped], ?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)?, ?provider_options: Hash[Symbol, untyped], ?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+. Accepts +nil+ or any value, coerced to String.
-  #
+  # Sets +identifier+, coercing the value to String.
   # --
   # : (untyped) -> String?
   def identifier=: (untyped) -> String?
 
-  # Sets +structured_output+. Accepts a Riffer::Params instance or +nil+.
-  #
-  # Raises Riffer::ArgumentError on any other type.
-  #
+  # Sets +structured_output+. Raises Riffer::ArgumentError on an invalid value.
   # --
   # : (Riffer::Params?) -> Riffer::Params?
   def structured_output=: (Riffer::Params?) -> Riffer::Params?
 
-  # Sets +tool_runtime+. Accepts a Riffer::Tools::Runtime subclass, a
-  # Riffer::Tools::Runtime instance, or a Proc.
-  #
-  # Raises Riffer::ArgumentError on any other type.
-  #
+  # 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+. Accepts a String ("provider/model"), a Proc, or +nil+.
-  #
-  # Raises Riffer::ArgumentError on non-String, non-Proc, or empty-String values.
-  #
+  # 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+. Accepts a String, a Proc, or +nil+.
-  #
-  # Raises Riffer::ArgumentError on non-String, non-Proc, or empty-String values.
-  #
+  # Sets +instructions+. Raises Riffer::ArgumentError on an invalid value (e.g.
+  # an empty string).
   # --
   # : ((String | Proc)?) -> (String | Proc)?
   def instructions=: ((String | Proc)?) -> (String | Proc)?
@@ -90,18 +78,12 @@ class Riffer::Agent::Config
   # Appends an MCP tag entry to +mcp_configs+.
   #
   # --
-  # : (String | Symbol) -> Array[Hash[Symbol, untyped]]
-  def add_mcp: (String | Symbol) -> Array[Hash[Symbol, untyped]]
+  # : (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.
-  #
-  # [phase] +:before+, +:after+, or +:around+. +:around+ appends to both
-  #   +:before+ and +:after+.
-  # [klass] the Riffer::Guardrail subclass to register.
-  # [options] options forwarded to the guardrail at runtime.
-  #
-  # Raises Riffer::ArgumentError on an invalid phase or non-Guardrail class.
-  #
+  # 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
@@ -114,6 +96,7 @@ class Riffer::Agent::Config
 
   private
 
+  # --
   # : (untyped, String) -> void
   def validate_string_or_proc!: (untyped, String) -> void
 end

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

@@ -1,36 +1,15 @@
 # Generated from lib/riffer/agent/context.rb with RBS::Inline
 
-# Typed value object wrapping the runtime context Hash held by a
-# Riffer::Agent. Exposes first-class accessors for the framework-managed
-# entries — +skills+ and +token_usage+ — and preserves +#[]+ / +#dig+
-# reads so tools (which receive +context:+ as a keyword) keep working
-# with both built-in and caller-provided keys.
-#
-# Reserved keys (+:skills+, +:token_usage+) cannot be set by the caller
-# at construction; they are owned by Riffer and written through the typed
-# setters. Type invariants are enforced on write — +skills+ must be a
-# +Riffer::Skills::Context+ (or nil); +token_usage+ must be a
-# +Riffer::Providers::TokenUsage+ (or nil).
-#
-#   context = Riffer::Agent::Context.new(user_id: 42)
-#   context[:user_id]    # => 42
-#   context.skills       # => nil
-#   context.token_usage  # => nil
+# 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]
 
-  # Keys reserved for framework use. Passing any of these to the
-  # constructor raises +Riffer::ArgumentError+.
   RESERVED_KEYS: Array[Symbol]
 
-  # Builds a new context.
-  #
-  # [data] caller-provided Hash passed as <tt>Agent.new(context:)</tt>.
-  #        Duped before storage so caller mutations do not affect the
-  #        agent. Must not contain any +RESERVED_KEYS+.
-  #
-  # Raises Riffer::ArgumentError when +data+ contains a reserved key.
-  #
+  # 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.
   # --
   # : (?Hash[Symbol, untyped]) -> void
   def initialize: (?Hash[Symbol, untyped]) -> void
@@ -42,12 +21,8 @@ class Riffer::Agent::Context
   # : () -> Riffer::Skills::Context?
   def skills: () -> Riffer::Skills::Context?
 
-  # Sets the resolved skills context. Called once by +Riffer::Agent+
-  # during construction.
-  #
-  # Raises Riffer::ArgumentError if +value+ is neither +nil+ nor a
-  # +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?
@@ -59,34 +34,51 @@ class Riffer::Agent::Context
   # : () -> Riffer::Providers::TokenUsage?
   def token_usage: () -> Riffer::Providers::TokenUsage?
 
-  # Sets the cumulative token usage. Called by +Riffer::Agent::Run+ after
-  # each LLM response.
-  #
-  # Raises Riffer::ArgumentError if +value+ is neither +nil+ nor a
-  # +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 downstream tool runtimes pulling
-  # caller-provided keys via <tt>context[:agent]</tt> or
-  # <tt>context[:tenant]</tt> keep working unchanged.
-  #
+  # Hash-style read, preserved so tools can pull caller-provided keys via
+  # <tt>context[:agent]</tt>.
   # --
   # : (Symbol) -> untyped
   def []: (Symbol) -> untyped
 
-  # Hash-style dig. Preserved for tools using
-  # <tt>context&.dig(:user_id)</tt>.
-  #
+  # 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)]
+
   # --
   # : (*Symbol) -> untyped
   def dig: (*Symbol) -> untyped
 
-  # Returns a copy of the underlying Hash. Mutating the result does not
-  # affect this context.
-  #
+  # Returns a copy of the underlying Hash; mutating it does not affect this
+  # context.
   # --
   # : () -> Hash[Symbol, untyped]
   def to_h: () -> Hash[Symbol, untyped]

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

@@ -1,9 +1,7 @@
 # Generated from lib/riffer/agent/response.rb with RBS::Inline
 
-# Wraps agent generation responses with optional tripwire information.
-#
-# When guardrails block execution, the response will contain a tripwire
-# with details about the block. The content will be empty for blocked responses.
+# Wraps an agent generation response. When a guardrail blocks execution,
+# +content+ is empty and +tripwire+ carries the block details.
 #
 #   response = agent.generate("Hello")
 #   if response.blocked?
@@ -32,24 +30,10 @@ class Riffer::Agent::Response
   # The full message history from the agent conversation.
   attr_reader messages: Array[Riffer::Messages::Base]
 
-  # Call ids of tool_use blocks that riffer filled with placeholder
-  # results during this turn — populated when an interrupt left them
-  # unanswered and +Riffer.config.experimental_history_healing+ is on.
-  # Empty otherwise.
+  # Call ids of tool_use blocks riffer filled with placeholder results this
+  # turn (when an interrupt left them unanswered and history healing is on).
   attr_reader healed_tool_call_ids: Array[String]
 
-  # Creates a new response.
-  #
-  # [content] the response content.
-  # [tripwire] optional tripwire for blocked responses.
-  # [modifications] guardrail modifications applied during processing.
-  # [interrupted] whether the agent loop was interrupted by a callback.
-  # [interrupt_reason] optional reason passed via <tt>throw :riffer_interrupt, reason</tt>.
-  # [structured_output] parsed structured output when structured output is configured.
-  # [messages] the full message history from the agent conversation.
-  # [healed_tool_call_ids] call ids filled with placeholder tool results
-  #   when history healing is enabled.
-  #
   # --
   # : (String, ?tripwire: Riffer::Guardrails::Tripwire?, ?modifications: Array[Riffer::Guardrails::Modification], ?interrupted: bool, ?interrupt_reason: (String | Symbol)?, ?structured_output: Hash[Symbol, untyped]?, ?messages: Array[Riffer::Messages::Base], ?healed_tool_call_ids: Array[String]) -> void
   def initialize: (String, ?tripwire: Riffer::Guardrails::Tripwire?, ?modifications: Array[Riffer::Guardrails::Modification], ?interrupted: bool, ?interrupt_reason: (String | Symbol)?, ?structured_output: Hash[Symbol, untyped]?, ?messages: Array[Riffer::Messages::Base], ?healed_tool_call_ids: Array[String]) -> void

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

@@ -1,21 +1,8 @@
 # Generated from lib/riffer/agent/run.rb with RBS::Inline
 
-# Riffer::Agent::Run is the generation loop. A pure module of functions over an
-# +agent+ — Agent owns every per-call value (provider, model, tools, tool
-# runtime, structured output, session, context); Run just orchestrates.
-#
-# Tools and user code see the agent's +context+ (a +Riffer::Agent::Context+)
-# unchanged through the loop, so downstream tool runtimes can read
-# caller-provided keys via <tt>context[:agent]</tt> /
-# <tt>context.dig(:key)</tt>, or the framework built-ins via
-# +context.skills+. Cumulative token usage is updated into
-# +agent.context.token_usage+ as the loop progresses.
-#
-#   Riffer::Agent::Run.generate(agent: my_agent, prompt: "Hello")
-#   Riffer::Agent::Run.stream(agent: my_agent, prompt: "Hello")
+# The generation loop — a pure module of functions over an +agent+, which owns
+# every per-call value; Run just orchestrates.
 module Riffer::Agent::Run
-  include Riffer::Messages::Converter
-
   # Runs the generate loop for the given agent. See Riffer::Agent#generate
   # for prompt/files semantics.
   #
@@ -32,43 +19,22 @@ module Riffer::Agent::Run
 
   private
 
-  # The generation loop. When +stream_yielder+ is provided, per-step events are
-  # pushed to it (and +stream+ discards the return value). When +stream_yielder+
-  # is +nil+, no events are emitted and +generate+ returns the Response
-  # directly. The two modes share every step of the loop — the only
-  # divergences are the LLM call shape (atomic vs. accumulated stream)
-  # and whether per-step events are emitted.
-  #
   # --
   # : (Riffer::Agent, ?stream_yielder: Enumerator::Yielder?) -> Riffer::Agent::Response
   def run_loop: (Riffer::Agent, ?stream_yielder: Enumerator::Yielder?) -> Riffer::Agent::Response
 
-  # Consumes one provider stream, forwarding every event to +stream_yielder+
-  # and folding it into an +Assistant+ message.
-  #
   # --
   # : (Riffer::Agent, Enumerator::Yielder) -> Riffer::Messages::Assistant
   def accumulate_streamed_response: (Riffer::Agent, Enumerator::Yielder) -> Riffer::Messages::Assistant
 
-  # Appends +new_modifications+ to +all_modifications+ and emits a
-  # +GuardrailModification+ event for each one when streaming.
-  #
   # --
   # : (Enumerator::Yielder?, Array[Riffer::Guardrails::Modification], Array[Riffer::Guardrails::Modification]) -> void
   def record_modifications!: (Enumerator::Yielder?, Array[Riffer::Guardrails::Modification], Array[Riffer::Guardrails::Modification]) -> void
 
-  # Emits a +GuardrailTripwire+ event when streaming and returns the
-  # short-circuit +Response+ for a tripped guardrail.
-  #
   # --
   # : (Riffer::Agent, Enumerator::Yielder?, Riffer::Guardrails::Tripwire, Array[Riffer::Guardrails::Modification]) -> Riffer::Agent::Response
   def tripwire_response: (Riffer::Agent, Enumerator::Yielder?, Riffer::Guardrails::Tripwire, Array[Riffer::Guardrails::Modification]) -> Riffer::Agent::Response
 
-  # Builds the final +Response+ from the session's last assistant
-  # message, validating structured output when configured. +extra+
-  # carries the interrupt-only fields (+interrupted:+, +interrupt_reason:+,
-  # +healed_tool_call_ids:+) on the interrupt exit path.
-  #
   # --
   # : (Riffer::Agent, Array[Riffer::Guardrails::Modification], **untyped) -> Riffer::Agent::Response
   def final_response: (Riffer::Agent, Array[Riffer::Guardrails::Modification], **untyped) -> Riffer::Agent::Response
@@ -85,31 +51,18 @@ module Riffer::Agent::Run
   # : (Riffer::Agent, Riffer::Messages::Assistant, ?tool_calls: Array[Riffer::Messages::Assistant::ToolCall]) -> void
   def execute_tool_calls: (Riffer::Agent, Riffer::Messages::Assistant, ?tool_calls: Array[Riffer::Messages::Assistant::ToolCall]) -> void
 
-  # Executes tool calls left unfinished by a prior interrupt.
-  #
-  # Detects gaps between the last assistant message's requested tool calls
-  # and the tool result messages that follow it, executing any that are
-  # missing. Safe to call unconditionally.
-  #
+  # --
+  # : (Riffer::Agent, Array[[Riffer::Messages::Assistant::ToolCall, Riffer::Tools::Response]]) -> void
+  def inject_discovered_tools: (Riffer::Agent, Array[[ Riffer::Messages::Assistant::ToolCall, Riffer::Tools::Response ]]) -> void
+
   # --
   # : (Riffer::Agent) -> void
   def execute_pending_tool_calls: (Riffer::Agent) -> void
 
-  # Runs the +:before+ guardrail phase. Records any modifications into
-  # +all_modifications+ (and emits them when streaming). When a tripwire
-  # fires, yields the short-circuit +Response+ — the caller's block is
-  # expected to +return+ it from +run_loop+.
-  #
   # --
   # : (Riffer::Agent, Enumerator::Yielder?, Array[Riffer::Guardrails::Modification]) { (Riffer::Agent::Response) -> void } -> void
   def run_before_guardrails: (Riffer::Agent, Enumerator::Yielder?, Array[Riffer::Guardrails::Modification]) { (Riffer::Agent::Response) -> void } -> void
 
-  # Runs the +:after+ guardrail phase against the assistant +response+.
-  # Records any modifications into +all_modifications+ (and emits them
-  # when streaming). When a tripwire fires, yields the short-circuit
-  # +Response+ — the caller's block is expected to +return+ it from
-  # +run_loop+. Otherwise returns the post-guardrails assistant message.
-  #
   # --
   # : (Riffer::Agent, Riffer::Messages::Assistant, Enumerator::Yielder?, Array[Riffer::Guardrails::Modification]) { (Riffer::Agent::Response) -> void } -> untyped
   def run_after_guardrails: (Riffer::Agent, Riffer::Messages::Assistant, Enumerator::Yielder?, Array[Riffer::Guardrails::Modification]) { (Riffer::Agent::Response) -> void } -> untyped
@@ -118,6 +71,10 @@ module Riffer::Agent::Run
   # : (Riffer::Agent, Riffer::Messages::Assistant?) -> Hash[Symbol, untyped]?
   def validate_structured_output: (Riffer::Agent, Riffer::Messages::Assistant?) -> Hash[Symbol, untyped]?
 
+  # --
+  # : (Riffer::Agent) -> Array[singleton(Riffer::Tool)]
+  def effective_tools: (Riffer::Agent) -> Array[singleton(Riffer::Tool)]
+
   # --
   # : (Riffer::Agent) -> Hash[Symbol, untyped]
   def merged_model_options: (Riffer::Agent) -> Hash[Symbol, untyped]
@@ -126,18 +83,12 @@ module Riffer::Agent::Run
   # : (Riffer::Agent, String, ?tripwire: Riffer::Guardrails::Tripwire?, ?modifications: Array[Riffer::Guardrails::Modification], ?interrupted: bool, ?interrupt_reason: (String | Symbol)?, ?structured_output: Hash[Symbol, untyped]?, ?healed_tool_call_ids: Array[String]) -> Riffer::Agent::Response
   def build_response: (Riffer::Agent, String, ?tripwire: Riffer::Guardrails::Tripwire?, ?modifications: Array[Riffer::Guardrails::Modification], ?interrupted: bool, ?interrupt_reason: (String | Symbol)?, ?structured_output: Hash[Symbol, untyped]?, ?healed_tool_call_ids: Array[String]) -> Riffer::Agent::Response
 
-  # Appends a +User+ message to the session. No-ops when +prompt+ is nil
-  # and +files+ is empty (the caller had nothing to add). Raises when
-  # +files+ are supplied without a +prompt+ — the provider needs text to
-  # anchor the attachments.
-  #
+  # Raises when +files+ are supplied without a +prompt+ — the provider needs
+  # text to anchor the attachments.
   # --
   # : (Riffer::Agent, String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?) -> void
   def append_user_message: (Riffer::Agent, String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?) -> void
 
-  # Accumulates token usage into +agent.context.token_usage+. Updates the
-  # context so cumulative usage persists across every run on the agent.
-  #
   # --
   # : (Riffer::Agent, Riffer::Providers::TokenUsage?) -> void
   def track_token_usage: (Riffer::Agent, Riffer::Providers::TokenUsage?) -> void