riffer 0.27.2 → 0.29.0

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

@@ -0,0 +1,144 @@
+# Generated from lib/riffer/agent/run.rb with RBS::Inline
+
+# Riffer::Agent::Run is the generation loop. A pure module of functions over an
+# +agent+ — Agent owns every per-call value (provider, model, tools, tool
+# runtime, structured output, session, context); Run just orchestrates.
+#
+# Tools and user code see the agent's +context+ (a +Riffer::Agent::Context+)
+# unchanged through the loop, so downstream tool runtimes can read
+# caller-provided keys via <tt>context[:agent]</tt> /
+# <tt>context.dig(:key)</tt>, or the framework built-ins via
+# +context.skills+. Cumulative token usage is updated into
+# +agent.context.token_usage+ as the loop progresses.
+#
+#   Riffer::Agent::Run.generate(agent: my_agent, prompt: "Hello")
+#   Riffer::Agent::Run.stream(agent: my_agent, prompt: "Hello")
+module Riffer::Agent::Run
+  include Riffer::Messages::Converter
+
+  # 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::FilePart]?) -> Riffer::Agent::Response
+  def generate: (agent: Riffer::Agent, ?prompt: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?) -> 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::FilePart]?) -> Enumerator[Riffer::StreamEvents::Base, void]
+  def stream: (agent: Riffer::Agent, ?prompt: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?) -> Enumerator[Riffer::StreamEvents::Base, void]
+
+  private
+
+  # The generation loop. When +stream_yielder+ is provided, per-step events are
+  # pushed to it (and +stream+ discards the return value). When +stream_yielder+
+  # is +nil+, no events are emitted and +generate+ returns the Response
+  # directly. The two modes share every step of the loop — the only
+  # divergences are the LLM call shape (atomic vs. accumulated stream)
+  # and whether per-step events are emitted.
+  #
+  # --
+  # : (Riffer::Agent, ?stream_yielder: Enumerator::Yielder?) -> Riffer::Agent::Response
+  def run_loop: (Riffer::Agent, ?stream_yielder: Enumerator::Yielder?) -> Riffer::Agent::Response
+
+  # Consumes one provider stream, forwarding every event to +stream_yielder+
+  # and folding it into an +Assistant+ message.
+  #
+  # --
+  # : (Riffer::Agent, Enumerator::Yielder) -> Riffer::Messages::Assistant
+  def accumulate_streamed_response: (Riffer::Agent, Enumerator::Yielder) -> Riffer::Messages::Assistant
+
+  # Appends +new_modifications+ to +all_modifications+ and emits a
+  # +GuardrailModification+ event for each one when streaming.
+  #
+  # --
+  # : (Enumerator::Yielder?, Array[Riffer::Guardrails::Modification], Array[Riffer::Guardrails::Modification]) -> void
+  def record_modifications!: (Enumerator::Yielder?, Array[Riffer::Guardrails::Modification], Array[Riffer::Guardrails::Modification]) -> void
+
+  # Emits a +GuardrailTripwire+ event when streaming and returns the
+  # short-circuit +Response+ for a tripped guardrail.
+  #
+  # --
+  # : (Riffer::Agent, Enumerator::Yielder?, Riffer::Guardrails::Tripwire, Array[Riffer::Guardrails::Modification]) -> Riffer::Agent::Response
+  def tripwire_response: (Riffer::Agent, Enumerator::Yielder?, Riffer::Guardrails::Tripwire, Array[Riffer::Guardrails::Modification]) -> Riffer::Agent::Response
+
+  # Builds the final +Response+ from the session's last assistant
+  # message, validating structured output when configured. +extra+
+  # carries the interrupt-only fields (+interrupted:+, +interrupt_reason:+,
+  # +healed_tool_call_ids:+) on the interrupt exit path.
+  #
+  # --
+  # : (Riffer::Agent, Array[Riffer::Guardrails::Modification], **untyped) -> Riffer::Agent::Response
+  def final_response: (Riffer::Agent, Array[Riffer::Guardrails::Modification], **untyped) -> Riffer::Agent::Response
+
+  # --
+  # : (Riffer::Agent) -> Riffer::Messages::Assistant
+  def call_llm: (Riffer::Agent) -> Riffer::Messages::Assistant
+
+  # --
+  # : (Riffer::Agent) -> Enumerator[Riffer::StreamEvents::Base, void]
+  def call_llm_stream: (Riffer::Agent) -> Enumerator[Riffer::StreamEvents::Base, void]
+
+  # --
+  # : (Riffer::Agent, Riffer::Messages::Assistant, ?tool_calls: Array[Riffer::Messages::Assistant::ToolCall]) -> void
+  def execute_tool_calls: (Riffer::Agent, Riffer::Messages::Assistant, ?tool_calls: Array[Riffer::Messages::Assistant::ToolCall]) -> void
+
+  # Executes tool calls left unfinished by a prior interrupt.
+  #
+  # Detects gaps between the last assistant message's requested tool calls
+  # and the tool result messages that follow it, executing any that are
+  # missing. Safe to call unconditionally.
+  #
+  # --
+  # : (Riffer::Agent) -> void
+  def execute_pending_tool_calls: (Riffer::Agent) -> void
+
+  # Runs the +:before+ guardrail phase. Records any modifications into
+  # +all_modifications+ (and emits them when streaming). When a tripwire
+  # fires, yields the short-circuit +Response+ — the caller's block is
+  # expected to +return+ it from +run_loop+.
+  #
+  # --
+  # : (Riffer::Agent, Enumerator::Yielder?, Array[Riffer::Guardrails::Modification]) { (Riffer::Agent::Response) -> void } -> void
+  def run_before_guardrails: (Riffer::Agent, Enumerator::Yielder?, Array[Riffer::Guardrails::Modification]) { (Riffer::Agent::Response) -> void } -> void
+
+  # Runs the +:after+ guardrail phase against the assistant +response+.
+  # Records any modifications into +all_modifications+ (and emits them
+  # when streaming). When a tripwire fires, yields the short-circuit
+  # +Response+ — the caller's block is expected to +return+ it from
+  # +run_loop+. Otherwise returns the post-guardrails assistant message.
+  #
+  # --
+  # : (Riffer::Agent, Riffer::Messages::Assistant, Enumerator::Yielder?, Array[Riffer::Guardrails::Modification]) { (Riffer::Agent::Response) -> void } -> untyped
+  def run_after_guardrails: (Riffer::Agent, Riffer::Messages::Assistant, Enumerator::Yielder?, Array[Riffer::Guardrails::Modification]) { (Riffer::Agent::Response) -> void } -> untyped
+
+  # --
+  # : (Riffer::Agent, Riffer::Messages::Assistant?) -> Hash[Symbol, untyped]?
+  def validate_structured_output: (Riffer::Agent, Riffer::Messages::Assistant?) -> Hash[Symbol, untyped]?
+
+  # --
+  # : (Riffer::Agent) -> Hash[Symbol, untyped]
+  def merged_model_options: (Riffer::Agent) -> Hash[Symbol, untyped]
+
+  # --
+  # : (Riffer::Agent, String, ?tripwire: Riffer::Guardrails::Tripwire?, ?modifications: Array[Riffer::Guardrails::Modification], ?interrupted: bool, ?interrupt_reason: (String | Symbol)?, ?structured_output: Hash[Symbol, untyped]?, ?healed_tool_call_ids: Array[String]) -> Riffer::Agent::Response
+  def build_response: (Riffer::Agent, String, ?tripwire: Riffer::Guardrails::Tripwire?, ?modifications: Array[Riffer::Guardrails::Modification], ?interrupted: bool, ?interrupt_reason: (String | Symbol)?, ?structured_output: Hash[Symbol, untyped]?, ?healed_tool_call_ids: Array[String]) -> Riffer::Agent::Response
+
+  # Appends a +User+ message to the session. No-ops when +prompt+ is nil
+  # and +files+ is empty (the caller had nothing to add). 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::FilePart]?) -> void
+  def append_user_message: (Riffer::Agent, String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?) -> void
+
+  # Accumulates token usage into +agent.context.token_usage+. Updates the
+  # context so cumulative usage persists across every run on the agent.
+  #
+  # --
+  # : (Riffer::Agent, Riffer::Providers::TokenUsage?) -> void
+  def track_token_usage: (Riffer::Agent, Riffer::Providers::TokenUsage?) -> void
+end

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

@@ -0,0 +1,51 @@
+# 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.
+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.
+  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.
+  #
+  # --
+  # : (Array[Riffer::Messages::Base]) -> [Array[Riffer::Messages::Base], Array[String]]
+  def self.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.
+  #
+  # --
+  # : (Array[Riffer::Messages::Base]) -> Array[Riffer::Messages::Base]
+  def self.prune_orphans: (Array[Riffer::Messages::Base]) -> Array[Riffer::Messages::Base]
+end

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

@@ -0,0 +1,145 @@
+# 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.
+#
+#   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]
+
+  # 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+.
+  #
+  # 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+.
+  #
+  # --
+  # : (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).
+  #
+  # --
+  # : (Array[Riffer::Messages::Base]) -> self
+  def set: (Array[Riffer::Messages::Base]) -> self
+
+  # Clears the session. Does NOT fire +on_message+ callbacks; registered
+  # callbacks persist.
+  #
+  # --
+  # : () -> 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).
+  #
+  # --
+  # : (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.
+  #
+  # --
+  # : (?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.
+  #
+  # --
+  # : () -> 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.
+  #
+  # --
+  # : () -> [Riffer::Messages::Assistant?, Array[Riffer::Messages::Assistant::ToolCall]]
+  def pending_tool_calls: () -> [ Riffer::Messages::Assistant?, Array[Riffer::Messages::Assistant::ToolCall] ]
+
+  # --
+  # : () -> 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
+  # +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
+
+  # : (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/{structured_output → agent/structured_output}/result.rbs

@@ -1,4 +1,4 @@
-# Generated from lib/riffer/structured_output/result.rb with RBS::Inline
+# Generated from lib/riffer/agent/structured_output/result.rb with RBS::Inline
 
 # Wraps the result of structured output parsing and validation.
 #
@@ -11,7 +11,7 @@
 #   else
 #     result.error   #=> "JSON parse error: ..."
 #   end
-class Riffer::StructuredOutput::Result
+class Riffer::Agent::StructuredOutput::Result
   attr_reader object: Hash[Symbol, untyped]?
 
   attr_reader error: String?

data/sig/generated/riffer/{structured_output.rbs → agent/structured_output.rbs}

@@ -1,14 +1,14 @@
-# Generated from lib/riffer/structured_output.rb with RBS::Inline
+# Generated from lib/riffer/agent/structured_output.rb with RBS::Inline
 
-# Riffer::StructuredOutput provides parse/validate for structured JSON
+# Riffer::Agent::StructuredOutput provides parse/validate for structured JSON
 # responses from LLM providers.
 #
 #   params = Riffer::Params.new
 #   params.required(:sentiment, String)
-#   so = Riffer::StructuredOutput.new(params)
+#   so = Riffer::Agent::StructuredOutput.new(params)
 #   result = so.parse_and_validate('{"sentiment":"positive","score":0.9}')
 #   result.object  #=> {sentiment: "positive", score: 0.9}
-class Riffer::StructuredOutput
+class Riffer::Agent::StructuredOutput
   attr_reader params: Riffer::Params
 
   # --
@@ -26,6 +26,6 @@ class Riffer::StructuredOutput
   # Returns a Result with the validated object on success, or an error message on failure.
   #
   # --
-  # : (String) -> Riffer::StructuredOutput::Result
-  def parse_and_validate: (String) -> Riffer::StructuredOutput::Result
+  # : (String) -> Riffer::Agent::StructuredOutput::Result
+  def parse_and_validate: (String) -> Riffer::Agent::StructuredOutput::Result
 end