riffer 0.28.0 → 0.29.0

data/sig/generated/riffer/agent.rbs

@@ -19,16 +19,14 @@ class Riffer::Agent
 
   extend Riffer::Helpers::ClassNameConverter
 
-  extend Riffer::Helpers::Validations
-
-  DEFAULT_MAX_STEPS: Integer
-
   INTERRUPT_MAX_STEPS: Symbol
 
-  # Placeholder used to fill orphan +tool_use+ blocks when
-  # +Riffer.config.experimental_history_healing+ is enabled and an
-  # interrupt fires mid-tool-use.
-  HEALING_PLACEHOLDER: ^(Riffer::Messages::Assistant::ToolCall) -> Riffer::Tools::Response
+  # Returns the per-class Riffer::Agent::Config value object holding every
+  # DSL setting. Lazily initialized on first read; each subclass has its own.
+  #
+  # --
+  # : () -> Riffer::Agent::Config
+  def self.config: () -> Riffer::Agent::Config
 
   # Gets or sets the agent identifier.
   #
@@ -75,13 +73,13 @@ class Riffer::Agent
   # Accepts a Riffer::Params instance or a block evaluated against a new Params.
   #
   # --
-  # : (?Riffer::Params?) ?{ () -> void } -> Riffer::Params?
-  def self.structured_output: (?Riffer::Params?) ?{ () -> void } -> Riffer::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 DEFAULT_MAX_STEPS (16). Set to +Float::INFINITY+ for
-  # unlimited steps.
+  # Defaults to Riffer::Agent::Config::DEFAULT_MAX_STEPS (16). Set to
+  # +Float::INFINITY+ for unlimited steps.
   #
   # --
   # : (?Numeric?) -> Numeric
@@ -93,35 +91,6 @@ 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)?
 
-  # Returns the tool classes the LLM should see for this agent.
-  #
-  # Class-level companion to the instance #resolved_tools. Resolves the
-  # Proc form of +uses_tools+ and appends the skill activation tool when
-  # a +skills+ block is configured. Does not read the skills backend —
-  # the LLM-facing tool schema reflects class-level intent, not the
-  # runtime state of any backend.
-  #
-  # When +uses_tools+ is a Proc, +context+ is forwarded to it.
-  #
-  # The activation tool class is resolved from the agent's
-  # <tt>skills do; activate_tool ...; end</tt> override when set, otherwise
-  # from <tt>Riffer.config.skills.default_activate_tool</tt>.
-  #
-  # Each returned tool class is validated via +validate_as_tool!+, so
-  # callers serializing this list to a provider can rely on every entry
-  # having the metadata required for tool use (name + description).
-  #
-  # Raises Riffer::ArgumentError on tool name conflicts with the skill
-  # activation tool, or when a tool class fails +validate_as_tool!+.
-  #
-  # --
-  # : (?context: Hash[Symbol, untyped]?) -> Array[singleton(Riffer::Tool)]
-  def self.resolved_tool_classes: (?context: Hash[Symbol, untyped]?) -> Array[singleton(Riffer::Tool)]
-
-  # --
-  # : (Hash[Symbol, untyped]?) -> Array[singleton(Riffer::Tool)]
-  def self.resolve_uses_tools_config: (Hash[Symbol, untyped]?) -> Array[singleton(Riffer::Tool)]
-
   # Opts this agent into tools from all MCP registrations that share any of
   # the given tag(s).
   #
@@ -137,15 +106,12 @@ class Riffer::Agent
 
   # Gets or sets the tool runtime for this agent.
   #
-  # Accepts a Riffer::ToolRuntime subclass, a Riffer::ToolRuntime instance,
-  # or a Proc.
-  #
-  # Inherited by subclasses. When unset, walks the ancestor chain and
-  # falls back to the global <tt>Riffer.config.tool_runtime</tt>.
+  # Accepts a Riffer::Tools::Runtime subclass, a Riffer::Tools::Runtime instance,
+  # or a Proc. Defaults to <tt>Riffer.config.tool_runtime</tt> when unset.
   #
   # --
-  # : (?(singleton(Riffer::ToolRuntime) | Riffer::ToolRuntime | Proc)?) -> (singleton(Riffer::ToolRuntime) | Riffer::ToolRuntime | Proc)?
-  def self.tool_runtime: (?(singleton(Riffer::ToolRuntime) | Riffer::ToolRuntime | Proc)?) -> (singleton(Riffer::ToolRuntime) | Riffer::ToolRuntime | Proc)?
+  # : (?(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.
   #
@@ -158,8 +124,8 @@ class Riffer::Agent
   #   end
   #
   # --
-  # : () ?{ () -> void } -> Riffer::Skills::Config?
-  def self.skills: () ?{ () -> void } -> Riffer::Skills::Config?
+  # : () ?{ (Riffer::Skills::Config) [self: Riffer::Skills::Config] -> void } -> Riffer::Skills::Config?
+  def self.skills: () ?{ (Riffer::Skills::Config) [self: Riffer::Skills::Config] -> void } -> Riffer::Skills::Config?
 
   # Finds an agent class by identifier.
   #
@@ -175,19 +141,21 @@ class Riffer::Agent
 
   # Generates a response using a new agent instance.
   #
-  # See #generate for parameters and return value.
+  # +context:+ is threaded into +new+; +prompt+ and +files:+ are forwarded
+  # to +#generate+.
   #
   # --
-  # : (*untyped, **untyped) -> Riffer::Agent::Response
-  def self.generate: (*untyped, **untyped) -> Riffer::Agent::Response
+  # : (?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.
   #
-  # See #stream for parameters and return value.
+  # +context:+ is threaded into +new+; +prompt+ and +files:+ are forwarded
+  # to +#stream+.
   #
   # --
-  # : (*untyped, **untyped) -> Enumerator[Riffer::StreamEvents::Base, void]
-  def self.stream: (*untyped, **untyped) -> Enumerator[Riffer::StreamEvents::Base, void]
+  # : (?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]
 
   # Registers a guardrail for input, output, or both phases.
   #
@@ -208,71 +176,111 @@ class Riffer::Agent
   # : (Symbol) -> Array[Hash[Symbol, untyped]]
   def self.guardrails_for: (Symbol) -> Array[Hash[Symbol, untyped]]
 
-  # The message history for the agent.
-  attr_reader messages: Array[Riffer::Messages::Base]
-
-  # Cumulative token usage across all LLM calls.
-  attr_reader token_usage: Riffer::TokenUsage?
+  # The conversation handle. See Riffer::Agent::Session.
+  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:)+.
+  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.
+  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.
+  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.
+  attr_reader context: Riffer::Agent::Context
+
+  # The resolved model name (the part after "provider/"), used as the model
+  # argument on every LLM call. Resolved eagerly at +Agent.new+.
+  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+.
+  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+.
+  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).
+  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).
+  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.
+  #
   # Raises Riffer::ArgumentError if the configured model string is invalid
   # (must be "provider/model" format).
   #
   # --
-  # : () -> void
-  def initialize: () -> void
+  # : (?session: Riffer::Agent::Session?, ?context: Hash[Symbol, untyped]?, ?config: Riffer::Agent::Config?) -> void
+  def initialize: (?session: Riffer::Agent::Session?, ?context: Hash[Symbol, untyped]?, ?config: Riffer::Agent::Config?) -> void
 
   # Generates a response from the agent.
   #
-  # When +Riffer.config.experimental_history_healing+ is enabled, seeded
-  # message arrays that violate the +tool_use+ ↔ +tool_result+ invariant
-  # are silently repaired before the run begins.
-  #
-  # --
-  # : ((String | Array[Hash[Symbol, untyped] | Riffer::Messages::Base]), ?files: Array[Hash[Symbol, untyped] | Riffer::FilePart]?, ?context: Hash[Symbol, untyped]?) -> Riffer::Agent::Response
-  def generate: (String | Array[Hash[Symbol, untyped] | Riffer::Messages::Base], ?files: Array[Hash[Symbol, untyped] | Riffer::FilePart]?, ?context: Hash[Symbol, untyped]?) -> Riffer::Agent::Response
-
-  # Streams a response from the agent.
-  #
-  # Raises Riffer::ArgumentError if structured output is configured.
-  #
-  # See +#generate+ for the +experimental_history_healing+ behavior on
-  # seeded arrays.
-  #
-  # --
-  # : ((String | Array[Hash[Symbol, untyped] | Riffer::Messages::Base]), ?files: Array[Hash[Symbol, untyped] | Riffer::FilePart]?, ?context: Hash[Symbol, untyped]?) -> Enumerator[Riffer::StreamEvents::Base, void]
-  def stream: (String | Array[Hash[Symbol, untyped] | Riffer::Messages::Base], ?files: Array[Hash[Symbol, untyped] | Riffer::FilePart]?, ?context: Hash[Symbol, untyped]?) -> Enumerator[Riffer::StreamEvents::Base, void]
-
-  # Registers a callback to be invoked when messages are added during generation.
+  # 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.
   #
-  # Raises Riffer::ArgumentError if no block is given.
+  # +files:+ requires +prompt+. Pass files to attach to the new user message.
   #
   # --
-  # : () { (Riffer::Messages::Base) -> void } -> self
-  def on_message: () { (Riffer::Messages::Base) -> void } -> self
+  # : (?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
 
-  # Generates the instruction system message for this agent.
-  #
-  # Useful for database persistence workflows where the system messages
-  # need to be stored independently.
+  # Streams a response from the agent.
   #
-  # Returns +nil+ when no instructions are configured.
+  # Runs the inference loop via +Riffer::Agent::Run.stream+, returning an
+  # +Enumerator+ of +Riffer::StreamEvents+.
   #
-  # --
-  # : (?context: Hash[Symbol, untyped]?) -> Riffer::Messages::System?
-  def generate_instruction_message: (?context: Hash[Symbol, untyped]?) -> Riffer::Messages::System?
-
-  # Generates the skills catalog system message for this agent.
-  #
-  # Useful for database persistence workflows where the system messages
-  # need to be stored independently.
+  # Raises Riffer::ArgumentError if structured output is configured.
   #
-  # Returns +nil+ when no skills are configured or the catalog is empty.
+  # See +#generate+ for prompt/files semantics.
   #
   # --
-  # : (?context: Hash[Symbol, untyped]?) -> Riffer::Messages::System?
-  def generate_skills_message: (?context: Hash[Symbol, untyped]?) -> Riffer::Messages::System?
+  # : (?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.
   #
@@ -290,215 +298,57 @@ class Riffer::Agent
   # : (?(String | Symbol)?) -> void
   def interrupt!: (?(String | Symbol)?) -> void
 
-  # Returns the message with the given id, or +nil+ when no message matches.
-  #
-  # --
-  # : (String) -> Riffer::Messages::Base?
-  def message_by_id: (String) -> Riffer::Messages::Base?
-
-  # Returns the +Riffer::Messages::Tool+ message that satisfies +tool_call_id+,
-  # or +nil+ when no such tool result exists in history.
-  #
-  # --
-  # : (String) -> Riffer::Messages::Tool?
-  # TODO: Replace with rfind when minimum Ruby is 4.0+
-  # rubocop:disable Style/ReverseFind
-  def tool_message_for: (String) -> Riffer::Messages::Tool?
-
-  # Returns the most recent +Riffer::Messages::Assistant+ in history, or
-  # +nil+ when no assistant message has been recorded yet.
-  #
-  # --
-  # : () -> Riffer::Messages::Assistant?
-  # TODO: Replace with rfind when minimum Ruby is 4.0+
-  # rubocop:disable Style/ReverseFind
-  def last_assistant: () -> Riffer::Messages::Assistant?
-
-  # Returns the call_ids of every +tool_call+ on any assistant message that
-  # has no matching +Riffer::Messages::Tool+ result anywhere in history.
-  #
-  # Zero-cost validation hook for callers that want to check the
-  # +tool_use+ ↔ +tool_result+ invariant before mutating or persisting.
-  #
-  # --
-  # : () -> Array[String]
-  def orphaned_tool_call_ids: () -> Array[String]
-
-  # Replaces the content of an assistant message in place. Preserves +id+,
-  # +tool_calls+, +token_usage+, and +structured_output+. Lookup is by id.
-  #
-  # When +content+ is empty, delegates to +remove_message+ — including the
-  # cascade that drops dependent +Riffer::Messages::Tool+ children.
-  #
-  # Raises Riffer::ArgumentError when no assistant message has the given id.
-  #
-  # --
-  # : (id: String, content: String) -> Riffer::Messages::Base?
-  def replace_assistant_content: (id: String, content: String) -> Riffer::Messages::Base?
-
-  # Removes a message by id. When the target is an assistant message that
-  # carries +tool_calls+, every +Riffer::Messages::Tool+ result whose
-  # +tool_call_id+ matches one of those calls is removed atomically — keeping
-  # the +tool_use+ ↔ +tool_result+ invariant intact.
-  #
-  # Raises Riffer::ArgumentError when called on a +Riffer::Messages::Tool+
-  # message — that would orphan the parent's +tool_use+. Use
-  # +replace_tool_result+ instead.
-  #
-  # Returns the removed message, or +nil+ when no message has the given id
-  # (idempotent).
-  #
-  # --
-  # : (id: String) -> Riffer::Messages::Base?
-  def remove_message: (id: String) -> Riffer::Messages::Base?
-
-  # Replaces a tool result's content (and optional error fields) in place.
-  # Lookup is by +tool_call_id+. Preserves the existing message's +name+ and
-  # +id+.
-  #
-  # Raises Riffer::ArgumentError when no Tool message exists for the given
-  # +tool_call_id+.
-  #
-  # --
-  # : (tool_call_id: String, content: String, ?error: String?, ?error_type: Symbol?) -> Riffer::Messages::Tool
-  def replace_tool_result: (tool_call_id: String, content: String, ?error: String?, ?error_type: Symbol?) -> Riffer::Messages::Tool
-
   private
 
-  # Fills any orphaned +tool_use+ in history with the +HEALING_PLACEHOLDER+
-  # response. Each placeholder Tool message is inserted immediately after
-  # its parent assistant message. Returns the array of call_ids that were
-  # filled, in order; +[]+ when there are no orphans.
-  #
-  # Bypasses +on_message+ — placeholders are not inference output.
-  # Consumers learn that healing happened via the structured
-  # +Riffer::Agent::Response#healed_tool_call_ids+ field (and the streaming
-  # +Interrupt+ event's matching field).
-  #
-  # --
-  # : () -> Array[String]
-  def heal_orphan_tool_calls: () -> Array[String]
-
-  # --
-  # : (?Array[Riffer::Guardrails::Modification]) -> Riffer::Agent::Response
-  def run_generate_loop: (?Array[Riffer::Guardrails::Modification]) -> Riffer::Agent::Response
-
-  # --
-  # : (Riffer::Messages::Base) -> void
-  def add_message: (Riffer::Messages::Base) -> void
-
   # --
-  # : (Riffer::TokenUsage?) -> void
-  def track_token_usage: (Riffer::TokenUsage?) -> void
+  # : () -> Riffer::Messages::System?
+  def build_instruction_message: () -> Riffer::Messages::System?
 
   # --
-  # : ((String | Array[Hash[Symbol, untyped] | Riffer::Messages::Base]), ?files: Array[Hash[Symbol, untyped] | Riffer::FilePart]?) -> void
-  def initialize_messages: (String | Array[Hash[Symbol, untyped] | Riffer::Messages::Base], ?files: Array[Hash[Symbol, untyped] | Riffer::FilePart]?) -> void
+  # : () -> Riffer::Messages::System?
+  def build_skills_message: () -> Riffer::Messages::System?
 
-  # --
-  # : (Array[Hash[Symbol, untyped] | Riffer::Messages::Base]) -> void
-  def validate_seed_ids!: (Array[Hash[Symbol, untyped] | Riffer::Messages::Base]) -> void
-
-  # Repairs a seeded message array so the +tool_use+ ↔ +tool_result+
-  # invariant holds. Drops orphaned tool exchanges (assistant +tool_call+
-  # with no matching Tool result) and parentless Tool messages. Returns a
-  # new array; the input is not mutated.
+  # Resolves +Config#model+ to a "provider/model" string (calling the Proc
+  # form against +@context+), parses it, and looks up the provider class.
   #
-  # Pending tool_calls on the resume boundary — the last assistant whose
-  # tail is purely Tool results (or empty) — are preserved. They get swept
-  # up by +execute_pending_tool_calls+ at the start of the next
-  # generate/stream call.
-  #
-  # Only invoked when +Riffer.config.experimental_history_healing+ is on.
+  # Returns +[provider_class, model_name]+. Raises Riffer::ArgumentError on
+  # an invalid model string or an unregistered provider.
   #
   # --
-  # : (Array[Riffer::Messages::Base]) -> Array[Riffer::Messages::Base]
-  def heal_seeded_history: (Array[Riffer::Messages::Base]) -> Array[Riffer::Messages::Base]
-
-  # --
-  # : (?Hash[Symbol, untyped]?) -> Riffer::Messages::System?
-  def build_instruction_message: (?Hash[Symbol, untyped]?) -> Riffer::Messages::System?
-
-  # --
-  # : (?Riffer::Skills::Context?) -> Riffer::Messages::System?
-  def build_skills_message: (?Riffer::Skills::Context?) -> Riffer::Messages::System?
-
-  # --
-  # : () -> Integer
-  def count_assistant_messages: () -> Integer
-
-  # --
-  # : (Enumerator::Yielder) -> void
-  def run_stream_loop: (Enumerator::Yielder) -> void
-
-  # --
-  # : () -> Riffer::Messages::Assistant
-  def call_llm: () -> Riffer::Messages::Assistant
-
-  # --
-  # : () -> Enumerator[Riffer::StreamEvents::Base, void]
-  def call_llm_stream: () -> Enumerator[Riffer::StreamEvents::Base, void]
-
-  # --
-  # : () -> Riffer::Providers::Base
-  def provider_instance: () -> Riffer::Providers::Base
+  # : () -> [singleton(Riffer::Providers::Base), String]
+  def resolve_provider_and_model: () -> [ singleton(Riffer::Providers::Base), String ]
 
+  # Resolves the skills backend, lists skills, and selects an adapter.
+  # Returns nil if skills are unconfigured or the backend is empty.
+  #
   # --
-  # : (Riffer::Messages::Assistant) -> bool
-  def has_tool_calls?: (Riffer::Messages::Assistant) -> bool
+  # : (singleton(Riffer::Providers::Base)) -> Riffer::Skills::Context?
+  def resolve_skills: (singleton(Riffer::Providers::Base)) -> Riffer::Skills::Context?
 
   # --
-  # : (Riffer::Messages::Assistant) -> void
-  def execute_tool_calls: (Riffer::Messages::Assistant) -> void
+  # : () -> Riffer::Agent::StructuredOutput?
+  def resolve_structured_output: () -> Riffer::Agent::StructuredOutput?
 
-  # Executes tool calls left unfinished by a prior interrupt.
+  # Resolves the full tool catalog for the agent:
   #
-  # When an interrupt fires mid-way through tool execution, some tool calls
-  # from the last assistant message may not have been executed yet. This
-  # method detects those gaps by comparing the tool call ids requested by the
-  # last assistant message against the tool result messages that follow it,
-  # then executes any that are missing.
+  # - 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.
   #
-  # --
-  # : () -> void
-  # Executes tool calls from the last assistant message that don't yet
-  # have a corresponding tool result. Safe to call unconditionally —
-  # returns immediately when there is nothing pending.
-  def execute_pending_tool_calls: () -> void
-
-  # Returns +[assistant, pending_tool_calls]+ for the last assistant message.
-  # When there is no assistant message or no pending calls, the second
-  # element is an empty array.
+  # 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).
   #
   # --
-  # : () -> [untyped, Array[Riffer::Messages::Assistant::ToolCall]]
-  def pending_tool_calls: () -> [ untyped, Array[Riffer::Messages::Assistant::ToolCall] ]
-
-  # --
-  # : () -> void
-  def prepare_run: () -> void
-
-  # --
-  # : (untyped) -> void
-  def parse_model_string!: (untyped) -> void
-
-  # --
-  # : () -> void
-  def clear_resolved_model: () -> void
-
-  # --
-  # : (?Hash[Symbol, untyped]?) -> String?
-  def generate_instructions: (?Hash[Symbol, untyped]?) -> String?
-
-  attr_reader resolved_model: String?
-
-  # --
-  # : () -> String
-  def resolve_model: () -> String
+  # : () -> Array[singleton(Riffer::Tool)]
+  def resolve_tools: () -> Array[singleton(Riffer::Tool)]
 
   # --
-  # : () -> Array[singleton(Riffer::Tool)]
-  def resolve_uses_tools_config: () -> Array[singleton(Riffer::Tool)]
+  # : () -> Riffer::Tools::Runtime
+  def resolve_tool_runtime: () -> Riffer::Tools::Runtime
 
   # --
   # : () -> Array[singleton(Riffer::Tool)]
@@ -509,60 +359,11 @@ class Riffer::Agent
   # : (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]]
 
-  # : (Riffer::Mcp::Registration, Array[Symbol], Proc?, Hash[Symbol, untyped]) -> Array[singleton(Riffer::Tool)]
-  def mcp_tools_for_registration: (Riffer::Mcp::Registration, Array[Symbol], Proc?, Hash[Symbol, untyped]) -> Array[singleton(Riffer::Tool)]
+  # : (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
-
-  # : () -> Array[singleton(Riffer::Tool)]
-  def resolved_tools: () -> Array[singleton(Riffer::Tool)]
-
-  # --
-  # : () -> Riffer::ToolRuntime
-  def resolve_tool_runtime: () -> Riffer::ToolRuntime
-
-  # Resolves the skills backend, lists skills, and selects an adapter.
-  #
-  # Returns nil if skills are not configured or empty.
-  # Does not mutate instance state — callers are responsible for
-  # assigning the returned context.
-  #
-  # --
-  # : (?Hash[Symbol, untyped]?) -> Riffer::Skills::Context?
-  def resolve_skills: (?Hash[Symbol, untyped]?) -> Riffer::Skills::Context?
-
-  # --
-  # : () -> singleton(Riffer::Providers::Base)
-  def provider_class: () -> singleton(Riffer::Providers::Base)
-
-  # --
-  # : () -> Riffer::Messages::Assistant?
-  def extract_final_response: () -> Riffer::Messages::Assistant?
-
-  # --
-  # : () -> [Riffer::Guardrails::Tripwire?, Array[Riffer::Guardrails::Modification]]
-  def run_before_guardrails: () -> [ Riffer::Guardrails::Tripwire?, Array[Riffer::Guardrails::Modification] ]
-
-  # --
-  # : (Riffer::Messages::Assistant) -> [untyped, Riffer::Guardrails::Tripwire?, Array[Riffer::Guardrails::Modification]]
-  def run_after_guardrails: (Riffer::Messages::Assistant) -> [ untyped, Riffer::Guardrails::Tripwire?, Array[Riffer::Guardrails::Modification] ]
-
-  # --
-  # : (Riffer::Messages::Assistant?) -> Hash[Symbol, untyped]?
-  def validate_structured_output: (Riffer::Messages::Assistant?) -> Hash[Symbol, untyped]?
-
-  # --
-  # : () -> Riffer::StructuredOutput?
-  def resolve_structured_output: () -> Riffer::StructuredOutput?
-
-  # --
-  # : () -> Hash[Symbol, untyped]
-  def merged_model_options: () -> Hash[Symbol, untyped]
-
-  # --
-  # : (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: (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
 end

data/sig/generated/riffer/config.rbs

@@ -11,6 +11,8 @@
 #
 #   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]
@@ -56,6 +58,13 @@ class Riffer::Config
                 | ({ ?api_key: untyped }) -> instance
   end
 
+  class OpenRouter < Struct[untyped]
+    attr_accessor api_key(): untyped
+
+    def self.new: (?api_key: untyped) -> instance
+                | ({ ?api_key: untyped }) -> instance
+  end
+
   class Evals < Struct[untyped]
     attr_accessor judge_model(): untyped
 
@@ -130,6 +139,9 @@ class Riffer::Config
   # OpenAI configuration (Struct with +api_key+).
   attr_reader openai: Riffer::Config::OpenAI
 
+  # OpenRouter configuration (Struct with +api_key+).
+  attr_reader openrouter: Riffer::Config::OpenRouter
+
   # Evals configuration (Struct with +judge_model+).
   attr_reader evals: Riffer::Config::Evals
 
@@ -146,9 +158,9 @@ class Riffer::Config
 
   # Global tool runtime configuration (experimental).
   #
-  # Accepts a Riffer::ToolRuntime subclass, a Riffer::ToolRuntime instance,
-  # or a Proc. Defaults to <tt>Riffer::ToolRuntime::Inline.new</tt>.
-  attr_reader tool_runtime: singleton(Riffer::ToolRuntime) | Riffer::ToolRuntime | Proc
+  # Accepts a Riffer::Tools::Runtime subclass, a Riffer::Tools::Runtime instance,
+  # or a Proc. 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.
   #
@@ -156,8 +168,8 @@ class Riffer::Config
   # (ToolRuntime subclass, ToolRuntime instance, or Proc).
   #
   # --
-  # : ((singleton(Riffer::ToolRuntime) | Riffer::ToolRuntime | Proc)) -> void
-  def tool_runtime=: (singleton(Riffer::ToolRuntime) | Riffer::ToolRuntime | Proc) -> void
+  # : ((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>.