riffer 0.30.0 → 0.32.0

data/sig/generated/riffer/agent.rbs

@@ -1,11 +1,7 @@
 # Generated from lib/riffer/agent.rb with RBS::Inline
 
-# Riffer::Agent is the base class for all agents in the Riffer framework.
-#
-# Provides orchestration for LLM calls, tool use, and message management.
-# Subclass this to create your own agents.
-#
-# See Riffer::Messages and Riffer::Providers.
+# Base class for all agents in the Riffer framework. Subclass it to define an
+# agent's model, instructions, tools, and guardrails.
 #
 #   class MyAgent < Riffer::Agent
 #     model 'openai/gpt-4o'
@@ -17,15 +13,9 @@
 class Riffer::Agent
   self.@config: Riffer::Agent::Config?
 
-  include Riffer::Messages::Converter
-
-  extend Riffer::Helpers::ClassNameConverter
-
   INTERRUPT_MAX_STEPS: Symbol
 
-  # Returns the per-class Riffer::Agent::Config value object holding every
-  # DSL setting. Lazily initialized on first read; each subclass has its own.
-  #
+  # Returns the per-class Riffer::Agent::Config holding every DSL setting.
   # --
   # : () -> Riffer::Agent::Config
   def self.config: () -> Riffer::Agent::Config
@@ -36,16 +26,13 @@ class Riffer::Agent
   # : (?String?) -> String
   def self.identifier: (?String?) -> String
 
-  # Gets or sets the model string (e.g., "openai/gpt-4o") or Proc.
+  # Gets or sets the model string (e.g., "openai/gpt-4o").
   #
   # --
   # : (?(String | Proc)?) -> (String | Proc)?
   def self.model: (?(String | Proc)?) -> (String | Proc)?
 
-  # Gets or sets the agent instructions.
-  #
-  # Accepts a static string or a Proc for dynamic instructions.
-  # When a Proc is given, it is called at generate time and receives
+  # Gets or sets the agent instructions. A Proc is called at generate time with
   # the +context+ hash (which may be +nil+).
   #
   #   instructions "You are a helpful assistant."
@@ -71,18 +58,13 @@ class Riffer::Agent
   def self.model_options: (?Hash[Symbol, untyped]?) -> Hash[Symbol, untyped]
 
   # Gets or sets the structured output schema for this agent.
-  #
-  # Accepts a Riffer::Params instance or a block evaluated against a new Params.
-  #
   # --
   # : (?Riffer::Params?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> Riffer::Params?
   def self.structured_output: (?Riffer::Params?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> Riffer::Params?
 
   # Gets or sets the maximum number of LLM call steps in the tool-use loop.
-  #
-  # Defaults to Riffer::Agent::Config::DEFAULT_MAX_STEPS (16). Set to +nil+
-  # for unlimited steps. The splat distinguishes a getter call (no argument)
-  # from setting the limit to +nil+.
+  # The splat distinguishes a getter (no argument) from setting the limit to
+  # +nil+ (unlimited); it defaults to Riffer::Agent::Config::DEFAULT_MAX_STEPS.
   #
   #   max_steps        # reads the current limit
   #   max_steps 8      # cap the loop at 8 steps
@@ -98,31 +80,25 @@ class Riffer::Agent
   # : (?(Array[singleton(Riffer::Tool)] | Proc)?) -> (Array[singleton(Riffer::Tool)] | Proc)?
   def self.uses_tools: (?(Array[singleton(Riffer::Tool)] | Proc)?) -> (Array[singleton(Riffer::Tool)] | Proc)?
 
-  # Opts this agent into tools from all MCP registrations that share any of
-  # the given tag(s).
+  # Opts this agent into MCP tools from registrations matching the given tag.
+  # Progressive registrations expose +mcp_search+ instead of every schema up front.
   #
-  # +tag+ - a String or Symbol; matched against registration manifest tags.
-  #
-  # : (String | Symbol) -> void
-  def self.use_mcp: (String | Symbol) -> void
+  # : (String | Symbol, ?progressive: bool) -> void
+  def self.use_mcp: (String | Symbol, ?progressive: bool) -> void
 
   # Returns the accumulated +use_mcp+ configurations for this agent class.
   #
   # : () -> Array[Hash[Symbol, untyped]]
   def self.mcp_configs: () -> Array[Hash[Symbol, untyped]]
 
-  # Gets or sets the tool runtime for this agent.
-  #
-  # Accepts a Riffer::Tools::Runtime subclass, a Riffer::Tools::Runtime instance,
-  # or a Proc. Defaults to <tt>Riffer.config.tool_runtime</tt> when unset.
-  #
+  # Gets or sets the tool runtime for this agent; defaults to
+  # <tt>Riffer.config.tool_runtime</tt> when unset.
   # --
   # : (?(singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)?) -> (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)
   def self.tool_runtime: (?(singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)?) -> (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)
 
-  # Configures skills for this agent via a block DSL.
-  #
-  # Returns the current Riffer::Skills::Config when called without a block.
+  # Configures skills for this agent via a block DSL, or returns the current
+  # Riffer::Skills::Config when called without a block.
   #
   #   skills do
   #     backend Riffer::Skills::FilesystemBackend.new(".skills")
@@ -147,139 +123,84 @@ class Riffer::Agent
   def self.all: () -> Array[singleton(Riffer::Agent)]
 
   # Generates a response using a new agent instance.
-  #
-  # +context:+ is threaded into +new+; +prompt+ and +files:+ are forwarded
-  # to +#generate+.
-  #
   # --
   # : (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?context: Hash[Symbol, untyped]?) -> Riffer::Agent::Response
   def self.generate: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?context: Hash[Symbol, untyped]?) -> Riffer::Agent::Response
 
   # Streams a response using a new agent instance.
-  #
-  # +context:+ is threaded into +new+; +prompt+ and +files:+ are forwarded
-  # to +#stream+.
-  #
   # --
   # : (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?context: Hash[Symbol, untyped]?) -> Enumerator[Riffer::StreamEvents::Base, void]
   def self.stream: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?context: Hash[Symbol, untyped]?) -> Enumerator[Riffer::StreamEvents::Base, void]
 
-  # Reconstructs a runnable agent from a wire dict produced by +#to_h+.
-  #
-  # Delegates to Riffer::Agent::Serializer.from_h. See it for the
-  # +tool_resolver+ / +tool_runtime+ injection points and what does not
-  # transfer.
-  #
+  # Reconstructs a runnable agent from a wire hash produced by +#to_h+.
   # --
-  # : (Hash[Symbol, untyped], ?context: Hash[Symbol, untyped]?, ?tool_resolver: ^(Hash[Symbol, untyped]) -> singleton(Riffer::Tool), ?tool_runtime: (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)?) -> Riffer::Agent
-  def self.from_h: (Hash[Symbol, untyped], ?context: Hash[Symbol, untyped]?, ?tool_resolver: ^(Hash[Symbol, untyped]) -> singleton(Riffer::Tool), ?tool_runtime: (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)?) -> Riffer::Agent
+  # : (Hash[Symbol, untyped], ?context: Hash[Symbol, untyped]?, ?session: Riffer::Agent::Session?, ?tool_resolver: ^(Hash[Symbol, untyped]) -> singleton(Riffer::Tool), ?tool_runtime: (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)?) -> Riffer::Agent
+  def self.from_h: (Hash[Symbol, untyped], ?context: Hash[Symbol, untyped]?, ?session: Riffer::Agent::Session?, ?tool_resolver: ^(Hash[Symbol, untyped]) -> singleton(Riffer::Tool), ?tool_runtime: (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)?) -> Riffer::Agent
 
   # Reconstructs a runnable agent from a JSON string produced by +#to_json+.
-  #
-  # Delegates to Riffer::Agent::Serializer.from_json, which parses the JSON
-  # (with symbol keys) for you. See Riffer::Agent::Serializer.from_h for the
-  # +tool_resolver+ / +tool_runtime+ injection points.
-  #
   # --
-  # : (String, ?context: Hash[Symbol, untyped]?, ?tool_resolver: ^(Hash[Symbol, untyped]) -> singleton(Riffer::Tool), ?tool_runtime: (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)?) -> Riffer::Agent
-  def self.from_json: (String, ?context: Hash[Symbol, untyped]?, ?tool_resolver: ^(Hash[Symbol, untyped]) -> singleton(Riffer::Tool), ?tool_runtime: (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)?) -> Riffer::Agent
+  # : (String, ?context: Hash[Symbol, untyped]?, ?session: Riffer::Agent::Session?, ?tool_resolver: ^(Hash[Symbol, untyped]) -> singleton(Riffer::Tool), ?tool_runtime: (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)?) -> Riffer::Agent
+  def self.from_json: (String, ?context: Hash[Symbol, untyped]?, ?session: Riffer::Agent::Session?, ?tool_resolver: ^(Hash[Symbol, untyped]) -> singleton(Riffer::Tool), ?tool_runtime: (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)?) -> Riffer::Agent
 
-  # Registers a guardrail for input, output, or both phases.
-  #
-  # [phase] :before, :after, or :around.
-  # [with] the guardrail class (must be subclass of Riffer::Guardrail).
-  # [options] additional options passed to the guardrail.
-  #
-  # Raises Riffer::ArgumentError if phase is invalid or guardrail is not a Guardrail class.
+  # Registers a guardrail for input, output, or both phases. Raises
+  # Riffer::ArgumentError unless +phase+ is :before, :after, or :around.
   # --
   # : (Symbol, with: singleton(Riffer::Guardrail), **untyped) -> void
   def self.guardrail: (Symbol, with: singleton(Riffer::Guardrail), **untyped) -> void
 
   # Returns the registered guardrail configs for a given phase.
-  #
-  # [phase] :before or :after.
-  #
   # --
   # : (Symbol) -> Array[Hash[Symbol, untyped]]
   def self.guardrails_for: (Symbol) -> Array[Hash[Symbol, untyped]]
 
-  # The conversation handle. See Riffer::Agent::Session.
+  # The conversation handle.
   attr_reader session: Riffer::Agent::Session
 
-  # The per-instance Riffer::Agent::Config. Either the class-level default or
-  # an explicit Config passed to +Agent.new(config:)+.
+  # The per-instance Riffer::Agent::Config.
   attr_reader config: Riffer::Agent::Config
 
-  # The system message built from the configured +instructions+, or +nil+
-  # when no instructions are configured. Built once at +Agent.new+ using the
-  # constructor +context:+ and cached. Useful for persistence flows.
+  # The system message built from the configured +instructions+, or +nil+ when
+  # none are configured.
   attr_reader instruction_message: Riffer::Messages::System?
 
-  # The system message describing the configured skills catalog, or +nil+
-  # when skills are unconfigured or the catalog is empty. Built once at
-  # +Agent.new+ and cached.
+  # The system message describing the configured skills catalog, or +nil+ when
+  # skills are unconfigured or the catalog is empty.
   attr_reader skills_message: Riffer::Messages::System?
 
-  # The mutable runtime context, a +Riffer::Agent::Context+ value object
-  # threaded into every Proc-based DSL setting, guardrail, tool runtime,
-  # and skills resolution, and shared with every +Riffer::Agent::Run+
-  # this agent executes. Exposes:
-  #
-  # - +context.skills+ — the resolved +Riffer::Skills::Context+ (when
-  #   skills are configured), set at +Agent.new+ time.
-  # - +context.token_usage+ — the cumulative +Riffer::Providers::TokenUsage+,
-  #   updated by each Run as the loop progresses.
-  # - +context[:key]+ / <tt>context.dig(:key)</tt> — Hash-style reads for
-  #   caller-provided keys (e.g. <tt>context[:agent]</tt>,
-  #   <tt>context[:tenant]</tt>). +:skills+ and +:token_usage+ are
-  #   reserved and cannot be passed by the caller.
+  # The mutable runtime context shared with every +Riffer::Agent::Run+ this
+  # agent executes and threaded through all Proc-based settings.
   attr_reader context: Riffer::Agent::Context
 
-  # The resolved provider name (the part before "provider/"), e.g. +"openai"+.
-  # Resolved eagerly at +Agent.new+ alongside +model_name+; together they
-  # form the provider-neutral model identifier the agent serializes.
+  # The resolved provider name (the part before "/" in the model string),
+  # e.g. +"openai"+.
   attr_reader provider_name: String
 
-  # The resolved model name (the part after "provider/"), used as the model
-  # argument on every LLM call. Resolved eagerly at +Agent.new+.
+  # The resolved model name (the part after "/" in the model string), used as
+  # the model argument on every LLM call.
   attr_reader model_name: String
 
-  # The provider client. Built eagerly at +Agent.new+ from the configured
-  # provider class and +Config#provider_options+, then handed to every
-  # +Riffer::Agent::Run+ this agent executes. Public so tests can pre-queue
-  # responses on +Riffer::Providers::Mock+ before calling +#generate+.
+  # The provider client. Public so tests can pre-queue responses on
+  # +Riffer::Providers::Mock+ before calling +#generate+.
   attr_reader provider: Riffer::Providers::Base
 
-  # The +Riffer::Agent::StructuredOutput+ wrapping the configured schema, or +nil+
-  # when structured output is not configured. Resolved eagerly at +Agent.new+.
+  # The +Riffer::Agent::StructuredOutput+ wrapping the configured schema, or
+  # +nil+ when not configured.
   attr_reader structured_output: Riffer::Agent::StructuredOutput?
 
-  # The tool classes the LLM sees on every call this agent makes. Resolved
-  # eagerly at +Agent.new+ (Proc-form +uses_tools+ is called against
-  # +context+ once; MCP tools and the skill_activate tool are merged in).
+  # The tool classes the LLM sees on every call this agent makes.
   attr_reader tools: Array[singleton(Riffer::Tool)]
 
-  # The tool runtime instance used to execute tool calls. Resolved eagerly
-  # at +Agent.new+ (Proc-form +tool_runtime+ is called against +context+ once).
+  # The tool runtime instance used to execute tool calls.
   attr_reader tool_runtime: Riffer::Tools::Runtime
 
   # Initializes a new agent.
   #
-  # When +session:+ is omitted, a fresh +Riffer::Agent::Session+ is built and seeded
-  # with the system instruction message and skills catalog (when configured),
-  # using +context:+. When +session:+ is provided, the agent uses it as-is —
-  # the caller is responsible for the session's contents (typical use case:
-  # cross-process resume from persisted history). With
-  # +Riffer.config.experimental_history_healing+ on, a provided session is
-  # healed at construction time so the +tool_use+ ↔ +tool_result+ invariant
-  # holds before the next inference call.
-  #
-  # +context:+ flows through Proc-based instructions, model, skills resolution,
-  # tool resolution, guardrails, and tool runtime. It is fixed for the
-  # lifetime of the agent.
+  # A provided +session:+ is used as-is — the caller owns its contents (e.g.
+  # cross-process resume from persisted history); an omitted one is seeded with
+  # the instruction and skills messages.
   #
-  # Raises Riffer::ArgumentError if the configured model string is invalid
-  # (must be "provider/model" format).
+  # Raises Riffer::ArgumentError unless the configured model string is
+  # "provider/model" format.
   #
   # --
   # : (?session: Riffer::Agent::Session?, ?context: Hash[Symbol, untyped]?, ?config: Riffer::Agent::Config?) -> void
@@ -287,60 +208,38 @@ class Riffer::Agent
 
   # Generates a response from the agent.
   #
-  # Runs the inference loop via +Riffer::Agent::Run.generate+. When +prompt+
-  # is given, a new +Riffer::Messages::User+ is appended to the session
-  # (silently — +on_message+ does not fire for user inputs) and then the
-  # loop runs. When +prompt+ is omitted, the loop runs against the current
-  # session — useful for resuming a persisted conversation whose last turn
-  # is already a user message, or for picking up pending tool calls after
-  # an interrupt.
-  #
-  # +files:+ requires +prompt+. Pass files to attach to the new user message.
+  # With +prompt+, a new user message is appended (silently — +on_message+ does
+  # not fire for user inputs) before the loop runs. Without it, the loop runs
+  # against the current session, resuming a persisted conversation or pending
+  # tool calls. +files:+ requires +prompt+.
   #
   # --
   # : (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?) -> Riffer::Agent::Response
   def generate: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?) -> Riffer::Agent::Response
 
-  # Streams a response from the agent.
-  #
-  # Runs the inference loop via +Riffer::Agent::Run.stream+, returning an
-  # +Enumerator+ of +Riffer::StreamEvents+.
+  # Streams a response from the agent, returning an +Enumerator+ of
+  # +Riffer::StreamEvents+. See +#generate+ for prompt/files semantics.
   #
   # Raises Riffer::ArgumentError if structured output is configured.
   #
-  # See +#generate+ for prompt/files semantics.
-  #
   # --
   # : (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?) -> Enumerator[Riffer::StreamEvents::Base, void]
   def stream: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?) -> Enumerator[Riffer::StreamEvents::Base, void]
 
-  # Interrupts the agent loop.
-  #
-  # Call from an +on_message+ callback to cleanly interrupt the loop.
-  # Equivalent to <tt>throw :riffer_interrupt, reason</tt>.
-  #
-  # When +Riffer.config.experimental_history_healing+ is enabled, riffer
-  # fills any orphaned +tool_use+ on the way out with a placeholder
-  # +Riffer::Messages::Tool+ carrying +error_type: :interrupted+. The
-  # filled call_ids are exposed on
-  # +Riffer::Agent::Response#healed_tool_call_ids+ (and the streaming
-  # +Riffer::StreamEvents::Interrupt+ event).
-  #
+  # Interrupts the agent loop from an +on_message+ callback. Equivalent to
+  # <tt>throw :riffer_interrupt, reason</tt>.
   # --
   # : (?(String | Symbol)?) -> void
   def interrupt!: (?(String | Symbol)?) -> void
 
-  # Snapshots this resolved agent into a self-contained, provider-neutral
-  # wire dict. Delegates to Riffer::Agent::Serializer.to_h.
-  #
+  # Snapshots this resolved agent into a self-contained, provider-neutral wire
+  # hash.
   # --
   # : () -> Hash[Symbol, untyped]
   def to_h: () -> Hash[Symbol, untyped]
 
-  # Snapshots this resolved agent into a wire JSON string. Delegates to
-  # Riffer::Agent::Serializer.to_json. The +*+ absorbs the JSON generator
-  # state argument so <tt>JSON.generate(agent)</tt> works too.
-  #
+  # Snapshots this resolved agent into a wire JSON string. The +*+ absorbs the
+  # JSON generator state argument so <tt>JSON.generate(agent)</tt> works too.
   # --
   # : (*untyped) -> String
   def to_json: (*untyped) -> String
@@ -355,28 +254,14 @@ class Riffer::Agent
   # : () -> Riffer::Messages::System?
   def build_skills_message: () -> Riffer::Messages::System?
 
-  # Resolves +Config#model+ to a "provider/model" string (calling the Proc
-  # form against +@context+) and parses it.
-  #
-  # Returns +[provider_name, model_name]+. Raises Riffer::ArgumentError on an
-  # invalid model string.
-  #
   # --
   # : () -> [String, String]
   def resolve_provider_and_model: () -> [ String, String ]
 
-  # Builds the provider client from the resolved +@provider_name+ and the
-  # configured +provider_options+.
-  #
-  # Raises Riffer::ArgumentError on an unregistered provider.
-  #
   # --
   # : () -> Riffer::Providers::Base
   def build_provider: () -> Riffer::Providers::Base
 
-  # Resolves the skills backend, lists skills, and selects an adapter.
-  # Returns nil if skills are unconfigured or the backend is empty.
-  #
   # --
   # : () -> Riffer::Skills::Context?
   def resolve_skills: () -> Riffer::Skills::Context?
@@ -385,19 +270,6 @@ class Riffer::Agent
   # : () -> Riffer::Agent::StructuredOutput?
   def resolve_structured_output: () -> Riffer::Agent::StructuredOutput?
 
-  # Resolves the full tool catalog for the agent:
-  #
-  # - The configured +uses_tools+ value (Proc-form resolved against +context+).
-  # - The skill activation tool, when a +skills+ block is configured. The
-  #   activation tool class comes from the per-agent +skills do; activate_tool ...; end+
-  #   override when set, otherwise from +Riffer.config.skills.default_activate_tool+.
-  # - All MCP tools matching any +use_mcp+ tag, optionally wrapped in
-  #   AuthenticatedTool when +Riffer.config.mcp.credentials+ is configured.
-  #
-  # Raises Riffer::ArgumentError on tool name conflicts with the skill
-  # activation tool, on duplicate tool names across sources, or on tool
-  # classes missing required metadata (description, params).
-  #
   # --
   # : () -> Array[singleton(Riffer::Tool)]
   def resolve_tools: () -> Array[singleton(Riffer::Tool)]
@@ -410,16 +282,15 @@ class Riffer::Agent
   # : () -> Array[singleton(Riffer::Tool)]
   def resolve_mcp_tool_classes: () -> Array[singleton(Riffer::Tool)]
 
-  # Each matching MCP registration once, with tag symbols unioned across +use_mcp+ rows.
-  #
-  # : (Array[Hash[Symbol, untyped]]) -> Hash[Riffer::Mcp::Registration, Array[Symbol]]
-  def gather_mcp_registrations_with_tags: (Array[Hash[Symbol, untyped]]) -> Hash[Riffer::Mcp::Registration, Array[Symbol]]
+  # --
+  # : (Array[Hash[Symbol, untyped]]) -> [Hash[Riffer::Mcp::Registration, Array[Symbol]], Hash[Riffer::Mcp::Registration, Array[Symbol]]]
+  def gather_mcp_registrations_with_tags: (Array[Hash[Symbol, untyped]]) -> [ Hash[Riffer::Mcp::Registration, Array[Symbol]], Hash[Riffer::Mcp::Registration, Array[Symbol]] ]
 
+  # --
   # : (Riffer::Mcp::Registration, Array[Symbol], (^(manifest: Riffer::Mcp::Manifest, matched_tags: Array[Symbol], context: Riffer::Agent::Context) -> Hash[Symbol, untyped]?)?, Riffer::Agent::Context) -> Array[singleton(Riffer::Tool)]
   def mcp_tools_for_registration: (Riffer::Mcp::Registration, Array[Symbol], (^(manifest: Riffer::Mcp::Manifest, matched_tags: Array[Symbol], context: Riffer::Agent::Context) -> Hash[Symbol, untyped]?)?, Riffer::Agent::Context) -> Array[singleton(Riffer::Tool)]
 
-  # Raises if two or more tool classes share the same +.name+ (ambiguous dispatch).
-  #
+  # --
   # : (Array[singleton(Riffer::Tool)]) -> void
   def assert_distinct_tool_names!: (Array[singleton(Riffer::Tool)]) -> void
 end

data/sig/generated/riffer/config.rbs

@@ -1,19 +1,6 @@
 # Generated from lib/riffer/config.rb with RBS::Inline
 
 # Configuration for the Riffer framework.
-#
-# Provides configuration options for AI providers and other settings.
-#
-#   Riffer.config.openai.api_key = "sk-..."
-#
-#   Riffer.config.amazon_bedrock.region = "us-east-1"
-#   Riffer.config.amazon_bedrock.api_token = "..."
-#
-#   Riffer.config.anthropic.api_key = "sk-ant-..."
-#
-#   Riffer.config.openrouter.api_key = "sk-or-..."
-#
-#   Riffer.config.evals.judge_model = "anthropic/claude-sonnet-4-20250514"
 class Riffer::Config
   class AmazonBedrock < Struct[untyped]
     attr_accessor api_token(): untyped
@@ -82,41 +69,27 @@ class Riffer::Config
   end
 
   # Skills-related global configuration.
-  #
-  # See <tt>Riffer.config.skills.default_activate_tool</tt> and
-  # <tt>Riffer.config.skills.default_backend</tt>.
   class Skills
-    # Default skill activation tool class.
-    #
-    # The tool class the LLM calls to activate a skill. Defaults to
-    # <tt>Riffer::Skills::ActivateTool</tt>. Per-agent override is available
-    # via <tt>skills do; activate_tool ...; end</tt>.
+    # The tool class the LLM calls to activate a skill; defaults to
+    # <tt>Riffer::Skills::ActivateTool</tt>.
     attr_reader default_activate_tool: singleton(Riffer::Tool)
 
-    # Default skills backend.
-    #
-    # Used by agents that declare a +skills+ block without specifying a
-    # backend. Accepts a Riffer::Skills::Backend instance or a Proc.
-    # Defaults to +nil+ (no global default).
+    # Default skills backend for agents that declare a +skills+ block without
+    # one; defaults to +nil+.
     attr_reader default_backend: (Riffer::Skills::Backend | Proc)?
 
     # --
     # : () -> void
     def initialize: () -> void
 
-    # Sets the default skill activation tool class.
-    #
-    # Raises +Riffer::ArgumentError+ if the value is not a Riffer::Tool subclass.
-    #
+    # Sets the default skill activation tool class. Raises Riffer::ArgumentError
+    # on an invalid value.
     # --
     # : (singleton(Riffer::Tool)) -> void
     def default_activate_tool=: (singleton(Riffer::Tool)) -> void
 
-    # Sets the default skills backend.
-    #
-    # Raises +Riffer::ArgumentError+ if the value is not a
-    # Riffer::Skills::Backend instance, a Proc, or +nil+.
-    #
+    # Sets the default skills backend. Raises Riffer::ArgumentError on an
+    # invalid value.
     # --
     # : ((Riffer::Skills::Backend | Proc)?) -> void
     def default_backend=: ((Riffer::Skills::Backend | Proc)?) -> void
@@ -124,103 +97,64 @@ class Riffer::Config
 
   VALID_MESSAGE_ID_STRATEGIES: untyped
 
-  # Amazon Bedrock configuration (Struct with +api_token+ and +region+).
+  # Amazon Bedrock configuration.
   attr_reader amazon_bedrock: Riffer::Config::AmazonBedrock
 
-  # Anthropic configuration (Struct with +api_key+).
+  # Anthropic configuration.
   attr_reader anthropic: Riffer::Config::Anthropic
 
-  # Azure OpenAI configuration (Struct with +api_key+ and +endpoint+).
+  # Azure OpenAI configuration.
   attr_reader azure_openai: Riffer::Config::AzureOpenAI
 
-  # Google Gemini configuration (Struct with +api_key+, +open_timeout+, and +read_timeout+).
+  # Google Gemini configuration.
   attr_reader gemini: Riffer::Config::Gemini
 
-  # OpenAI configuration (Struct with +api_key+).
+  # OpenAI configuration.
   attr_reader openai: Riffer::Config::OpenAI
 
-  # OpenRouter configuration (Struct with +api_key+).
+  # OpenRouter configuration.
   attr_reader openrouter: Riffer::Config::OpenRouter
 
-  # Evals configuration (Struct with +judge_model+).
+  # Evals configuration.
   attr_reader evals: Riffer::Config::Evals
 
-  # MCP configuration (Struct with +credentials+ and +discovery_runner+).
-  #
-  # +credentials+ is an optional Proc for per-run MCP +tools/call+ HTTP headers.
-  # Signature: +->(manifest:, matched_tags:, context:) { Hash or nil }+.
-  # +nil+ from the proc at tool-resolution time omits that server's tools; +nil+
-  # at tool-call time raises Riffer::Mcp::CredentialsDeniedError.
-  #
-  # +discovery_runner+ is the Riffer::Runner used to execute tool discovery
-  # (default +Runner::Sequential+).
+  # MCP configuration. +credentials+ is an optional Proc returning per-run
+  # +tools/call+ headers (or +nil+ to deny); +discovery_runner+ runs tool
+  # discovery.
   attr_reader mcp: Riffer::Config::Mcp
 
-  # Global tool runtime configuration (experimental).
-  #
-  # Accepts a Riffer::Tools::Runtime subclass, a Riffer::Tools::Runtime instance,
-  # or a Proc. Defaults to <tt>Riffer::Tools::Runtime::Inline.new</tt>.
+  # Global tool runtime configuration (experimental); defaults to
+  # <tt>Riffer::Tools::Runtime::Inline.new</tt>.
   attr_reader tool_runtime: singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc
 
-  # Sets the global tool runtime.
-  #
-  # Raises +Riffer::ArgumentError+ if the value is not a valid runtime
-  # (ToolRuntime subclass, ToolRuntime instance, or Proc).
-  #
+  # Sets the global tool runtime. Raises Riffer::ArgumentError on an invalid
+  # value.
   # --
   # : ((singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)) -> void
   def tool_runtime=: (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc) -> void
 
-  # Skills-related global configuration. Returns a Riffer::Config::Skills
-  # object — see <tt>Riffer.config.skills.default_activate_tool</tt>.
+  # Skills-related global configuration.
   attr_reader skills: Riffer::Config::Skills
 
-  # Strategy for auto-generating message ids. One of +:none+ (default, no id),
-  # +:uuid+ (UUIDv4), or +:uuidv7+ (time-ordered UUIDv7).
-  #
-  # When set to anything other than +:none+, each +Riffer::Messages::Base+
-  # instance gets an +id+ populated at construction time, and seeded messages
-  # passed to +Riffer::Agent#generate+ must carry their own +:id+.
+  # Strategy for auto-generating message ids: +:none+ (default), +:uuid+, or
+  # +:uuidv7+. When not +:none+, messages get an +id+ at construction, and
+  # seeded messages passed to +Riffer::Agent#generate+ must carry their own.
   attr_reader message_id_strategy: Symbol
 
-  # Sets the message id strategy.
-  #
-  # Raises +Riffer::ArgumentError+ if the value is not one of
-  # +:none+, +:uuid+, or +:uuidv7+.
-  #
+  # Sets the message id strategy. Raises Riffer::ArgumentError unless the value
+  # is +:none+, +:uuid+, or +:uuidv7+.
   # --
   # : (Symbol) -> void
   def message_id_strategy=: (Symbol) -> void
 
-  # Experimental: when +true+, riffer keeps the +tool_use+ ↔ +tool_result+
-  # invariant intact on its own.
-  #
-  # - On +Riffer::Agent#generate(messages_array)+, orphaned +tool_use+
-  #   exchanges and parentless +Riffer::Messages::Tool+ messages are
-  #   silently stripped from the seed. Pending tool calls on the resume
-  #   boundary (last assistant whose tail is purely Tool results) are
-  #   preserved for +execute_pending_tool_calls+.
-  # - On any interrupt (caller-issued +interrupt!+ or
-  #   +INTERRUPT_MAX_STEPS+), riffer fills any orphaned +tool_use+ with a
-  #   placeholder +Riffer::Messages::Tool+ carrying
-  #   +error_type: :interrupted+, leaving history valid for the next turn.
-  #   Filled call_ids are exposed on
-  #   +Riffer::Agent::Response#healed_tool_call_ids+ (and the streaming
-  #   +Riffer::StreamEvents::Interrupt+ event).
-  #
-  # Defaults to +false+ — the pre-healing behavior. Experimental: the
-  # surface and default may change without notice.
+  # Experimental: when +true+, riffer maintains the +tool_use+ ↔ +tool_result+
+  # invariant itself — stripping orphaned exchanges and filling interrupted
+  # ones. Defaults to +false+; the surface may change without notice.
   attr_reader experimental_history_healing: bool
 
-  # Sets the +experimental_history_healing+ flag.
-  #
-  # Coerces common boolean representations so values pulled from
-  # environment variables don't silently enable healing — the string
-  # +"false"+ is truthy in Ruby and would otherwise flip the flag on.
-  # Accepts +true+/+false+, +"true"+/+"false"+, +1+/+0+, +"1"+/+"0"+, and
-  # +nil+ (treated as +false+, the default). Raises
-  # +Riffer::ArgumentError+ for any other value.
-  #
+  # Sets the +experimental_history_healing+ flag, coercing boolean-ish values so
+  # an env-var +"false"+ (truthy in Ruby) doesn't silently enable healing.
+  # Raises Riffer::ArgumentError on an unrecognized value.
   # --
   # : (untyped) -> void
   def experimental_history_healing=: (untyped) -> void