riffer 0.30.0 → 0.32.0

data/lib/riffer/agent/context.rb

@@ -1,38 +1,16 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# 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
-#
+# 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]
 
-  # Keys reserved for framework use. Passing any of these to the
-  # constructor raises +Riffer::ArgumentError+.
-  RESERVED_KEYS = [:skills, :token_usage].freeze #: Array[Symbol]
+  RESERVED_KEYS = [:skills, :token_usage, :mcp_progressive_tools, :discovered_tools].freeze #: 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.
-  #
+  # 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.
   #--
   #: (?Hash[Symbol, untyped]) -> void
   def initialize(data = {})
@@ -45,6 +23,8 @@ class Riffer::Agent::Context
     @data = data.dup
     @data[:skills] = nil
     @data[:token_usage] = nil
+    @data[:mcp_progressive_tools] = nil
+    @data[:discovered_tools] = nil
   end
 
   # The agent's resolved +Riffer::Skills::Context+, or +nil+ when skills
@@ -56,12 +36,8 @@ class Riffer::Agent::Context
     @data[:skills]
   end
 
-  # 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+.
-  #
+  # Sets the resolved skills context. Raises Riffer::ArgumentError on an
+  # invalid value.
   #--
   #: (Riffer::Skills::Context?) -> Riffer::Skills::Context?
   def skills=(value)
@@ -81,12 +57,8 @@ class Riffer::Agent::Context
     @data[:token_usage]
   end
 
-  # 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+.
-  #
+  # Sets the cumulative token usage. Raises Riffer::ArgumentError on an invalid
+  # value.
   #--
   #: (Riffer::Providers::TokenUsage?) -> Riffer::Providers::TokenUsage?
   def token_usage=(value)
@@ -97,28 +69,76 @@ class Riffer::Agent::Context
     @data[:token_usage] = value
   end
 
-  # 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.
-  #
+  # Hash-style read, preserved so tools can pull caller-provided keys via
+  # <tt>context[:agent]</tt>.
   #--
   #: (Symbol) -> untyped
   def [](key)
     @data[key]
   end
 
-  # Hash-style dig. Preserved for tools using
-  # <tt>context&.dig(:user_id)</tt>.
-  #
+  # 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)
+    valid = value.nil? || (
+      value.is_a?(Array) &&
+      value.all? { |tool| tool.is_a?(Class) && tool < Riffer::Tool }
+    )
+    unless valid
+      raise Riffer::ArgumentError,
+        "mcp_progressive_tools must be an Array of Riffer::Tool subclasses or nil, got #{value.class}"
+    end
+    @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)
+    valid = value.nil? || (
+      value.is_a?(Array) &&
+      value.all? { |tool| tool.is_a?(Class) && tool < Riffer::Tool }
+    )
+    unless valid
+      raise Riffer::ArgumentError,
+        "discovered_tools must be an Array of Riffer::Tool subclasses or nil, got #{value.class}"
+    end
+    @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)
+    existing = @data[:discovered_tools] || []
+    @data[:discovered_tools] = (existing + tools).uniq(&:name)
+  end
+
   #--
   #: (*Symbol) -> untyped
   def dig(*keys)
     @data.dig(*keys)
   end
 
-  # Returns a copy of the underlying Hash. Mutating the result does not
-  # affect this context.
-  #
+  # Returns a copy of the underlying Hash; mutating it does not affect this
+  # context.
   #--
   #: () -> Hash[Symbol, untyped]
   def to_h

data/lib/riffer/agent/response.rb

@@ -1,10 +1,8 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Wraps agent generation responses with optional tripwire information.
-#
-# When guardrails block execution, the response will contain a tripwire
-# with details about the block. The content will be empty for blocked responses.
+# Wraps an agent generation response. When a guardrail blocks execution,
+# +content+ is empty and +tripwire+ carries the block details.
 #
 #   response = agent.generate("Hello")
 #   if response.blocked?
@@ -33,24 +31,10 @@ 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.
+  # 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]
 
-  # Creates a new response.
-  #
-  # [content] the response content.
-  # [tripwire] optional tripwire for blocked responses.
-  # [modifications] guardrail modifications applied during processing.
-  # [interrupted] whether the agent loop was interrupted by a callback.
-  # [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], ?healed_tool_call_ids: Array[String]) -> void
   def initialize(content, tripwire: nil, modifications: [], interrupted: false, interrupt_reason: nil, structured_output: nil, messages: [], healed_tool_call_ids: [])

data/lib/riffer/agent/run.rb

@@ -1,23 +1,10 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Riffer::Agent::Run is the generation loop. A pure module of functions over an
-# +agent+ — Agent owns every per-call value (provider, model, tools, tool
-# runtime, structured output, session, context); Run just orchestrates.
-#
-# Tools and user code see the agent's +context+ (a +Riffer::Agent::Context+)
-# unchanged through the loop, so downstream tool runtimes can read
-# caller-provided keys via <tt>context[:agent]</tt> /
-# <tt>context.dig(:key)</tt>, or the framework built-ins via
-# +context.skills+. Cumulative token usage is updated into
-# +agent.context.token_usage+ as the loop progresses.
-#
-#   Riffer::Agent::Run.generate(agent: my_agent, prompt: "Hello")
-#   Riffer::Agent::Run.stream(agent: my_agent, prompt: "Hello")
-#
+# 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
-  include Riffer::Messages::Converter
 
   # Runs the generate loop for the given agent. See Riffer::Agent#generate
   # for prompt/files semantics.
@@ -41,13 +28,6 @@ module Riffer::Agent::Run
 
   private
 
-  # The generation loop. When +stream_yielder+ is provided, per-step events are
-  # pushed to it (and +stream+ discards the return value). When +stream_yielder+
-  # is +nil+, no events are emitted and +generate+ returns the Response
-  # directly. The two modes share every step of the loop — the only
-  # divergences are the LLM call shape (atomic vs. accumulated stream)
-  # and whether per-step events are emitted.
-  #
   #--
   #: (Riffer::Agent, ?stream_yielder: Enumerator::Yielder?) -> Riffer::Agent::Response
   def run_loop(agent, stream_yielder: nil)
@@ -86,17 +66,12 @@ module Riffer::Agent::Run
       return final_response(agent, all_modifications)
     end
 
-    # catch returns the thrown value when throw :riffer_interrupt fires;
-    # the return above exits on the successful (non-interrupted) path.
     new_messages, filled = Riffer::Agent::Session::Repair.fill_orphans(agent.session.messages)
     agent.session.set(new_messages)
     stream_yielder << Riffer::StreamEvents::Interrupt.new(reason: reason, healed_tool_call_ids: filled) if stream_yielder
     final_response(agent, all_modifications, interrupted: true, interrupt_reason: reason, healed_tool_call_ids: filled)
   end
 
-  # Consumes one provider stream, forwarding every event to +stream_yielder+
-  # and folding it into an +Assistant+ message.
-  #
   #--
   #: (Riffer::Agent, Enumerator::Yielder) -> Riffer::Messages::Assistant
   def accumulate_streamed_response(agent, stream_yielder)
@@ -130,9 +105,6 @@ module Riffer::Agent::Run
     )
   end
 
-  # Appends +new_modifications+ to +all_modifications+ and emits a
-  # +GuardrailModification+ event for each one when streaming.
-  #
   #--
   #: (Enumerator::Yielder?, Array[Riffer::Guardrails::Modification], Array[Riffer::Guardrails::Modification]) -> void
   def record_modifications!(stream_yielder, all_modifications, new_modifications)
@@ -140,9 +112,6 @@ module Riffer::Agent::Run
     new_modifications.each { |m| stream_yielder << Riffer::StreamEvents::GuardrailModification.new(m) } if stream_yielder
   end
 
-  # Emits a +GuardrailTripwire+ event when streaming and returns the
-  # short-circuit +Response+ for a tripped guardrail.
-  #
   #--
   #: (Riffer::Agent, Enumerator::Yielder?, Riffer::Guardrails::Tripwire, Array[Riffer::Guardrails::Modification]) -> Riffer::Agent::Response
   def tripwire_response(agent, stream_yielder, tripwire, all_modifications)
@@ -150,11 +119,6 @@ module Riffer::Agent::Run
     build_response(agent, "", tripwire: tripwire, modifications: all_modifications)
   end
 
-  # Builds the final +Response+ from the session's last assistant
-  # message, validating structured output when configured. +extra+
-  # carries the interrupt-only fields (+interrupted:+, +interrupt_reason:+,
-  # +healed_tool_call_ids:+) on the interrupt exit path.
-  #
   #--
   #: (Riffer::Agent, Array[Riffer::Guardrails::Modification], **untyped) -> Riffer::Agent::Response
   def final_response(agent, all_modifications, **extra)
@@ -168,7 +132,7 @@ module Riffer::Agent::Run
     agent.provider.generate_text(
       messages: agent.session.messages,
       model: agent.model_name,
-      tools: agent.tools,
+      tools: effective_tools(agent),
       **merged_model_options(agent)
     )
   end
@@ -179,7 +143,7 @@ module Riffer::Agent::Run
     agent.provider.stream_text(
       messages: agent.session.messages,
       model: agent.model_name,
-      tools: agent.tools,
+      tools: effective_tools(agent),
       **merged_model_options(agent)
     )
   end
@@ -189,7 +153,9 @@ module Riffer::Agent::Run
   def execute_tool_calls(agent, assistant_message, tool_calls: assistant_message.tool_calls)
     return if tool_calls.empty?
 
-    results = agent.tool_runtime.execute(tool_calls, tools: agent.tools, context: agent.context, assistant_message: assistant_message)
+    results = agent.tool_runtime.execute(tool_calls, tools: effective_tools(agent), context: agent.context, assistant_message: assistant_message)
+
+    inject_discovered_tools(agent, results)
 
     results.each do |tool_call, result|
       agent.session.add(Riffer::Messages::Tool.new(
@@ -202,12 +168,17 @@ module Riffer::Agent::Run
     end
   end
 
-  # Executes tool calls left unfinished by a prior interrupt.
-  #
-  # Detects gaps between the last assistant message's requested tool calls
-  # and the tool result messages that follow it, executing any that are
-  # missing. Safe to call unconditionally.
-  #
+  #--
+  #: (Riffer::Agent, Array[[Riffer::Messages::Assistant::ToolCall, Riffer::Tools::Response]]) -> void
+  def inject_discovered_tools(agent, results)
+    to_inject = results.flat_map { |_, result|
+      result.is_a?(Riffer::Mcp::SearchTool::Result) ? result.discovered_tools : [] #: Array[singleton(Riffer::Tool)]
+    }
+    return if to_inject.empty?
+
+    agent.context.discover_tools(to_inject)
+  end
+
   #--
   #: (Riffer::Agent) -> void
   def execute_pending_tool_calls(agent)
@@ -215,11 +186,6 @@ module Riffer::Agent::Run
     execute_tool_calls(agent, assistant_message, tool_calls: pending) if assistant_message
   end
 
-  # Runs the +:before+ guardrail phase. Records any modifications into
-  # +all_modifications+ (and emits them when streaming). When a tripwire
-  # fires, yields the short-circuit +Response+ — the caller's block is
-  # expected to +return+ it from +run_loop+.
-  #
   #--
   #: (Riffer::Agent, Enumerator::Yielder?, Array[Riffer::Guardrails::Modification]) { (Riffer::Agent::Response) -> void } -> void
   def run_before_guardrails(agent, stream_yielder, all_modifications)
@@ -233,12 +199,6 @@ module Riffer::Agent::Run
     yield tripwire_response(agent, stream_yielder, tripwire, all_modifications) if tripwire
   end
 
-  # Runs the +:after+ guardrail phase against the assistant +response+.
-  # Records any modifications into +all_modifications+ (and emits them
-  # when streaming). When a tripwire fires, yields the short-circuit
-  # +Response+ — the caller's block is expected to +return+ it from
-  # +run_loop+. Otherwise returns the post-guardrails assistant message.
-  #
   #--
   #: (Riffer::Agent, Riffer::Messages::Assistant, Enumerator::Yielder?, Array[Riffer::Guardrails::Modification]) { (Riffer::Agent::Response) -> void } -> untyped
   def run_after_guardrails(agent, response, stream_yielder, all_modifications)
@@ -265,6 +225,13 @@ module Riffer::Agent::Run
     agent.structured_output.parse_and_validate(response.content).object
   end
 
+  #--
+  #: (Riffer::Agent) -> Array[singleton(Riffer::Tool)]
+  def effective_tools(agent)
+    discovered = agent.context.discovered_tools || []
+    discovered.empty? ? agent.tools : agent.tools + discovered
+  end
+
   #--
   #: (Riffer::Agent) -> Hash[Symbol, untyped]
   def merged_model_options(agent)
@@ -280,24 +247,18 @@ module Riffer::Agent::Run
     Riffer::Agent::Response.new(content, tripwire: tripwire, modifications: modifications, interrupted: interrupted, interrupt_reason: interrupt_reason, structured_output: structured_output, messages: messages.frozen? ? messages : messages.dup.freeze, healed_tool_call_ids: healed_tool_call_ids)
   end
 
-  # Appends a +User+ message to the session. No-ops when +prompt+ is nil
-  # and +files+ is empty (the caller had nothing to add). Raises when
-  # +files+ are supplied without a +prompt+ — the provider needs text to
-  # anchor the attachments.
-  #
+  # 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(agent, prompt, files: nil)
     raise Riffer::ArgumentError, "files: requires a prompt" if files && !files.empty? && prompt.nil?
     return unless prompt
 
-    file_parts = (files || []).map { |f| convert_to_file_part(f) }
+    file_parts = (files || []).map { |f| Riffer::Messages::FilePart.from_hash(f) }
     agent.session.add(Riffer::Messages::User.new(prompt, files: file_parts), silent: true)
   end
 
-  # Accumulates token usage into +agent.context.token_usage+. Updates the
-  # context so cumulative usage persists across every run on the agent.
-  #
   #--
   #: (Riffer::Agent, Riffer::Providers::TokenUsage?) -> void
   def track_token_usage(agent, usage)

data/lib/riffer/agent/serializer.rb

@@ -3,56 +3,29 @@
 
 require "json"
 
-# Riffer::Agent::Serializer turns a resolved agent into a self-contained,
-# provider-neutral data dict and back into a runnable agent. A pure module
-# (sibling to Riffer::Agent::Run), reached most often through the
-# +Riffer::Agent#to_h+ / +Riffer::Agent.from_h+ delegators.
+# 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.
 #
-# The dict carries only data — no Procs, no class references, no tool
-# runtime. The same dict serves two rehydration targets:
-#
-# - <b>In-process</b> (a monolith persisting agent definitions): pass a
-#   +tool_resolver+ that looks tool descriptors up in a local registry and
-#   returns the real, body-bearing classes. They run on the default runtime.
-# - <b>Distributed</b> (a receiver holding only the Riffer gem): the default
-#   resolver synthesizes body-less tool shells; inject a remote
-#   +Riffer::Tools::Runtime+ to forward each call back to the origin.
-#
-#   dict  = Riffer::Agent::Serializer.to_h(agent: agent)
-#   rebuilt = Riffer::Agent::Serializer.from_h(dict, context: {tenant: "acme"})
-#
-# == What does not transfer
-#
-# Guardrails and the skills subsystem (backend/adapter/catalog) are not
-# serialized; a rebuilt agent enforces no guardrails and renders no skills
-# catalog (the +skill_activate+ tool, if present, crosses as an ordinary
-# tool). Secrets must not be placed in +provider_options+/+model_options+:
-# both ride on the wire as plain data.
+#   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
-  # dict shape; +from_h+ refuses any other version. See +from_h+ for the
-  # dispatch seam that carries back-compat decoders.
+  # The wire format version, bumped only on an incompatible change to the hash
+  # shape; +from_h+ refuses any other version.
   SCHEMA_VERSION = 1 #: Integer
 
-  # Raised by +from_h+ when the dict's +schema_version+ is unsupported.
+  # 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 dict.
-  #
-  # Reads the agent's resolved instance state — Proc-based settings have
-  # already been evaluated against the agent's own context, so the dict
-  # carries plain strings/data, never Procs. Tools are emitted as
-  # +{name, description, parameters_schema, timeout}+ descriptors (the
-  # resolved +agent.tools+, including MCP tools and +skill_activate+).
-  #
-  # [agent] a resolved Riffer::Agent instance.
-  #
+  # 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:)
@@ -71,61 +44,45 @@ module Riffer::Agent::Serializer
     }
   end
 
-  # Reconstructs a runnable agent from a wire dict.
-  #
-  # [hash] a Symbol-keyed wire dict (parse JSON with +symbolize_names: true+).
-  # [context] the rebuilt agent's runtime context — the same value you'd pass
-  #   to +Agent.new(context:)+. It is *not* used to re-resolve serialized
-  #   config (the dict is already resolved); it is threaded into tool dispatch
-  #   and read by tools/runtimes at call time (e.g. a remote runtime keying off
-  #   <tt>context[:tenant]</tt>). Defaults to an empty context.
-  # [tool_resolver] maps a tool descriptor to a Riffer::Tool class. Defaults
-  #   to DEFAULT_TOOL_RESOLVER (body-less shells). Pass a registry lookup to
-  #   rebuild real, in-process tools.
-  # [tool_runtime] an optional Riffer::Tools::Runtime to inject (e.g. a
-  #   remote runtime for shells). When omitted, the agent uses the configured
-  #   default (+Riffer.config.tool_runtime+).
-  #
-  # Raises Riffer::Agent::Serializer::VersionError on an unsupported
-  # +schema_version+, and Riffer::ArgumentError on a malformed dict.
+  # 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+.
   #
   #--
-  #: (Hash[Symbol, untyped], ?context: Hash[Symbol, untyped]?, ?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, tool_resolver: DEFAULT_TOOL_RESOLVER, tool_runtime: nil)
+  #: (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 dicts readable.
+    # decoder) is how a future breaking change keeps older hashes readable.
     case hash[:schema_version]
     when SCHEMA_VERSION
-      decode_v1(hash, context: context, tool_resolver: tool_resolver, tool_runtime: tool_runtime)
+      decode_v1(hash, context: context, session: session, tool_resolver: tool_resolver, tool_runtime: tool_runtime)
     else
       raise VersionError, "Unsupported schema_version: #{hash[:schema_version].inspect} (this Riffer supports #{SCHEMA_VERSION})"
     end
   end
 
-  # Snapshots a resolved agent to a JSON string. Convenience over
-  # <tt>JSON.generate(to_h(agent:))</tt>.
-  #
+  # 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+.
-  # Handles the JSON parse (with symbol keys) so callers don't have to. See
+  # Reconstructs a runnable agent from a JSON string produced by +to_json+. See
   # +from_h+ for the arguments.
-  #
   #--
-  #: (String, ?context: Hash[Symbol, untyped]?, ?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, tool_resolver: DEFAULT_TOOL_RESOLVER, tool_runtime: nil)
-    from_h(JSON.parse(json, symbolize_names: true), context: context, tool_resolver: tool_resolver, tool_runtime: tool_runtime)
+  #: (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)
+    from_h(JSON.parse(json, symbolize_names: true), context: context, session: session, tool_resolver: tool_resolver, tool_runtime: tool_runtime)
   end
 
   private
 
   #--
-  #: (Hash[Symbol, untyped], context: Hash[Symbol, untyped]?, tool_resolver: ^(Hash[Symbol, untyped]) -> singleton(Riffer::Tool), tool_runtime: (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)?) -> Riffer::Agent
-  def decode_v1(hash, context:, tool_resolver:, tool_runtime:)
+  #: (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 decode_v1(hash, context:, session:, tool_resolver:, tool_runtime:)
     tools = Array(hash[:tools]).map { |descriptor| tool_resolver.call(descriptor) }
 
     config_args = {
@@ -142,7 +99,11 @@ module Riffer::Agent::Serializer
     # Config default (Riffer.config.tool_runtime) applies.
     config_args[:tool_runtime] = tool_runtime if tool_runtime
 
-    Riffer::Agent.new(config: Riffer::Agent::Config.new(**config_args), context: context)
+    # +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.
+    Riffer::Agent.new(config: Riffer::Agent::Config.new(**config_args), context: context, session: session)
   end
 
   #--
@@ -152,20 +113,16 @@ module Riffer::Agent::Serializer
     Riffer::Params.from_json_schema(schema)
   end
 
-  # The DSL represents unlimited steps as +nil+, but the wire encodes it as
-  # +-1+ so the dict stays portable across transports where JSON +null+ is
-  # awkward (e.g. proto3, which can't tell null from an absent field). The
-  # magic value lives only on the wire — +encode_max_steps+/+decode_max_steps+
-  # translate at the boundary so neither the DSL nor consumers see it.
+  # 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)
     value.nil? ? -1 : value
   end
 
-  # Reverses +encode_max_steps+: +-1+ (or a literal +null+) means unlimited.
-  # An absent key falls back to the default — a partial dict must not silently
-  # become an unbounded loop.
+  # 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)
@@ -179,12 +136,6 @@ module Riffer::Agent::Serializer
     tool_class.to_tool_schema(strict: false).merge(timeout: tool_class.timeout)
   end
 
-  # Builds an anonymous, body-less Riffer::Tool subclass that advertises the
-  # descriptor's schema to the LLM. Its +#call+ raises — a shell only has
-  # identity, not behavior; route its calls through a remote runtime.
-  #
-  # Returns +untyped+: steep can't see that +Class.new(Riffer::Tool)+ is a
-  # +singleton(Riffer::Tool)+ (cf. Riffer::Mcp::ToolFactory#build_tool_class).
   #--
   #: (Hash[Symbol, untyped]) -> untyped
   def build_tool_shell(descriptor)