riffer 0.29.1 → 0.30.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 91f54f388c63e670d155ae2b8d84bdafe18edd2f29423d92b52c9bfb686332d3
-  data.tar.gz: 7b1bc3bb32951cadbadfe4ba388ca4dc805849a2724cbfae944daf1a59ea241c
+  metadata.gz: 7557c63ca04fa006d66a61a53bef6b1f7069ebab67439f00104fbb877d1aceda
+  data.tar.gz: 39bbe45b7e111ae343e32c54b9769db17dd7d8d9b98cd5cb7d42338aa5e4179c
 SHA512:
-  metadata.gz: 5e573dd0b3ad056266a7c8a88b24754a510ceac1737f730cedf98e73dc18be17e2f9dc93ebe47d4c89e2d483c1c40c40a7fcbad586ba1ceac949b11af2011a8c
-  data.tar.gz: c1aa387e0298c3999da9da89a640a86048207dd54abe6a336781a9dd265acec49939729fcca7378872efa595131357601b5639b2437508225470fe473a9a5989
+  metadata.gz: 61694198a05d63d831dca9b4b37e38b6cacbd7b67214fa47c2027a0a7e1636ee07e5f85641f9fe00ee597d66dfdb0a6fccd0e494b6ec670a84a2020907cfdd0b
+  data.tar.gz: fbff4457d39da36a1c77e9cb7ea86ccb5e96f0887ba982f6a8a960557ee4beceda3a604011fcfd20951f9baedd59eadbf188832cb6bcc8fcf71e256d93e8cdc3

data/.release-please-manifest.json

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

data/CHANGELOG.md

@@ -5,6 +5,17 @@ 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)
 
 

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/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/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.rb

@@ -102,13 +102,19 @@ class Riffer::Agent
 
   # Gets or sets the maximum number of LLM call steps in the tool-use loop.
   #
-  # Defaults to Riffer::Agent::Config::DEFAULT_MAX_STEPS (16). Set to
-  # +Float::INFINITY+ for unlimited steps.
+  # Defaults to Riffer::Agent::Config::DEFAULT_MAX_STEPS (16). Set to +nil+
+  # for unlimited steps. The splat distinguishes a getter call (no argument)
+  # from setting the limit to +nil+.
+  #
+  #   max_steps        # reads the current limit
+  #   max_steps 8      # cap the loop at 8 steps
+  #   max_steps nil    # unlimited
   #
   #--
-  #: (?Numeric?) -> Numeric
-  def self.max_steps(value = nil)
-    value.nil? ? config.max_steps : (config.max_steps = value)
+  #: (*Numeric?) -> Numeric?
+  def self.max_steps(*value)
+    return config.max_steps if value.empty?
+    config.max_steps = value.first
   end
 
   # Gets or sets the tools used by this agent.
@@ -206,6 +212,30 @@ class Riffer::Agent
     new(context: context).stream(prompt, files: files)
   end
 
+  # Reconstructs a runnable agent from a wire dict produced by +#to_h+.
+  #
+  # Delegates to Riffer::Agent::Serializer.from_h. See it for the
+  # +tool_resolver+ / +tool_runtime+ injection points and what does not
+  # transfer.
+  #
+  #--
+  #: (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 self.from_h(hash, context: nil, tool_resolver: Riffer::Agent::Serializer::DEFAULT_TOOL_RESOLVER, tool_runtime: nil)
+    Riffer::Agent::Serializer.from_h(hash, context: context, tool_resolver: tool_resolver, tool_runtime: tool_runtime)
+  end
+
+  # Reconstructs a runnable agent from a JSON string produced by +#to_json+.
+  #
+  # Delegates to Riffer::Agent::Serializer.from_json, which parses the JSON
+  # (with symbol keys) for you. See Riffer::Agent::Serializer.from_h for the
+  # +tool_resolver+ / +tool_runtime+ injection points.
+  #
+  #--
+  #: (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 self.from_json(json, context: nil, tool_resolver: Riffer::Agent::Serializer::DEFAULT_TOOL_RESOLVER, tool_runtime: nil)
+    Riffer::Agent::Serializer.from_json(json, context: context, tool_resolver: tool_resolver, tool_runtime: tool_runtime)
+  end
+
   # Registers a guardrail for input, output, or both phases.
   #
   # [phase] :before, :after, or :around.
@@ -261,6 +291,11 @@ class Riffer::Agent
   #   reserved and cannot be passed by the caller.
   attr_reader :context #: Riffer::Agent::Context
 
+  # The resolved provider name (the part before "provider/"), e.g. +"openai"+.
+  # Resolved eagerly at +Agent.new+ alongside +model_name+; together they
+  # form the provider-neutral model identifier the agent serializes.
+  attr_reader :provider_name #: String
+
   # The resolved model name (the part after "provider/"), used as the model
   # argument on every LLM call. Resolved eagerly at +Agent.new+.
   attr_reader :model_name #: String
@@ -308,10 +343,10 @@ class Riffer::Agent
     @config = config || self.class.config
     @context = Riffer::Agent::Context.new(context || {})
 
-    provider_class, @model_name = resolve_provider_and_model
-    @provider = provider_class.new(**@config.provider_options)
+    @provider_name, @model_name = resolve_provider_and_model
+    @provider = build_provider
 
-    @context.skills = resolve_skills(provider_class)
+    @context.skills = resolve_skills
 
     @structured_output = resolve_structured_output
     @tools = resolve_tools
@@ -376,6 +411,25 @@ class Riffer::Agent
     throw :riffer_interrupt, reason
   end
 
+  # Snapshots this resolved agent into a self-contained, provider-neutral
+  # wire dict. Delegates to Riffer::Agent::Serializer.to_h.
+  #
+  #--
+  #: () -> Hash[Symbol, untyped]
+  def to_h
+    Riffer::Agent::Serializer.to_h(agent: self)
+  end
+
+  # Snapshots this resolved agent into a wire JSON string. Delegates to
+  # Riffer::Agent::Serializer.to_json. The +*+ absorbs the JSON generator
+  # state argument so <tt>JSON.generate(agent)</tt> works too.
+  #
+  #--
+  #: (*untyped) -> String
+  def to_json(*)
+    Riffer::Agent::Serializer.to_json(agent: self)
+  end
+
   private
 
   #--
@@ -395,13 +449,13 @@ class Riffer::Agent
   end
 
   # Resolves +Config#model+ to a "provider/model" string (calling the Proc
-  # form against +@context+), parses it, and looks up the provider class.
+  # form against +@context+) and parses it.
   #
-  # Returns +[provider_class, model_name]+. Raises Riffer::ArgumentError on
-  # an invalid model string or an unregistered provider.
+  # Returns +[provider_name, model_name]+. Raises Riffer::ArgumentError on an
+  # invalid model string.
   #
   #--
-  #: () -> [singleton(Riffer::Providers::Base), String]
+  #: () -> [String, String]
   def resolve_provider_and_model
     model_string = Riffer::Helpers::CallOrValue.resolve(@config.model, context: @context)
     raise Riffer::ArgumentError, "Invalid model string: #{model_string}" unless model_string.is_a?(String)
@@ -412,18 +466,28 @@ class Riffer::Agent
       raise Riffer::ArgumentError, "Invalid model string: #{model_string}"
     end
 
-    provider_class = Riffer::Providers::Repository.find(provider_name)
-    raise Riffer::ArgumentError, "Provider not found: #{provider_name}" unless provider_class
+    [provider_name, model_name]
+  end
 
-    [provider_class, model_name]
+  # Builds the provider client from the resolved +@provider_name+ and the
+  # configured +provider_options+.
+  #
+  # Raises Riffer::ArgumentError on an unregistered provider.
+  #
+  #--
+  #: () -> Riffer::Providers::Base
+  def build_provider
+    provider_class = Riffer::Providers::Repository.find(@provider_name)
+    raise Riffer::ArgumentError, "Provider not found: #{@provider_name}" unless provider_class
+    provider_class.new(**@config.provider_options)
   end
 
   # Resolves the skills backend, lists skills, and selects an adapter.
   # Returns nil if skills are unconfigured or the backend is empty.
   #
   #--
-  #: (singleton(Riffer::Providers::Base)) -> Riffer::Skills::Context?
-  def resolve_skills(provider_class)
+  #: () -> Riffer::Skills::Context?
+  def resolve_skills
     skills_config = @config.skills_config
     return nil unless skills_config
 
@@ -434,7 +498,7 @@ class Riffer::Agent
     return nil if backend.list_skills.empty?
 
     skills = backend.list_skills.to_h { |s| [s.name, s] }
-    adapter_class = skills_config.adapter || provider_class.skills_adapter(@model_name)
+    adapter_class = skills_config.adapter || @provider.class.skills_adapter(@model_name)
     skill_activate_tool_class = skills_config.activate_tool || Riffer.config.skills.default_activate_tool
 
     skills_context = Riffer::Skills::Context.new(

data/lib/riffer/params/param.rb

@@ -18,19 +18,90 @@ class Riffer::Params::Param
   }.freeze #: Hash[Module, String]
 
   # Primitive types allowed for the <tt>of:</tt> keyword on Array params
-  PRIMITIVE_TYPES = (TYPE_MAPPINGS.keys - [Array, Hash]).freeze #: Array[Class]
+  PRIMITIVE_TYPES = (TYPE_MAPPINGS.keys - [Array, Hash]).freeze #: Array[Module]
+
+  # Maps JSON Schema type strings back to Ruby types. The inverse of
+  # TYPE_MAPPINGS, collapsing the three boolean spellings onto
+  # Riffer::Params::Boolean. Used by +from_json_schema+.
+  JSON_TYPE_MAPPINGS = {
+    "string" => String,
+    "integer" => Integer,
+    "number" => Float,
+    "boolean" => Riffer::Params::Boolean,
+    "array" => Array,
+    "object" => Hash
+  }.freeze #: Hash[String, Module]
 
   attr_reader :name #: Symbol
-  attr_reader :type #: Class
+  attr_reader :type #: Module
   attr_reader :required #: bool
   attr_reader :description #: String?
   attr_reader :enum #: Array[untyped]?
   attr_reader :default #: untyped
-  attr_reader :item_type #: Class?
+  attr_reader :item_type #: Module?
   attr_reader :nested_params #: Riffer::Params?
 
   #--
-  #: (name: Symbol, type: Class, required: bool, ?description: String?, ?enum: Array[untyped]?, ?default: untyped, ?item_type: Class?, ?nested_params: Riffer::Params?) -> void
+  # Reconstructs a Param from a single JSON Schema property.
+  #
+  # [name] the parameter name (Symbol).
+  # [schema] the property's JSON Schema (Symbol-keyed).
+  # [required] whether the property appeared in the parent's +required+ list.
+  #
+  # Raises Riffer::ArgumentError on a type outside the Params-expressible subset.
+  #
+  #--
+  #: (Symbol, Hash[Symbol, untyped], required: bool) -> Riffer::Params::Param
+  def self.from_json_schema(name, schema, required:)
+    ruby_type = json_type_to_ruby(schema[:type])
+    item_type, nested = resolve_nesting(ruby_type, schema)
+
+    new(
+      name: name,
+      type: ruby_type,
+      required: required,
+      description: schema[:description],
+      enum: schema[:enum],
+      default: schema[:default],
+      item_type: item_type,
+      nested_params: nested
+    )
+  end
+
+  # Resolves the +[item_type, nested_params]+ pair for a reconstructed Param:
+  # a nested Params for object / array-of-object schemas, an +item_type+ for
+  # typed primitive arrays, and +nil+ for everything else.
+  #
+  #--
+  #: (Module, Hash[Symbol, untyped]) -> [Module?, Riffer::Params?]
+  def self.resolve_nesting(ruby_type, schema)
+    return [nil, Riffer::Params.from_json_schema(schema)] if ruby_type == Hash && schema[:properties]
+    return [nil, nil] unless ruby_type == Array
+
+    items = schema[:items]
+    return [nil, nil] unless items.is_a?(Hash)
+    return [nil, Riffer::Params.from_json_schema(items)] if items[:properties]
+
+    [json_type_to_ruby(items[:type]), nil]
+  end
+  private_class_method :resolve_nesting
+
+  # Resolves a JSON Schema +type+ (a String, or a <tt>[type, "null"]</tt>
+  # union) back to its Ruby type. Returns a Module because
+  # Riffer::Params::Boolean is a Module, not a Class — the same widening the
+  # +type+ attribute uses. Raises Riffer::ArgumentError on a type outside the
+  # Params-expressible subset (the block runs only for an unmapped type).
+  #
+  #--
+  #: (untyped) -> Module
+  def self.json_type_to_ruby(type)
+    key = type.is_a?(Array) ? type.find { |t| t != "null" } : type
+    JSON_TYPE_MAPPINGS.fetch(key) { raise Riffer::ArgumentError, "Unsupported JSON Schema type: #{type.inspect}" }
+  end
+  private_class_method :json_type_to_ruby
+
+  #--
+  #: (name: Symbol, type: Module, required: bool, ?description: String?, ?enum: Array[untyped]?, ?default: untyped, ?item_type: Module?, ?nested_params: Riffer::Params?) -> void
   def initialize(name:, type:, required:, description: nil, enum: nil, default: nil, item_type: nil, nested_params: nil)
     @name = name.to_sym
     @type = type
@@ -74,6 +145,11 @@ class Riffer::Params::Param
   # constraint from the null type, since providers like Anthropic reject
   # <tt>{"type": ["string", "null"], "enum": [...]}</tt>.
   #
+  # In non-strict mode a +default+ is emitted when set (a standard JSON
+  # Schema keyword), making the schema a lossless source for
+  # +Riffer::Params.from_json_schema+. Strict mode omits it, since strict
+  # providers reject the keyword.
+  #
   #--
   #: (?strict: bool) -> Hash[Symbol, untyped]
   def to_json_schema(strict: false)
@@ -91,6 +167,10 @@ class Riffer::Params::Param
     schema = {type: type} #: Hash[Symbol, untyped]
     schema[:description] = description if description
     schema[:enum] = enum if enum
+    # Strict providers reject the +default+ keyword; emit it only in
+    # non-strict mode, where it makes the schema a lossless round-trip
+    # source for +from_json_schema+.
+    schema[:default] = default unless strict || default.nil?
 
     if self.type == Array && nested_params
       schema[:items] = nested_params.to_json_schema(strict: strict)

data/lib/riffer/params.rb

@@ -20,10 +20,41 @@ class Riffer::Params
     @parameters = []
   end
 
+  # Reconstructs a Params from a JSON Schema object (the inverse of
+  # +to_json_schema(strict: false)+).
+  #
+  # Accepts the Symbol-keyed object schema produced by +to_json_schema+
+  # (property-name keys may be String or Symbol — both are normalized).
+  # Reconstructs types, +required+, +description+, +enum+, +default+,
+  # typed-array +item_type+, and nested object/array Params recursively.
+  #
+  # Round-trips losslessly with +to_json_schema(strict: false)+ over the
+  # Params-expressible subset of JSON Schema. Raises Riffer::ArgumentError
+  # on a schema using features outside that subset.
+  #
+  #   schema = params.to_json_schema(strict: false)
+  #   Riffer::Params.from_json_schema(schema) # => equivalent Riffer::Params
+  #
+  #--
+  #: (Hash[Symbol, untyped]) -> Riffer::Params
+  def self.from_json_schema(schema)
+    params = new
+    properties = schema[:properties] || {}
+    required = (schema[:required] || []).map { |key| key.to_s }
+
+    properties.each do |name, property_schema|
+      params.parameters << Riffer::Params::Param.from_json_schema(
+        name.to_sym, property_schema, required: required.include?(name.to_s)
+      )
+    end
+
+    params
+  end
+
   # Defines a required parameter.
   #
   #--
-  #: (Symbol, Class, ?description: String?, ?enum: Array[untyped]?, ?of: Class?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> void
+  #: (Symbol, Module, ?description: String?, ?enum: Array[untyped]?, ?of: Module?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> void
   def required(name, type, description: nil, enum: nil, of: nil, &block)
     nested = build_nested(type, of, &block)
     @parameters << Riffer::Params::Param.new(
@@ -40,7 +71,7 @@ class Riffer::Params
   # Defines an optional parameter.
   #
   #--
-  #: (Symbol, Class, ?description: String?, ?enum: Array[untyped]?, ?default: untyped, ?of: Class?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> void
+  #: (Symbol, Module, ?description: String?, ?enum: Array[untyped]?, ?default: untyped, ?of: Module?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> void
   def optional(name, type, description: nil, enum: nil, default: nil, of: nil, &block)
     nested = build_nested(type, of, &block)
     @parameters << Riffer::Params::Param.new(
@@ -126,7 +157,7 @@ class Riffer::Params
   private
 
   #--
-  #: (Class, Class?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> Riffer::Params?
+  #: (Module, Module?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> Riffer::Params?
   def build_nested(type, of, &block)
     if of && block
       raise Riffer::ArgumentError, "cannot use both of: and a block"

data/lib/riffer/version.rb

@@ -2,5 +2,5 @@
 # rbs_inline: enabled
 
 module Riffer
-  VERSION = "0.29.1" #: String
+  VERSION = "0.30.0" #: String
 end

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

@@ -26,7 +26,7 @@ class Riffer::Agent::Config
 
   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)?
 
@@ -45,8 +45,8 @@ 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
-  def initialize: (?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: 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
 
   # Sets +identifier+. Accepts +nil+ or any value, coerced to String.
   #

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

@@ -0,0 +1,132 @@
+# Generated from lib/riffer/agent/serializer.rb with RBS::Inline
+
+# 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
+  # 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: 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: ^(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: Riffer::Agent) -> Hash[Symbol, untyped]
+
+  # 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[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
+
+  # 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: Riffer::Agent) -> String
+
+  # 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: (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
+
+  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[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
+
+  # --
+  # : (Hash[Symbol, untyped]?) -> Riffer::Params?
+  def decode_structured_output: (Hash[Symbol, untyped]?) -> Riffer::Params?
+
+  # 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: (Numeric?) -> Numeric
+
+  # 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[Symbol, untyped]) -> Numeric?
+
+  # --
+  # : (singleton(Riffer::Tool)) -> Hash[Symbol, untyped]
+  def tool_descriptor: (singleton(Riffer::Tool)) -> Hash[Symbol, untyped]
+
+  # 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: (Hash[Symbol, untyped]) -> untyped
+end

data/sig/generated/riffer/agent.rbs

@@ -80,12 +80,17 @@ class Riffer::Agent
 
   # Gets or sets the maximum number of LLM call steps in the tool-use loop.
   #
-  # Defaults to Riffer::Agent::Config::DEFAULT_MAX_STEPS (16). Set to
-  # +Float::INFINITY+ for unlimited steps.
+  # Defaults to Riffer::Agent::Config::DEFAULT_MAX_STEPS (16). Set to +nil+
+  # for unlimited steps. The splat distinguishes a getter call (no argument)
+  # from setting the limit to +nil+.
+  #
+  #   max_steps        # reads the current limit
+  #   max_steps 8      # cap the loop at 8 steps
+  #   max_steps nil    # unlimited
   #
   # --
-  # : (?Numeric?) -> Numeric
-  def self.max_steps: (?Numeric?) -> Numeric
+  # : (*Numeric?) -> Numeric?
+  def self.max_steps: (*Numeric?) -> Numeric?
 
   # Gets or sets the tools used by this agent.
   #
@@ -159,6 +164,26 @@ class Riffer::Agent
   # : (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?context: Hash[Symbol, untyped]?) -> Enumerator[Riffer::StreamEvents::Base, void]
   def self.stream: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?context: Hash[Symbol, untyped]?) -> Enumerator[Riffer::StreamEvents::Base, void]
 
+  # Reconstructs a runnable agent from a wire dict produced by +#to_h+.
+  #
+  # Delegates to Riffer::Agent::Serializer.from_h. See it for the
+  # +tool_resolver+ / +tool_runtime+ injection points and what does not
+  # transfer.
+  #
+  # --
+  # : (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 self.from_h: (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
+
+  # Reconstructs a runnable agent from a JSON string produced by +#to_json+.
+  #
+  # Delegates to Riffer::Agent::Serializer.from_json, which parses the JSON
+  # (with symbol keys) for you. See Riffer::Agent::Serializer.from_h for the
+  # +tool_resolver+ / +tool_runtime+ injection points.
+  #
+  # --
+  # : (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 self.from_json: (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
+
   # Registers a guardrail for input, output, or both phases.
   #
   # [phase] :before, :after, or :around.
@@ -210,6 +235,11 @@ class Riffer::Agent
   #   reserved and cannot be passed by the caller.
   attr_reader context: Riffer::Agent::Context
 
+  # The resolved provider name (the part before "provider/"), e.g. +"openai"+.
+  # Resolved eagerly at +Agent.new+ alongside +model_name+; together they
+  # form the provider-neutral model identifier the agent serializes.
+  attr_reader provider_name: String
+
   # The resolved model name (the part after "provider/"), used as the model
   # argument on every LLM call. Resolved eagerly at +Agent.new+.
   attr_reader model_name: String
@@ -300,6 +330,21 @@ class Riffer::Agent
   # : (?(String | Symbol)?) -> void
   def interrupt!: (?(String | Symbol)?) -> void
 
+  # Snapshots this resolved agent into a self-contained, provider-neutral
+  # wire dict. Delegates to Riffer::Agent::Serializer.to_h.
+  #
+  # --
+  # : () -> Hash[Symbol, untyped]
+  def to_h: () -> Hash[Symbol, untyped]
+
+  # Snapshots this resolved agent into a wire JSON string. Delegates to
+  # Riffer::Agent::Serializer.to_json. The +*+ absorbs the JSON generator
+  # state argument so <tt>JSON.generate(agent)</tt> works too.
+  #
+  # --
+  # : (*untyped) -> String
+  def to_json: (*untyped) -> String
+
   private
 
   # --
@@ -311,21 +356,30 @@ class Riffer::Agent
   def build_skills_message: () -> Riffer::Messages::System?
 
   # Resolves +Config#model+ to a "provider/model" string (calling the Proc
-  # form against +@context+), parses it, and looks up the provider class.
+  # form against +@context+) and parses it.
+  #
+  # Returns +[provider_name, model_name]+. Raises Riffer::ArgumentError on an
+  # invalid model string.
+  #
+  # --
+  # : () -> [String, String]
+  def resolve_provider_and_model: () -> [ String, String ]
+
+  # Builds the provider client from the resolved +@provider_name+ and the
+  # configured +provider_options+.
   #
-  # Returns +[provider_class, model_name]+. Raises Riffer::ArgumentError on
-  # an invalid model string or an unregistered provider.
+  # Raises Riffer::ArgumentError on an unregistered provider.
   #
   # --
-  # : () -> [singleton(Riffer::Providers::Base), String]
-  def resolve_provider_and_model: () -> [ singleton(Riffer::Providers::Base), String ]
+  # : () -> Riffer::Providers::Base
+  def build_provider: () -> Riffer::Providers::Base
 
   # Resolves the skills backend, lists skills, and selects an adapter.
   # Returns nil if skills are unconfigured or the backend is empty.
   #
   # --
-  # : (singleton(Riffer::Providers::Base)) -> Riffer::Skills::Context?
-  def resolve_skills: (singleton(Riffer::Providers::Base)) -> Riffer::Skills::Context?
+  # : () -> Riffer::Skills::Context?
+  def resolve_skills: () -> Riffer::Skills::Context?
 
   # --
   # : () -> Riffer::Agent::StructuredOutput?

data/sig/generated/riffer/params/param.rbs

@@ -8,11 +8,16 @@ class Riffer::Params::Param
   TYPE_MAPPINGS: Hash[Module, String]
 
   # Primitive types allowed for the <tt>of:</tt> keyword on Array params
-  PRIMITIVE_TYPES: Array[Class]
+  PRIMITIVE_TYPES: Array[Module]
+
+  # Maps JSON Schema type strings back to Ruby types. The inverse of
+  # TYPE_MAPPINGS, collapsing the three boolean spellings onto
+  # Riffer::Params::Boolean. Used by +from_json_schema+.
+  JSON_TYPE_MAPPINGS: Hash[String, Module]
 
   attr_reader name: Symbol
 
-  attr_reader type: Class
+  attr_reader type: Module
 
   attr_reader required: bool
 
@@ -22,13 +27,44 @@ class Riffer::Params::Param
 
   attr_reader default: untyped
 
-  attr_reader item_type: Class?
+  attr_reader item_type: Module?
 
   attr_reader nested_params: Riffer::Params?
 
   # --
-  # : (name: Symbol, type: Class, required: bool, ?description: String?, ?enum: Array[untyped]?, ?default: untyped, ?item_type: Class?, ?nested_params: Riffer::Params?) -> void
-  def initialize: (name: Symbol, type: Class, required: bool, ?description: String?, ?enum: Array[untyped]?, ?default: untyped, ?item_type: Class?, ?nested_params: Riffer::Params?) -> void
+  #  Reconstructs a Param from a single JSON Schema property.
+  #
+  #  [name] the parameter name (Symbol).
+  #  [schema] the property's JSON Schema (Symbol-keyed).
+  #  [required] whether the property appeared in the parent's +required+ list.
+  #
+  #  Raises Riffer::ArgumentError on a type outside the Params-expressible subset.
+  #
+  # --
+  # : (Symbol, Hash[Symbol, untyped], required: bool) -> Riffer::Params::Param
+  def self.from_json_schema: (Symbol, Hash[Symbol, untyped], required: bool) -> Riffer::Params::Param
+
+  # Resolves the +[item_type, nested_params]+ pair for a reconstructed Param:
+  # a nested Params for object / array-of-object schemas, an +item_type+ for
+  # typed primitive arrays, and +nil+ for everything else.
+  #
+  # --
+  # : (Module, Hash[Symbol, untyped]) -> [Module?, Riffer::Params?]
+  def self.resolve_nesting: (Module, Hash[Symbol, untyped]) -> [ Module?, Riffer::Params? ]
+
+  # Resolves a JSON Schema +type+ (a String, or a <tt>[type, "null"]</tt>
+  # union) back to its Ruby type. Returns a Module because
+  # Riffer::Params::Boolean is a Module, not a Class — the same widening the
+  # +type+ attribute uses. Raises Riffer::ArgumentError on a type outside the
+  # Params-expressible subset (the block runs only for an unmapped type).
+  #
+  # --
+  # : (untyped) -> Module
+  def self.json_type_to_ruby: (untyped) -> Module
+
+  # --
+  # : (name: Symbol, type: Module, required: bool, ?description: String?, ?enum: Array[untyped]?, ?default: untyped, ?item_type: Module?, ?nested_params: Riffer::Params?) -> void
+  def initialize: (name: Symbol, type: Module, required: bool, ?description: String?, ?enum: Array[untyped]?, ?default: untyped, ?item_type: Module?, ?nested_params: Riffer::Params?) -> void
 
   # Validates that a value matches the expected type.
   #
@@ -52,6 +88,11 @@ class Riffer::Params::Param
   # constraint from the null type, since providers like Anthropic reject
   # <tt>{"type": ["string", "null"], "enum": [...]}</tt>.
   #
+  # In non-strict mode a +default+ is emitted when set (a standard JSON
+  # Schema keyword), making the schema a lossless source for
+  # +Riffer::Params.from_json_schema+. Strict mode omits it, since strict
+  # providers reject the keyword.
+  #
   # --
   # : (?strict: bool) -> Hash[Symbol, untyped]
   def to_json_schema: (?strict: bool) -> Hash[Symbol, untyped]

data/sig/generated/riffer/params.rbs

@@ -16,17 +16,36 @@ class Riffer::Params
   # : () -> void
   def initialize: () -> void
 
+  # Reconstructs a Params from a JSON Schema object (the inverse of
+  # +to_json_schema(strict: false)+).
+  #
+  # Accepts the Symbol-keyed object schema produced by +to_json_schema+
+  # (property-name keys may be String or Symbol — both are normalized).
+  # Reconstructs types, +required+, +description+, +enum+, +default+,
+  # typed-array +item_type+, and nested object/array Params recursively.
+  #
+  # Round-trips losslessly with +to_json_schema(strict: false)+ over the
+  # Params-expressible subset of JSON Schema. Raises Riffer::ArgumentError
+  # on a schema using features outside that subset.
+  #
+  #   schema = params.to_json_schema(strict: false)
+  #   Riffer::Params.from_json_schema(schema) # => equivalent Riffer::Params
+  #
+  # --
+  # : (Hash[Symbol, untyped]) -> Riffer::Params
+  def self.from_json_schema: (Hash[Symbol, untyped]) -> Riffer::Params
+
   # Defines a required parameter.
   #
   # --
-  # : (Symbol, Class, ?description: String?, ?enum: Array[untyped]?, ?of: Class?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> void
-  def required: (Symbol, Class, ?description: String?, ?enum: Array[untyped]?, ?of: Class?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> void
+  # : (Symbol, Module, ?description: String?, ?enum: Array[untyped]?, ?of: Module?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> void
+  def required: (Symbol, Module, ?description: String?, ?enum: Array[untyped]?, ?of: Module?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> void
 
   # Defines an optional parameter.
   #
   # --
-  # : (Symbol, Class, ?description: String?, ?enum: Array[untyped]?, ?default: untyped, ?of: Class?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> void
-  def optional: (Symbol, Class, ?description: String?, ?enum: Array[untyped]?, ?default: untyped, ?of: Class?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> void
+  # : (Symbol, Module, ?description: String?, ?enum: Array[untyped]?, ?default: untyped, ?of: Module?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> void
+  def optional: (Symbol, Module, ?description: String?, ?enum: Array[untyped]?, ?default: untyped, ?of: Module?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> void
 
   # Validates arguments against parameter definitions.
   #
@@ -49,8 +68,8 @@ class Riffer::Params
   private
 
   # --
-  # : (Class, Class?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> Riffer::Params?
-  def build_nested: (Class, Class?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> Riffer::Params?
+  # : (Module, Module?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> Riffer::Params?
+  def build_nested: (Module, Module?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> Riffer::Params?
 
   # --
   # : (Riffer::Params::Param, untyped, Array[String]) -> untyped

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

@@ -0,0 +1,5 @@
+# `Riffer::Agent::Serializer` uses `extend self`; rbs-inline doesn't emit that,
+# so re-extend here to expose its instance methods as singleton methods.
+module Riffer::Agent::Serializer
+  extend ::Riffer::Agent::Serializer
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: riffer
 version: !ruby/object:Gem::Version
-  version: 0.29.1
+  version: 0.30.0
 platform: ruby
 authors:
 - Jake Bottrall
@@ -277,6 +277,7 @@ files:
 - docs/12_GUARDRAILS.md
 - docs/13_SKILLS.md
 - docs/14_MCP.md
+- docs/15_SERIALIZATION.md
 - docs/providers/01_PROVIDERS.md
 - docs/providers/02_AMAZON_BEDROCK.md
 - docs/providers/03_ANTHROPIC.md
@@ -292,6 +293,7 @@ files:
 - lib/riffer/agent/context.rb
 - lib/riffer/agent/response.rb
 - lib/riffer/agent/run.rb
+- lib/riffer/agent/serializer.rb
 - lib/riffer/agent/session.rb
 - lib/riffer/agent/session/repair.rb
 - lib/riffer/agent/structured_output.rb
@@ -398,6 +400,7 @@ files:
 - sig/generated/riffer/agent/context.rbs
 - sig/generated/riffer/agent/response.rbs
 - sig/generated/riffer/agent/run.rbs
+- sig/generated/riffer/agent/serializer.rbs
 - sig/generated/riffer/agent/session.rbs
 - sig/generated/riffer/agent/session/repair.rbs
 - sig/generated/riffer/agent/structured_output.rbs
@@ -489,6 +492,7 @@ files:
 - sig/generated/riffer/version.rbs
 - sig/manifest.yaml
 - sig/manual/riffer/agent/run.rbs
+- sig/manual/riffer/agent/serializer.rbs
 - sig/manual/riffer/helpers/call_or_value.rbs
 - sig/manual/riffer/tools/toolable.rbs
 homepage: https://riffer.ai