riffer 0.29.0 → 0.30.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: be73ae37c66f2f6ad16acdd7b52c271a782172878086821a9c95dbbe238541d3
-  data.tar.gz: 29ea65859395f2e6daaa993d9e8c60cf1908781f1acf79b642588439f4e41781
+  metadata.gz: 7557c63ca04fa006d66a61a53bef6b1f7069ebab67439f00104fbb877d1aceda
+  data.tar.gz: 39bbe45b7e111ae343e32c54b9769db17dd7d8d9b98cd5cb7d42338aa5e4179c
 SHA512:
-  metadata.gz: cce21dcb1840e39b96032cf6061dcce6030e35c21c1ce8f3937138405067cd39644f4a55fd4fddfcc9623549441dccb0d76b5443e7fa890ab84ce73f6af2736d
-  data.tar.gz: 3c0e8a0fbcd42c3aceee9b4d8837188e260d444c2e22df72f1976bdfc7b05bf2669f2494d3121ca066d142baa8629bdd01c51acd294869702b5357d83943a4a6
+  metadata.gz: 61694198a05d63d831dca9b4b37e38b6cacbd7b67214fa47c2027a0a7e1636ee07e5f85641f9fe00ee597d66dfdb0a6fccd0e494b6ec670a84a2020907cfdd0b
+  data.tar.gz: fbff4457d39da36a1c77e9cb7ea86ccb5e96f0887ba982f6a8a960557ee4beceda3a604011fcfd20951f9baedd59eadbf188832cb6bcc8fcf71e256d93e8cdc3

data/.agents/rbs-inline.md

@@ -98,6 +98,23 @@ VERSION = "1.0.0" #: String
 DEFAULTS = {}.freeze #: Hash[Symbol, untyped]
 ```
 
+### Instance variables
+
+The `#:` shorthand on an assignment is a Steep _assertion_ — it types the expression but does
+**not declare the ivar**. To declare an ivar's type, use a `# @rbs` comment inside the class
+body. `# @rbs` is used **only** for ivar declarations in this codebase; everything else uses
+`#:`.
+
+```ruby
+class Riffer::Agent::Session
+  # @rbs @callbacks: Array[^(Riffer::Messages::Base) -> void]   # instance ivar
+end
+
+module Riffer
+  # @rbs self.@config: Riffer::Config?                          # class/module-level ivar
+end
+```
+
 ## Common Type Patterns
 
 | Pattern                   | Meaning                     |
@@ -112,6 +129,40 @@ DEFAULTS = {}.freeze #: Hash[Symbol, untyped]
 | `untyped`                 | Any type                    |
 | `void`                    | No meaningful return        |
 
+## Optional-dependency types (consumer-safe signatures)
+
+`sig/generated/` ships with the gem and is loaded by downstream projects (`rbs collection` / `rbs -r riffer`). rbs-inline copies a method's `#:` signature **verbatim** into the shipped sig, so **never name an optional-dependency type in a `#:` signature** — `OpenAI::*`, `Anthropic::*`, `Aws::*`, `MCP::*`, `Async::*`, `Zeitwerk::*`, etc. A consumer who installs riffer without that gem would hit `Cannot find type`, because those providers are pluggable and the gems ship no usable RBS of their own.
+
+**Workaround — assert the type inside the method body instead.** An inline assertion (`local = arg #: OpenAI::Models::…`) is a Steep-only hint that rbs-inline does **not** emit into the signature. Leave the SDK param/return `untyped` in the `#:` line, keep every riffer/stdlib param and return typed, and recover the SDK type with a body assertion:
+
+```ruby
+#: (untyped) -> String
+def extract_content(response)
+  message = response #: Anthropic::Models::Message
+  message.content&.first&.text || ""        # fully type-checked against the SDK type
+end
+
+#: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+def handle_stream_chunk(chunk, state:, yielder:)
+  typed = chunk #: OpenAI::Models::Chat::ChatCompletionChunk
+  # ...
+end
+
+# When the return value IS the SDK object, type the return `untyped` (no body assertion needed):
+#: (Hash[Symbol, untyped]) -> untyped
+def execute_generate(params)
+  @client.messages.create(**params)
+end
+```
+
+`test/shipped_signatures_test.rb` enforces this — it fails if any optional-dependency type appears in `sig/generated/` or `sig/manual/`.
+
+### Where stubs and stdlib deps live
+
+- `sig/_private/` — signatures that must **not** ship. RBS **skips** `_`-prefixed directories in library mode, so consumers never load them; riffer's own `steep check` does (via the `Steepfile`). Two kinds, by predictable path: external-gem signatures are named by gem at the top level (`async.rbs`, `mcp.rbs`, `zeitwerk.rbs`, `openai.rbs`, `anthropic.rbs`, `aws-sdk-core/*` — full stubs for RBS-less gems plus arity patches for the provider SDKs); riffer's own hidden stubs mirror `lib/` under `riffer/` (e.g. `riffer/providers/anthropic.rbs` declares the SDK-typed `@client` ivar).
+- `sig/manual/` — hand-written riffer-only signatures that are **safe to ship**, for the few things rbs-inline can't generate _at all_ (mirroring `lib/`). In practice that's `extend self` modules (`riffer/agent/run.rbs`, `riffer/helpers/call_or_value.rbs`) and modeling an include applied dynamically (`riffer/tools/toolable.rbs`). SDK-free ivars are **not** hand-written here — declare them inline with `# @rbs` (see "Instance variables"). SDK-typed ivars can't ship, so they go in `_private/riffer/providers/` (`@client`).
+- `sig/manifest.yaml` — declares the **stdlib** RBS the shipped sigs reference (`uri`, `net-http`) so `rbs -r riffer` resolves them.
+
 ## Workflow
 
 After changing type annotations:

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.29.0"
+  ".": "0.30.0"
 }

data/CHANGELOG.md

@@ -5,6 +5,24 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.30.0](https://github.com/janeapp/riffer/compare/riffer/v0.29.1...riffer/v0.30.0) (2026-06-03)
+
+
+### ⚠ BREAKING CHANGES
+
+* unlimited max_steps is now represented as `nil` at the agent level (set via `max_steps nil`), not Float::INFINITY — Riffer::Agent::Config#max_steps may be nil and is no longer normalized. Riffer::Params parameter types are typed Module (widened from Class) to honestly include Riffer::Params::Boolean, which is a Module.
+
+### Features
+
+* Riffer::Agent::Serializer for transferable agent definitions ([#293](https://github.com/janeapp/riffer/issues/293)) ([99134b0](https://github.com/janeapp/riffer/commit/99134b0bf52bccfd727e52349aba8432389775be))
+
+## [0.29.1](https://github.com/janeapp/riffer/compare/riffer/v0.29.0...riffer/v0.29.1) (2026-06-01)
+
+
+### Bug Fixes
+
+* **rbs:** ship consumer-safe RBS signatures ([#286](https://github.com/janeapp/riffer/issues/286)) ([ac8ce6c](https://github.com/janeapp/riffer/commit/ac8ce6c40ab665456cee6cd9275649024492f4a0))
+
 ## [0.29.0](https://github.com/janeapp/riffer/compare/riffer/v0.28.0...riffer/v0.29.0) (2026-05-29)
 
 

data/README.md

@@ -61,6 +61,7 @@ For comprehensive documentation, see the [docs](docs/) directory:
 - [Guardrails](docs/12_GUARDRAILS.md) - Input/output validation
 - [Skills](docs/13_SKILLS.md) - Packaged agent capabilities
 - [MCP](docs/14_MCP.md) - Integrating third-party MCP servers
+- [Serialization](docs/15_SERIALIZATION.md) - Persisting and transferring agent definitions
 - [Providers](docs/providers/01_PROVIDERS.md) - LLM provider adapters
 
 ### API Reference

data/Steepfile

@@ -2,7 +2,8 @@ D = Steep::Diagnostic
 
 target :lib do
   signature "sig/generated"
-  signature "sig/stubs"
+  signature "sig/manual"
+  signature "sig/_private"
 
   check "lib"
 

data/docs/01_OVERVIEW.md

@@ -134,3 +134,4 @@ Response
 - [Evals](11_EVALS.md) - Evaluating agent quality
 - [Guardrails](12_GUARDRAILS.md) - Input/output validation
 - [Skills](13_SKILLS.md) - Packaged agent capabilities
+- [Serialization](15_SERIALIZATION.md) - Persisting and transferring agent definitions

data/docs/03_AGENTS.md

@@ -152,7 +152,7 @@ end
 
 ### max_steps
 
-Sets the maximum number of LLM call steps in the tool-use loop. When the limit is reached, the loop interrupts with reason `:max_steps`. Defaults to `16`. Set to `Float::INFINITY` for unlimited steps:
+Sets the maximum number of LLM call steps in the tool-use loop. When the limit is reached, the loop interrupts with reason `:max_steps`. Defaults to `16`. Set to `nil` (`max_steps nil`) for unlimited steps:
 
 ```ruby
 class MyAgent < Riffer::Agent

data/docs/15_SERIALIZATION.md

@@ -0,0 +1,103 @@
+# Serialization
+
+`Riffer::Agent::Serializer` turns a **resolved agent** into a self-contained, provider-neutral data dict (`to_h`) and reconstructs a **runnable agent** from that dict (`from_h`). Use it to persist agent definitions outside of code, or to transfer them across a process/service boundary.
+
+You normally reach it through the delegators on `Riffer::Agent`:
+
+```ruby
+dict    = agent.to_h          # snapshot
+rebuilt = Riffer::Agent.from_h(dict) # reconstruct
+```
+
+The dict is plain data — symbol-keyed, JSON-safe. For the wire, use the JSON helpers, which handle generating and parsing for you:
+
+```ruby
+json    = agent.to_json       # or Riffer::Agent::Serializer.to_json(agent:)
+rebuilt = Riffer::Agent.from_json(json)
+```
+
+The hash forms (`to_h` / `from_h`) are public too, if you want to embed the dict in a larger payload. `from_h` expects symbol keys, so parse with `JSON.parse(str, symbolize_names: true)` — or just use `from_json`, which does that for you.
+
+### Runtime context
+
+`from_h` / `from_json` accept an optional `context:` — the rebuilt agent's **runtime** context, exactly the value you'd pass to `Agent.new(context:)`. It is **not** used to re-resolve the serialized definition (that's already resolved); it's threaded into tool dispatch and read by tools/runtimes at call time. Pass it when a tool or a remote runtime needs per-call data — e.g. `context: { tenant: "acme" }` for multi-tenant dispatch, or Maestro passing `context: { agent: self }` so its runtime can call back. Omit it (defaults to empty) when nothing downstream reads context.
+
+## What the dict carries
+
+```ruby
+{
+  schema_version:    1,                       # wire format version
+  riffer_version:    "0.29.1",                # diagnostic only
+  identifier:        "support_agent",
+  model:             "openai/gpt-4o",         # resolved "provider/model" string
+  instructions:      "You are…",              # resolved system prompt
+  model_options:     { temperature: 0.2 },
+  provider_options:  { … },                   # see the secrets warning below
+  max_steps:         8,                        # integer; -1 = unlimited (see below)
+  structured_output: { type: "object", … },   # JSON Schema, or null
+  tools: [ { name:, description:, parameters_schema:, timeout: }, … ]
+}
+```
+
+### Resolved snapshot
+
+`to_h` reads the agent's **resolved** state, not its raw configuration. By the time you call it, `Agent.new` has already evaluated any `Proc`-based `model`, `instructions`, or `uses_tools` against the agent's own context — so the dict carries plain strings and data, never Procs. The receiver's `context:` drives runtime behavior (tool dispatch); it does **not** re-evaluate baked-in fields.
+
+### Structured output
+
+Structured output crosses as **provider-neutral JSON Schema** (`Riffer::Params#to_json_schema`), never a provider-rendered schema. `from_h` rebuilds a validating `Riffer::Params` via `Riffer::Params.from_json_schema`, so the rebuilt agent both constrains the model and can `parse_and_validate` responses — rendering provider-correct bytes at call time, the same way an in-code agent does.
+
+## Reconstructing tools
+
+Tools cross as `{name, description, parameters_schema, timeout}` descriptors — never code. How a descriptor becomes a runnable tool is controlled by the `tool_resolver:` you pass to `from_h`. The two common shapes:
+
+### In-process (registry lookup)
+
+When the rebuilt agent runs in the **same** codebase that defined the tools (e.g. persisting an agent definition and rehydrating it later), resolve each descriptor back to its real class:
+
+```ruby
+rebuilt = Riffer::Agent.from_h(dict,
+  tool_resolver: ->(descriptor) { MyToolRegistry.fetch(descriptor[:name]) })
+```
+
+The real classes carry their `#call` bodies, so the agent runs on the default `Inline` runtime — no further wiring.
+
+### Distributed (body-less shells)
+
+When the receiver holds **only the Riffer gem**, the default `tool_resolver` synthesizes body-less **tool shells**. A shell advertises the tool's schema to the LLM but has no `#call` — invoking it in-process raises. Pair the default resolver with a remote `Riffer::Tools::Runtime` that forwards each call back to the origin:
+
+```ruby
+rebuilt = Riffer::Agent.from_h(dict,
+  tool_runtime: MyRemoteToolRuntime.new(client: rpc_client))
+```
+
+Implement the remote runtime by subclassing `Riffer::Tools::Runtime` and overriding `#dispatch_tool_call` to forward the call over your transport, mapping any failure to `Tools::Response.error`. See [Advanced Tools](07_TOOL_ADVANCED.md) for the runtime API.
+
+You own what a resolved tool does: a resolver may return real in-process classes, shells, or classes that themselves make network calls. Riffer does not require a runtime — it only ships shells by default.
+
+## `max_steps`
+
+Unlimited steps are `nil` at the agent level — set it with `max_steps nil`. On the wire, the serializer encodes that as **`-1`** (and decodes `-1` back to `nil`), so the dict stays portable across transports where JSON `null` is awkward — proto3, for one, can't distinguish `null` from an absent field. The `-1` is purely a wire detail: the DSL and your code only ever see `nil`, and the encode/decode handles the translation at the boundary.
+
+- **DSL** — integer = bounded, `nil` = unlimited, omitted = `Config`'s default (16).
+- **Wire** — integer = bounded, `-1` = unlimited, omitted = default (16).
+
+A finite integer round-trips as-is; a dict missing the key falls back to the default rather than running unbounded.
+
+## Versioning
+
+`schema_version` is an integer (`Riffer::Agent::Serializer::SCHEMA_VERSION`). `from_h` refuses any version it doesn't recognize with `Riffer::Agent::Serializer::VersionError` (a `Riffer::ArgumentError`). A future incompatible change bumps the integer and adds a backwards-compatible decoder, giving distributed consumers a window to upgrade before the old format is dropped.
+
+## Secrets
+
+`provider_options` and `model_options` **ride on the wire as plain data** — they are part of the dict and _will_ transfer. Prefer configuring API keys via environment/global provider configuration rather than `provider_options`. **Never serialize an agent whose options carry sensitive values** — and if a serialized definition ever does, handle it as a secret (encrypt it, keep it out of logs).
+
+## What does **not** transfer
+
+- **Guardrails and skills** are **not supported yet** — neither is serialized, so a rebuilt agent enforces no guardrails and has no skills catalog. (As a stopgap, a skills-enabled agent's `skill_activate` tool still crosses as an ordinary tool descriptor.) Both are expected to be revisited.
+
+## Next Steps
+
+- [Tools](06_TOOLS.md) - Creating tools
+- [Advanced Tools](07_TOOL_ADVANCED.md) - Tool runtime and dispatch
+- [Configuration](10_CONFIGURATION.md) - Global configuration

data/lib/riffer/agent/config.rb

@@ -21,7 +21,7 @@ class Riffer::Agent::Config
   attr_accessor :provider_options #: Hash[Symbol, untyped]
   attr_accessor :model_options #: Hash[Symbol, untyped]
   attr_reader :structured_output #: Riffer::Params?
-  attr_accessor :max_steps #: Numeric
+  attr_accessor :max_steps #: Numeric?
   attr_accessor :tools_config #: (Array[singleton(Riffer::Tool)] | Proc)?
   attr_reader :mcp_configs #: Array[Hash[Symbol, untyped]]
   attr_reader :tool_runtime #: (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)
@@ -35,7 +35,7 @@ class Riffer::Agent::Config
   # as a non-String, non-Proc value (or as an empty String).
   #
   #--
-  #: (?identifier: String?, ?model: (String | Proc)?, ?instructions: (String | Proc)?, ?provider_options: Hash[Symbol, untyped], ?model_options: Hash[Symbol, untyped], ?structured_output: Riffer::Params?, ?max_steps: Numeric, ?tools_config: (Array[singleton(Riffer::Tool)] | Proc)?, ?mcp_configs: Array[Hash[Symbol, untyped]], ?tool_runtime: (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc), ?skills_config: Riffer::Skills::Config?, ?guardrails: Hash[Symbol, Array[Hash[Symbol, untyped]]]) -> void
+  #: (?identifier: String?, ?model: (String | Proc)?, ?instructions: (String | Proc)?, ?provider_options: Hash[Symbol, untyped], ?model_options: Hash[Symbol, untyped], ?structured_output: Riffer::Params?, ?max_steps: Numeric?, ?tools_config: (Array[singleton(Riffer::Tool)] | Proc)?, ?mcp_configs: Array[Hash[Symbol, untyped]], ?tool_runtime: (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc), ?skills_config: Riffer::Skills::Config?, ?guardrails: Hash[Symbol, Array[Hash[Symbol, untyped]]]) -> void
   def initialize(
     identifier: nil,
     model: nil,

data/lib/riffer/agent/context.rb

@@ -19,6 +19,8 @@
 #   context.token_usage  # => nil
 #
 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]

data/lib/riffer/agent/response.rb

@@ -13,6 +13,8 @@
 #     puts response.content
 #   end
 class Riffer::Agent::Response
+  # @rbs @interrupted: bool
+
   # The response content.
   attr_reader :content #: String
 

data/lib/riffer/agent/run.rb

@@ -77,7 +77,8 @@ module Riffer::Agent::Run
 
         break unless processed_response.has_tool_calls?
 
-        throw :riffer_interrupt, Riffer::Agent::INTERRUPT_MAX_STEPS if step >= agent.config.max_steps
+        max_steps = agent.config.max_steps
+        throw :riffer_interrupt, Riffer::Agent::INTERRUPT_MAX_STEPS if max_steps && step >= max_steps
 
         execute_tool_calls(agent, processed_response)
       end

data/lib/riffer/agent/serializer.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+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.
+#
+# 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.
+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.
+  SCHEMA_VERSION = 1 #: Integer
+
+  # Raised by +from_h+ when the dict'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.
+  #
+  #--
+  #: (agent: Riffer::Agent) -> Hash[Symbol, untyped]
+  def to_h(agent:)
+    config = agent.config
+    {
+      schema_version: SCHEMA_VERSION,
+      riffer_version: Riffer::VERSION,
+      identifier: config.identifier,
+      model: "#{agent.provider_name}/#{agent.model_name}",
+      instructions: agent.instruction_message&.content,
+      model_options: config.model_options,
+      provider_options: config.provider_options,
+      max_steps: encode_max_steps(config.max_steps),
+      structured_output: config.structured_output&.to_json_schema(strict: false),
+      tools: agent.tools.map { |tool_class| tool_descriptor(tool_class) }
+    }
+  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.
+  #
+  #--
+  #: (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)
+    # Version -> decoder dispatch. Adding a +when 2+ arm (a backwards-compatible
+    # decoder) is how a future breaking change keeps older dicts readable.
+    case hash[:schema_version]
+    when SCHEMA_VERSION
+      decode_v1(hash, context: context, 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>.
+  #
+  #--
+  #: (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
+  # +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)
+  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:)
+    tools = Array(hash[:tools]).map { |descriptor| tool_resolver.call(descriptor) }
+
+    config_args = {
+      identifier: hash[:identifier],
+      model: hash[:model],
+      instructions: hash[:instructions],
+      provider_options: hash[:provider_options] || {},
+      model_options: hash[:model_options] || {},
+      structured_output: decode_structured_output(hash[:structured_output]),
+      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_args[:tool_runtime] = tool_runtime if tool_runtime
+
+    Riffer::Agent.new(config: Riffer::Agent::Config.new(**config_args), context: context)
+  end
+
+  #--
+  #: (Hash[Symbol, untyped]?) -> Riffer::Params?
+  def decode_structured_output(schema)
+    return nil if schema.nil?
+    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.
+  #--
+  #: (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.
+  #--
+  #: (Hash[Symbol, untyped]) -> Numeric?
+  def decode_max_steps(hash)
+    return Riffer::Agent::Config::DEFAULT_MAX_STEPS unless hash.key?(:max_steps)
+    (hash[:max_steps] == -1) ? nil : hash[:max_steps]
+  end
+
+  #--
+  #: (singleton(Riffer::Tool)) -> Hash[Symbol, untyped]
+  def tool_descriptor(tool_class)
+    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)
+    tool_name = descriptor[:name]
+    tool_description = descriptor[:description]
+    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.
+    Class.new(Riffer::Tool) do
+      # steep:ignore:start
+      identifier tool_name
+      description tool_description
+      timeout tool_timeout if tool_timeout
+      define_singleton_method(:parameters_schema) { |strict: false| schema }
+
+      define_method(:call) do |context:, **kwargs|
+        raise Riffer::Error,
+          "#{self.class.name || "wire tool shell"} '#{self.class.identifier}' has no body; " \
+          "route its calls through a remote Riffer::Tools::Runtime (see Riffer::Agent::Serializer)"
+      end
+      # steep:ignore:end
+    end
+  end
+end

data/lib/riffer/agent/session.rb

@@ -18,6 +18,8 @@
 class Riffer::Agent::Session
   include Enumerable #[Riffer::Messages::Base]
 
+  # @rbs @callbacks: Array[^(Riffer::Messages::Base) -> void]
+
   # The message history.
   attr_reader :messages #: Array[Riffer::Messages::Base]