riffer 0.48.0 → 0.50.0

data/lib/riffer/agent/config.rb

@@ -1,46 +1,22 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# 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 = 16 #: Integer
 
   # @rbs @tool_runtime: (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)?
 
-  # The configured agent identifier.
   attr_reader :identifier #: String? # @dynamic identifier
-
-  # The configured model.
   attr_reader :model #: (String | Proc)? # @dynamic model
-
-  # The configured instructions.
   attr_reader :instructions #: (String | Proc)? # @dynamic instructions
-
-  # Options passed to generate_text/stream_text.
   attr_accessor :model_options #: Hash[Symbol, untyped] # @dynamic model_options, model_options=
-
-  # The configured structured-output schema.
   attr_reader :structured_output #: Riffer::Params? # @dynamic structured_output
-
-  # The maximum number of LLM call steps in the tool-use loop.
   attr_accessor :max_steps #: Numeric? # @dynamic max_steps, max_steps=
-
-  # The configured tools.
   attr_accessor :tools_config #: (Array[singleton(Riffer::Tool)] | Proc)? # @dynamic tools_config, tools_config=
-
-  # The accumulated +use_mcp+ tag configurations.
   attr_reader :mcp_configs #: Array[Hash[Symbol, untyped]] # @dynamic mcp_configs
-
-  # The configured skills.
   attr_accessor :skills_config #: Riffer::Skills::Config? # @dynamic skills_config, skills_config=
-
-  # Registered guardrail entries keyed by phase.
   attr_reader :guardrails #: Hash[Symbol, Array[Hash[Symbol, untyped]]] # @dynamic guardrails
 
-  # Builds a new Config. Raises Riffer::ArgumentError if +model+ or
-  # +instructions+ is invalid (e.g. an empty string).
   #--
   #: (
   #    ?identifier: String?,
@@ -81,14 +57,12 @@ class Riffer::Agent::Config
     self.tool_runtime = tool_runtime if tool_runtime
   end
 
-  # Sets +identifier+, coercing the value to String.
   #--
   #: (untyped) -> String?
   def identifier=(value)
     @identifier = value&.to_s
   end
 
-  # Sets +structured_output+. Raises Riffer::ArgumentError on an invalid value.
   #--
   #: (Riffer::Params?) -> Riffer::Params?
   def structured_output=(value)
@@ -99,16 +73,14 @@ class Riffer::Agent::Config
     @structured_output = value
   end
 
-  # Returns the declared tool runtime, or +Riffer.config.tool_runtime+ when none
-  # was declared. Resolving the global here rather than at construction is what
-  # lets a copy tell an inherited runtime from a defaulted one.
   #--
   #: () -> (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)
   def tool_runtime
+    # Resolved here rather than at construction so a copy can tell an inherited
+    # runtime from a defaulted one.
     @tool_runtime || Riffer.config.tool_runtime
   end
 
-  # Sets +tool_runtime+. Raises Riffer::ArgumentError on an invalid value.
   #--
   #: ((singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)) -> (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)
   def tool_runtime=(value)
@@ -122,8 +94,6 @@ class Riffer::Agent::Config
     @tool_runtime = value
   end
 
-  # Sets +model+. Raises Riffer::ArgumentError on an invalid value (e.g. an
-  # empty string).
   #--
   #: ((String | Proc)?) -> (String | Proc)?
   def model=(value)
@@ -131,8 +101,6 @@ class Riffer::Agent::Config
     @model = value
   end
 
-  # Sets +instructions+. Raises Riffer::ArgumentError on an invalid value (e.g.
-  # an empty string).
   #--
   #: ((String | Proc)?) -> (String | Proc)?
   def instructions=(value)
@@ -140,8 +108,6 @@ class Riffer::Agent::Config
     @instructions = value
   end
 
-  # Appends an MCP tag entry to +mcp_configs+.
-  #
   #--
   #: (String | Symbol, ?progressive: bool) -> Array[Hash[Symbol, untyped]]
   def add_mcp(tag, progressive: true)
@@ -150,9 +116,6 @@ class Riffer::Agent::Config
     @mcp_configs << { tags: [tag.to_sym], progressive: progressive }
   end
 
-  # 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(phase, klass:, options: {})
@@ -175,8 +138,6 @@ class Riffer::Agent::Config
     end
   end
 
-  # Returns the guardrail entries for the given phase, or +[]+ if none.
-  #
   #--
   #: (Symbol) -> Array[Hash[Symbol, untyped]]
   def guardrails_for(phase)
@@ -185,14 +146,12 @@ class Riffer::Agent::Config
 
   private
 
-  # +dup+ would leave the copy sharing every collection with this one, so a
-  # declaration on either would reach the other. The nesting runs deeper than one
-  # level: an mcp entry holds its own +:tags+ array, a guardrail entry its own
-  # +:options+ hash, and +model_options+ is arbitrary.
   #--
   #: (Riffer::Agent::Config) -> void
   def initialize_copy(source)
     super
+    # A shallow copy would share collections, letting a declaration on either
+    # config reach the other; entries nest (mcp +:tags+, guardrail +:options+).
     @model_options = Riffer::Helpers::DeepDup.call(source.model_options)
     @mcp_configs = Riffer::Helpers::DeepDup.call(source.mcp_configs)
     @guardrails = Riffer::Helpers::DeepDup.call(source.guardrails)

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,50 +1,17 @@
 # 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 reasoning parts on the final assistant message, if the provider
-  # produced any.
   attr_reader :reasoning #: Array[Riffer::Messages::Assistant::ReasoningPart] # @dynamic reasoning
-
-  # The parsed structured output, if structured output was configured.
   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,
@@ -54,7 +21,6 @@ class Riffer::Agent::Response
   #    ?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
@@ -66,7 +32,6 @@ class Riffer::Agent::Response
     reasoning: [],
     structured_output: nil,
     messages: [],
-    healed_tool_call_ids: [],
     token_usage: nil,
     steps: 0
   )
@@ -77,13 +42,10 @@ class Riffer::Agent::Response
     @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,14 +1,9 @@
 # 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::User::FilePart]?, ?tags: Hash[(String | Symbol), untyped]) -> Riffer::Agent::Response
   def generate(agent:, prompt: nil, files: nil, tags: {})
@@ -16,17 +11,13 @@ module Riffer::Agent::Run
     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::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,12 +26,6 @@ module Riffer::Agent::Run
 
   private
 
-  # Both +generate+ and +stream+ funnel here, so this is the single place raw
-  # +tags+ are normalized and merged over the default tags (a caller tag wins
-  # on a shared key). 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)
@@ -125,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,
       )
@@ -164,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(
@@ -239,14 +216,12 @@ module Riffer::Agent::Run
     )
   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
@@ -374,20 +349,17 @@ 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
 
-  # The tags riffer adds to every run, identifying the agent it's on behalf of.
   #--
   #: (Riffer::Agent) -> Hash[String, String]
   def default_tags(agent)
@@ -403,7 +375,6 @@ module Riffer::Agent::Run
   #    ?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
@@ -415,7 +386,6 @@ module Riffer::Agent::Run
     modifications: [],
     reasoning: [],
     structured_output: nil,
-    healed_tool_call_ids: [],
     token_usage: nil,
     steps: 0
   )
@@ -428,17 +398,15 @@ module Riffer::Agent::Run
       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::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
 

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