riffer 0.47.2 → 0.49.0

data/lib/riffer/agent/context.rb

@@ -1,16 +1,12 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# 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
   # @rbs @data: Hash[Symbol, untyped]
 
   RESERVED_KEYS = %i[skills token_usage mcp_progressive_tools discovered_tools].freeze #: 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(data = {})
@@ -27,17 +23,12 @@ class Riffer::Agent::Context
     @data[:discovered_tools] = nil
   end
 
-  # The agent's resolved +Riffer::Skills::Context+, or +nil+ when skills
-  # are not configured.
-  #
   #--
   #: () -> Riffer::Skills::Context?
   def skills
     @data[:skills]
   end
 
-  # Sets the resolved skills context. Raises Riffer::ArgumentError on an
-  # invalid value.
   #--
   #: (Riffer::Skills::Context?) -> Riffer::Skills::Context?
   def skills=(value)
@@ -48,17 +39,13 @@ class Riffer::Agent::Context
     @data[:skills] = value
   end
 
-  # 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
     @data[:token_usage]
   end
 
-  # Sets the cumulative token usage. Raises Riffer::ArgumentError on an invalid
-  # value.
   #--
   #: (Riffer::Providers::TokenUsage?) -> Riffer::Providers::TokenUsage?
   def token_usage=(value)
@@ -69,22 +56,18 @@ class Riffer::Agent::Context
     @data[:token_usage] = value
   end
 
-  # Hash-style read, preserved so tools can pull caller-provided keys via
-  # <tt>context[:agent]</tt>.
   #--
   #: (Symbol) -> untyped
   def [](key)
     @data[key]
   end
 
-  # Auth-wrapped MCP tool classes for progressive discovery, or +nil+.
   #--
   #: () -> Array[singleton(Riffer::Tool)]?
   def mcp_progressive_tools
     @data[:mcp_progressive_tools]
   end
 
-  # Sets progressive MCP tools. Raises Riffer::ArgumentError on an invalid value.
   #--
   #: (Array[singleton(Riffer::Tool)]?) -> Array[singleton(Riffer::Tool)]?
   def mcp_progressive_tools=(value)
@@ -99,15 +82,12 @@ class Riffer::Agent::Context
     @data[:mcp_progressive_tools] = value
   end
 
-  # 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
     @data[:discovered_tools]
   end
 
-  # Sets the discovered tools array. Raises Riffer::ArgumentError on an invalid value.
   #--
   #: (Array[singleton(Riffer::Tool)]?) -> Array[singleton(Riffer::Tool)]?
   def discovered_tools=(value)
@@ -122,8 +102,6 @@ class Riffer::Agent::Context
     @data[:discovered_tools] = value
   end
 
-  # 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(tools)
@@ -137,8 +115,6 @@ class Riffer::Agent::Context
     @data.dig(*keys)
   end
 
-  # Returns a copy of the underlying Hash; mutating it does not affect this
-  # context.
   #--
   #: () -> Hash[Symbol, untyped]
   def to_h

data/lib/riffer/agent/outcome.rb

@@ -1,36 +1,18 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# 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 = %i[stop tool_calls].freeze #: Array[Symbol]
 
-  # Derived from the provider vocabulary so a new finish reason becomes an
-  # outcome without a second list to update.
   PROVIDER_STOP_REASONS = (Riffer::Providers::FinishReason::VALUES - NORMAL_FINISH_REASONS).freeze #: Array[Symbol]
 
-  # The vocabulary every run ends in.
   VALUES = (%i[completed guardrail_blocked interrupted max_steps invalid_structured_output] +
             PROVIDER_STOP_REASONS).freeze #: Array[Symbol]
 
-  # Why the run ended.
   attr_reader :reason #: Symbol # @dynamic reason
 
-  # Human-readable specifics for +reason+, when there are any.
   attr_reader :detail #: String? # @dynamic detail
 
-  # Raises Riffer::ArgumentError when +reason+ is outside VALUES.
   #--
   #: (reason: Symbol, ?detail: String?) -> void
   def initialize(reason:, detail: nil)
@@ -42,8 +24,6 @@ class Riffer::Agent::Outcome
     @detail = detail
   end
 
-  # Returns true when the run completed normally.
-  #
   #--
   #: () -> bool
   def success?

data/lib/riffer/agent/response.rb

@@ -1,55 +1,26 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# 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 # @dynamic content
-
-  # How the run ended.
   attr_reader :outcome #: Riffer::Agent::Outcome # @dynamic outcome
-
-  # The tripwire if execution was blocked.
   attr_reader :tripwire #: Riffer::Guardrails::Tripwire? # @dynamic tripwire
-
-  # The modifications made by guardrails during processing.
   attr_reader :modifications #: Array[Riffer::Guardrails::Modification] # @dynamic modifications
-
-  # The parsed structured output, if structured output was configured.
+  attr_reader :reasoning #: Array[Riffer::Messages::Assistant::ReasoningPart] # @dynamic reasoning
   attr_reader :structured_output #: Hash[Symbol, untyped]? # @dynamic structured_output
-
-  # The aggregate token usage across this run's LLM calls, if any was reported.
   attr_reader :token_usage #: Riffer::Providers::TokenUsage? # @dynamic token_usage
-
-  # 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 # @dynamic steps
-
-  # The full message history from the agent conversation.
   attr_reader :messages #: Array[Riffer::Messages::Base] # @dynamic messages
 
-  # 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] # @dynamic healed_tool_call_ids
-
   #--
   #: (
   #    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
@@ -58,9 +29,9 @@ class Riffer::Agent::Response
     outcome:,
     tripwire: nil,
     modifications: [],
+    reasoning: [],
     structured_output: nil,
     messages: [],
-    healed_tool_call_ids: [],
     token_usage: nil,
     steps: 0
   )
@@ -68,15 +39,13 @@ class Riffer::Agent::Response
     @outcome = outcome
     @tripwire = tripwire
     @modifications = modifications
+    @reasoning = reasoning
     @structured_output = structured_output
     @messages = messages
-    @healed_tool_call_ids = healed_tool_call_ids
     @token_usage = token_usage
     @steps = steps
   end
 
-  # Returns true if any guardrail modified data during processing.
-  #
   #--
   #: () -> bool
   def modified?

data/lib/riffer/agent/run.rb

@@ -1,32 +1,23 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# The generation loop — a pure module of functions over an +agent+, which owns
-# every per-call value; Run just orchestrates.
 module Riffer::Agent::Run
   extend self
 
-  # 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
+  #: (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:, prompt: nil, files: nil, tags: {})
     append_user_message(agent, prompt, files: files)
     run_loop(agent, tags: tags)
   end
 
-  # 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]
+  #: (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:, prompt: nil, files: nil, tags: {})
     append_user_message(agent, prompt, files: files)
     # The enumerator body runs in its own fiber, where the fiber-local OTEL
     # context is empty — capture here so the run span parents to the caller's
-    # trace. tags ride as an ordinary argument captured in the closure, so they
-    # cross the fiber boundary without any re-propagation.
+    # trace.
     trace_context = Riffer::Tracing.current_context
     Enumerator.new do |stream_yielder|
       Riffer::Tracing.with_context(trace_context) { run_loop(agent, tags: tags, stream_yielder: stream_yielder) }
@@ -35,17 +26,12 @@ module Riffer::Agent::Run
 
   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(agent, tags: {}, stream_yielder: nil)
-    tags = normalize_tags(tags)
+    tags = default_tags(agent).merge(normalize_tags(tags))
     Riffer::Tracing.in_span(
-      "invoke_agent #{agent.class.identifier}",
+      "invoke_agent #{agent.identifier}",
       attributes: run_span_attributes(agent, tags),
       kind: :internal,
     ) do |span|
@@ -124,20 +110,12 @@ module Riffer::Agent::Run
         return final_response(agent, all_modifications, token_usage: run_usage, steps: run_steps)
       end
 
-      new_messages, filled = Riffer::Agent::Session::Repair.fill_orphans(agent.session.messages)
-      agent.session.set(new_messages)
-      if stream_yielder
-        stream_yielder << Riffer::StreamEvents::Interrupt.new(
-          reason: reason,
-          healed_tool_call_ids: filled,
-        )
-      end
+      stream_yielder << Riffer::StreamEvents::Interrupt.new(reason: reason) if stream_yielder
       final_response(
         agent,
         all_modifications,
         interrupted: true,
         interrupt_reason: reason,
-        healed_tool_call_ids: filled,
         token_usage: run_usage,
         steps: run_steps,
       )
@@ -153,6 +131,7 @@ module Riffer::Agent::Run
   def accumulate_streamed_response(agent, stream_yielder, tags = {})
     accumulated_content = +""
     accumulated_tool_calls = [] #: Array[Riffer::Messages::Assistant::ToolCall]
+    accumulated_reasoning = [] #: Array[Riffer::Messages::Assistant::ReasoningPart]
     accumulated_token_usage = nil #: Riffer::Providers::TokenUsage?
     accumulated_finish_reason = nil #: Symbol?
     accumulated_finish_reason_raw = nil #: String?
@@ -162,12 +141,12 @@ module Riffer::Agent::Run
 
       case event
       when Riffer::StreamEvents::TextDelta
-        # Append in place rather than += (which reallocates and copies the whole
-        # buffer per delta, O(n^2) over a stream). accumulated_content stays an
-        # owned buffer; replace (not =) on TextDone keeps it that way so a later
-        # delta's << can never mutate the string held by a TextDone event.
+        # << rather than +=, which copies the whole buffer per delta (O(n^2)
+        # over a stream).
         accumulated_content << event.content
       when Riffer::StreamEvents::TextDone
+        # replace, not =, so a later delta's << can never mutate the string
+        # this event holds.
         accumulated_content.replace(event.content)
       when Riffer::StreamEvents::ToolCallDone
         accumulated_tool_calls << Riffer::Messages::Assistant::ToolCall.new(
@@ -175,6 +154,8 @@ module Riffer::Agent::Run
           name: event.name,
           arguments: event.arguments,
         )
+      when Riffer::StreamEvents::ReasoningDone
+        accumulated_reasoning << event.part
       when Riffer::StreamEvents::TokenUsageDone
         accumulated_token_usage = event.token_usage
       when Riffer::StreamEvents::FinishReasonDone
@@ -186,6 +167,7 @@ module Riffer::Agent::Run
     Riffer::Messages::Assistant.new(
       accumulated_content,
       tool_calls: accumulated_tool_calls,
+      reasoning: accumulated_reasoning,
       token_usage: accumulated_token_usage,
       finish_reason: accumulated_finish_reason,
       finish_reason_raw: accumulated_finish_reason_raw,
@@ -228,19 +210,18 @@ module Riffer::Agent::Run
       message&.content || "",
       outcome: final_outcome(message, result, interrupted: interrupted, interrupt_reason: interrupt_reason),
       modifications: all_modifications,
+      reasoning: message&.reasoning || [],
       structured_output: result&.object,
       **extra,
     )
   end
 
-  # 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(message, result, interrupted:, interrupt_reason:)
     finish_reason = message&.finish_reason
+    # Precedence follows the order things happened: a stopped loop beats the
+    # provider's finish reason, which beats schema validation of the content.
     if interrupted && interrupt_reason == Riffer::Agent::INTERRUPT_MAX_STEPS
       Riffer::Agent::Outcome.new(reason: :max_steps)
     elsif interrupted
@@ -368,19 +349,23 @@ module Riffer::Agent::Run
     discovered.empty? ? agent.tools : agent.tools + discovered
   end
 
-  # +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(agent, tags = {})
     opts = agent.config.model_options.dup
     opts[:structured_output] = agent.structured_output if agent.structured_output
+    # Providers extract :tags for native request metadata; it never reaches an
+    # SDK call verbatim.
     opts[:tags] = tags unless tags.empty?
     opts
   end
 
+  #--
+  #: (Riffer::Agent) -> Hash[String, String]
+  def default_tags(agent)
+    { "kind" => "agent", "agent" => agent.identifier }
+  end
+
   #--
   #: (
   #    Riffer::Agent,
@@ -388,8 +373,8 @@ 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
@@ -399,8 +384,8 @@ module Riffer::Agent::Run
     outcome:,
     tripwire: nil,
     modifications: [],
+    reasoning: [],
     structured_output: nil,
-    healed_tool_call_ids: [],
     token_usage: nil,
     steps: 0
   )
@@ -410,23 +395,22 @@ module Riffer::Agent::Run
       outcome: outcome,
       tripwire: tripwire,
       modifications: modifications,
+      reasoning: reasoning,
       structured_output: structured_output,
       messages: messages.frozen? ? messages : messages.dup.freeze,
-      healed_tool_call_ids: healed_tool_call_ids,
       token_usage: token_usage,
       steps: steps,
     )
   end
 
-  # 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
+  #: (Riffer::Agent, String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::User::FilePart]?) -> void
   def append_user_message(agent, prompt, files: nil)
+    # The provider needs text to anchor the attachments.
     raise Riffer::ArgumentError, "files: requires a prompt" if files && !files.empty? && prompt.nil?
     return unless prompt
 
-    file_parts = (files || []).map { |f| Riffer::Messages::FilePart.from_hash(f) }
+    file_parts = (files || []).map { |f| Riffer::Messages::User::FilePart.from_hash(f) }
     agent.session.add(Riffer::Messages::User.new(prompt, files: file_parts), silent: true)
   end
 
@@ -451,7 +435,7 @@ module Riffer::Agent::Run
   def run_span_attributes(agent, tags = {})
     {
       "gen_ai.operation.name" => "invoke_agent",
-      "gen_ai.agent.name" => agent.class.identifier,
+      "gen_ai.agent.name" => agent.identifier,
       "gen_ai.provider.name" => agent.provider.class.semconv_provider_name,
       "gen_ai.request.model" => agent.model_name,
     }.merge(tag_attributes(tags))

data/lib/riffer/agent/serializer.rb

@@ -3,32 +3,20 @@
 
 require "json"
 
-# 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
   extend self
 
-  # 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 = 1 #: 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 = ->(descriptor) { build_tool_shell(descriptor) } #: ^(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:)
+    # Already resolved against the agent's context, so the hash carries plain data, never Procs.
     config = agent.config
     {
       schema_version: SCHEMA_VERSION,
@@ -43,17 +31,11 @@ module Riffer::Agent::Serializer
     }
   end
 
-  # 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, context: nil, session: nil, tool_resolver: DEFAULT_TOOL_RESOLVER, tool_runtime: nil)
-    # Version -> decoder dispatch. Adding a +when 2+ arm (a backwards-compatible
-    # decoder) is how a future breaking change keeps older hashes readable.
+    # One arm per supported version keeps older hashes decodable after a breaking change.
     case hash[:schema_version]
     when SCHEMA_VERSION
       decode_v1(hash, context: context, session: session, tool_resolver: tool_resolver, tool_runtime: tool_runtime)
@@ -63,15 +45,12 @@ module Riffer::Agent::Serializer
     end
   end
 
-  # Snapshots a resolved agent to a JSON string.
   #--
   #: (agent: Riffer::Agent) -> String
   def to_json(agent:)
     JSON.generate(to_h(agent: agent))
   end
 
-  # 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(json, context: nil, session: nil, tool_resolver: DEFAULT_TOOL_RESOLVER, tool_runtime: nil)
@@ -100,14 +79,11 @@ module Riffer::Agent::Serializer
       max_steps: decode_max_steps(hash),
       tools_config: tools,
     } #: Hash[Symbol, untyped]
-    # tool_runtime= rejects nil, so only inject when supplied; otherwise the
-    # Config default (Riffer.config.tool_runtime) applies.
+    # Config#tool_runtime= rejects nil.
     config_args[:tool_runtime] = tool_runtime if tool_runtime
 
-    # +session+ is forwarded verbatim: when nil, Agent.new seeds a fresh session
-    # from the decoded instructions; when supplied, Agent.new uses it as-is to
-    # resume persisted history. The hash never carries history (see "What does
-    # not transfer"), so this is the only seam for rehydrating a conversation.
+    # The hash never carries history, so +session+ is the only seam for rehydrating a conversation.
+    # +context+ feeds tool dispatch only; the config was resolved before serialization.
     Riffer::Agent.new(config: Riffer::Agent::Config.new(**config_args), context: context, session: session)
   end
 
@@ -119,19 +95,17 @@ module Riffer::Agent::Serializer
     Riffer::Params.from_json_schema(schema)
   end
 
-  # 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(value)
+    # A JSON null is awkward across transports (e.g. proto3), so unlimited travels as -1.
     value.nil? ? -1 : value
   end
 
-  # 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)
+    # A partial hash must not become an unbounded loop.
     return Riffer::Agent::Config::DEFAULT_MAX_STEPS unless hash.key?(:max_steps)
 
     hash[:max_steps] == -1 ? nil : hash[:max_steps]
@@ -151,10 +125,7 @@ module Riffer::Agent::Serializer
     schema = descriptor[:parameters_schema]
     tool_timeout = descriptor[:timeout]
 
-    # An anonymous Riffer::Tool subclass is the idiom for synthesizing a tool
-    # from data — the tool DSL is class-level, so there is no value-level
-    # builder to type against. Same approach as Riffer::Mcp::ToolFactory;
-    # steep can't type the dynamic class body, hence the ignore block.
+    # The tool DSL is class-level, so there is no value-level builder to synthesize a tool from data.
     Class.new(Riffer::Tool) do
       # steep:ignore:start
       identifier tool_name

data/lib/riffer/agent/session/repair.rb

@@ -1,24 +1,18 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# 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
   extend self
 
-  # Placeholder response filled in for an orphaned +tool_use+ on interrupt.
   ORPHAN_PLACEHOLDER = lambda { |_tool_call|
     Riffer::Tools::Response.error("Tool call interrupted before completion.", type: :interrupted)
   } #: ^(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(messages)
-    return [messages, []] unless Riffer.config.experimental_history_healing
-
     result_ids = messages.filter_map { |m| m.tool_call_id if m.is_a?(Riffer::Messages::Tool) }
     filled = [] #: Array[String]
     new_messages = [] #: Array[Riffer::Messages::Base]
@@ -45,15 +39,9 @@ module Riffer::Agent::Session::Repair
     [new_messages, filled]
   end
 
-  # 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(messages)
-    return messages unless Riffer.config.experimental_history_healing
-
     resume_boundary = (messages.length - 1).downto(0).find do |idx|
       m = messages[idx]
       m.is_a?(Riffer::Messages::Assistant) &&
@@ -67,7 +55,7 @@ module Riffer::Agent::Session::Repair
 
     strip_offenders = messages.each_with_index.flat_map do |m, idx|
       next [] unless m.is_a?(Riffer::Messages::Assistant) && !m.tool_calls.empty?
-      next [] if idx == resume_boundary # preserve pending exchange
+      next [] if idx == resume_boundary # execute_pending_tool_calls still runs these
       next [] if m.tool_calls.all? { |tc| result_ids.include?(tc.call_id) }
 
       m.tool_calls.map(&:call_id)