riffer 0.47.2 → 0.49.0

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

@@ -1,110 +1,88 @@
 # Generated from lib/riffer/agent/config.rb with RBS::Inline
 
-# Typed configuration object holding every class-level DSL setting on a
-# Riffer::Agent subclass. Procs are stored unresolved and resolved per-instance
-# later.
 class Riffer::Agent::Config
   DEFAULT_MAX_STEPS: Integer
 
-  # The configured agent identifier.
+  @tool_runtime: (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)?
+
   attr_reader identifier: String?
 
-  # The configured model.
   attr_reader model: (String | Proc)?
 
-  # The configured instructions.
   attr_reader instructions: (String | Proc)?
 
-  # Options passed to generate_text/stream_text.
   attr_accessor model_options: Hash[Symbol, untyped]
 
-  # The configured structured-output schema.
   attr_reader structured_output: Riffer::Params?
 
-  # The maximum number of LLM call steps in the tool-use loop.
   attr_accessor max_steps: Numeric?
 
-  # The configured tools.
   attr_accessor tools_config: (Array[singleton(Riffer::Tool)] | Proc)?
 
-  # The accumulated +use_mcp+ tag configurations.
   attr_reader mcp_configs: Array[Hash[Symbol, untyped]]
 
-  # The configured tool runtime.
-  attr_reader tool_runtime: singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc
-
-  # The configured skills.
   attr_accessor skills_config: Riffer::Skills::Config?
 
-  # Registered guardrail entries keyed by phase.
   attr_reader guardrails: Hash[Symbol, Array[Hash[Symbol, untyped]]]
 
-  # Builds a new Config. Raises Riffer::ArgumentError if +model+ or
-  # +instructions+ is invalid (e.g. an empty string).
   # --
   # : (
-  #    ?identifier: String?,
-  #    ?model: (String | Proc)?,
-  #    ?instructions: (String | Proc)?,
-  #    ?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)?, ?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+, coercing the value to String.
+  #     ?identifier: String?,
+  #     ?model: (String | Proc)?,
+  #     ?instructions: (String | Proc)?,
+  #     ?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)?, ?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
+
   # --
   # : (untyped) -> String?
   def identifier=: (untyped) -> String?
 
-  # Sets +structured_output+. Raises Riffer::ArgumentError on an invalid value.
   # --
   # : (Riffer::Params?) -> Riffer::Params?
   def structured_output=: (Riffer::Params?) -> Riffer::Params?
 
-  # Sets +tool_runtime+. Raises Riffer::ArgumentError on an invalid value.
+  # --
+  # : () -> (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)) -> (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+. Raises Riffer::ArgumentError on an invalid value (e.g. an
-  # empty string).
   # --
   # : ((String | Proc)?) -> (String | Proc)?
   def model=: ((String | Proc)?) -> (String | Proc)?
 
-  # Sets +instructions+. Raises Riffer::ArgumentError on an invalid value (e.g.
-  # an empty string).
   # --
   # : ((String | Proc)?) -> (String | Proc)?
   def instructions=: ((String | Proc)?) -> (String | Proc)?
 
-  # Appends an MCP tag entry to +mcp_configs+.
-  #
   # --
   # : (String | Symbol, ?progressive: bool) -> Array[Hash[Symbol, untyped]]
   def add_mcp: (String | Symbol, ?progressive: bool) -> Array[Hash[Symbol, untyped]]
 
-  # Appends a guardrail entry to +guardrails+ for the given phase; +:around+
-  # appends to both +:before+ and +:after+. Raises Riffer::ArgumentError unless
-  # +phase+ is :before, :after, or :around.
   # --
   # : (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
 
+  # --
+  # : (Riffer::Agent::Config) -> void
+  def initialize_copy: (Riffer::Agent::Config) -> void
+
   # --
   # : (untyped, String) -> void
   def validate_string_or_proc!: (untyped, String) -> void

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

@@ -1,74 +1,52 @@
 # Generated from lib/riffer/agent/context.rb with RBS::Inline
 
-# Typed value object wrapping the runtime context Hash held by a Riffer::Agent.
-# Exposes typed +skills+, +token_usage+, +mcp_progressive_tools+, and
-# +discovered_tools+ accessors while preserving +#[]+ / +#dig+ for caller-provided keys.
 class Riffer::Agent::Context
   @data: Hash[Symbol, untyped]
 
   RESERVED_KEYS: Array[Symbol]
 
-  # Builds a new context. The caller Hash is duped so later caller mutations
-  # don't leak in. Raises Riffer::ArgumentError if it contains a reserved key.
+  # Raises Riffer::ArgumentError if +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. Raises Riffer::ArgumentError on an
-  # invalid value.
   # --
   # : (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.
-  #
+  # Cumulative across every run on this agent.
   # --
   # : () -> Riffer::Providers::TokenUsage?
   def token_usage: () -> Riffer::Providers::TokenUsage?
 
-  # Sets the cumulative token usage. Raises Riffer::ArgumentError on an invalid
-  # value.
   # --
   # : (Riffer::Providers::TokenUsage?) -> Riffer::Providers::TokenUsage?
   def token_usage=: (Riffer::Providers::TokenUsage?) -> Riffer::Providers::TokenUsage?
 
-  # Hash-style read, preserved so tools can pull caller-provided keys via
-  # <tt>context[:agent]</tt>.
   # --
   # : (Symbol) -> untyped
   def []: (Symbol) -> untyped
 
-  # Auth-wrapped MCP tool classes for progressive discovery, or +nil+.
   # --
   # : () -> Array[singleton(Riffer::Tool)]?
   def mcp_progressive_tools: () -> Array[singleton(Riffer::Tool)]?
 
-  # Sets progressive MCP tools. Raises Riffer::ArgumentError on an invalid value.
   # --
   # : (Array[singleton(Riffer::Tool)]?) -> Array[singleton(Riffer::Tool)]?
   def mcp_progressive_tools=: (Array[singleton(Riffer::Tool)]?) -> Array[singleton(Riffer::Tool)]?
 
-  # MCP tool classes discovered during progressive search. Accumulates across
-  # +generate+ calls and is merged into the active tool list on every LLM call.
   # --
   # : () -> Array[singleton(Riffer::Tool)]?
   def discovered_tools: () -> Array[singleton(Riffer::Tool)]?
 
-  # Sets the discovered tools array. Raises Riffer::ArgumentError on an invalid value.
   # --
   # : (Array[singleton(Riffer::Tool)]?) -> Array[singleton(Riffer::Tool)]?
   def discovered_tools=: (Array[singleton(Riffer::Tool)]?) -> Array[singleton(Riffer::Tool)]?
 
-  # Accumulates newly discovered MCP tool classes, deduplicating by name.
-  # Each call extends the existing set; calling multiple times is safe.
   # --
   # : (Array[singleton(Riffer::Tool)]) -> Array[singleton(Riffer::Tool)]
   def discover_tools: (Array[singleton(Riffer::Tool)]) -> Array[singleton(Riffer::Tool)]
@@ -77,8 +55,6 @@ class Riffer::Agent::Context
   # : (*Symbol) -> untyped
   def dig: (*Symbol) -> untyped
 
-  # Returns a copy of the underlying Hash; mutating it does not affect this
-  # context.
   # --
   # : () -> Hash[Symbol, untyped]
   def to_h: () -> Hash[Symbol, untyped]

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

@@ -1,40 +1,20 @@
 # Generated from lib/riffer/agent/outcome.rb with RBS::Inline
 
-# How a run ended — the single place to read whether the agent completed
-# normally and, if not, why. +detail+ carries the specifics when there are any:
-# the tripwire reason, the interrupt reason, the provider's raw finish value,
-# or the structured output parse/validation error.
-#
-#   response = agent.generate("Analyze this")
-#   case response.outcome.reason
-#   when :completed then puts response.structured_output
-#   when :invalid_structured_output then warn response.outcome.detail
-#   end
 class Riffer::Agent::Outcome
-  # Finish reasons that end a turn normally; every other finish reason means the
-  # provider cut the turn short and surfaces as the run's outcome verbatim.
   NORMAL_FINISH_REASONS: Array[Symbol]
 
-  # Derived from the provider vocabulary so a new finish reason becomes an
-  # outcome without a second list to update.
   PROVIDER_STOP_REASONS: Array[Symbol]
 
-  # The vocabulary every run ends in.
   VALUES: Array[Symbol]
 
-  # Why the run ended.
   attr_reader reason: Symbol
 
-  # Human-readable specifics for +reason+, when there are any.
   attr_reader detail: String?
 
-  # Raises Riffer::ArgumentError when +reason+ is outside VALUES.
   # --
   # : (reason: Symbol, ?detail: String?) -> void
   def initialize: (reason: Symbol, ?detail: String?) -> void
 
-  # Returns true when the run completed normally.
-  #
   # --
   # : () -> bool
   def success?: () -> bool

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

@@ -1,61 +1,38 @@
 # Generated from lib/riffer/agent/response.rb with RBS::Inline
 
-# Wraps an agent generation response. +outcome+ says how the run ended; when a
-# guardrail blocks execution, +content+ is empty and +tripwire+ carries the
-# block details.
-#
-#   response = agent.generate("Hello")
-#   if response.outcome.success?
-#     puts response.content
-#   else
-#     puts "#{response.outcome.reason}: #{response.outcome.detail}"
-#   end
 class Riffer::Agent::Response
-  # The response content.
   attr_reader content: String
 
-  # How the run ended.
   attr_reader outcome: Riffer::Agent::Outcome
 
-  # The tripwire if execution was blocked.
   attr_reader tripwire: Riffer::Guardrails::Tripwire?
 
-  # The modifications made by guardrails during processing.
   attr_reader modifications: Array[Riffer::Guardrails::Modification]
 
-  # The parsed structured output, if structured output was configured.
+  attr_reader reasoning: Array[Riffer::Messages::Assistant::ReasoningPart]
+
   attr_reader structured_output: Hash[Symbol, untyped]?
 
-  # The aggregate token usage across this run's LLM calls, if any was reported.
   attr_reader token_usage: Riffer::Providers::TokenUsage?
 
-  # The number of LLM calls made during this run (0 when a before-guardrail
-  # blocks before any call). Distinct from the session's cumulative step count.
   attr_reader steps: Integer
 
-  # The full message history from the agent conversation.
   attr_reader messages: Array[Riffer::Messages::Base]
 
-  # Call ids of tool_use blocks riffer filled with placeholder results this
-  # turn (when an interrupt left them unanswered and history healing is on).
-  attr_reader healed_tool_call_ids: Array[String]
-
   # --
   # : (
   #     String,
   #     outcome: Riffer::Agent::Outcome,
   #     ?tripwire: Riffer::Guardrails::Tripwire?,
   #     ?modifications: Array[Riffer::Guardrails::Modification],
+  #     ?reasoning: Array[Riffer::Messages::Assistant::ReasoningPart],
   #     ?structured_output: Hash[Symbol, untyped]?,
   #     ?messages: Array[Riffer::Messages::Base],
-  #     ?healed_tool_call_ids: Array[String],
   #     ?token_usage: Riffer::Providers::TokenUsage?,
   #     ?steps: Integer
   #   ) -> void
-  def initialize: (String, outcome: Riffer::Agent::Outcome, ?tripwire: Riffer::Guardrails::Tripwire?, ?modifications: Array[Riffer::Guardrails::Modification], ?structured_output: Hash[Symbol, untyped]?, ?messages: Array[Riffer::Messages::Base], ?healed_tool_call_ids: Array[String], ?token_usage: Riffer::Providers::TokenUsage?, ?steps: Integer) -> void
+  def initialize: (String, outcome: Riffer::Agent::Outcome, ?tripwire: Riffer::Guardrails::Tripwire?, ?modifications: Array[Riffer::Guardrails::Modification], ?reasoning: Array[Riffer::Messages::Assistant::ReasoningPart], ?structured_output: Hash[Symbol, untyped]?, ?messages: Array[Riffer::Messages::Base], ?token_usage: Riffer::Providers::TokenUsage?, ?steps: Integer) -> void
 
-  # Returns true if any guardrail modified data during processing.
-  #
   # --
   # : () -> bool
   def modified?: () -> bool

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

@@ -1,29 +1,16 @@
 # Generated from lib/riffer/agent/run.rb with RBS::Inline
 
-# The generation loop — a pure module of functions over an +agent+, which owns
-# every per-call value; Run just orchestrates.
 module Riffer::Agent::Run
-  # 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]?, ?tags: Hash[(String | Symbol), untyped]) -> Riffer::Agent::Response
-  def generate: (agent: Riffer::Agent, ?prompt: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?tags: Hash[String | Symbol, untyped]) -> Riffer::Agent::Response
+  # : (agent: Riffer::Agent, ?prompt: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::User::FilePart]?, ?tags: Hash[(String | Symbol), untyped]) -> Riffer::Agent::Response
+  def generate: (agent: Riffer::Agent, ?prompt: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::User::FilePart]?, ?tags: Hash[String | Symbol, untyped]) -> 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]?, ?tags: Hash[(String | Symbol), untyped]) -> Enumerator[Riffer::StreamEvents::Base, Riffer::Agent::Response]
-  def stream: (agent: Riffer::Agent, ?prompt: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?tags: Hash[String | Symbol, untyped]) -> Enumerator[Riffer::StreamEvents::Base, Riffer::Agent::Response]
+  # : (agent: Riffer::Agent, ?prompt: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::User::FilePart]?, ?tags: Hash[(String | Symbol), untyped]) -> Enumerator[Riffer::StreamEvents::Base, Riffer::Agent::Response]
+  def stream: (agent: Riffer::Agent, ?prompt: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::User::FilePart]?, ?tags: Hash[String | Symbol, untyped]) -> Enumerator[Riffer::StreamEvents::Base, Riffer::Agent::Response]
 
   private
 
-  # Both +generate+ and +stream+ funnel here, so this is the single place raw
-  # +tags+ are normalized. The clean <tt>String => String</tt> map is then
-  # threaded to every span builder in the run as +riffer.tag.*+ and to each
-  # provider call (via +merged_model_options+) for native request-metadata
-  # mapping.
   # --
   # : (Riffer::Agent, ?tags: Hash[(String | Symbol), untyped]?, ?stream_yielder: Enumerator::Yielder?) -> Riffer::Agent::Response
   def run_loop: (Riffer::Agent, ?tags: Hash[String | Symbol, untyped]?, ?stream_yielder: Enumerator::Yielder?) -> Riffer::Agent::Response
@@ -48,10 +35,6 @@ module Riffer::Agent::Run
   # : (Riffer::Agent, Array[Riffer::Guardrails::Modification], ?interrupted: bool, ?interrupt_reason: (String | Symbol)?, **untyped) -> Riffer::Agent::Response
   def final_response: (Riffer::Agent, Array[Riffer::Guardrails::Modification], ?interrupted: bool, ?interrupt_reason: (String | Symbol)?, **untyped) -> Riffer::Agent::Response
 
-  # Checked in the order things happened. The loop being stopped (max_steps or
-  # an interrupt) beats the provider's finish reason, which beats riffer's own
-  # validation of the content. A truncated response that also fails the schema
-  # therefore reports :length, not :invalid_structured_output.
   # --
   # : (Riffer::Messages::Assistant?, Riffer::Agent::StructuredOutput::Result?, interrupted: bool, interrupt_reason: (String | Symbol)?) -> Riffer::Agent::Outcome
   def final_outcome: (Riffer::Messages::Assistant?, Riffer::Agent::StructuredOutput::Result?, interrupted: bool, interrupt_reason: (String | Symbol)?) -> Riffer::Agent::Outcome
@@ -92,14 +75,14 @@ module Riffer::Agent::Run
   # : (Riffer::Agent) -> Array[singleton(Riffer::Tool)]
   def effective_tools: (Riffer::Agent) -> Array[singleton(Riffer::Tool)]
 
-  # +tags+ rides in the options hash as a curated key the providers extract for
-  # native request-metadata mapping (alongside +:structured_output+); it never
-  # reaches an SDK call verbatim. Span tagging is threaded separately to each
-  # builder.
   # --
   # : (Riffer::Agent, ?Hash[String, String]) -> Hash[Symbol, untyped]
   def merged_model_options: (Riffer::Agent, ?Hash[String, String]) -> Hash[Symbol, untyped]
 
+  # --
+  # : (Riffer::Agent) -> Hash[String, String]
+  def default_tags: (Riffer::Agent) -> Hash[String, String]
+
   # --
   # : (
   #     Riffer::Agent,
@@ -107,18 +90,16 @@ module Riffer::Agent::Run
   #     outcome: Riffer::Agent::Outcome,
   #     ?tripwire: Riffer::Guardrails::Tripwire?,
   #     ?modifications: Array[Riffer::Guardrails::Modification],
+  #     ?reasoning: Array[Riffer::Messages::Assistant::ReasoningPart],
   #     ?structured_output: Hash[Symbol, untyped]?,
-  #     ?healed_tool_call_ids: Array[String],
   #     ?token_usage: Riffer::Providers::TokenUsage?,
   #     ?steps: Integer
   #   ) -> Riffer::Agent::Response
-  def build_response: (Riffer::Agent, String, outcome: Riffer::Agent::Outcome, ?tripwire: Riffer::Guardrails::Tripwire?, ?modifications: Array[Riffer::Guardrails::Modification], ?structured_output: Hash[Symbol, untyped]?, ?healed_tool_call_ids: Array[String], ?token_usage: Riffer::Providers::TokenUsage?, ?steps: Integer) -> Riffer::Agent::Response
+  def build_response: (Riffer::Agent, String, outcome: Riffer::Agent::Outcome, ?tripwire: Riffer::Guardrails::Tripwire?, ?modifications: Array[Riffer::Guardrails::Modification], ?reasoning: Array[Riffer::Messages::Assistant::ReasoningPart], ?structured_output: Hash[Symbol, untyped]?, ?token_usage: Riffer::Providers::TokenUsage?, ?steps: Integer) -> Riffer::Agent::Response
 
-  # 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
+  # : (Riffer::Agent, String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::User::FilePart]?) -> void
+  def append_user_message: (Riffer::Agent, String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::User::FilePart]?) -> void
 
   # --
   # : (Riffer::Agent, Riffer::Providers::TokenUsage?) -> void

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

@@ -1,48 +1,27 @@
 # Generated from lib/riffer/agent/serializer.rb with RBS::Inline
 
-# Turns a resolved agent into a self-contained, provider-neutral data hash and
-# back into a runnable agent, behind the +Riffer::Agent#to_h+ /
-# +Riffer::Agent.from_h+ delegators.
-#
-#   hash    = Riffer::Agent::Serializer.to_h(agent: agent)
-#   rebuilt = Riffer::Agent::Serializer.from_h(hash, context: {tenant: "acme"})
 module Riffer::Agent::Serializer
-  # The wire format version, bumped only on an incompatible change to the hash
-  # shape; +from_h+ refuses any other version.
+  # Bump only on an incompatible change to the hash shape.
   SCHEMA_VERSION: Integer
 
-  # Raised by +from_h+ when the hash's +schema_version+ is unsupported.
   class VersionError < Riffer::ArgumentError
   end
 
-  # The default +tool_resolver+: synthesizes a body-less tool shell from a
-  # descriptor. Its +#call+ raises — route shells through a remote runtime.
   DEFAULT_TOOL_RESOLVER: ^(Hash[Symbol, untyped]) -> singleton(Riffer::Tool)
 
-  # Snapshots a resolved agent into a self-contained wire hash. Proc-based
-  # settings are already evaluated against the agent's context, so the hash
-  # carries plain data, never Procs.
   # --
   # : (agent: Riffer::Agent) -> Hash[Symbol, untyped]
   def to_h: (agent: Riffer::Agent) -> Hash[Symbol, untyped]
 
-  # Reconstructs a runnable agent from a wire hash. +context+ is threaded into
-  # tool dispatch (not used to re-resolve the already-resolved config);
-  # +session+ seeds conversation history (the hash carries the agent definition,
-  # not its history). Raises Riffer::Agent::Serializer::VersionError on an
-  # unsupported +schema_version+.
-  #
+  # Raises Riffer::Agent::Serializer::VersionError on an unsupported +schema_version+.
   # --
   # : (Hash[Symbol, untyped], ?context: Hash[Symbol, untyped]?, ?session: Riffer::Agent::Session?, ?tool_resolver: ^(Hash[Symbol, untyped]) -> singleton(Riffer::Tool), ?tool_runtime: (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)?) -> Riffer::Agent
   def from_h: (Hash[Symbol, untyped], ?context: Hash[Symbol, untyped]?, ?session: Riffer::Agent::Session?, ?tool_resolver: ^(Hash[Symbol, untyped]) -> singleton(Riffer::Tool), ?tool_runtime: (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)?) -> Riffer::Agent
 
-  # Snapshots a resolved agent to a JSON string.
   # --
   # : (agent: Riffer::Agent) -> String
   def to_json: (agent: Riffer::Agent) -> String
 
-  # Reconstructs a runnable agent from a JSON string produced by +to_json+. See
-  # +from_h+ for the arguments.
   # --
   # : (String, ?context: Hash[Symbol, untyped]?, ?session: Riffer::Agent::Session?, ?tool_resolver: ^(Hash[Symbol, untyped]) -> singleton(Riffer::Tool), ?tool_runtime: (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)?) -> Riffer::Agent
   def from_json: (String, ?context: Hash[Symbol, untyped]?, ?session: Riffer::Agent::Session?, ?tool_resolver: ^(Hash[Symbol, untyped]) -> singleton(Riffer::Tool), ?tool_runtime: (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)?) -> Riffer::Agent
@@ -57,14 +36,10 @@ module Riffer::Agent::Serializer
   # : (Hash[Symbol, untyped]?) -> Riffer::Params?
   def decode_structured_output: (Hash[Symbol, untyped]?) -> Riffer::Params?
 
-  # Encodes unlimited steps (+nil+ in the DSL) as +-1+ on the wire, where a
-  # JSON +null+ is awkward across transports (e.g. proto3).
   # --
   # : (Numeric?) -> Numeric
   def encode_max_steps: (Numeric?) -> Numeric
 
-  # Reverses +encode_max_steps+; a missing key falls back to the default so a
-  # partial hash can't become an unbounded loop.
   # --
   # : (Hash[Symbol, untyped]) -> Numeric?
   def decode_max_steps: (Hash[Symbol, untyped]) -> Numeric?

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

@@ -1,22 +1,14 @@
 # Generated from lib/riffer/agent/session/repair.rb with RBS::Inline
 
-# Pure, stateless transformations keeping the +tool_use+ ↔ +tool_result+
-# invariant on a message array. Each entry point no-ops when
-# +Riffer.config.experimental_history_healing+ is off.
+# Maintains the invariant that every +tool_use+ has a matching +tool_result+
+# and every +tool_result+ has a parent +tool_use+.
 module Riffer::Agent::Session::Repair
-  # Placeholder response filled in for an orphaned +tool_use+ on interrupt.
   ORPHAN_PLACEHOLDER: ^(Riffer::Messages::Assistant::ToolCall) -> Riffer::Tools::Response
 
-  # Fills each orphaned +tool_use+ in +messages+ with an +ORPHAN_PLACEHOLDER+
-  # result inserted after its parent. Returns +[new_messages, filled_call_ids]+.
   # --
   # : (Array[Riffer::Messages::Base]) -> [Array[Riffer::Messages::Base], Array[String]]
   def fill_orphans: (Array[Riffer::Messages::Base]) -> [ Array[Riffer::Messages::Base], Array[String] ]
 
-  # Prunes a seeded message array to the invariant — dropping orphaned tool
-  # exchanges and parentless Tool messages, but preserving the pending
-  # tool_calls on the resume boundary (the last assistant) for
-  # +execute_pending_tool_calls+. Returns a new array.
   # --
   # : (Array[Riffer::Messages::Base]) -> Array[Riffer::Messages::Base]
   def prune_orphans: (Array[Riffer::Messages::Base]) -> Array[Riffer::Messages::Base]

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

@@ -1,100 +1,74 @@
 # Generated from lib/riffer/agent/session.rb with RBS::Inline
 
-# Owns the conversation handle for an agent: the message array, the
-# +on_message+ callbacks, and the +tool_use+ ↔ +tool_result+ invariant that
-# keeps tool calls and their results consistent.
-#
-#   agent.session.add(msg)                  # append + fire callbacks
-#   agent.session.set([msg1, msg2])         # bulk replace (silent)
-#   agent.session.unset                     # clear (silent)
-#   agent.session.remove(id: "a_1")
-#   agent.session.update(id: "a_1", content: "...")
-#   agent.session.find { |m| m.id == "a_1" }
 class Riffer::Agent::Session
   include Enumerable[Riffer::Messages::Base]
 
   @callbacks: Array[^(Riffer::Messages::Base) -> void]
 
-  # The message history.
   attr_reader messages: Array[Riffer::Messages::Base]
 
   # --
   # : (?messages: Array[Riffer::Messages::Base]) -> void
   def initialize: (?messages: Array[Riffer::Messages::Base]) -> void
 
-  # Registers a callback invoked once per message appended via +#add+.
   # --
   # : () { (Riffer::Messages::Base) -> void } -> self
   def on_message: () { (Riffer::Messages::Base) -> void } -> self
 
-  # Appends +message+ and fires every registered callback once with it. Pass
-  # +silent: true+ to skip callbacks — used for non-inference inputs like user
-  # messages that subscribers don't expect on the callback channel.
   # --
   # : (Riffer::Messages::Base, ?silent: bool) -> Riffer::Messages::Base
   def add: (Riffer::Messages::Base, ?silent: bool) -> Riffer::Messages::Base
 
-  # Replaces the message history wholesale
   # --
   # : (Array[Riffer::Messages::Base]) -> self
   def set: (Array[Riffer::Messages::Base]) -> self
 
-  # Clears the session.
   # --
   # : () -> self
   def unset: () -> self
 
-  # Removes a message by id, cascading to drop the +Tool+ results of a removed
-  # assistant's +tool_calls+ so the +tool_use+ ↔ +tool_result+ invariant holds.
-  # Raises on a +Tool+ message — that would orphan its parent; use +#update+
-  # instead. Returns +nil+ if no message matches.
   # --
   # : (id: String) -> Riffer::Messages::Base?
   def remove: (id: String) -> Riffer::Messages::Base?
 
-  # Partial in-place update: looks up a message by +id:+ or +tool_call_id:+
-  # (exactly one), overlays +attrs+ onto a same-type replacement, and swaps it
-  # in. Dropping +tool_calls+ from an assistant cascades to remove their +Tool+
-  # results, preserving the invariant. Raises on neither/both keys or no match.
   # --
   # : (?id: String?, ?tool_call_id: String?, **untyped) -> Riffer::Messages::Base
   def update: (?id: String?, ?tool_call_id: String?, **untyped) -> Riffer::Messages::Base
 
-  # Returns the call_ids of every +tool_call+ with no matching
-  # +Riffer::Messages::Tool+ result anywhere in history — a hook for checking
-  # the +tool_use+ ↔ +tool_result+ invariant before mutating or persisting.
   # --
   # : () -> Array[String]
   def orphaned_tool_call_ids: () -> Array[String]
 
-  # Returns +[last_assistant, pending_tool_calls]+; the second element is empty
-  # when there's no assistant message or no pending calls.
   # --
   # : () -> [Riffer::Messages::Assistant?, Array[Riffer::Messages::Assistant::ToolCall]]
   def pending_tool_calls: () -> [ Riffer::Messages::Assistant?, Array[Riffer::Messages::Assistant::ToolCall] ]
 
-  # Yields each message in order, or returns an Enumerator without a block.
+  # --
+  # : () -> Array[String]
+  def discard_pending_tool_calls: () -> Array[String]
+
   # --
   # : () -> Enumerator[Riffer::Messages::Base, self]
   # : () { (Riffer::Messages::Base) -> void } -> untyped
   def each: () -> Enumerator[Riffer::Messages::Base, self]
           | () { (Riffer::Messages::Base) -> void } -> untyped
 
-  # The number of LLM steps completed, used by the agent loop to enforce
-  # +max_steps+ on resume.
   # --
   # : () -> Integer
   def steps: () -> Integer
 
-  # The most recent +Riffer::Messages::Assistant+ in the session, or +nil+
-  # when none exists.
-  #
   # --
   # : () -> Riffer::Messages::Assistant?
   def final_assistant_message: () -> Riffer::Messages::Assistant?
 
   private
 
+  # Providers require tool results to directly follow their tool_use, but a
+  # resumed turn appends the new user message before pending calls execute.
+  # --
+  # : (Riffer::Messages::Base) -> Integer
+  def insertion_index: (Riffer::Messages::Base) -> Integer
+
   # --
   # : (Riffer::Messages::Base, Riffer::Messages::Base) -> void
   def cascade_dropped_tool_calls: (Riffer::Messages::Base, Riffer::Messages::Base) -> void

data/sig/generated/riffer/agent/structured_output/result.rbs

@@ -1,25 +1,18 @@
 # Generated from lib/riffer/agent/structured_output/result.rb with RBS::Inline
 
-# Wraps the result of structured output parsing and validation.
 class Riffer::Agent::StructuredOutput::Result
-  # The validated object, or +nil+ on failure.
   attr_reader object: Hash[Symbol, untyped]?
 
-  # The error message, or +nil+ on success.
   attr_reader error: String?
 
   # --
   # : (?object: Hash[Symbol, untyped]?, ?error: String?) -> void
   def initialize: (?object: Hash[Symbol, untyped]?, ?error: String?) -> void
 
-  # Returns true when parsing and validation succeeded.
-  #
   # --
   # : () -> bool
   def success?: () -> bool
 
-  # Returns true when parsing or validation failed.
-  #
   # --
   # : () -> bool
   def failure?: () -> bool