riffer 0.31.0 → 0.32.0

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

@@ -1,34 +1,14 @@
 # Generated from lib/riffer/agent/serializer.rb with RBS::Inline
 
-# Riffer::Agent::Serializer turns a resolved agent into a self-contained,
-# provider-neutral data hash and back into a runnable agent. A pure module
-# (sibling to Riffer::Agent::Run), reached most often through the
-# +Riffer::Agent#to_h+ / +Riffer::Agent.from_h+ delegators.
+# Turns a resolved agent into a self-contained, provider-neutral data hash and
+# back into a runnable agent, behind the +Riffer::Agent#to_h+ /
+# +Riffer::Agent.from_h+ delegators.
 #
-# The hash carries only data — no Procs, no class references, no tool
-# runtime. The same hash 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.
-#
-#   data  = Riffer::Agent::Serializer.to_h(agent: agent)
-#   rebuilt = Riffer::Agent::Serializer.from_h(data, context: {tenant: "acme"})
-#
-# == What does not transfer
-#
-# Guardrails and the skills subsystem (backend/adapter/catalog) are not
-# serialized; a rebuilt agent enforces no guardrails and renders no skills
-# catalog (the +skill_activate+ tool, if present, crosses as an ordinary
-# tool). Secrets must not be placed in +provider_options+/+model_options+:
-# both ride on the wire as plain data.
+#   hash    = Riffer::Agent::Serializer.to_h(agent: agent)
+#   rebuilt = Riffer::Agent::Serializer.from_h(hash, context: {tenant: "acme"})
 module Riffer::Agent::Serializer
-  # The wire format version. Bumped only on an incompatible change to the
-  # hash shape; +from_h+ refuses any other version. See +from_h+ for the
-  # dispatch seam that carries back-compat decoders.
+  # The wire format version, bumped only on an incompatible change to the hash
+  # shape; +from_h+ refuses any other version.
   SCHEMA_VERSION: Integer
 
   # Raised by +from_h+ when the hash's +schema_version+ is unsupported.
@@ -39,59 +19,30 @@ module Riffer::Agent::Serializer
   # 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 hash.
-  #
-  # Reads the agent's resolved instance state — Proc-based settings have
-  # already been evaluated against the agent's own context, so the hash
-  # carries plain strings/data, never Procs. Tools are emitted as
-  # +{name, description, parameters_schema, timeout}+ descriptors (the
-  # resolved +agent.tools+, including MCP tools and +skill_activate+).
-  #
-  # [agent] a resolved Riffer::Agent instance.
-  #
+  # Snapshots a resolved agent into a self-contained wire hash. Proc-based
+  # settings are already evaluated against the agent's context, so the hash
+  # carries plain data, never Procs.
   # --
   # : (agent: Riffer::Agent) -> Hash[Symbol, untyped]
   def to_h: (agent: Riffer::Agent) -> Hash[Symbol, untyped]
 
-  # Reconstructs a runnable agent from a wire hash.
-  #
-  # [hash] a Symbol-keyed wire hash (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 hash 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.
-  # [session] an optional Riffer::Agent::Session to seed conversation history,
-  #   forwarded verbatim to +Agent.new(session:)+. The hash carries the agent
-  #   *definition*, not its history (see "What does not transfer"); pass a
-  #   session here to resume a persisted conversation. Used as-is — the caller
-  #   owns its contents, including the system instruction message. When omitted,
-  #   a fresh session seeded with the hash's instructions is built.
-  # [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 hash.
+  # Reconstructs a runnable agent from a wire hash. +context+ is threaded into
+  # tool dispatch (not used to re-resolve the already-resolved config);
+  # +session+ seeds conversation history (the hash carries the agent definition,
+  # not its history). Raises Riffer::Agent::Serializer::VersionError on an
+  # unsupported +schema_version+.
   #
   # --
   # : (Hash[Symbol, untyped], ?context: Hash[Symbol, untyped]?, ?session: Riffer::Agent::Session?, ?tool_resolver: ^(Hash[Symbol, untyped]) -> singleton(Riffer::Tool), ?tool_runtime: (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)?) -> Riffer::Agent
   def from_h: (Hash[Symbol, untyped], ?context: Hash[Symbol, untyped]?, ?session: Riffer::Agent::Session?, ?tool_resolver: ^(Hash[Symbol, untyped]) -> singleton(Riffer::Tool), ?tool_runtime: (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)?) -> Riffer::Agent
 
-  # Snapshots a resolved agent to a JSON string. Convenience over
-  # <tt>JSON.generate(to_h(agent:))</tt>.
-  #
+  # Snapshots a resolved agent to a JSON string.
   # --
   # : (agent: Riffer::Agent) -> String
   def to_json: (agent: 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
+  # Reconstructs a runnable agent from a JSON string produced by +to_json+. See
   # +from_h+ for the arguments.
-  #
   # --
   # : (String, ?context: Hash[Symbol, untyped]?, ?session: Riffer::Agent::Session?, ?tool_resolver: ^(Hash[Symbol, untyped]) -> singleton(Riffer::Tool), ?tool_runtime: (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)?) -> Riffer::Agent
   def from_json: (String, ?context: Hash[Symbol, untyped]?, ?session: Riffer::Agent::Session?, ?tool_resolver: ^(Hash[Symbol, untyped]) -> singleton(Riffer::Tool), ?tool_runtime: (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)?) -> Riffer::Agent
@@ -106,18 +57,14 @@ module Riffer::Agent::Serializer
   # : (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 hash stays portable across transports where JSON +null+ is
-  # awkward (e.g. proto3, which can't tell null from an absent field). The
-  # magic value lives only on the wire — +encode_max_steps+/+decode_max_steps+
-  # translate at the boundary so neither the DSL nor consumers see it.
+  # Encodes unlimited steps (+nil+ in the DSL) as +-1+ on the wire, where a
+  # JSON +null+ is awkward across transports (e.g. proto3).
   # --
   # : (Numeric?) -> Numeric
   def encode_max_steps: (Numeric?) -> Numeric
 
-  # Reverses +encode_max_steps+: +-1+ (or a literal +null+) means unlimited.
-  # An absent key falls back to the default — a partial hash must not silently
-  # become an unbounded loop.
+  # Reverses +encode_max_steps+; a missing key falls back to the default so a
+  # partial hash can't become an unbounded loop.
   # --
   # : (Hash[Symbol, untyped]) -> Numeric?
   def decode_max_steps: (Hash[Symbol, untyped]) -> Numeric?
@@ -126,12 +73,6 @@ module Riffer::Agent::Serializer
   # : (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

data/sig/generated/riffer/agent/session/repair.rbs

@@ -1,51 +1,23 @@
 # Generated from lib/riffer/agent/session/repair.rb with RBS::Inline
 
-# Riffer::Agent::Session::Repair holds the pure transformations that keep the
-# +tool_use+ ↔ +tool_result+ invariant on a message array. No state, no
-# instance — module-level functions only. Each entry point is gated by
-# +Riffer.config.experimental_history_healing+: when the flag is off the
-# function returns its input unchanged.
-#
-# Two seams:
-#
-# - +fill_orphans+ — fills orphan +tool_use+ blocks with placeholder
-#   results. Used on interrupt (caller-issued or +max_steps+).
-# - +prune_orphans+ — drops orphan +tool_use+ blocks and parentless Tool
-#   messages from a caller-provided seed so it is well-formed before the
-#   next inference call. Used at construction time when
-#   +Riffer::Agent.new(session:)+ receives a session.
+# Pure, stateless transformations keeping the +tool_use+ ↔ +tool_result+
+# invariant on a message array. Each entry point no-ops when
+# +Riffer.config.experimental_history_healing+ is off.
 module Riffer::Agent::Session::Repair
-  # Placeholder used to fill orphan +tool_use+ blocks. Emitted as the
-  # +Riffer::Tools::Response+ body for each filled call_id.
+  # Placeholder response filled in for an orphaned +tool_use+ on interrupt.
   ORPHAN_PLACEHOLDER: ^(Riffer::Messages::Assistant::ToolCall) -> Riffer::Tools::Response
 
-  # Fills any orphaned +tool_use+ in +messages+ with the
-  # +ORPHAN_PLACEHOLDER+ response. Each placeholder Tool message is
-  # inserted immediately after its parent assistant message. Returns
-  # +[new_messages, filled_call_ids]+; +filled_call_ids+ is empty when
-  # there are no orphans.
-  #
-  # No-op when +Riffer.config.experimental_history_healing+ is off:
-  # returns +[messages, []]+ with the same array reference.
-  #
+  # Fills each orphaned +tool_use+ in +messages+ with an +ORPHAN_PLACEHOLDER+
+  # result inserted after its parent. Returns +[new_messages, filled_call_ids]+.
   # --
   # : (Array[Riffer::Messages::Base]) -> [Array[Riffer::Messages::Base], Array[String]]
-  def self.fill_orphans: (Array[Riffer::Messages::Base]) -> [ Array[Riffer::Messages::Base], Array[String] ]
+  def fill_orphans: (Array[Riffer::Messages::Base]) -> [ Array[Riffer::Messages::Base], Array[String] ]
 
-  # Prunes a seeded message array so the +tool_use+ ↔ +tool_result+
-  # invariant holds. Drops orphaned tool exchanges (assistant +tool_call+
-  # with no matching Tool result) and parentless Tool messages. Returns a
-  # new array; the input is not mutated.
-  #
-  # Pending tool_calls on the resume boundary — the last assistant whose
-  # tail is purely Tool results (or empty) — are preserved. They get
-  # swept up by +execute_pending_tool_calls+ at the start of the next
-  # generate/stream call.
-  #
-  # No-op when +Riffer.config.experimental_history_healing+ is off:
-  # returns +messages+ unchanged.
-  #
+  # Prunes a seeded message array to the invariant — dropping orphaned tool
+  # exchanges and parentless Tool messages, but preserving the pending
+  # tool_calls on the resume boundary (the last assistant) for
+  # +execute_pending_tool_calls+. Returns a new array.
   # --
   # : (Array[Riffer::Messages::Base]) -> Array[Riffer::Messages::Base]
-  def self.prune_orphans: (Array[Riffer::Messages::Base]) -> Array[Riffer::Messages::Base]
+  def prune_orphans: (Array[Riffer::Messages::Base]) -> Array[Riffer::Messages::Base]
 end

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

@@ -1,11 +1,8 @@
 # Generated from lib/riffer/agent/session.rb with RBS::Inline
 
-# Riffer::Agent::Session owns the conversation handle for an agent: the message
-# array, the +on_message+ callback list, and the +tool_use+ ↔ +tool_result+
-# invariant that keeps tool calls and their results consistent.
-#
-# Access via +agent.session+. Sessions are constructed by +Riffer::Agent+
-# and live for the lifetime of the agent.
+# Owns the conversation handle for an agent: the message array, the
+# +on_message+ callbacks, and the +tool_use+ ↔ +tool_result+ invariant that
+# keeps tool calls and their results consistent.
 #
 #   agent.session.add(msg)                  # append + fire callbacks
 #   agent.session.set([msg1, msg2])         # bulk replace (silent)
@@ -26,106 +23,65 @@ class Riffer::Agent::Session
   def initialize: (?messages: Array[Riffer::Messages::Base]) -> void
 
   # Registers a callback invoked once per message appended via +#add+.
-  #
-  # Callbacks do NOT fire for +#set+, +#unset+, +#remove+, or +#update+.
-  # Returns +self+ to allow chaining.
-  #
-  # Raises Riffer::ArgumentError if no block is given.
-  #
   # --
   # : () { (Riffer::Messages::Base) -> void } -> self
   def on_message: () { (Riffer::Messages::Base) -> void } -> self
 
-  # Appends +message+ and fires every registered callback once with it.
-  #
-  # Pass +silent: true+ to skip +on_message+ callbacks — used for
-  # non-inference inputs like user messages, which subscribers don't
-  # expect to observe through the callback channel. Inference-produced
-  # messages (Assistant, Tool) always go through +add+ without +silent+.
-  #
+  # Appends +message+ and fires every registered callback once with it. Pass
+  # +silent: true+ to skip callbacks — used for non-inference inputs like user
+  # messages that subscribers don't expect on the callback channel.
   # --
   # : (Riffer::Messages::Base, ?silent: bool) -> Riffer::Messages::Base
   def add: (Riffer::Messages::Base, ?silent: bool) -> Riffer::Messages::Base
 
-  # Replaces the message history wholesale. Does NOT fire +on_message+
-  # callbacks; registered callbacks persist across the swap.
-  #
-  # Used for seeding, guardrail rewrites, and history healing — cases
-  # where firing callbacks would double-emit messages that subscribers
-  # have already observed (or never produced).
-  #
+  # Replaces the message history wholesale
   # --
   # : (Array[Riffer::Messages::Base]) -> self
   def set: (Array[Riffer::Messages::Base]) -> self
 
-  # Clears the session. Does NOT fire +on_message+ callbacks; registered
-  # callbacks persist.
-  #
+  # Clears the session.
   # --
   # : () -> self
   def unset: () -> self
 
-  # Removes a message by id. When the target is an assistant message that
-  # carries +tool_calls+, every +Riffer::Messages::Tool+ result whose
-  # +tool_call_id+ matches one of those calls is removed atomically — keeping
-  # the +tool_use+ ↔ +tool_result+ invariant intact.
-  #
-  # Raises Riffer::ArgumentError when called on a +Riffer::Messages::Tool+
-  # message — that would orphan the parent's +tool_use+. Use
-  # +#update+ to rewrite a tool result instead.
-  #
-  # Returns the removed message, or +nil+ when no message has the given id
-  # (idempotent).
-  #
+  # Removes a message by id, cascading to drop the +Tool+ results of a removed
+  # assistant's +tool_calls+ so the +tool_use+ ↔ +tool_result+ invariant holds.
+  # Raises on a +Tool+ message — that would orphan its parent; use +#update+
+  # instead. Returns +nil+ if no message matches.
   # --
   # : (id: String) -> Riffer::Messages::Base?
   def remove: (id: String) -> Riffer::Messages::Base?
 
-  # Partial in-place update. Looks up a message by either +id:+ or
-  # +tool_call_id:+ (exactly one required), constructs a replacement of the
-  # same concrete type with +attrs+ overlaid on the existing fields, and
-  # swaps it in place.
-  #
-  # When the target is an assistant message and the update drops one or more
-  # entries from +tool_calls+, every +Riffer::Messages::Tool+ result whose
-  # +tool_call_id+ matches a dropped call is removed atomically — keeping the
-  # +tool_use+ ↔ +tool_result+ invariant intact.
-  #
-  # Raises Riffer::ArgumentError when neither or both lookup keys are
-  # provided, or when no message matches.
-  #
+  # Partial in-place update: looks up a message by +id:+ or +tool_call_id:+
+  # (exactly one), overlays +attrs+ onto a same-type replacement, and swaps it
+  # in. Dropping +tool_calls+ from an assistant cascades to remove their +Tool+
+  # results, preserving the invariant. Raises on neither/both keys or no match.
   # --
   # : (?id: String?, ?tool_call_id: String?, **untyped) -> Riffer::Messages::Base
   def update: (?id: String?, ?tool_call_id: String?, **untyped) -> Riffer::Messages::Base
 
-  # Returns the call_ids of every +tool_call+ on any assistant message that
-  # has no matching +Riffer::Messages::Tool+ result anywhere in history.
-  #
-  # Zero-cost validation hook for callers that want to check the
-  # +tool_use+ ↔ +tool_result+ invariant before mutating or persisting.
-  #
+  # Returns the call_ids of every +tool_call+ with no matching
+  # +Riffer::Messages::Tool+ result anywhere in history — a hook for checking
+  # the +tool_use+ ↔ +tool_result+ invariant before mutating or persisting.
   # --
   # : () -> Array[String]
   def orphaned_tool_call_ids: () -> Array[String]
 
-  # Returns +[assistant, pending_tool_calls]+ for the last assistant message.
-  # When there is no assistant message or no pending calls, the second
-  # element is an empty array.
-  #
+  # Returns +[last_assistant, pending_tool_calls]+; the second element is empty
+  # when there's no assistant message or no pending calls.
   # --
   # : () -> [Riffer::Messages::Assistant?, Array[Riffer::Messages::Assistant::ToolCall]]
   def pending_tool_calls: () -> [ Riffer::Messages::Assistant?, Array[Riffer::Messages::Assistant::ToolCall] ]
 
+  # Yields each message in order, or returns an Enumerator without a block.
   # --
   # : () -> Enumerator[Riffer::Messages::Base, self]
   # : () { (Riffer::Messages::Base) -> void } -> untyped
   def each: () -> Enumerator[Riffer::Messages::Base, self]
           | () { (Riffer::Messages::Base) -> void } -> untyped
 
-  # The number of LLM steps completed in this session, derived from the
-  # count of assistant messages. Used by the agent loop to enforce
+  # The number of LLM steps completed, used by the agent loop to enforce
   # +max_steps+ on resume.
-  #
   # --
   # : () -> Integer
   def steps: () -> Integer
@@ -139,9 +95,11 @@ class Riffer::Agent::Session
 
   private
 
+  # --
   # : (Riffer::Messages::Base, Riffer::Messages::Base) -> void
   def cascade_dropped_tool_calls: (Riffer::Messages::Base, Riffer::Messages::Base) -> void
 
+  # --
   # : (Riffer::Messages::Base, Hash[Symbol, untyped]) -> Riffer::Messages::Base
   def rebuild_message: (Riffer::Messages::Base, Hash[Symbol, untyped]) -> Riffer::Messages::Base
 end

data/sig/generated/riffer/agent/structured_output/result.rbs

@@ -1,19 +1,11 @@
 # Generated from lib/riffer/agent/structured_output/result.rb with RBS::Inline
 
 # Wraps the result of structured output parsing and validation.
-#
-# On success, +object+ contains the validated Hash and +error+ is nil.
-# On failure, +error+ contains the error message and +object+ is nil.
-#
-#   result = structured_output.parse_and_validate(json_string)
-#   if result.success?
-#     result.object  #=> {sentiment: "positive", score: 0.9}
-#   else
-#     result.error   #=> "JSON parse error: ..."
-#   end
 class Riffer::Agent::StructuredOutput::Result
+  # The validated object, or +nil+ on failure.
   attr_reader object: Hash[Symbol, untyped]?
 
+  # The error message, or +nil+ on success.
   attr_reader error: String?
 
   # --

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

@@ -1,14 +1,9 @@
 # Generated from lib/riffer/agent/structured_output.rb with RBS::Inline
 
-# Riffer::Agent::StructuredOutput provides parse/validate for structured JSON
-# responses from LLM providers.
-#
-#   params = Riffer::Params.new
-#   params.required(:sentiment, String)
-#   so = Riffer::Agent::StructuredOutput.new(params)
-#   result = so.parse_and_validate('{"sentiment":"positive","score":0.9}')
-#   result.object  #=> {sentiment: "positive", score: 0.9}
+# Parses and validates structured JSON responses against a Riffer::Params
+# schema.
 class Riffer::Agent::StructuredOutput
+  # The schema parameters.
   attr_reader params: Riffer::Params
 
   # --
@@ -21,10 +16,8 @@ class Riffer::Agent::StructuredOutput
   # : (?strict: bool) -> Hash[Symbol, untyped]
   def json_schema: (?strict: bool) -> Hash[Symbol, untyped]
 
-  # Parses a JSON string and validates it against the schema.
-  #
-  # Returns a Result with the validated object on success, or an error message on failure.
-  #
+  # Parses a JSON string and validates it against the schema, returning a
+  # Result carrying either the validated object or an error message.
   # --
   # : (String) -> Riffer::Agent::StructuredOutput::Result
   def parse_and_validate: (String) -> Riffer::Agent::StructuredOutput::Result