riffer 0.29.0 → 0.30.0

data/lib/riffer/providers/open_ai.rb

@@ -66,15 +66,16 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
   end
 
   #--
-  #: (Hash[Symbol, untyped]) -> OpenAI::Models::Responses::Response
+  #: (Hash[Symbol, untyped]) -> untyped
   def execute_generate(params)
     @client.responses.create(params)
   end
 
   #--
-  #: (OpenAI::Models::Responses::Response) -> Riffer::Providers::TokenUsage?
+  #: (untyped) -> Riffer::Providers::TokenUsage?
   def extract_token_usage(response)
-    usage = response.usage
+    typed_response = response #: OpenAI::Models::Responses::Response
+    usage = typed_response.usage
     return nil unless usage
 
     Riffer::Providers::TokenUsage.new(
@@ -84,11 +85,12 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
   end
 
   #--
-  #: (OpenAI::Models::Responses::Response) -> String
+  #: (untyped) -> String
   def extract_content(response)
+    typed_response = response #: OpenAI::Models::Responses::Response
     text_content = ""
 
-    response.output.each do |item|
+    typed_response.output.each do |item|
       next unless item.is_a?(::OpenAI::Models::Responses::ResponseOutputMessage)
 
       text_block = item.content.find { |c| c.is_a?(::OpenAI::Models::Responses::ResponseOutputText) }
@@ -99,11 +101,12 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
   end
 
   #--
-  #: (OpenAI::Models::Responses::Response) -> Array[Riffer::Messages::Assistant::ToolCall]
+  #: (untyped) -> Array[Riffer::Messages::Assistant::ToolCall]
   def extract_tool_calls(response)
+    typed_response = response #: OpenAI::Models::Responses::Response
     tool_calls = [] #: Array[Riffer::Messages::Assistant::ToolCall]
 
-    response.output.each do |item|
+    typed_response.output.each do |item|
       next unless item.is_a?(::OpenAI::Models::Responses::ResponseFunctionToolCall)
 
       tool_calls << Riffer::Messages::Assistant::ToolCall.new(

data/lib/riffer/providers/open_router.rb

@@ -64,15 +64,16 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
   end
 
   #--
-  #: (Hash[Symbol, untyped]) -> OpenAI::Models::Chat::ChatCompletion
+  #: (Hash[Symbol, untyped]) -> untyped
   def execute_generate(params)
     @client.chat.completions.create(**params)
   end
 
   #--
-  #: (OpenAI::Models::Chat::ChatCompletion) -> Riffer::Providers::TokenUsage?
+  #: (untyped) -> Riffer::Providers::TokenUsage?
   def extract_token_usage(response)
-    usage = response.usage
+    typed_response = response #: OpenAI::Models::Chat::ChatCompletion
+    usage = typed_response.usage
     return nil unless usage
 
     Riffer::Providers::TokenUsage.new(
@@ -82,15 +83,17 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
   end
 
   #--
-  #: (OpenAI::Models::Chat::ChatCompletion) -> String
+  #: (untyped) -> String
   def extract_content(response)
-    response.choices.first&.message&.content || ""
+    typed_response = response #: OpenAI::Models::Chat::ChatCompletion
+    typed_response.choices.first&.message&.content || ""
   end
 
   #--
-  #: (OpenAI::Models::Chat::ChatCompletion) -> Array[Riffer::Messages::Assistant::ToolCall]
+  #: (untyped) -> Array[Riffer::Messages::Assistant::ToolCall]
   def extract_tool_calls(response)
-    message = response.choices.first&.message
+    typed_response = response #: OpenAI::Models::Chat::ChatCompletion
+    message = typed_response.choices.first&.message
     return [] unless message
 
     tool_calls = message.tool_calls
@@ -145,9 +148,10 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
   end
 
   #--
-  #: (OpenAI::Models::Chat::ChatCompletionChunk, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  #: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
   def handle_stream_chunk(chunk, state:, yielder:)
-    choice = chunk.choices&.first
+    typed_chunk = chunk #: OpenAI::Models::Chat::ChatCompletionChunk
+    choice = typed_chunk.choices&.first
     delta = choice&.delta
 
     if delta
@@ -160,20 +164,21 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
       emit_tool_call_done_events(state: state, yielder: yielder)
     end
 
-    return unless chunk.usage
+    return unless typed_chunk.usage
 
     yielder << Riffer::StreamEvents::TokenUsageDone.new(
       token_usage: Riffer::Providers::TokenUsage.new(
-        input_tokens: chunk.usage.prompt_tokens,
-        output_tokens: chunk.usage.completion_tokens
+        input_tokens: typed_chunk.usage.prompt_tokens,
+        output_tokens: typed_chunk.usage.completion_tokens
       )
     )
   end
 
   #--
-  #: (OpenAI::Models::Chat::ChatCompletionChunk::Choice::Delta, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  #: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
   def handle_text_delta(delta, state:, yielder:)
-    content = delta.content
+    typed_delta = delta #: OpenAI::Models::Chat::ChatCompletionChunk::Choice::Delta
+    content = typed_delta.content
     return if content.nil? || content.empty?
 
     state[:text] << content
@@ -194,9 +199,10 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
   end
 
   #--
-  #: (OpenAI::Models::Chat::ChatCompletionChunk::Choice::Delta, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  #: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
   def handle_tool_call_deltas(delta, state:, yielder:)
-    tool_calls = delta.tool_calls
+    typed_delta = delta #: OpenAI::Models::Chat::ChatCompletionChunk::Choice::Delta
+    tool_calls = typed_delta.tool_calls
     return if tool_calls.nil? || tool_calls.empty?
 
     tool_calls.each do |tc|
@@ -236,9 +242,10 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
   end
 
   #--
-  #: (OpenAI::Models::Chat::ChatCompletionChunk::Choice) -> bool
+  #: (untyped) -> bool
   def finish_reason_is_tool_calls?(choice)
-    choice.finish_reason.to_s == "tool_calls"
+    typed_choice = choice #: OpenAI::Models::Chat::ChatCompletionChunk::Choice
+    typed_choice.finish_reason.to_s == "tool_calls"
   end
 
   #--

data/lib/riffer/runner/fibers.rb

@@ -14,6 +14,8 @@
 #   runner.map(items) { |item| expensive_operation(item) }
 #
 class Riffer::Runner::Fibers < Riffer::Runner
+  # @rbs @max_concurrency: Integer?
+
   include Riffer::Helpers::Dependencies
 
   # [max_concurrency] maximum number of fibers to run simultaneously.

data/lib/riffer/runner/threaded.rb

@@ -14,6 +14,8 @@
 #   runner.map(items) { |item| expensive_operation(item) }
 #
 class Riffer::Runner::Threaded < Riffer::Runner
+  # @rbs @max_concurrency: Integer
+
   DEFAULT_MAX_CONCURRENCY = 5 #: Integer
 
   # [max_concurrency] maximum number of threads to run simultaneously.

data/lib/riffer/skills/config.rb

@@ -11,6 +11,11 @@
 #     activate ["code-review"]
 #   end
 class Riffer::Skills::Config
+  # @rbs @backend: (Riffer::Skills::Backend | Proc)?
+  # @rbs @adapter: singleton(Riffer::Skills::Adapter)?
+  # @rbs @activate: (Array[String] | Proc)?
+  # @rbs @activate_tool: singleton(Riffer::Tool)?
+
   # Creates a new Config with all options unset.
   #
   #--

data/lib/riffer/skills/context.rb

@@ -11,6 +11,9 @@
 #
 # See Riffer::Skills::Backend, Riffer::Skills::Frontmatter.
 class Riffer::Skills::Context
+  # @rbs @backend: Riffer::Skills::Backend
+  # @rbs @activated: Hash[String, String]
+
   # Skill catalog indexed by name.
   attr_reader :skills #: Hash[String, Riffer::Skills::Frontmatter]
 

data/lib/riffer/skills/filesystem_backend.rb

@@ -11,6 +11,9 @@
 #   backend.read_skill("code-review")  # => "Full skill instructions..."
 #
 class Riffer::Skills::FilesystemBackend < Riffer::Skills::Backend
+  # @rbs @paths: Array[String]
+  # @rbs @skills_cache: Hash[String, String]?
+
   # Creates a new FilesystemBackend.
   #
   # [paths] one or more directory paths to scan for skills.

data/lib/riffer/tools/response.rb

@@ -18,6 +18,8 @@ require "json"
 #   end
 #
 class Riffer::Tools::Response
+  # @rbs @success: bool
+
   VALID_FORMATS = %i[text json].freeze #: Array[Symbol]
 
   attr_reader :content #: String

data/lib/riffer/tools/runtime.rb

@@ -15,6 +15,8 @@ require "json"
 #   results = runtime.execute(tool_calls, tools: tools, context: context)
 #
 class Riffer::Tools::Runtime
+  # @rbs @runner: Riffer::Runner
+
   # [runner] the concurrency runner to use for batch execution.
   #
   # Subclasses must provide a runner; instantiating Riffer::Tools::Runtime directly

data/lib/riffer/tools/toolable.rb

@@ -23,6 +23,13 @@
 #   end
 #
 module Riffer::Tools::Toolable
+  # @rbs self.@extenders: Array[Module]?
+  # @rbs @description: String?
+  # @rbs @identifier: String?
+  # @rbs @timeout: (Integer | Float)?
+  # @rbs @params_builder: Riffer::Params?
+  # @rbs @kind: Symbol?
+
   DEFAULT_TIMEOUT = 10 #: Integer
 
   # Tracks all classes that extend Toolable.

data/lib/riffer/version.rb

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

data/lib/riffer.rb

@@ -17,6 +17,8 @@ loader.inflector.inflect(
 loader.setup
 
 module Riffer
+  # @rbs self.@config: Riffer::Config?
+
   # Base error class for Riffer.
   class Error < StandardError; end
 

data/sig/_private/anthropic.rbs

@@ -0,0 +1,16 @@
+# Arity patch for the `anthropic` gem (see openai.rbs for the rationale).
+# `Messages#create` is positional at runtime but typed keyword-only in the gem's
+# RBS; `Messages#stream` is omitted from the gem's RBS but present at runtime
+# (returns a MessageStream helper). Loaded only for riffer's own Steep run.
+module Anthropic
+  module Resources
+    class Messages
+      def create: (Hash[Symbol, untyped] params) -> Anthropic::Models::Message
+                | (**untyped) -> Anthropic::Models::Message
+                | ...
+
+      def stream: (Hash[Symbol, untyped] params) -> untyped
+                | (**untyped) -> untyped
+    end
+  end
+end

data/sig/_private/openai.rbs

@@ -0,0 +1,29 @@
+# Arity patch for the `openai` gem. Its Resources methods are positional
+# `def x(params)` at runtime, but the gem's shipped RBS advertises keyword-only
+# signatures. We accept a positional hash or a keyword splat (`| ...` extends the
+# gem's existing overloads). Streaming returns `untyped` — the event objects are a
+# ~60-member union dispatched dynamically on `#type`. Loaded only for riffer's own
+# Steep run (consumers skip sig/_private).
+module OpenAI
+  module Resources
+    class Responses
+      def create: (Hash[Symbol, untyped] params) -> OpenAI::Models::Responses::Response
+                | (**untyped) -> OpenAI::Models::Responses::Response
+                | ...
+      def stream: (Hash[Symbol, untyped] params) -> untyped
+                | (**untyped) -> untyped
+                | ...
+    end
+
+    class Chat
+      class Completions
+        def create: (Hash[Symbol, untyped] params) -> OpenAI::Models::Chat::ChatCompletion
+                  | (**untyped) -> OpenAI::Models::Chat::ChatCompletion
+                  | ...
+        def stream_raw: (Hash[Symbol, untyped] params) -> untyped
+                      | (**untyped) -> untyped
+                      | ...
+      end
+    end
+  end
+end

data/sig/_private/riffer/providers/amazon_bedrock.rbs

@@ -0,0 +1,4 @@
+# `@client` is typed against the SDK, so this ivar stub stays in _private (never ships)
+class Riffer::Providers::AmazonBedrock
+  @client: ::Aws::BedrockRuntime::Client
+end

data/sig/_private/riffer/providers/anthropic.rbs

@@ -0,0 +1,4 @@
+# `@client` is typed against the SDK, so this ivar stub stays in _private (never ships)
+class Riffer::Providers::Anthropic
+  @client: ::Anthropic::Client
+end

data/sig/_private/riffer/providers/open_ai.rbs

@@ -0,0 +1,4 @@
+# `@client` is typed against the SDK, so this ivar stub stays in _private (never ships)
+class Riffer::Providers::OpenAI
+  @client: ::OpenAI::Client
+end

data/sig/_private/riffer/providers/open_router.rbs

@@ -0,0 +1,4 @@
+# `@client` is typed against the SDK, so this ivar stub stays in _private (never ships)
+class Riffer::Providers::OpenRouter
+  @client: ::OpenAI::Client
+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/context.rbs

@@ -17,6 +17,8 @@
 #   context.skills       # => nil
 #   context.token_usage  # => nil
 class Riffer::Agent::Context
+  @data: Hash[Symbol, untyped]
+
   # Keys reserved for framework use. Passing any of these to the
   # constructor raises +Riffer::ArgumentError+.
   RESERVED_KEYS: Array[Symbol]

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

@@ -12,6 +12,8 @@
 #     puts response.content
 #   end
 class Riffer::Agent::Response
+  @interrupted: bool
+
   # The response content.
   attr_reader content: 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/session.rbs

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

data/sig/generated/riffer/agent.rbs

@@ -15,6 +15,8 @@
 #   agent = MyAgent.new
 #   agent.generate('Hello!')
 class Riffer::Agent
+  self.@config: Riffer::Agent::Config?
+
   include Riffer::Messages::Converter
 
   extend Riffer::Helpers::ClassNameConverter
@@ -78,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.
   #
@@ -157,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.
@@ -208,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
@@ -298,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
 
   # --
@@ -309,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?