riffer 0.28.0 → 0.29.0

data/lib/riffer/tool.rb

@@ -24,7 +24,7 @@ require "timeout"
 #   end
 #
 class Riffer::Tool
-  extend Riffer::Toolable
+  extend Riffer::Tools::Toolable
 
   kind :tool
 
@@ -33,7 +33,7 @@ class Riffer::Tool
   # Raises NotImplementedError if not implemented by subclass.
   #
   #--
-  #: (context: Hash[Symbol, untyped]?, **untyped) -> Riffer::Tools::Response
+  #: (context: Riffer::Agent::Context?, **untyped) -> Riffer::Tools::Response
   def call(context:, **kwargs)
     raise NotImplementedError, "#{self.class} must implement #call"
   end
@@ -69,7 +69,7 @@ class Riffer::Tool
   # Raises Riffer::Error if the tool does not return a Response object.
   #
   #--
-  #: (context: Hash[Symbol, untyped]?, **untyped) -> Riffer::Tools::Response
+  #: (context: Riffer::Agent::Context?, **untyped) -> Riffer::Tools::Response
   def call_with_validation(context:, **kwargs)
     params_builder = self.class.params
     validated_args = params_builder ? params_builder.validate(kwargs) : kwargs

data/lib/riffer/{tool_runtime → tools/runtime}/fibers.rb

@@ -4,10 +4,10 @@
 # Executes tool calls concurrently using fibers via the +async+ gem.
 #
 #   class MyAgent < Riffer::Agent
-#     tool_runtime Riffer::ToolRuntime::Fibers
+#     tool_runtime Riffer::Tools::Runtime::Fibers
 #   end
 #
-class Riffer::ToolRuntime::Fibers < Riffer::ToolRuntime
+class Riffer::Tools::Runtime::Fibers < Riffer::Tools::Runtime
   # [max_concurrency] maximum number of tool calls to execute simultaneously.
   #   When +nil+, all tool calls run as fibers without limit.
   #

data/lib/riffer/{tool_runtime → tools/runtime}/inline.rb

@@ -5,7 +5,7 @@
 #
 # This is the default tool runtime used when no runtime is configured.
 #
-class Riffer::ToolRuntime::Inline < Riffer::ToolRuntime
+class Riffer::Tools::Runtime::Inline < Riffer::Tools::Runtime
   #--
   #: () -> void
   def initialize

data/lib/riffer/{tool_runtime → tools/runtime}/threaded.rb

@@ -4,10 +4,10 @@
 # Executes tool calls concurrently using threads.
 #
 #   class MyAgent < Riffer::Agent
-#     tool_runtime Riffer::ToolRuntime::Threaded
+#     tool_runtime Riffer::Tools::Runtime::Threaded
 #   end
 #
-class Riffer::ToolRuntime::Threaded < Riffer::ToolRuntime
+class Riffer::Tools::Runtime::Threaded < Riffer::Tools::Runtime
   DEFAULT_MAX_CONCURRENCY = 5 #: Integer
 
   # [max_concurrency] maximum number of tool calls to execute simultaneously.

data/lib/riffer/{tool_runtime.rb → tools/runtime.rb}

@@ -3,7 +3,7 @@
 
 require "json"
 
-# Riffer::ToolRuntime handles tool call execution for an agent.
+# Riffer::Tools::Runtime handles tool call execution for an agent.
 #
 # Composes with a Riffer::Runner for concurrency control and provides
 # +execute+ as the sole public entry point.
@@ -11,19 +11,19 @@ require "json"
 # Subclass and override +dispatch_tool_call+ to customize how individual
 # tool calls are dispatched (e.g., HTTP, gRPC).
 #
-#   runtime = Riffer::ToolRuntime::Inline.new
+#   runtime = Riffer::Tools::Runtime::Inline.new
 #   results = runtime.execute(tool_calls, tools: tools, context: context)
 #
-class Riffer::ToolRuntime
+class Riffer::Tools::Runtime
   # [runner] the concurrency runner to use for batch execution.
   #
-  # Subclasses must provide a runner; instantiating ToolRuntime directly
+  # Subclasses must provide a runner; instantiating Riffer::Tools::Runtime directly
   # raises +NotImplementedError+.
   #
   #--
   #: (runner: Riffer::Runner) -> void
   def initialize(runner:)
-    raise NotImplementedError, "#{self.class} is abstract — use a subclass like Riffer::ToolRuntime::Inline" if instance_of?(Riffer::ToolRuntime)
+    raise NotImplementedError, "#{self.class} is abstract — use a subclass like Riffer::Tools::Runtime::Inline" if instance_of?(Riffer::Tools::Runtime)
     @runner = runner
   end
 
@@ -38,7 +38,7 @@ class Riffer::ToolRuntime
   #   instrumentation that needs the accompanying assistant text).
   #
   #--
-  #: (Array[Riffer::Messages::Assistant::ToolCall], tools: Array[singleton(Riffer::Tool)], context: Hash[Symbol, untyped]?, ?assistant_message: Riffer::Messages::Assistant?) -> Array[[Riffer::Messages::Assistant::ToolCall, Riffer::Tools::Response]]
+  #: (Array[Riffer::Messages::Assistant::ToolCall], tools: Array[singleton(Riffer::Tool)], context: Riffer::Agent::Context?, ?assistant_message: Riffer::Messages::Assistant?) -> Array[[Riffer::Messages::Assistant::ToolCall, Riffer::Tools::Response]]
   def execute(tool_calls, tools:, context:, assistant_message: nil)
     @runner.map(tool_calls, context: context) do |tool_call|
       result = around_tool_call(tool_call, context: context, assistant_message: assistant_message) do
@@ -53,7 +53,7 @@ class Riffer::ToolRuntime
   #
   # The default implementation simply yields.
   #
-  #   class InstrumentedRuntime < Riffer::ToolRuntime::Inline
+  #   class InstrumentedRuntime < Riffer::Tools::Runtime::Inline
   #     private
   #
   #     def around_tool_call(tool_call, context:, assistant_message: nil)
@@ -65,7 +65,7 @@ class Riffer::ToolRuntime
   #   end
   #
   #--
-  #: (Riffer::Messages::Assistant::ToolCall, context: Hash[Symbol, untyped]?, ?assistant_message: Riffer::Messages::Assistant?) { () -> Riffer::Tools::Response } -> Riffer::Tools::Response
+  #: (Riffer::Messages::Assistant::ToolCall, context: Riffer::Agent::Context?, ?assistant_message: Riffer::Messages::Assistant?) { () -> Riffer::Tools::Response } -> Riffer::Tools::Response
   def around_tool_call(tool_call, context:, assistant_message: nil)
     yield
   end
@@ -82,7 +82,7 @@ class Riffer::ToolRuntime
   #   call, when known.
   #
   #--
-  #: (Riffer::Messages::Assistant::ToolCall, tools: Array[singleton(Riffer::Tool)], context: Hash[Symbol, untyped]?, ?assistant_message: Riffer::Messages::Assistant?) -> Riffer::Tools::Response
+  #: (Riffer::Messages::Assistant::ToolCall, tools: Array[singleton(Riffer::Tool)], context: Riffer::Agent::Context?, ?assistant_message: Riffer::Messages::Assistant?) -> Riffer::Tools::Response
   def dispatch_tool_call(tool_call, tools:, context:, assistant_message: nil)
     tool_class = tools.find { |tc| tc.name == tool_call.name }
 

data/lib/riffer/{toolable.rb → tools/toolable.rb}

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Riffer::Toolable provides the shared class-level DSL for anything that can
+# Riffer::Tools::Toolable provides the shared class-level DSL for anything that can
 # present as a tool to an LLM — tools today, and subagents/workflows in the
 # future.
 #
@@ -13,7 +13,7 @@
 # are NOT part of Toolable — those belong on Riffer::Tool.
 #
 #   class MyTool
-#     extend Riffer::Toolable
+#     extend Riffer::Tools::Toolable
 #
 #     description "Does something useful"
 #
@@ -22,7 +22,7 @@
 #     end
 #   end
 #
-module Riffer::Toolable
+module Riffer::Tools::Toolable
   DEFAULT_TIMEOUT = 10 #: Integer
 
   # Tracks all classes that extend Toolable.
@@ -31,8 +31,8 @@ module Riffer::Toolable
   #: (Module) -> void
   def self.extended(base)
     base.extend Riffer::Helpers::ClassNameConverter
-    @extenders ||= []
-    @extenders << base
+    extenders = (@extenders ||= []) #: Array[Module]
+    extenders << base
   end
 
   # Returns all classes that have extended Toolable.
@@ -82,11 +82,12 @@ module Riffer::Toolable
   # Defines parameters using the Params DSL.
   #
   #--
-  #: () ?{ () -> void } -> Riffer::Params?
+  #: () ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> Riffer::Params?
   def params(&block)
     return @params_builder if block.nil?
-    @params_builder = Riffer::Params.new
-    @params_builder.instance_eval(&block)
+    builder = Riffer::Params.new
+    builder.instance_eval(&block)
+    @params_builder = builder
   end
 
   # Returns the JSON Schema for the tool's parameters.
@@ -135,6 +136,8 @@ module Riffer::Toolable
   private
 
   def empty_schema # :nodoc:
-    {type: "object", properties: {}, required: [], additionalProperties: false}
+    properties = {} #: Hash[Symbol, untyped]
+    required = [] #: Array[untyped]
+    {type: "object", properties: properties, required: required, additionalProperties: false}
   end
 end

data/lib/riffer/version.rb

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

data/lib/riffer.rb

@@ -11,7 +11,8 @@ require "zeitwerk"
 loader = Zeitwerk::Loader.for_gem
 loader.inflector.inflect(
   "open_ai" => "OpenAI",
-  "azure_open_ai" => "AzureOpenAI"
+  "azure_open_ai" => "AzureOpenAI",
+  "open_router" => "OpenRouter"
 )
 loader.setup
 

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

@@ -0,0 +1,119 @@
+# Generated from lib/riffer/agent/config.rb with RBS::Inline
+
+# Typed configuration object holding every class-level DSL setting on a
+# Riffer::Agent subclass.
+#
+# Each subclass of Riffer::Agent owns one Config, accessible via the class
+# method <tt>config</tt>. The class-level DSL (+model+, +instructions+, +uses_tools+,
+# etc.) reads and mutates this Config in place. Append-style DSL methods
+# (+use_mcp+, +guardrail+) are handled by the +add_mcp+ and +add_guardrail+
+# helpers below.
+#
+# Config stores Procs unresolved. Per-instance resolution happens elsewhere
+# (instructions, model, tools, tool runtime, skills).
+class Riffer::Agent::Config
+  DEFAULT_MAX_STEPS: Integer
+
+  attr_reader identifier: String?
+
+  attr_reader model: (String | Proc)?
+
+  attr_reader instructions: (String | Proc)?
+
+  attr_accessor provider_options: Hash[Symbol, untyped]
+
+  attr_accessor model_options: Hash[Symbol, untyped]
+
+  attr_reader structured_output: Riffer::Params?
+
+  attr_accessor max_steps: Numeric
+
+  attr_accessor tools_config: (Array[singleton(Riffer::Tool)] | Proc)?
+
+  attr_reader mcp_configs: Array[Hash[Symbol, untyped]]
+
+  attr_reader tool_runtime: singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc
+
+  attr_accessor skills_config: Riffer::Skills::Config?
+
+  attr_reader guardrails: Hash[Symbol, Array[Hash[Symbol, untyped]]]
+
+  # Builds a new Config. All fields are optional; unset fields take the
+  # documented defaults.
+  #
+  # Raises Riffer::ArgumentError if +model+ or +instructions+ is provided
+  # as a non-String, non-Proc value (or as an empty String).
+  #
+  # --
+  # : (?identifier: String?, ?model: (String | Proc)?, ?instructions: (String | Proc)?, ?provider_options: Hash[Symbol, untyped], ?model_options: Hash[Symbol, untyped], ?structured_output: Riffer::Params?, ?max_steps: Numeric, ?tools_config: (Array[singleton(Riffer::Tool)] | Proc)?, ?mcp_configs: Array[Hash[Symbol, untyped]], ?tool_runtime: (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc), ?skills_config: Riffer::Skills::Config?, ?guardrails: Hash[Symbol, Array[Hash[Symbol, untyped]]]) -> void
+  def initialize: (?identifier: String?, ?model: (String | Proc)?, ?instructions: (String | Proc)?, ?provider_options: Hash[Symbol, untyped], ?model_options: Hash[Symbol, untyped], ?structured_output: Riffer::Params?, ?max_steps: Numeric, ?tools_config: (Array[singleton(Riffer::Tool)] | Proc)?, ?mcp_configs: Array[Hash[Symbol, untyped]], ?tool_runtime: singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc, ?skills_config: Riffer::Skills::Config?, ?guardrails: Hash[Symbol, Array[Hash[Symbol, untyped]]]) -> void
+
+  # Sets +identifier+. Accepts +nil+ or any value, coerced to String.
+  #
+  # --
+  # : (untyped) -> String?
+  def identifier=: (untyped) -> String?
+
+  # Sets +structured_output+. Accepts a Riffer::Params instance or +nil+.
+  #
+  # Raises Riffer::ArgumentError on any other type.
+  #
+  # --
+  # : (Riffer::Params?) -> Riffer::Params?
+  def structured_output=: (Riffer::Params?) -> Riffer::Params?
+
+  # Sets +tool_runtime+. Accepts a Riffer::Tools::Runtime subclass, a
+  # Riffer::Tools::Runtime instance, or a Proc.
+  #
+  # Raises Riffer::ArgumentError on any other type.
+  #
+  # --
+  # : ((singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)) -> (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)
+  def tool_runtime=: (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc) -> (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)
+
+  # Sets +model+. Accepts a String ("provider/model"), a Proc, or +nil+.
+  #
+  # Raises Riffer::ArgumentError on non-String, non-Proc, or empty-String values.
+  #
+  # --
+  # : ((String | Proc)?) -> (String | Proc)?
+  def model=: ((String | Proc)?) -> (String | Proc)?
+
+  # Sets +instructions+. Accepts a String, a Proc, or +nil+.
+  #
+  # Raises Riffer::ArgumentError on non-String, non-Proc, or empty-String values.
+  #
+  # --
+  # : ((String | Proc)?) -> (String | Proc)?
+  def instructions=: ((String | Proc)?) -> (String | Proc)?
+
+  # Appends an MCP tag entry to +mcp_configs+.
+  #
+  # --
+  # : (String | Symbol) -> Array[Hash[Symbol, untyped]]
+  def add_mcp: (String | Symbol) -> Array[Hash[Symbol, untyped]]
+
+  # Appends a guardrail entry to +guardrails+ for the given phase.
+  #
+  # [phase] +:before+, +:after+, or +:around+. +:around+ appends to both
+  #   +:before+ and +:after+.
+  # [klass] the Riffer::Guardrail subclass to register.
+  # [options] options forwarded to the guardrail at runtime.
+  #
+  # Raises Riffer::ArgumentError on an invalid phase or non-Guardrail class.
+  #
+  # --
+  # : (Symbol, klass: singleton(Riffer::Guardrail), ?options: Hash[Symbol, untyped]) -> void
+  def add_guardrail: (Symbol, klass: singleton(Riffer::Guardrail), ?options: Hash[Symbol, untyped]) -> void
+
+  # Returns the guardrail entries for the given phase, or +[]+ if none.
+  #
+  # --
+  # : (Symbol) -> Array[Hash[Symbol, untyped]]
+  def guardrails_for: (Symbol) -> Array[Hash[Symbol, untyped]]
+
+  private
+
+  # : (untyped, String) -> void
+  def validate_string_or_proc!: (untyped, String) -> void
+end

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

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

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

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

data/sig/generated/riffer/agent/session/repair.rbs

@@ -0,0 +1,51 @@
+# Generated from lib/riffer/agent/session/repair.rb with RBS::Inline
+
+# Riffer::Agent::Session::Repair holds the pure transformations that keep the
+# +tool_use+ ↔ +tool_result+ invariant on a message array. No state, no
+# instance — module-level functions only. Each entry point is gated by
+# +Riffer.config.experimental_history_healing+: when the flag is off the
+# function returns its input unchanged.
+#
+# Two seams:
+#
+# - +fill_orphans+ — fills orphan +tool_use+ blocks with placeholder
+#   results. Used on interrupt (caller-issued or +max_steps+).
+# - +prune_orphans+ — drops orphan +tool_use+ blocks and parentless Tool
+#   messages from a caller-provided seed so it is well-formed before the
+#   next inference call. Used at construction time when
+#   +Riffer::Agent.new(session:)+ receives a session.
+module Riffer::Agent::Session::Repair
+  # Placeholder used to fill orphan +tool_use+ blocks. Emitted as the
+  # +Riffer::Tools::Response+ body for each filled call_id.
+  ORPHAN_PLACEHOLDER: ^(Riffer::Messages::Assistant::ToolCall) -> Riffer::Tools::Response
+
+  # Fills any orphaned +tool_use+ in +messages+ with the
+  # +ORPHAN_PLACEHOLDER+ response. Each placeholder Tool message is
+  # inserted immediately after its parent assistant message. Returns
+  # +[new_messages, filled_call_ids]+; +filled_call_ids+ is empty when
+  # there are no orphans.
+  #
+  # No-op when +Riffer.config.experimental_history_healing+ is off:
+  # returns +[messages, []]+ with the same array reference.
+  #
+  # --
+  # : (Array[Riffer::Messages::Base]) -> [Array[Riffer::Messages::Base], Array[String]]
+  def self.fill_orphans: (Array[Riffer::Messages::Base]) -> [ Array[Riffer::Messages::Base], Array[String] ]
+
+  # Prunes 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.
+  #
+  # 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.
+  #
+  # No-op when +Riffer.config.experimental_history_healing+ is off:
+  # returns +messages+ unchanged.
+  #
+  # --
+  # : (Array[Riffer::Messages::Base]) -> Array[Riffer::Messages::Base]
+  def self.prune_orphans: (Array[Riffer::Messages::Base]) -> Array[Riffer::Messages::Base]
+end