riffer 0.44.0 → 0.46.0

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

@@ -0,0 +1,41 @@
+# 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
+end

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

@@ -1,29 +1,28 @@
 # Generated from lib/riffer/agent/response.rb with RBS::Inline
 
-# Wraps an agent generation response. When a guardrail blocks execution,
-# +content+ is empty and +tripwire+ carries the block details.
+# 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.blocked?
-#     puts "Blocked: #{response.tripwire.reason}"
-#   else
+#   if response.outcome.success?
 #     puts response.content
+#   else
+#     puts "#{response.outcome.reason}: #{response.outcome.detail}"
 #   end
 class Riffer::Agent::Response
-  @interrupted: bool
-
   # 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 reason provided with the interrupt, if any.
-  attr_reader interrupt_reason: (String | Symbol)?
-
   # The parsed structured output, if structured output was configured.
   attr_reader structured_output: Hash[Symbol, untyped]?
 
@@ -44,34 +43,20 @@ class Riffer::Agent::Response
   # --
   # : (
   #     String,
+  #     outcome: Riffer::Agent::Outcome,
   #     ?tripwire: Riffer::Guardrails::Tripwire?,
   #     ?modifications: Array[Riffer::Guardrails::Modification],
-  #     ?interrupted: bool,
-  #     ?interrupt_reason: (String | Symbol)?,
   #     ?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, ?tripwire: Riffer::Guardrails::Tripwire?, ?modifications: Array[Riffer::Guardrails::Modification], ?interrupted: bool, ?interrupt_reason: (String | Symbol)?, ?structured_output: Hash[Symbol, untyped]?, ?messages: Array[Riffer::Messages::Base], ?healed_tool_call_ids: Array[String], ?token_usage: Riffer::Providers::TokenUsage?, ?steps: Integer) -> void
-
-  # Returns true if the response was blocked by a guardrail.
-  #
-  # --
-  # : () -> bool
-  def blocked?: () -> bool
+  def initialize: (String, outcome: Riffer::Agent::Outcome, ?tripwire: Riffer::Guardrails::Tripwire?, ?modifications: Array[Riffer::Guardrails::Modification], ?structured_output: Hash[Symbol, untyped]?, ?messages: Array[Riffer::Messages::Base], ?healed_tool_call_ids: Array[String], ?token_usage: Riffer::Providers::TokenUsage?, ?steps: Integer) -> void
 
   # Returns true if any guardrail modified data during processing.
   #
   # --
   # : () -> bool
   def modified?: () -> bool
-
-  # Returns true if the agent loop was interrupted by a callback
-  # via <tt>throw :riffer_interrupt</tt>.
-  #
-  # --
-  # : () -> bool
-  def interrupted?: () -> bool
 end

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

@@ -45,8 +45,16 @@ module Riffer::Agent::Run
   def tripwire_response: (Riffer::Agent, Enumerator::Yielder?, Riffer::Guardrails::Tripwire, Array[Riffer::Guardrails::Modification], ?token_usage: Riffer::Providers::TokenUsage?, ?steps: Integer) -> Riffer::Agent::Response
 
   # --
-  # : (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, 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
 
   # --
   # : (Riffer::Agent, ?Hash[String, String]) -> Riffer::Messages::Assistant
@@ -77,8 +85,8 @@ module Riffer::Agent::Run
   def run_after_guardrails: (Riffer::Agent, Riffer::Messages::Assistant, Enumerator::Yielder?, Array[Riffer::Guardrails::Modification], ?Hash[String, String]) { (Riffer::Guardrails::Tripwire) -> void } -> untyped
 
   # --
-  # : (Riffer::Agent, Riffer::Messages::Assistant?) -> Hash[Symbol, untyped]?
-  def validate_structured_output: (Riffer::Agent, Riffer::Messages::Assistant?) -> Hash[Symbol, untyped]?
+  # : (Riffer::Agent, Riffer::Messages::Assistant?) -> Riffer::Agent::StructuredOutput::Result?
+  def structured_output_result: (Riffer::Agent, Riffer::Messages::Assistant?) -> Riffer::Agent::StructuredOutput::Result?
 
   # --
   # : (Riffer::Agent) -> Array[singleton(Riffer::Tool)]
@@ -96,16 +104,15 @@ module Riffer::Agent::Run
   # : (
   #     Riffer::Agent,
   #     String,
+  #     outcome: Riffer::Agent::Outcome,
   #     ?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],
   #     ?token_usage: Riffer::Providers::TokenUsage?,
   #     ?steps: Integer
   #   ) -> 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], ?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], ?structured_output: Hash[Symbol, untyped]?, ?healed_tool_call_ids: Array[String], ?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.
@@ -136,4 +143,8 @@ module Riffer::Agent::Run
   # --
   # : (Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span, Riffer::Agent::Response) -> void
   def record_run_outcome: (Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span, Riffer::Agent::Response) -> void
+
+  # --
+  # : (Riffer::Agent::Outcome) -> String?
+  def interrupt_reason_attribute: (Riffer::Agent::Outcome) -> String?
 end

data/sig/generated/riffer/messages/assistant.rbs

@@ -27,11 +27,23 @@ class Riffer::Messages::Assistant < Riffer::Messages::Base
   # <tt>Riffer::Providers::FinishReason::VALUES</tt>).
   attr_reader finish_reason: Symbol?
 
+  # The provider's raw finish-reason value behind +finish_reason+, when one
+  # exists on the wire.
+  attr_reader finish_reason_raw: String?
+
   # Raises Riffer::ArgumentError when +finish_reason+ is outside the
   # normalized vocabulary.
   # --
-  # : (String, ?id: String?, ?tool_calls: Array[Riffer::Messages::Assistant::ToolCall], ?token_usage: Riffer::Providers::TokenUsage?, ?structured_output: Hash[Symbol, untyped]?, ?finish_reason: Symbol?) -> void
-  def initialize: (String, ?id: String?, ?tool_calls: Array[Riffer::Messages::Assistant::ToolCall], ?token_usage: Riffer::Providers::TokenUsage?, ?structured_output: Hash[Symbol, untyped]?, ?finish_reason: Symbol?) -> void
+  # : (
+  #    String,
+  #    ?id: String?,
+  #    ?tool_calls: Array[Riffer::Messages::Assistant::ToolCall],
+  #    ?token_usage: Riffer::Providers::TokenUsage?,
+  #    ?structured_output: Hash[Symbol, untyped]?,
+  #    ?finish_reason: Symbol?,
+  #    ?finish_reason_raw: String?
+  #  ) -> void
+  def initialize: (String, ?id: String?, ?tool_calls: Array[Riffer::Messages::Assistant::ToolCall], ?token_usage: Riffer::Providers::TokenUsage?, ?structured_output: Hash[Symbol, untyped]?, ?finish_reason: Symbol?, ?finish_reason_raw: String?) -> void
 
   # --
   # : () -> Symbol

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

@@ -4,6 +4,11 @@
 class Riffer::Providers::OpenAI < Riffer::Providers::Base
   WEB_SEARCH_TOOL_TYPE: String
 
+  # The Responses API has no finish_reason field. The response +status+ is
+  # the primary signal; an +incomplete+ status is only meaningful together
+  # with <tt>incomplete_details.reason</tt>, so that branch nests one level.
+  FINISH_REASONS: Hash[String, Symbol | Hash[String, Symbol]]
+
   # The GenAI semconv well-known provider name.
   # --
   # : () -> String
@@ -50,14 +55,14 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
   # : (untyped) -> Riffer::Providers::FinishReason?
   def extract_finish_reason: (untyped) -> Riffer::Providers::FinishReason?
 
-  # The Responses API reports no finish_reason field, so one is derived.
   # --
   # : (untyped) -> Riffer::Providers::FinishReason?
   def build_finish_reason: (untyped) -> Riffer::Providers::FinishReason?
 
+  # The nested field that names the cause behind an ambiguous status.
   # --
-  # : (untyped) -> Riffer::Providers::FinishReason
-  def incomplete_finish_reason: (untyped) -> Riffer::Providers::FinishReason
+  # : (untyped, String) -> String?
+  def finish_detail: (untyped, String) -> String?
 
   # --
   # : (untyped) -> String

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

@@ -57,9 +57,17 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
   # : (untyped) -> Riffer::Providers::FinishReason?
   def extract_finish_reason: (untyped) -> Riffer::Providers::FinishReason?
 
+  # +native+ is the upstream model's own finish reason, which OpenRouter
+  # reports alongside its normalized one; it wins as +raw+ when present.
   # --
-  # : (untyped) -> Riffer::Providers::FinishReason?
-  def build_finish_reason: (untyped) -> Riffer::Providers::FinishReason?
+  # : (untyped, ?native: untyped) -> Riffer::Providers::FinishReason?
+  def build_finish_reason: (untyped, ?native: untyped) -> Riffer::Providers::FinishReason?
+
+  # +native_finish_reason+ is outside the OpenAI schema, so it is only
+  # reachable through the SDK model's raw data hash.
+  # --
+  # : (untyped) -> untyped
+  def native_finish_reason: (untyped) -> untyped
 
   # --
   # : (untyped) -> String

data/sig/generated/riffer/runner/fibers.rbs

@@ -4,6 +4,8 @@
 # +max_concurrency+ caps simultaneous fibers via an <tt>Async::Semaphore</tt>.
 # If multiple fibers raise, only the first exception is re-raised after all
 # finish.
+# Joins the current reactor task when one is already running, and otherwise
+# starts its own.
 class Riffer::Runner::Fibers < Riffer::Runner
   @max_concurrency: Integer?
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: riffer
 version: !ruby/object:Gem::Version
-  version: 0.44.0
+  version: 0.46.0
 platform: ruby
 authors:
 - Jake Bottrall
@@ -110,6 +110,7 @@ files:
 - lib/riffer/agent.rb
 - lib/riffer/agent/config.rb
 - lib/riffer/agent/context.rb
+- lib/riffer/agent/outcome.rb
 - lib/riffer/agent/response.rb
 - lib/riffer/agent/run.rb
 - lib/riffer/agent/serializer.rb
@@ -239,6 +240,7 @@ files:
 - sig/generated/riffer/agent.rbs
 - sig/generated/riffer/agent/config.rbs
 - sig/generated/riffer/agent/context.rbs
+- sig/generated/riffer/agent/outcome.rbs
 - sig/generated/riffer/agent/response.rbs
 - sig/generated/riffer/agent/run.rbs
 - sig/generated/riffer/agent/serializer.rbs