riffer 0.44.0 → 0.45.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7f7862ed670d852eee1e076386032449773a8782424fbfc9bc80e96aab61b1e3
-  data.tar.gz: b520d7629441e6acd75a677bc3d094359f5a5b7f31c2986d6aadd51f2935b3e1
+  metadata.gz: b166b910624129bd5b64b9443caba3b5c781b691a7453b5640cd132c21cd72c2
+  data.tar.gz: d64178e66b49945647393430b57f84a501ec7c0bfbe866b20f6f1b6af44ef570
 SHA512:
-  metadata.gz: '069d1d96193748ffdc48eb95a8fe22b57c6293a33e7ba4658a01fda4e5c4a7847145bb234605c0507059830c300dc2d85ec295ecf2d59de20265385644d6dc89'
-  data.tar.gz: 86bbcfb5408f3b5ba0fbb327dff9c2a98c0ee410e3ce4ab72c89a3a66d8aaa8e4d095e2ee14bc32c814caa28503cf0d099095441a60eb4cb9e11b7639f522d65
+  metadata.gz: 36ce62e6539e22a01c5f8523278203b0307a2753c8e3af8e683133b741144417b360721862249d2c64fb118211f134e7b968d681e4c31e20f9ca051768e9aef6
+  data.tar.gz: 39ac8834695876cd923e3dffe7065045f7296e418056e18eae9da4811ba04c886b546342a4a4586d92ac529ec456a18e0b272b0598eb70c72371af2dbefebce3

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.44.0"
+  ".": "0.45.0"
 }

data/CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.45.0](https://github.com/janeapp/riffer/compare/riffer/v0.44.0...riffer/v0.45.0) (2026-09-03)
+
+
+### Features
+
+* expand finish reason vocabulary and close provider gaps ([#419](https://github.com/janeapp/riffer/issues/419)) ([daf91a6](https://github.com/janeapp/riffer/commit/daf91a61956ce8da626a590d30307e11e90d474b))
+
 ## [0.44.0](https://github.com/janeapp/riffer/compare/riffer/v0.43.0...riffer/v0.44.0) (2026-08-28)
 
 

data/docs/MESSAGES.md

@@ -83,16 +83,18 @@ The cache buckets are subsets of `input_tokens`, never additions to it — summi
 
 `finish_reason` carries the same meaning for every provider — each adapter maps its raw wire value (Anthropic's `end_turn`, OpenAI's response status, Gemini's `STOP`, …) into a normalized vocabulary:
 
-| Value             | Meaning                                                         |
-| ----------------- | --------------------------------------------------------------- |
-| `:stop`           | The model finished its turn naturally (or hit a stop sequence). |
-| `:length`         | Output was truncated at the max-token limit.                    |
-| `:tool_calls`     | The model stopped to call tools.                                |
-| `:content_filter` | A provider safety system blocked or cut the response.           |
-| `:error`          | The provider reported an error finish.                          |
-| `:other`          | A provider-specific value with no normalized equivalent.        |
-
-`finish_reason` is `nil` when the provider doesn't report one. Use it to detect truncation without parsing provider responses:
+| Value               | Meaning                                                                                                                 |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `:stop`             | The model finished its turn naturally (or hit a stop sequence).                                                         |
+| `:length`           | Output was truncated at the max-token limit.                                                                            |
+| `:tool_calls`       | The model stopped to call tools.                                                                                        |
+| `:content_filter`   | A provider safety system blocked or cut the response.                                                                   |
+| `:context_window`   | Input plus output hit the model's context window; trim or compact history rather than raising `max_tokens`.             |
+| `:malformed_output` | The model emitted output the provider could not parse, such as an invalid tool call; retry or nudge rather than backing off. |
+| `:error`            | The provider reported an error finish.                                                                                  |
+| `:other`            | A provider-specific value with no normalized equivalent.                                                                |
+
+`finish_reason` is `nil` when the provider doesn't report one. The provider's raw wire value travels alongside on the `FinishReasonDone` stream event and the `riffer.finish_reason.raw` trace attribute — for OpenRouter that is the upstream model's `native_finish_reason`, and for a failed OpenAI response it is the error code. Use `finish_reason` to detect truncation without parsing provider responses:
 
 ```ruby
 response = agent.generate("Summarize this document")

data/docs/TRACING.md

@@ -153,7 +153,7 @@ Usage on this span is the run total, aggregated across every step. See [Token us
 | `gen_ai.output.messages`                   | string   | When `capture_messages` is on (JSON)                                          |
 | `error.type`                               | string   | On an unhandled exception                                                     |
 
-`gen_ai.response.finish_reasons` is an array of exactly one normalized value, from the fixed vocabulary `stop`, `length`, `tool_calls`, `content_filter`, `error`, `other`. When the provider's raw wire value carries more nuance than the normalized one, the raw string is preserved on `riffer.finish_reason.raw`.
+`gen_ai.response.finish_reasons` is an array of exactly one normalized value, from the fixed vocabulary `stop`, `length`, `tool_calls`, `content_filter`, `context_window`, `malformed_output`, `error`, `other`. When the provider's raw wire value carries more nuance than the normalized one, the raw string is preserved on `riffer.finish_reason.raw`.
 
 ## `execute_tool {tool}` — the tool call span
 

data/docs/providers/CUSTOM_PROVIDERS.md

@@ -252,7 +252,7 @@ Riffer::StreamEvents::FinishReasonDone.new(
 
 ## Finish Reasons
 
-`Riffer::Providers::FinishReason` is the same kind of normalized contract — map your provider's raw finish/stop value into the vocabulary defined in [Messages — Finish Reasons](../MESSAGES.md#finish-reasons) (`:stop`, `:length`, `:tool_calls`, `:content_filter`, `:error`, `:other`), keeping the raw wire value alongside:
+`Riffer::Providers::FinishReason` is the same kind of normalized contract — map your provider's raw finish/stop value into the vocabulary defined in [Messages — Finish Reasons](../MESSAGES.md#finish-reasons) (`:stop`, `:length`, `:tool_calls`, `:content_filter`, `:context_window`, `:malformed_output`, `:error`, `:other`), keeping the raw wire value alongside:
 
 ```ruby
 def extract_finish_reason(response)

data/lib/riffer/providers/amazon_bedrock.rb

@@ -17,6 +17,9 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
     "tool_use" => :tool_calls,
     "guardrail_intervened" => :content_filter,
     "content_filtered" => :content_filter,
+    "malformed_model_output" => :malformed_output,
+    "malformed_tool_use" => :malformed_output,
+    "model_context_window_exceeded" => :context_window,
   }.freeze #: Hash[String, Symbol]
 
   # Returns the skill adapter for the Bedrock model — XML for Anthropic models

data/lib/riffer/providers/anthropic.rb

@@ -12,6 +12,10 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
     "max_tokens" => :length,
     "tool_use" => :tool_calls,
     "refusal" => :content_filter,
+    "model_context_window_exceeded" => :context_window,
+    # A paused server-tool turn resumes only by re-sending the response; the
+    # agent loop does not do that, so it has no normalized equivalent.
+    "pause_turn" => :other,
   }.freeze #: Hash[String, Symbol]
 
   # Returns the XML skill adapter for Anthropic/Claude.

data/lib/riffer/providers/finish_reason.rb

@@ -5,7 +5,7 @@
 # wire value. +reason+ carries the same meaning for every provider.
 class Riffer::Providers::FinishReason
   # The normalized vocabulary every provider maps into.
-  VALUES = %i[stop length tool_calls content_filter error other].freeze #: Array[Symbol]
+  VALUES = %i[stop length tool_calls content_filter context_window malformed_output error other].freeze #: Array[Symbol]
 
   # The normalized reason.
   attr_reader :reason #: Symbol

data/lib/riffer/providers/gemini.rb

@@ -17,7 +17,16 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
     "PROHIBITED_CONTENT" => :content_filter,
     "SPII" => :content_filter,
     "IMAGE_SAFETY" => :content_filter,
-    "MALFORMED_FUNCTION_CALL" => :error,
+    "IMAGE_PROHIBITED_CONTENT" => :content_filter,
+    "IMAGE_RECITATION" => :content_filter,
+    "LANGUAGE" => :content_filter,
+    "MALFORMED_FUNCTION_CALL" => :malformed_output,
+    "UNEXPECTED_TOOL_CALL" => :malformed_output,
+    "NO_IMAGE" => :error,
+    "TOO_MANY_TOOL_CALLS" => :other,
+    "OTHER" => :other,
+    "IMAGE_OTHER" => :other,
+    "FINISH_REASON_UNSPECIFIED" => :other,
   }.freeze #: Hash[String, Symbol]
 
   # The GenAI semconv well-known provider name.

data/lib/riffer/providers/open_ai.rb

@@ -5,6 +5,21 @@
 class Riffer::Providers::OpenAI < Riffer::Providers::Base
   WEB_SEARCH_TOOL_TYPE = "web_search_preview" #: 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 = {
+    "completed" => :stop,
+    "incomplete" => {
+      "max_output_tokens" => :length,
+      "content_filter" => :content_filter,
+    },
+    "failed" => :error,
+    "cancelled" => :other,
+    "in_progress" => :other,
+    "queued" => :other,
+  }.freeze #: Hash[String, Symbol | Hash[String, Symbol]]
+
   # The GenAI semconv well-known provider name.
   #--
   #: () -> String
@@ -133,40 +148,32 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
     build_finish_reason(response)
   end
 
-  # The Responses API reports no finish_reason field, so one is derived.
   #--
   #: (untyped) -> Riffer::Providers::FinishReason?
   def build_finish_reason(response)
     typed_response = response #: OpenAI::Models::Responses::Response
-    status = typed_response.status
+    status = typed_response.status&.to_s
     return nil unless status
 
-    case status.to_sym
-    when :completed
-      reason = extract_tool_calls(typed_response).empty? ? :stop : :tool_calls
-      Riffer::Providers::FinishReason.new(reason: reason, raw: "completed")
-    when :incomplete
-      incomplete_finish_reason(typed_response)
-    when :failed
-      Riffer::Providers::FinishReason.new(reason: :error, raw: "failed")
-    else
-      Riffer::Providers::FinishReason.new(reason: :other, raw: status.to_s)
-    end
+    detail = finish_detail(typed_response, status)
+    mapping = FINISH_REASONS.fetch(status, :other)
+    reason = mapping.is_a?(Hash) ? mapping.fetch(detail.to_s, :other) : mapping
+    # A completed response signals tool use only through its output items.
+    reason = :tool_calls if reason == :stop && !extract_tool_calls(typed_response).empty?
+
+    Riffer::Providers::FinishReason.new(reason: reason, raw: detail || status)
   end
 
+  # The nested field that names the cause behind an ambiguous status.
   #--
-  #: (untyped) -> Riffer::Providers::FinishReason
-  def incomplete_finish_reason(response)
+  #: (untyped, String) -> String?
+  def finish_detail(response, status)
     typed_response = response #: OpenAI::Models::Responses::Response
-    raw = typed_response.incomplete_details&.reason&.to_s
-
-    reason = case raw
-             when "max_output_tokens" then :length
-             when "content_filter" then :content_filter
-             else :other
-             end
 
-    Riffer::Providers::FinishReason.new(reason: reason, raw: raw || "incomplete")
+    case status
+    when "incomplete" then typed_response.incomplete_details&.reason&.to_s
+    when "failed" then typed_response.error&.code&.to_s
+    end
   end
 
   #--

data/lib/riffer/providers/open_router.rb

@@ -133,18 +133,30 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
   #: (untyped) -> Riffer::Providers::FinishReason?
   def extract_finish_reason(response)
     typed_response = response #: OpenAI::Models::Chat::ChatCompletion
-    build_finish_reason(typed_response.choices.first&.finish_reason)
+    choice = typed_response.choices.first
+    build_finish_reason(choice&.finish_reason, native: native_finish_reason(choice))
   end
 
+  # +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(finish_reason)
+  #: (untyped, ?native: untyped) -> Riffer::Providers::FinishReason?
+  def build_finish_reason(finish_reason, native: nil)
     return nil unless finish_reason
 
-    raw = finish_reason.to_s
-    return nil if raw.empty?
+    normalized = finish_reason.to_s
+    return nil if normalized.empty?
+
+    raw = native.to_s.empty? ? normalized : native.to_s
+    Riffer::Providers::FinishReason.new(reason: FINISH_REASONS.fetch(normalized, :other), raw: raw)
+  end
 
-    Riffer::Providers::FinishReason.new(reason: FINISH_REASONS.fetch(raw, :other), raw: raw)
+  # +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(choice)
+    choice && choice.to_h[:native_finish_reason]
   end
 
   #--
@@ -187,6 +199,7 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
       reasoning: +"",
       tool_calls: {},
       finish_reason: nil,
+      native_finish_reason: nil,
     } #: Hash[Symbol, untyped]
 
     # Use stream_raw (not stream) — the latter yields a higher-level
@@ -211,7 +224,7 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
 
     yielder << Riffer::StreamEvents::TextDone.new(state[:text]) unless state[:text].empty?
     yielder << Riffer::StreamEvents::ReasoningDone.new(state[:reasoning]) unless state[:reasoning].empty?
-    yield_finish_reason(yielder, build_finish_reason(state[:finish_reason]))
+    yield_finish_reason(yielder, build_finish_reason(state[:finish_reason], native: state[:native_finish_reason]))
   end
 
   #--
@@ -228,6 +241,7 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
     end
 
     state[:finish_reason] = choice.finish_reason if choice&.finish_reason
+    state[:native_finish_reason] = native_finish_reason(choice) || state[:native_finish_reason]
 
     emit_tool_call_done_events(state: state, yielder: yielder) if choice && finish_reason_is_tool_calls?(choice)
 

data/lib/riffer/version.rb

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

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: riffer
 version: !ruby/object:Gem::Version
-  version: 0.44.0
+  version: 0.45.0
 platform: ruby
 authors:
 - Jake Bottrall