riffer 0.27.2 → 0.29.0

data/sig/generated/riffer/agent.rbs

@@ -19,12 +19,15 @@ class Riffer::Agent
 
   extend Riffer::Helpers::ClassNameConverter
 
-  extend Riffer::Helpers::Validations
-
-  DEFAULT_MAX_STEPS: Integer
-
   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.
+  #
+  # --
+  # : () -> Riffer::Agent::Config
+  def self.config: () -> Riffer::Agent::Config
+
   # Gets or sets the agent identifier.
   #
   # --
@@ -70,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
@@ -88,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).
   #
@@ -132,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.
   #
@@ -153,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.
   #
@@ -170,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.
   #
@@ -203,70 +176,124 @@ 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.
   #
-  # --
-  # : ((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.
+  # 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 structured output is configured.
+  # +files:+ requires +prompt+. Pass files to attach to the new user message.
   #
   # --
-  # : ((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]
+  # : (?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
 
-  # Registers a callback to be invoked when messages are added during generation.
-  #
-  # Raises Riffer::ArgumentError if no block is given.
-  #
-  # --
-  # : () { (Riffer::Messages::Base) -> void } -> self
-  def on_message: () { (Riffer::Messages::Base) -> void } -> self
-
-  # Generates the instruction system message for this agent.
-  #
-  # Useful for database persistence workflows where the system messages
-  # need to be stored independently.
-  #
-  # Returns +nil+ when no instructions are configured.
+  # Streams a response from the agent.
   #
-  # --
-  # : (?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.
+  # Runs the inference loop via +Riffer::Agent::Run.stream+, returning an
+  # +Enumerator+ of +Riffer::StreamEvents+.
   #
-  # 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.
   #
   # 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).
+  #
   # --
   # : (?(String | Symbol)?) -> void
   def interrupt!: (?(String | Symbol)?) -> void
@@ -274,103 +301,54 @@ class Riffer::Agent
   private
 
   # --
-  # : (?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
-
-  # --
-  # : ((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
-
-  # --
-  # : (Array[Hash[Symbol, untyped] | Riffer::Messages::Base]) -> void
-  def validate_seed_ids!: (Array[Hash[Symbol, untyped] | Riffer::Messages::Base]) -> void
-
-  # --
-  # : (?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
+  # : () -> Riffer::Messages::System?
+  def build_instruction_message: () -> Riffer::Messages::System?
 
   # --
-  # : (Enumerator::Yielder) -> void
-  def run_stream_loop: (Enumerator::Yielder) -> void
+  # : () -> Riffer::Messages::System?
+  def build_skills_message: () -> Riffer::Messages::System?
 
-  # --
-  # : () -> 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
-
-  # --
-  # : (Riffer::Messages::Assistant) -> bool
-  def has_tool_calls?: (Riffer::Messages::Assistant) -> bool
-
-  # --
-  # : (Riffer::Messages::Assistant) -> void
-  def execute_tool_calls: (Riffer::Messages::Assistant) -> void
-
-  # Executes tool calls left unfinished by a prior interrupt.
+  # Resolves +Config#model+ to a "provider/model" string (calling the Proc
+  # form against +@context+), parses it, and looks up the provider class.
   #
-  # 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.
+  # Returns +[provider_class, model_name]+. Raises Riffer::ArgumentError on
+  # an invalid model string or an unregistered provider.
   #
   # --
-  # : () -> 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
-
-  def pending_tool_calls: () -> untyped
-
-  # --
-  # : () -> void
-  def prepare_run: () -> void
-
-  # --
-  # : (untyped) -> void
-  def parse_model_string!: (untyped) -> void
+  # : () -> [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.
+  #
   # --
-  # : () -> void
-  def clear_resolved_model: () -> void
+  # : (singleton(Riffer::Providers::Base)) -> Riffer::Skills::Context?
+  def resolve_skills: (singleton(Riffer::Providers::Base)) -> Riffer::Skills::Context?
 
   # --
-  # : (?Hash[Symbol, untyped]?) -> String?
-  def generate_instructions: (?Hash[Symbol, untyped]?) -> String?
-
-  attr_reader resolved_model: String?
+  # : () -> 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).
+  #
   # --
-  # : () -> 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)]
@@ -381,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]?) -> 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]?) -> 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>.
@@ -180,6 +192,39 @@ class Riffer::Config
   # : (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.
+  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.
+  #
+  # --
+  # : (untyped) -> void
+  def experimental_history_healing=: (untyped) -> void
+
   # --
   # : () -> void
   def initialize: () -> void

data/sig/generated/riffer/evals/judge.rbs

@@ -18,8 +18,8 @@ class Riffer::Evals::Judge
   # Internal tool for structured evaluation output.
   class EvaluationTool < Riffer::Tool
     # --
-    # : (context: Hash[Symbol, untyped]?, score: Float, reason: String) -> Riffer::Tools::Response
-    def call: (context: Hash[Symbol, untyped]?, score: Float, reason: String) -> Riffer::Tools::Response
+    # : (context: Riffer::Agent::Context?, score: Float, reason: String) -> Riffer::Tools::Response
+    def call: (context: Riffer::Agent::Context?, score: Float, reason: String) -> Riffer::Tools::Response
   end
 
   # The model string (provider/model format).

data/sig/generated/riffer/helpers/call_or_value.rbs

@@ -0,0 +1,9 @@
+# Generated from lib/riffer/helpers/call_or_value.rb with RBS::Inline
+
+# Resolves the "Proc-or-value" idiom: if +thing+ is a Proc, calls it
+# (passing +context+ when its arity is non-zero); otherwise returns
+# +thing+ unchanged. When +thing+ is +nil+, returns +default+.
+module Riffer::Helpers::CallOrValue
+  # : (untyped, ?context: untyped, ?default: untyped) -> untyped
+  def resolve: (untyped, ?context: untyped, ?default: untyped) -> untyped
+end

data/sig/generated/riffer/helpers.rbs

@@ -5,6 +5,5 @@
 # Helpers provide reusable functionality across the library:
 # - Riffer::Helpers::ClassNameConverter - Class name to path conversion
 # - Riffer::Helpers::Dependencies - Lazy gem dependency loading
-# - Riffer::Helpers::Validations - Input validation
 module Riffer::Helpers
 end

data/sig/generated/riffer/messages/assistant.rbs

@@ -24,14 +24,14 @@ class Riffer::Messages::Assistant < Riffer::Messages::Base
   attr_reader tool_calls: Array[Riffer::Messages::Assistant::ToolCall]
 
   # Token usage data for this response.
-  attr_reader token_usage: Riffer::TokenUsage?
+  attr_reader token_usage: Riffer::Providers::TokenUsage?
 
   # Parsed structured output hash, or nil when not applicable.
   attr_reader structured_output: Hash[Symbol, untyped]?
 
   # --
-  # : (String, ?id: String?, ?tool_calls: Array[Riffer::Messages::Assistant::ToolCall], ?token_usage: Riffer::TokenUsage?, ?structured_output: Hash[Symbol, untyped]?) -> void
-  def initialize: (String, ?id: String?, ?tool_calls: Array[Riffer::Messages::Assistant::ToolCall], ?token_usage: Riffer::TokenUsage?, ?structured_output: Hash[Symbol, untyped]?) -> void
+  # : (String, ?id: String?, ?tool_calls: Array[Riffer::Messages::Assistant::ToolCall], ?token_usage: Riffer::Providers::TokenUsage?, ?structured_output: Hash[Symbol, untyped]?) -> void
+  def initialize: (String, ?id: String?, ?tool_calls: Array[Riffer::Messages::Assistant::ToolCall], ?token_usage: Riffer::Providers::TokenUsage?, ?structured_output: Hash[Symbol, untyped]?) -> void
 
   # --
   # : () -> Symbol
@@ -41,6 +41,10 @@ class Riffer::Messages::Assistant < Riffer::Messages::Base
   # : () -> bool
   def structured_output?: () -> bool
 
+  # --
+  # : () -> bool
+  def has_tool_calls?: () -> bool
+
   # --
   # : (Riffer::Messages::Assistant) -> Riffer::Messages::Assistant
   def +: (Riffer::Messages::Assistant) -> Riffer::Messages::Assistant