riffer 0.48.0 → 0.49.0

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

@@ -1,40 +1,20 @@
 # Generated from lib/riffer/agent/outcome.rb with RBS::Inline
 
-# How a run ended — the single place to read whether the agent completed
-# normally and, if not, why. +detail+ carries the specifics when there are any:
-# the tripwire reason, the interrupt reason, the provider's raw finish value,
-# or the structured output parse/validation error.
-#
-#   response = agent.generate("Analyze this")
-#   case response.outcome.reason
-#   when :completed then puts response.structured_output
-#   when :invalid_structured_output then warn response.outcome.detail
-#   end
 class Riffer::Agent::Outcome
-  # Finish reasons that end a turn normally; every other finish reason means the
-  # provider cut the turn short and surfaces as the run's outcome verbatim.
   NORMAL_FINISH_REASONS: Array[Symbol]
 
-  # Derived from the provider vocabulary so a new finish reason becomes an
-  # outcome without a second list to update.
   PROVIDER_STOP_REASONS: Array[Symbol]
 
-  # The vocabulary every run ends in.
   VALUES: Array[Symbol]
 
-  # Why the run ended.
   attr_reader reason: Symbol
 
-  # Human-readable specifics for +reason+, when there are any.
   attr_reader detail: String?
 
-  # Raises Riffer::ArgumentError when +reason+ is outside VALUES.
   # --
   # : (reason: Symbol, ?detail: String?) -> void
   def initialize: (reason: Symbol, ?detail: String?) -> void
 
-  # Returns true when the run completed normally.
-  #
   # --
   # : () -> bool
   def success?: () -> bool

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

@@ -1,49 +1,24 @@
 # Generated from lib/riffer/agent/response.rb with RBS::Inline
 
-# Wraps an agent generation response. +outcome+ says how the run ended; when a
-# guardrail blocks execution, +content+ is empty and +tripwire+ carries the
-# block details.
-#
-#   response = agent.generate("Hello")
-#   if response.outcome.success?
-#     puts response.content
-#   else
-#     puts "#{response.outcome.reason}: #{response.outcome.detail}"
-#   end
 class Riffer::Agent::Response
-  # The response content.
   attr_reader content: String
 
-  # How the run ended.
   attr_reader outcome: Riffer::Agent::Outcome
 
-  # The tripwire if execution was blocked.
   attr_reader tripwire: Riffer::Guardrails::Tripwire?
 
-  # The modifications made by guardrails during processing.
   attr_reader modifications: Array[Riffer::Guardrails::Modification]
 
-  # The reasoning parts on the final assistant message, if the provider
-  # produced any.
   attr_reader reasoning: Array[Riffer::Messages::Assistant::ReasoningPart]
 
-  # The parsed structured output, if structured output was configured.
   attr_reader structured_output: Hash[Symbol, untyped]?
 
-  # The aggregate token usage across this run's LLM calls, if any was reported.
   attr_reader token_usage: Riffer::Providers::TokenUsage?
 
-  # The number of LLM calls made during this run (0 when a before-guardrail
-  # blocks before any call). Distinct from the session's cumulative step count.
   attr_reader steps: Integer
 
-  # The full message history from the agent conversation.
   attr_reader messages: Array[Riffer::Messages::Base]
 
-  # Call ids of tool_use blocks riffer filled with placeholder results this
-  # turn (when an interrupt left them unanswered and history healing is on).
-  attr_reader healed_tool_call_ids: Array[String]
-
   # --
   # : (
   #     String,
@@ -53,14 +28,11 @@ class Riffer::Agent::Response
   #     ?reasoning: Array[Riffer::Messages::Assistant::ReasoningPart],
   #     ?structured_output: Hash[Symbol, untyped]?,
   #     ?messages: Array[Riffer::Messages::Base],
-  #     ?healed_tool_call_ids: Array[String],
   #     ?token_usage: Riffer::Providers::TokenUsage?,
   #     ?steps: Integer
   #   ) -> void
-  def initialize: (String, outcome: Riffer::Agent::Outcome, ?tripwire: Riffer::Guardrails::Tripwire?, ?modifications: Array[Riffer::Guardrails::Modification], ?reasoning: Array[Riffer::Messages::Assistant::ReasoningPart], ?structured_output: Hash[Symbol, untyped]?, ?messages: Array[Riffer::Messages::Base], ?healed_tool_call_ids: Array[String], ?token_usage: Riffer::Providers::TokenUsage?, ?steps: Integer) -> void
+  def initialize: (String, outcome: Riffer::Agent::Outcome, ?tripwire: Riffer::Guardrails::Tripwire?, ?modifications: Array[Riffer::Guardrails::Modification], ?reasoning: Array[Riffer::Messages::Assistant::ReasoningPart], ?structured_output: Hash[Symbol, untyped]?, ?messages: Array[Riffer::Messages::Base], ?token_usage: Riffer::Providers::TokenUsage?, ?steps: Integer) -> void
 
-  # Returns true if any guardrail modified data during processing.
-  #
   # --
   # : () -> bool
   def modified?: () -> bool

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

@@ -1,30 +1,16 @@
 # Generated from lib/riffer/agent/run.rb with RBS::Inline
 
-# The generation loop — a pure module of functions over an +agent+, which owns
-# every per-call value; Run just orchestrates.
 module Riffer::Agent::Run
-  # Runs the generate loop for the given agent. See Riffer::Agent#generate
-  # for prompt/files semantics.
-  #
   # --
   # : (agent: Riffer::Agent, ?prompt: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::User::FilePart]?, ?tags: Hash[(String | Symbol), untyped]) -> Riffer::Agent::Response
   def generate: (agent: Riffer::Agent, ?prompt: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::User::FilePart]?, ?tags: Hash[String | Symbol, untyped]) -> Riffer::Agent::Response
 
-  # Runs the streaming loop for the given agent. See Riffer::Agent#stream
-  # for prompt/files semantics.
-  #
   # --
   # : (agent: Riffer::Agent, ?prompt: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::User::FilePart]?, ?tags: Hash[(String | Symbol), untyped]) -> Enumerator[Riffer::StreamEvents::Base, Riffer::Agent::Response]
   def stream: (agent: Riffer::Agent, ?prompt: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::User::FilePart]?, ?tags: Hash[String | Symbol, untyped]) -> Enumerator[Riffer::StreamEvents::Base, Riffer::Agent::Response]
 
   private
 
-  # Both +generate+ and +stream+ funnel here, so this is the single place raw
-  # +tags+ are normalized and merged over the default tags (a caller tag wins
-  # on a shared key). The clean <tt>String => String</tt> map is then
-  # threaded to every span builder in the run as +riffer.tag.*+ and to each
-  # provider call (via +merged_model_options+) for native request-metadata
-  # mapping.
   # --
   # : (Riffer::Agent, ?tags: Hash[(String | Symbol), untyped]?, ?stream_yielder: Enumerator::Yielder?) -> Riffer::Agent::Response
   def run_loop: (Riffer::Agent, ?tags: Hash[String | Symbol, untyped]?, ?stream_yielder: Enumerator::Yielder?) -> Riffer::Agent::Response
@@ -49,10 +35,6 @@ module Riffer::Agent::Run
   # : (Riffer::Agent, Array[Riffer::Guardrails::Modification], ?interrupted: bool, ?interrupt_reason: (String | Symbol)?, **untyped) -> Riffer::Agent::Response
   def final_response: (Riffer::Agent, Array[Riffer::Guardrails::Modification], ?interrupted: bool, ?interrupt_reason: (String | Symbol)?, **untyped) -> Riffer::Agent::Response
 
-  # Checked in the order things happened. The loop being stopped (max_steps or
-  # an interrupt) beats the provider's finish reason, which beats riffer's own
-  # validation of the content. A truncated response that also fails the schema
-  # therefore reports :length, not :invalid_structured_output.
   # --
   # : (Riffer::Messages::Assistant?, Riffer::Agent::StructuredOutput::Result?, interrupted: bool, interrupt_reason: (String | Symbol)?) -> Riffer::Agent::Outcome
   def final_outcome: (Riffer::Messages::Assistant?, Riffer::Agent::StructuredOutput::Result?, interrupted: bool, interrupt_reason: (String | Symbol)?) -> Riffer::Agent::Outcome
@@ -93,15 +75,10 @@ module Riffer::Agent::Run
   # : (Riffer::Agent) -> Array[singleton(Riffer::Tool)]
   def effective_tools: (Riffer::Agent) -> Array[singleton(Riffer::Tool)]
 
-  # +tags+ rides in the options hash as a curated key the providers extract for
-  # native request-metadata mapping (alongside +:structured_output+); it never
-  # reaches an SDK call verbatim. Span tagging is threaded separately to each
-  # builder.
   # --
   # : (Riffer::Agent, ?Hash[String, String]) -> Hash[Symbol, untyped]
   def merged_model_options: (Riffer::Agent, ?Hash[String, String]) -> Hash[Symbol, untyped]
 
-  # The tags riffer adds to every run, identifying the agent it's on behalf of.
   # --
   # : (Riffer::Agent) -> Hash[String, String]
   def default_tags: (Riffer::Agent) -> Hash[String, String]
@@ -115,14 +92,11 @@ module Riffer::Agent::Run
   #     ?modifications: Array[Riffer::Guardrails::Modification],
   #     ?reasoning: Array[Riffer::Messages::Assistant::ReasoningPart],
   #     ?structured_output: Hash[Symbol, untyped]?,
-  #     ?healed_tool_call_ids: Array[String],
   #     ?token_usage: Riffer::Providers::TokenUsage?,
   #     ?steps: Integer
   #   ) -> Riffer::Agent::Response
-  def build_response: (Riffer::Agent, String, outcome: Riffer::Agent::Outcome, ?tripwire: Riffer::Guardrails::Tripwire?, ?modifications: Array[Riffer::Guardrails::Modification], ?reasoning: Array[Riffer::Messages::Assistant::ReasoningPart], ?structured_output: Hash[Symbol, untyped]?, ?healed_tool_call_ids: Array[String], ?token_usage: Riffer::Providers::TokenUsage?, ?steps: Integer) -> Riffer::Agent::Response
+  def build_response: (Riffer::Agent, String, outcome: Riffer::Agent::Outcome, ?tripwire: Riffer::Guardrails::Tripwire?, ?modifications: Array[Riffer::Guardrails::Modification], ?reasoning: Array[Riffer::Messages::Assistant::ReasoningPart], ?structured_output: Hash[Symbol, untyped]?, ?token_usage: Riffer::Providers::TokenUsage?, ?steps: Integer) -> Riffer::Agent::Response
 
-  # Raises when +files+ are supplied without a +prompt+ — the provider needs
-  # text to anchor the attachments.
   # --
   # : (Riffer::Agent, String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::User::FilePart]?) -> void
   def append_user_message: (Riffer::Agent, String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::User::FilePart]?) -> void

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

@@ -1,48 +1,27 @@
 # Generated from lib/riffer/agent/serializer.rb with RBS::Inline
 
-# 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.
-#
-#   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.
+  # Bump only on an incompatible change to the hash shape.
   SCHEMA_VERSION: Integer
 
-  # Raised by +from_h+ when the hash's +schema_version+ is unsupported.
   class VersionError < Riffer::ArgumentError
   end
 
-  # The default +tool_resolver+: synthesizes a body-less tool shell from a
-  # descriptor. Its +#call+ raises — route shells through a remote runtime.
   DEFAULT_TOOL_RESOLVER: ^(Hash[Symbol, untyped]) -> singleton(Riffer::Tool)
 
-  # 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. +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+.
-  #
+  # 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.
   # --
   # : (agent: Riffer::Agent) -> String
   def to_json: (agent: Riffer::Agent) -> String
 
-  # 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
@@ -57,14 +36,10 @@ module Riffer::Agent::Serializer
   # : (Hash[Symbol, untyped]?) -> Riffer::Params?
   def decode_structured_output: (Hash[Symbol, untyped]?) -> Riffer::Params?
 
-  # 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+; 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?

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

@@ -1,22 +1,14 @@
 # Generated from lib/riffer/agent/session/repair.rb with RBS::Inline
 
-# 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.
+# Maintains the invariant that every +tool_use+ has a matching +tool_result+
+# and every +tool_result+ has a parent +tool_use+.
 module Riffer::Agent::Session::Repair
-  # Placeholder response filled in for an orphaned +tool_use+ on interrupt.
   ORPHAN_PLACEHOLDER: ^(Riffer::Messages::Assistant::ToolCall) -> Riffer::Tools::Response
 
-  # 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 fill_orphans: (Array[Riffer::Messages::Base]) -> [ Array[Riffer::Messages::Base], Array[String] ]
 
-  # 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 prune_orphans: (Array[Riffer::Messages::Base]) -> Array[Riffer::Messages::Base]

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

@@ -1,100 +1,74 @@
 # Generated from lib/riffer/agent/session.rb with RBS::Inline
 
-# 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)
-#   agent.session.unset                     # clear (silent)
-#   agent.session.remove(id: "a_1")
-#   agent.session.update(id: "a_1", content: "...")
-#   agent.session.find { |m| m.id == "a_1" }
 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]
 
   # --
   # : (?messages: Array[Riffer::Messages::Base]) -> void
   def initialize: (?messages: Array[Riffer::Messages::Base]) -> void
 
-  # Registers a callback invoked once per message appended via +#add+.
   # --
   # : () { (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 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
   # --
   # : (Array[Riffer::Messages::Base]) -> self
   def set: (Array[Riffer::Messages::Base]) -> self
 
-  # Clears the session.
   # --
   # : () -> self
   def unset: () -> self
 
-  # 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 +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+ 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 +[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.
+  # --
+  # : () -> Array[String]
+  def discard_pending_tool_calls: () -> Array[String]
+
   # --
   # : () -> 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, used by the agent loop to enforce
-  # +max_steps+ on resume.
   # --
   # : () -> Integer
   def steps: () -> Integer
 
-  # The most recent +Riffer::Messages::Assistant+ in the session, or +nil+
-  # when none exists.
-  #
   # --
   # : () -> Riffer::Messages::Assistant?
   def final_assistant_message: () -> Riffer::Messages::Assistant?
 
   private
 
+  # Providers require tool results to directly follow their tool_use, but a
+  # resumed turn appends the new user message before pending calls execute.
+  # --
+  # : (Riffer::Messages::Base) -> Integer
+  def insertion_index: (Riffer::Messages::Base) -> Integer
+
   # --
   # : (Riffer::Messages::Base, Riffer::Messages::Base) -> void
   def cascade_dropped_tool_calls: (Riffer::Messages::Base, Riffer::Messages::Base) -> void

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

@@ -1,25 +1,18 @@
 # Generated from lib/riffer/agent/structured_output/result.rb with RBS::Inline
 
-# Wraps the result of structured output parsing and validation.
 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?
 
   # --
   # : (?object: Hash[Symbol, untyped]?, ?error: String?) -> void
   def initialize: (?object: Hash[Symbol, untyped]?, ?error: String?) -> void
 
-  # Returns true when parsing and validation succeeded.
-  #
   # --
   # : () -> bool
   def success?: () -> bool
 
-  # Returns true when parsing or validation failed.
-  #
   # --
   # : () -> bool
   def failure?: () -> bool

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

@@ -1,23 +1,16 @@
 # Generated from lib/riffer/agent/structured_output.rb with RBS::Inline
 
-# Parses and validates structured JSON responses against a Riffer::Params
-# schema.
 class Riffer::Agent::StructuredOutput
-  # The schema parameters.
   attr_reader params: Riffer::Params
 
   # --
   # : (Riffer::Params) -> void
   def initialize: (Riffer::Params) -> void
 
-  # Returns the JSON Schema for this structured output.
-  #
   # --
   # : (?strict: bool) -> Hash[Symbol, untyped]
   def json_schema: (?strict: bool) -> Hash[Symbol, untyped]
 
-  # 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