riffer 0.27.2 → 0.29.0

data/lib/riffer/skills/filesystem_backend.rb

@@ -31,8 +31,9 @@ class Riffer::Skills::FilesystemBackend < Riffer::Skills::Backend
   #--
   #: () -> Array[Riffer::Skills::Frontmatter]
   def list_skills
-    @skills_cache = {}
-    frontmatters = []
+    cache = {} #: Hash[String, String]
+    @skills_cache = cache
+    frontmatters = [] #: Array[Riffer::Skills::Frontmatter]
 
     @paths.each do |path|
       next unless File.directory?(path)
@@ -45,10 +46,10 @@ class Riffer::Skills::FilesystemBackend < Riffer::Skills::Backend
         frontmatter = Riffer::Skills::Frontmatter.parse_frontmatter(File.read(skill_file))
 
         validate_dirname_matches_name!(dirname, frontmatter.name)
-        next if @skills_cache.key?(frontmatter.name)
+        next if cache.key?(frontmatter.name)
 
         frontmatters << frontmatter
-        @skills_cache[frontmatter.name] = dir
+        cache[frontmatter.name] = dir
       end
     end
 
@@ -65,7 +66,8 @@ class Riffer::Skills::FilesystemBackend < Riffer::Skills::Backend
   #: (String) -> String
   def read_skill(name)
     list_skills unless @skills_cache
-    dir = @skills_cache[name]
+    cache = @skills_cache #: Hash[String, String]
+    dir = cache[name]
     raise Riffer::ArgumentError, "Skill not found: '#{name}'" unless dir
 
     _, body = Riffer::Skills::Frontmatter.parse(File.read(File.join(dir, SKILL_FILENAME)))

data/lib/riffer/skills/markdown_adapter.rb

@@ -15,7 +15,7 @@ class Riffer::Skills::MarkdownAdapter < Riffer::Skills::Adapter
   #--
   #: (Array[Riffer::Skills::Frontmatter]) -> String
   def render_catalog(skills)
-    lines = []
+    lines = [] #: Array[String]
     lines << "## Available Skills"
     lines << ""
     lines << "When a user's request matches a skill description below, call the `#{skill_activate_tool.name}` tool with the skill name. After activation, follow the skill's instructions."

data/lib/riffer/skills/xml_adapter.rb

@@ -16,7 +16,7 @@ class Riffer::Skills::XmlAdapter < Riffer::Skills::Adapter
   #--
   #: (Array[Riffer::Skills::Frontmatter]) -> String
   def render_catalog(skills)
-    lines = []
+    lines = [] #: Array[String]
     lines << "When a user's request matches a skill description below, call the `#{skill_activate_tool.name}` tool with the skill name. After activation, follow the skill's instructions."
     lines << ""
     lines << "<available_skills>"

data/lib/riffer/stream_events/interrupt.rb

@@ -8,11 +8,17 @@ class Riffer::StreamEvents::Interrupt < Riffer::StreamEvents::Base
   # The reason provided with the interrupt, if any.
   attr_reader :reason #: (String | Symbol)?
 
+  # Call ids of tool_use blocks that riffer filled with placeholder
+  # results when the interrupt fired. Populated only when
+  # +Riffer.config.experimental_history_healing+ is on.
+  attr_reader :healed_tool_call_ids #: Array[String]
+
   #--
-  #: (?reason: (String | Symbol)?) -> void
-  def initialize(reason: nil)
+  #: (?reason: (String | Symbol)?, ?healed_tool_call_ids: Array[String]) -> void
+  def initialize(reason: nil, healed_tool_call_ids: [])
     super(role: :system)
     @reason = reason
+    @healed_tool_call_ids = healed_tool_call_ids
   end
 
   # Converts the event to a hash.
@@ -20,8 +26,9 @@ class Riffer::StreamEvents::Interrupt < Riffer::StreamEvents::Base
   #--
   #: () -> Hash[Symbol, untyped]
   def to_h
-    h = {role: @role, interrupt: true}
+    h = {role: @role, interrupt: true} #: Hash[Symbol, untyped]
     h[:reason] = @reason if @reason
+    h[:healed_tool_call_ids] = @healed_tool_call_ids unless @healed_tool_call_ids.empty?
     h
   end
 end

data/lib/riffer/stream_events/token_usage_done.rb

@@ -11,10 +11,10 @@
 #
 class Riffer::StreamEvents::TokenUsageDone < Riffer::StreamEvents::Base
   # The token usage data for this response.
-  attr_reader :token_usage #: Riffer::TokenUsage
+  attr_reader :token_usage #: Riffer::Providers::TokenUsage
 
   #--
-  #: (token_usage: Riffer::TokenUsage, ?role: Symbol) -> void
+  #: (token_usage: Riffer::Providers::TokenUsage, ?role: Symbol) -> void
   def initialize(token_usage:, role: :assistant)
     super(role: role)
     @token_usage = token_usage

data/lib/riffer/stream_events/web_search_status.rb

@@ -26,7 +26,7 @@ class Riffer::StreamEvents::WebSearchStatus < Riffer::StreamEvents::Base
   #--
   #: () -> Hash[Symbol, untyped]
   def to_h
-    h = {role: @role, status: @status}
+    h = {role: @role, status: @status} #: Hash[Symbol, untyped]
     h[:url] = @url if @url
     h[:query] = @query if @query
     h

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
 
@@ -32,13 +32,17 @@ class Riffer::ToolRuntime
   # [tool_calls] the tool calls to execute.
   # [tools] the resolved tool classes.
   # [context] the context hash.
+  # [assistant_message] the assistant message that produced these tool
+  #   calls, when known. Forwarded to +around_tool_call+ and
+  #   +dispatch_tool_call+ so subclasses can access it (e.g. for
+  #   instrumentation that needs the accompanying assistant text).
   #
   #--
-  #: (Array[Riffer::Messages::Assistant::ToolCall], tools: Array[singleton(Riffer::Tool)], context: Hash[Symbol, untyped]?) -> Array[[Riffer::Messages::Assistant::ToolCall, Riffer::Tools::Response]]
-  def execute(tool_calls, tools:, context:)
+  #: (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) do
-        dispatch_tool_call(tool_call, tools: tools, context: context)
+      result = around_tool_call(tool_call, context: context, assistant_message: assistant_message) do
+        dispatch_tool_call(tool_call, tools: tools, context: context, assistant_message: assistant_message)
       end
       [tool_call, result]
     end
@@ -49,10 +53,10 @@ 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:)
+  #     def around_tool_call(tool_call, context:, assistant_message: nil)
   #       start = Time.now
   #       result = yield
   #       Rails.logger.info("Tool #{tool_call.name} took #{Time.now - start}s")
@@ -61,8 +65,8 @@ class Riffer::ToolRuntime
   #   end
   #
   #--
-  #: (Riffer::Messages::Assistant::ToolCall, context: Hash[Symbol, untyped]?) { () -> Riffer::Tools::Response } -> Riffer::Tools::Response
-  def around_tool_call(tool_call, context:)
+  #: (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
 
@@ -74,10 +78,12 @@ class Riffer::ToolRuntime
   # [tool_call] the tool call to execute.
   # [tools] the resolved tool classes.
   # [context] the context hash.
+  # [assistant_message] the assistant message that produced this tool
+  #   call, when known.
   #
   #--
-  #: (Riffer::Messages::Assistant::ToolCall, tools: Array[singleton(Riffer::Tool)], context: Hash[Symbol, untyped]?) -> Riffer::Tools::Response
-  def dispatch_tool_call(tool_call, tools:, context:)
+  #: (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 }
 
     if tool_class.nil?

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.27.2" #: 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/response.rbs

@@ -30,6 +30,12 @@ class Riffer::Agent::Response
   # The full message history from the agent conversation.
   attr_reader messages: Array[Riffer::Messages::Base]
 
+  # Call ids of tool_use blocks that riffer filled with placeholder
+  # results during this turn — populated when an interrupt left them
+  # unanswered and +Riffer.config.experimental_history_healing+ is on.
+  # Empty otherwise.
+  attr_reader healed_tool_call_ids: Array[String]
+
   # Creates a new response.
   #
   # [content] the response content.
@@ -39,10 +45,12 @@ class Riffer::Agent::Response
   # [interrupt_reason] optional reason passed via <tt>throw :riffer_interrupt, reason</tt>.
   # [structured_output] parsed structured output when structured output is configured.
   # [messages] the full message history from the agent conversation.
+  # [healed_tool_call_ids] call ids filled with placeholder tool results
+  #   when history healing is enabled.
   #
   # --
-  # : (String, ?tripwire: Riffer::Guardrails::Tripwire?, ?modifications: Array[Riffer::Guardrails::Modification], ?interrupted: bool, ?interrupt_reason: (String | Symbol)?, ?structured_output: Hash[Symbol, untyped]?, ?messages: Array[Riffer::Messages::Base]) -> void
-  def initialize: (String, ?tripwire: Riffer::Guardrails::Tripwire?, ?modifications: Array[Riffer::Guardrails::Modification], ?interrupted: bool, ?interrupt_reason: (String | Symbol)?, ?structured_output: Hash[Symbol, untyped]?, ?messages: Array[Riffer::Messages::Base]) -> void
+  # : (String, ?tripwire: Riffer::Guardrails::Tripwire?, ?modifications: Array[Riffer::Guardrails::Modification], ?interrupted: bool, ?interrupt_reason: (String | Symbol)?, ?structured_output: Hash[Symbol, untyped]?, ?messages: Array[Riffer::Messages::Base], ?healed_tool_call_ids: Array[String]) -> void
+  def initialize: (String, ?tripwire: Riffer::Guardrails::Tripwire?, ?modifications: Array[Riffer::Guardrails::Modification], ?interrupted: bool, ?interrupt_reason: (String | Symbol)?, ?structured_output: Hash[Symbol, untyped]?, ?messages: Array[Riffer::Messages::Base], ?healed_tool_call_ids: Array[String]) -> void
 
   # Returns true if the response was blocked by a guardrail.
   #