riffer 0.45.0 → 0.46.1

data/lib/riffer/agent/response.rb

@@ -1,30 +1,29 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# 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
-  # @rbs @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]?
 
@@ -45,10 +44,9 @@ 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],
@@ -57,10 +55,9 @@ class Riffer::Agent::Response
   #  ) -> void
   def initialize(
     content,
+    outcome:,
     tripwire: nil,
     modifications: [],
-    interrupted: false,
-    interrupt_reason: nil,
     structured_output: nil,
     messages: [],
     healed_tool_call_ids: [],
@@ -68,10 +65,9 @@ class Riffer::Agent::Response
     steps: 0
   )
     @content = content
+    @outcome = outcome
     @tripwire = tripwire
     @modifications = modifications
-    @interrupted = interrupted
-    @interrupt_reason = interrupt_reason
     @structured_output = structured_output
     @messages = messages
     @healed_tool_call_ids = healed_tool_call_ids
@@ -79,14 +75,6 @@ class Riffer::Agent::Response
     @steps = steps
   end
 
-  # Returns true if the response was blocked by a guardrail.
-  #
-  #--
-  #: () -> bool
-  def blocked?
-    !tripwire.nil?
-  end
-
   # Returns true if any guardrail modified data during processing.
   #
   #--
@@ -94,13 +82,4 @@ class Riffer::Agent::Response
   def modified?
     modifications.any?
   end
-
-  # Returns true if the agent loop was interrupted by a callback
-  # via <tt>throw :riffer_interrupt</tt>.
-  #
-  #--
-  #: () -> bool
-  def interrupted?
-    @interrupted
-  end
 end

data/lib/riffer/agent/run.rb

@@ -20,7 +20,7 @@ module Riffer::Agent::Run
   # for prompt/files semantics.
   #
   #--
-  #: (agent: Riffer::Agent, ?prompt: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?tags: Hash[(String | Symbol), untyped]) -> Enumerator[Riffer::StreamEvents::Base, void]
+  #: (agent: Riffer::Agent, ?prompt: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?tags: Hash[(String | Symbol), untyped]) -> Enumerator[Riffer::StreamEvents::Base, Riffer::Agent::Response]
   def stream(agent:, prompt: nil, files: nil, tags: {})
     append_user_message(agent, prompt, files: files)
     # The enumerator body runs in its own fiber, where the fiber-local OTEL
@@ -155,6 +155,7 @@ module Riffer::Agent::Run
     accumulated_tool_calls = [] #: Array[Riffer::Messages::Assistant::ToolCall]
     accumulated_token_usage = nil #: Riffer::Providers::TokenUsage?
     accumulated_finish_reason = nil #: Symbol?
+    accumulated_finish_reason_raw = nil #: String?
 
     call_llm_stream(agent, tags).each do |event|
       stream_yielder << event
@@ -178,6 +179,7 @@ module Riffer::Agent::Run
         accumulated_token_usage = event.token_usage
       when Riffer::StreamEvents::FinishReasonDone
         accumulated_finish_reason = event.finish_reason
+        accumulated_finish_reason_raw = event.raw_finish_reason
       end
     end
 
@@ -186,6 +188,7 @@ module Riffer::Agent::Run
       tool_calls: accumulated_tool_calls,
       token_usage: accumulated_token_usage,
       finish_reason: accumulated_finish_reason,
+      finish_reason_raw: accumulated_finish_reason_raw,
     )
   end
 
@@ -207,6 +210,7 @@ module Riffer::Agent::Run
     build_response(
       agent,
       "",
+      outcome: Riffer::Agent::Outcome.new(reason: :guardrail_blocked, detail: tripwire.reason),
       tripwire: tripwire,
       modifications: all_modifications,
       token_usage: token_usage,
@@ -215,18 +219,41 @@ module Riffer::Agent::Run
   end
 
   #--
-  #: (Riffer::Agent, Array[Riffer::Guardrails::Modification], **untyped) -> Riffer::Agent::Response
-  def final_response(agent, all_modifications, **extra)
-    response = agent.session.final_assistant_message
+  #: (Riffer::Agent, Array[Riffer::Guardrails::Modification], ?interrupted: bool, ?interrupt_reason: (String | Symbol)?, **untyped) -> Riffer::Agent::Response
+  def final_response(agent, all_modifications, interrupted: false, interrupt_reason: nil, **extra)
+    message = agent.session.final_assistant_message
+    result = agent.structured_output && structured_output_result(agent, message)
     build_response(
       agent,
-      response&.content || "",
+      message&.content || "",
+      outcome: final_outcome(message, result, interrupted: interrupted, interrupt_reason: interrupt_reason),
       modifications: all_modifications,
-      structured_output: validate_structured_output(agent, response),
+      structured_output: result&.object,
       **extra,
     )
   end
 
+  # 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(message, result, interrupted:, interrupt_reason:)
+    finish_reason = message&.finish_reason
+    if interrupted && interrupt_reason == Riffer::Agent::INTERRUPT_MAX_STEPS
+      Riffer::Agent::Outcome.new(reason: :max_steps)
+    elsif interrupted
+      Riffer::Agent::Outcome.new(reason: :interrupted, detail: interrupt_reason&.to_s)
+    elsif finish_reason && !Riffer::Agent::Outcome::NORMAL_FINISH_REASONS.include?(finish_reason)
+      Riffer::Agent::Outcome.new(reason: finish_reason, detail: message&.finish_reason_raw)
+    elsif result&.failure?
+      Riffer::Agent::Outcome.new(reason: :invalid_structured_output, detail: result.error)
+    else
+      Riffer::Agent::Outcome.new(reason: :completed)
+    end
+  end
+
   #--
   #: (Riffer::Agent, ?Hash[String, String]) -> Riffer::Messages::Assistant
   def call_llm(agent, tags = {})
@@ -327,11 +354,11 @@ module Riffer::Agent::Run
   end
 
   #--
-  #: (Riffer::Agent, Riffer::Messages::Assistant?) -> Hash[Symbol, untyped]?
-  def validate_structured_output(agent, response)
-    return unless response&.structured_output? && agent.structured_output
+  #: (Riffer::Agent, Riffer::Messages::Assistant?) -> Riffer::Agent::StructuredOutput::Result?
+  def structured_output_result(agent, message)
+    return unless message
 
-    agent.structured_output.parse_and_validate(response.content).object
+    agent.structured_output&.parse_and_validate(message.content)
   end
 
   #--
@@ -358,10 +385,9 @@ 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?,
@@ -370,10 +396,9 @@ module Riffer::Agent::Run
   def build_response(
     agent,
     content,
+    outcome:,
     tripwire: nil,
     modifications: [],
-    interrupted: false,
-    interrupt_reason: nil,
     structured_output: nil,
     healed_tool_call_ids: [],
     token_usage: nil,
@@ -382,10 +407,9 @@ module Riffer::Agent::Run
     messages = agent.session.messages
     Riffer::Agent::Response.new(
       content,
+      outcome: outcome,
       tripwire: tripwire,
       modifications: modifications,
-      interrupted: interrupted,
-      interrupt_reason: interrupt_reason,
       structured_output: structured_output,
       messages: messages.frozen? ? messages : messages.dup.freeze,
       healed_tool_call_ids: healed_tool_call_ids,
@@ -460,7 +484,12 @@ module Riffer::Agent::Run
     span.set_attribute("riffer.steps", response.steps)
     Riffer::Tracing.record_usage(span, response.token_usage)
 
-    span.set_attribute("riffer.interrupt.reason", response.interrupt_reason.to_s) if response.interrupt_reason
+    outcome = response.outcome
+    span.set_attribute("riffer.outcome.reason", outcome.reason.to_s)
+    detail = outcome.detail
+    span.set_attribute("riffer.outcome.detail", detail) if detail
+    interrupt_reason = interrupt_reason_attribute(outcome)
+    span.set_attribute("riffer.interrupt.reason", interrupt_reason) if interrupt_reason
 
     tripwire = response.tripwire
     return unless tripwire
@@ -470,4 +499,13 @@ module Riffer::Agent::Run
     span.set_attribute("riffer.tripwire.reason", tripwire.reason)
     span.set_attribute("riffer.tripwire.phase", tripwire.phase.to_s)
   end
+
+  #--
+  #: (Riffer::Agent::Outcome) -> String?
+  def interrupt_reason_attribute(outcome)
+    case outcome.reason
+    when :max_steps then Riffer::Agent::INTERRUPT_MAX_STEPS.to_s
+    when :interrupted then outcome.detail
+    end
+  end
 end

data/lib/riffer/agent/session.rb

@@ -203,6 +203,8 @@ class Riffer::Agent::Session
         tool_calls: attrs.fetch(:tool_calls, old.tool_calls),
         token_usage: attrs.fetch(:token_usage, old.token_usage),
         structured_output: attrs.fetch(:structured_output, old.structured_output),
+        finish_reason: attrs.fetch(:finish_reason, old.finish_reason),
+        finish_reason_raw: attrs.fetch(:finish_reason_raw, old.finish_reason_raw),
       )
     when Riffer::Messages::Tool
       Riffer::Messages::Tool.new(

data/lib/riffer/agent.rb

@@ -155,7 +155,7 @@ class Riffer::Agent
 
   # Streams a response using a new agent instance.
   #--
-  #: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?context: Hash[Symbol, untyped]?, ?tags: Hash[(String | Symbol), untyped]) -> Enumerator[Riffer::StreamEvents::Base, void]
+  #: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?context: Hash[Symbol, untyped]?, ?tags: Hash[(String | Symbol), untyped]) -> Enumerator[Riffer::StreamEvents::Base, Riffer::Agent::Response]
   def self.stream(prompt = nil, files: nil, context: nil, tags: {})
     new(context: context).stream(prompt, files: files, tags: tags)
   end
@@ -304,13 +304,14 @@ class Riffer::Agent
     Riffer::Agent::Run.generate(agent: self, prompt: prompt, files: files, tags: tags)
   end
 
-  # Streams a response from the agent, returning an +Enumerator+ of
-  # +Riffer::StreamEvents+. See +#generate+ for prompt/files/tags semantics.
+  # Streams a response from the agent as an +Enumerator+ of
+  # +Riffer::StreamEvents+ whose block-form +each+ returns the final
+  # Riffer::Agent::Response. See +#generate+ for prompt/files/tags semantics.
   #
   # Raises Riffer::ArgumentError if structured output is configured.
   #
   #--
-  #: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?tags: Hash[(String | Symbol), untyped]) -> Enumerator[Riffer::StreamEvents::Base, void]
+  #: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?tags: Hash[(String | Symbol), untyped]) -> Enumerator[Riffer::StreamEvents::Base, Riffer::Agent::Response]
   def stream(prompt = nil, files: nil, tags: {})
     if @structured_output
       raise Riffer::ArgumentError,

data/lib/riffer/messages/assistant.rb

@@ -19,11 +19,31 @@ 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(content, id: nil, tool_calls: [], token_usage: nil, structured_output: nil, finish_reason: nil)
+  #: (
+  #    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(
+    content,
+    id: nil,
+    tool_calls: [],
+    token_usage: nil,
+    structured_output: nil,
+    finish_reason: nil,
+    finish_reason_raw: nil
+  )
     if finish_reason && !Riffer::Providers::FinishReason::VALUES.include?(finish_reason)
       values = Riffer::Providers::FinishReason::VALUES.inspect
       raise Riffer::ArgumentError, "finish_reason must be one of #{values}, got #{finish_reason.inspect}"
@@ -34,6 +54,7 @@ class Riffer::Messages::Assistant < Riffer::Messages::Base
     @token_usage = token_usage
     @structured_output = structured_output
     @finish_reason = finish_reason
+    @finish_reason_raw = finish_reason_raw
   end
 
   #--
@@ -71,6 +92,7 @@ class Riffer::Messages::Assistant < Riffer::Messages::Base
     hash[:token_usage] = token_usage.to_h if token_usage
     hash[:structured_output] = structured_output if structured_output?
     hash[:finish_reason] = finish_reason if finish_reason
+    hash[:finish_reason_raw] = finish_reason_raw if finish_reason_raw
     hash
   end
 end

data/lib/riffer/messages/base.rb

@@ -14,38 +14,30 @@ class Riffer::Messages::Base
 
     raise Riffer::ArgumentError, "Message must be a Hash or Message object, got #{msg.class}" unless msg.is_a?(Hash)
 
-    role = msg[:role]
-    content = msg[:content]
+    raise Riffer::ArgumentError, "Message hash must include a 'role' key" if msg[:role].nil? || msg[:role].empty?
 
-    raise Riffer::ArgumentError, "Message hash must include a 'role' key" if role.nil? || role.empty?
-
-    id = msg[:id]
-
-    case role.to_sym
+    case msg[:role].to_sym
     when :user
       files = (msg[:files] || []).map { |f| Riffer::Messages::FilePart.from_hash(f) }
-      Riffer::Messages::User.new(content, id: id, files: files)
+      Riffer::Messages::User.new(msg[:content], id: msg[:id], files: files)
     when :assistant
       tool_calls = (msg[:tool_calls] || []).map do |tc|
         tc.is_a?(Riffer::Messages::Assistant::ToolCall) ? tc : Riffer::Messages::Assistant::ToolCall.new(**tc)
       end
-      structured_output = msg[:structured_output]
-      finish_reason = msg[:finish_reason]&.to_sym
       Riffer::Messages::Assistant.new(
-        content,
-        id: id,
+        msg[:content],
+        id: msg[:id],
         tool_calls: tool_calls,
-        structured_output: structured_output,
-        finish_reason: finish_reason,
+        structured_output: msg[:structured_output],
+        finish_reason: msg[:finish_reason]&.to_sym,
+        finish_reason_raw: msg[:finish_reason_raw],
       )
     when :system
-      Riffer::Messages::System.new(content, id: id)
+      Riffer::Messages::System.new(msg[:content], id: msg[:id])
     when :tool
-      tool_call_id = msg[:tool_call_id]
-      name = msg[:name]
-      Riffer::Messages::Tool.new(content, id: id, tool_call_id: tool_call_id, name: name)
+      Riffer::Messages::Tool.new(msg[:content], id: msg[:id], tool_call_id: msg[:tool_call_id], name: msg[:name])
     else
-      raise Riffer::ArgumentError, "Unknown message role: #{role}"
+      raise Riffer::ArgumentError, "Unknown message role: #{msg[:role]}"
     end
   end
 

data/lib/riffer/params/param.rb

@@ -121,6 +121,8 @@ class Riffer::Params::Param
 
     if [Riffer::Params::Boolean, TrueClass, FalseClass].include?(type)
       [true, false].include?(value)
+    elsif type == Float
+      value.is_a?(Numeric)
     else
       value.is_a?(type)
     end

data/lib/riffer/params.rb

@@ -79,6 +79,11 @@ class Riffer::Params
 
   # Validates arguments against parameter definitions.
   #
+  # A Float param accepts an Integer (JSON Schema <tt>"number"</tt> covers
+  # integers) and its value is coerced with +to_f+, so callers always get a
+  # Float. The same holds for the items of an <tt>of: Float</tt> array. No other
+  # type is coerced.
+  #
   # Raises Riffer::ValidationError if validation fails.
   #
   #--
@@ -112,7 +117,7 @@ class Riffer::Params
 
       value = validate_nested(param, value, errors)
 
-      validated[param.name] = value
+      validated[param.name] = coerce_value(param.type, value)
     end
 
     raise Riffer::ValidationError, errors.join("; ") if errors.any?
@@ -178,7 +183,6 @@ class Riffer::Params
       validate_nested_array_of_objects(param, value, errors)
     elsif param.type == Array && param.item_type
       validate_typed_array(param, value, errors)
-      value
     else
       value
     end
@@ -218,20 +222,40 @@ class Riffer::Params
     end
   end
 
+  # Returns the array with its valid items coerced by +coerce_value+.
   #--
-  #: (Riffer::Params::Param, Array[untyped], Array[String]) -> void
+  #: (Riffer::Params::Param, Array[untyped], Array[String]) -> Array[untyped]
   def validate_typed_array(param, value, errors)
     item_type = param.item_type
-    return unless item_type
+    return value unless item_type
 
     type_name = Riffer::Params::Param::TYPE_MAPPINGS[item_type]
     valid_item = if [Riffer::Params::Boolean, TrueClass, FalseClass].include?(item_type)
                    ->(item) { [true, false].include?(item) }
+                 elsif item_type == Float
+                   ->(item) { item.is_a?(Numeric) }
                  else
                    ->(item) { item.is_a?(item_type) }
                  end
-    value.each_with_index do |item, i|
-      errors << "#{param.name}[#{i}] must be a #{type_name}" unless valid_item.call(item)
+    value.map.with_index do |item, i|
+      unless valid_item.call(item)
+        errors << "#{param.name}[#{i}] must be a #{type_name}"
+        next item
+      end
+
+      coerce_value(item_type, item)
     end
   end
+
+  # Coerces an already-validated value to the Ruby type its param declares.
+  # Only Float coerces today, because JSON Schema "number" accepts integers and
+  # callers should not get a type that depends on whether the model wrote a
+  # decimal point. Add a branch here rather than inline at a call site.
+  #--
+  #: (Module, untyped) -> untyped
+  def coerce_value(type, value)
+    return value.to_f if type == Float
+
+    value
+  end
 end

data/lib/riffer/providers/anthropic.rb

@@ -96,7 +96,12 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
       # Use strict schema to make optional fields nullable. Without this,
       # Anthropic may return empty strings or whitespace instead of null
       # for optional fields that the model has no value for.
+      #
+      # Merged over any caller-supplied output_config (e.g. effort) so those
+      # keys survive; the structured-output format wins because the run loop
+      # validates the response against it.
       params[:output_config] = {
+        **(params[:output_config] || {}),
         format: {
           type: "json_schema",
           schema: structured_output.json_schema(strict: true),

data/lib/riffer/providers/base.rb

@@ -71,6 +71,7 @@ class Riffer::Providers::Base
         token_usage: token_usage,
         structured_output: structured_output,
         finish_reason: finish_reason&.reason,
+        finish_reason_raw: finish_reason&.raw,
       )
     end
   end

data/lib/riffer/runner/fibers.rb

@@ -5,6 +5,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
   # @rbs @max_concurrency: Integer?
 
@@ -25,15 +27,15 @@ class Riffer::Runner::Fibers < Riffer::Runner
     results = Array.new(items.size)
     errors = Array.new(items.size)
 
-    Async do
-      barrier = Async::Barrier.new
-      max = @max_concurrency
-      parent = if max
-                 Async::Semaphore.new(max, parent: barrier)
-               else
-                 barrier
-               end
+    barrier = Async::Barrier.new
+    max = @max_concurrency
+    parent = if max
+               Async::Semaphore.new(max, parent: barrier)
+             else
+               barrier
+             end
 
+    Sync do
       items.each_with_index do |item, index|
         parent.async do
           results[index] = yield(item)
@@ -43,6 +45,8 @@ class Riffer::Runner::Fibers < Riffer::Runner
       end
 
       barrier.wait
+    ensure
+      barrier.stop
     end
 
     first_error = errors.compact.first

data/lib/riffer/version.rb

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

data/sig/_private/async.rbs

@@ -10,6 +10,8 @@ module Async
     def async: () { () -> void } -> untyped
 
     def wait: () -> void
+
+    def stop: () -> void
   end
 
   class Semaphore
@@ -21,4 +23,6 @@ end
 
 module Kernel
   def Async: () { () -> void } -> untyped
+
+  def Sync: () { () -> void } -> untyped
 end

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