riffer 0.44.0 → 0.46.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7f7862ed670d852eee1e076386032449773a8782424fbfc9bc80e96aab61b1e3
-  data.tar.gz: b520d7629441e6acd75a677bc3d094359f5a5b7f31c2986d6aadd51f2935b3e1
+  metadata.gz: ac304f75fface8720f1e2565ea2064b643abb2f1c29f5a9dfe5281820e9d3986
+  data.tar.gz: de5695cffa30697e0356de921227caffdab12ff806e143166369c36e3ae010d6
 SHA512:
-  metadata.gz: '069d1d96193748ffdc48eb95a8fe22b57c6293a33e7ba4658a01fda4e5c4a7847145bb234605c0507059830c300dc2d85ec295ecf2d59de20265385644d6dc89'
-  data.tar.gz: 86bbcfb5408f3b5ba0fbb327dff9c2a98c0ee410e3ce4ab72c89a3a66d8aaa8e4d095e2ee14bc32c814caa28503cf0d099095441a60eb4cb9e11b7639f522d65
+  metadata.gz: dfe9da5a5cb0a8a1147846766acc79b518a9f7025d1d95fbfddce3604e2315afafc04762b339879eee2db875aba5cc296056045f213f47a17cb9f730e17f3e07
+  data.tar.gz: b548a4b44b001b79ee295969af5a868f50d0e847a183dc9433e5b23d4b1e7c9effed3ea64a76a8f5022db959a65394d8f8ff28bba9a6d46484841322483ebe02

data/.release-please-manifest.json

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

data/CHANGELOG.md

@@ -5,6 +5,30 @@ 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.46.0](https://github.com/janeapp/riffer/compare/riffer/v0.45.0...riffer/v0.46.0) (2026-09-08)
+
+
+### ⚠ BREAKING CHANGES
+
+* Response#blocked?, Response#interrupted?, and Response#interrupt_reason are removed. Check response.outcome.reason for :guardrail_blocked, :interrupted, or :max_steps instead; response.tripwire still carries the full tripwire object. Response.new now requires outcome:.
+
+### Features
+
+* report how a run ended through Response#outcome ([#425](https://github.com/janeapp/riffer/issues/425)) ([2ba2157](https://github.com/janeapp/riffer/commit/2ba2157668cd4a2b013da190dd647ae131accfa3))
+
+
+### Bug Fixes
+
+* **anthropic:** merge caller output_config with structured output ([#422](https://github.com/janeapp/riffer/issues/422)) ([e1a60e6](https://github.com/janeapp/riffer/commit/e1a60e6f082dbf7d4ee9d151e96e56bdf3f26359))
+* **runner:** make Fibers runner safe inside a running Async reactor ([#424](https://github.com/janeapp/riffer/issues/424)) ([47d3706](https://github.com/janeapp/riffer/commit/47d3706dbeac1e456bbf8365361cf16741b09adf))
+
+## [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/AGENTS.md

@@ -168,6 +168,19 @@ end
 
 The LLM response is automatically parsed and validated against the schema. Access the result via `response.structured_output`.
 
+When the response is not valid JSON or does not satisfy the schema, `response.structured_output` is `nil`, `response.outcome.reason` is `:invalid_structured_output`, and `response.outcome.detail` carries the parse or validation message:
+
+```ruby
+response = SentimentAgent.generate('Analyze: "I love this!"')
+
+if response.outcome.success?
+  response.structured_output  # => {sentiment: "positive", score: 0.95}
+else
+  response.outcome.reason     # => :invalid_structured_output
+  response.outcome.detail     # => "score is required"
+end
+```
+
 #### Nested Objects
 
 Use `Hash` with a block to define nested object schemas:

data/docs/AGENT_LIFECYCLE.md

@@ -30,9 +30,8 @@ agent.generate(prompt = nil, files: nil)
 ```ruby
 # New conversation (class method — recommended for simple calls)
 response = MyAgent.generate('Hello', context: {user_id: 123})
-puts response.content       # Access the response text
-puts response.blocked?      # Check if guardrail blocked (always false without guardrails)
-puts response.interrupted?  # Check if a callback interrupted the loop
+puts response.content         # Access the response text
+puts response.outcome.reason  # How the run ended (:completed, :guardrail_blocked, :interrupted, ...)
 
 # New conversation (instance method — when you need message history or callbacks)
 agent = MyAgent.new(context: {user_id: 123})
@@ -142,9 +141,9 @@ Works with both `generate` and `stream`. Only emits agent-generated messages (As
 
 Callbacks can interrupt the agent loop. This is useful for human-in-the-loop approval, cost limits, or content filtering.
 
-Use `agent.interrupt!` (or the lower-level `throw :riffer_interrupt`) to stop the loop. The response will have `interrupted?` set to `true` and contain the accumulated content up to the point of interruption.
+Use `agent.interrupt!` (or the lower-level `throw :riffer_interrupt`) to stop the loop. The response's `outcome.reason` will be `:interrupted` and `content` will hold the accumulated content up to the point of interruption.
 
-An optional reason can be passed to `interrupt!`. It is available via `interrupt_reason` on the response (generate) or `reason` on the `Interrupt` event (stream):
+An optional reason can be passed to `interrupt!`. It is available via `outcome.detail` on the response (generate) or `reason` on the `Interrupt` event (stream):
 
 ```ruby
 agent = MyAgent.new
@@ -155,9 +154,9 @@ agent.session.on_message do |msg|
 end
 
 response = agent.generate('Call the tool')
-response.interrupted?      # => true
-response.interrupt_reason  # => "needs human approval"
-response.content           # => last assistant content before interrupt
+response.outcome.reason  # => :interrupted
+response.outcome.detail  # => "needs human approval"
+response.content         # => last assistant content before interrupt
 ```
 
 **Streaming** — interrupts emit an `Interrupt` event:
@@ -188,7 +187,7 @@ agent.session.on_message { |msg| throw :riffer_interrupt if needs_approval?(msg)
 
 response = agent.generate('Do something risky')
 
-if response.interrupted?
+if response.outcome.reason == :interrupted
   approve_action(agent.session.messages)
   response = agent.generate('Approved, go ahead')  # executes pending tools, then calls the LLM
   # or: agent.generate                              # resume without a new turn
@@ -301,23 +300,49 @@ agent.context[:skills]        # the Skills::Context, if skills configured
 
 ## Response Attributes
 
-`Riffer::Agent::Response` is returned by `generate`:
+`Riffer::Agent::Response` is returned by `generate`. Start with `response.outcome`: its `reason` says how the run ended, and everything else on the response is detail for that reason. `response.content` and `response.structured_output` are only meaningful when the reason is `:completed`; see [response.outcome](#responseoutcome) for the full vocabulary.
 
 | Attribute              | Type                        | Description                                                                                      |
 | ---------------------- | --------------------------- | ------------------------------------------------------------------------------------------------ |
 | `content`              | `String`                    | The response text                                                                                |
+| `outcome`              | `Outcome`                   | How the run ended — `reason` and optional `detail` (see below)                                   |
 | `structured_output`    | `Hash` / `nil`              | Parsed and validated structured output (see below)                                               |
-| `blocked?`             | `Boolean`                   | `true` if a guardrail tripwire fired                                                             |
 | `tripwire`             | `Tripwire` / `nil`          | The guardrail tripwire that blocked the request                                                  |
 | `modified?`            | `Boolean`                   | `true` if a guardrail modified the content                                                       |
 | `modifications`        | `Array`                     | List of guardrail modifications applied                                                          |
-| `interrupted?`         | `Boolean`                   | `true` if the loop was interrupted                                                               |
-| `interrupt_reason`     | `String` / `Symbol` / `nil` | The reason passed to `throw :riffer_interrupt`                                                   |
 | `messages`             | `Array`                     | Full message history from the conversation                                                       |
 | `healed_tool_call_ids` | `Array[String]`             | `tool_call` ids filled with placeholder results during interrupt healing (else `[]`)             |
 | `token_usage`          | `TokenUsage` / `nil`        | Aggregate `Riffer::Providers::TokenUsage` across this run's LLM calls (`nil` when none reported) |
 | `steps`                | `Integer`                   | LLM calls made during this run (`0` when a before-guardrail blocks first); not the session's cumulative count |
 
+### response.outcome
+
+`response.outcome` is a `Riffer::Agent::Outcome` — the single place to read how the run ended. `reason` is always one of the values below; `detail` is a `String` with the specifics when there are any, else `nil`. `outcome.success?` is shorthand for `reason == :completed`.
+
+| Reason                       | Source                                                     | `detail`                                  |
+| ---------------------------- | ---------------------------------------------------------- | ----------------------------------------- |
+| `:completed`                 | The loop ended normally                                    | `nil`                                     |
+| `:guardrail_blocked`         | A guardrail tripwire fired (`tripwire` is set)             | The tripwire reason                       |
+| `:max_steps`                 | The `max_steps` limit was reached                          | `nil`                                     |
+| `:interrupted`               | A callback called `interrupt!` / `throw :riffer_interrupt` | The interrupt reason, or `nil`            |
+| `:length`, `:content_filter`, `:context_window`, `:malformed_output`, `:error`, `:other` | The assistant message's normalized `finish_reason` (see [Messages — Finish Reasons](MESSAGES.md#finish-reasons)) | The provider's raw finish value (`finish_reason_raw`), or `nil` |
+| `:invalid_structured_output` | The final message failed JSON parsing or schema validation | The parse or validation error             |
+
+When several apply, the most causal wins: a guardrail block outranks an interrupt, an interrupt outranks the provider's finish reason, and the provider's finish reason outranks a structured output failure. A run that hit `:length` and therefore produced invalid JSON reports `:length`.
+
+```ruby
+agent = MyAgent.new
+response = agent.generate('Hello')
+
+case response.outcome.reason
+when :completed                 then puts response.content
+when :guardrail_blocked         then puts "Blocked: #{response.outcome.detail}"
+when :interrupted, :max_steps   then response = agent.generate('Continue')
+when :invalid_structured_output then warn response.outcome.detail
+else warn "Provider stopped early: #{response.outcome.reason}"
+end
+```
+
 ### response.structured_output
 
 When structured output is configured, the LLM response is parsed as JSON and validated against the schema. The validated result is available as `response.structured_output`:
@@ -328,7 +353,7 @@ response.content            # => raw JSON string from the LLM
 response.structured_output  # => {sentiment: "positive", score: 0.95}
 ```
 
-Returns `nil` when structured output is not configured or when validation fails.
+Returns `nil` when structured output is not configured, or when parsing or validation fails — in which case `response.outcome.reason` is `:invalid_structured_output` and `response.outcome.detail` carries the error.
 
 The assistant message in the message history stores the parsed hash, so you can access structured output directly from persisted messages:
 

data/docs/AGENT_LOOP.md

@@ -34,7 +34,7 @@ The agent loop normally runs until the LLM produces a response with no tool call
 Guardrails are registered at class definition time and run automatically on every request. When a guardrail calls `block`, it sets a **tripwire** that stops the loop immediately. The LLM is never called (for `:before` guardrails) or its response is discarded (for `:after` guardrails).
 
 - **When to use:** Policy enforcement that should always apply — content filtering, input validation, length limits.
-- **Response:** `response.blocked?` returns `true`, `response.tripwire` contains the reason and metadata.
+- **Response:** `response.outcome.reason` is `:guardrail_blocked`, `response.tripwire` contains the reason and metadata.
 - **Streaming:** Yields a `GuardrailTripwire` event.
 - **Resumable:** No. A tripwire is a hard stop. The caller must change the input and start a new `generate`/`stream` call.
 
@@ -45,7 +45,7 @@ class MyAgent < Riffer::Agent
 end
 
 response = MyAgent.generate('blocked input')
-response.blocked?          # => true
+response.outcome.reason    # => :guardrail_blocked
 response.tripwire.reason   # => "Content policy violation"
 ```
 
@@ -54,7 +54,7 @@ response.tripwire.reason   # => "Content policy violation"
 Callbacks registered with `on_message` can call `agent.interrupt!` (or `throw :riffer_interrupt`) to pause the loop at any point — after receiving an assistant message, after a tool result, etc. The caller controls exactly when and why to interrupt.
 
 - **When to use:** Flow control that depends on runtime decisions — human-in-the-loop approval, budget tracking, conditional pausing.
-- **Response:** `response.interrupted?` returns `true`, `response.interrupt_reason` contains the optional reason.
+- **Response:** `response.outcome.reason` is `:interrupted`, `response.outcome.detail` contains the optional reason.
 - **Streaming:** Yields an `Interrupt` event with a `reason` attribute.
 - **Resumable:** Yes. Call `generate('Continue')` or `stream('Continue')` on the same agent instance to resume. For cross-process resume, pass persisted messages as an array to a new agent. Pending tool calls are automatically executed before the LLM loop resumes.
 
@@ -65,8 +65,8 @@ agent.session.on_message do |msg|
 end
 
 response = agent.generate('Do something risky')
-response.interrupted?      # => true
-response.interrupt_reason  # => "approval needed"
+response.outcome.reason    # => :interrupted
+response.outcome.detail    # => "approval needed"
 response = agent.generate('Approved, continue')  # continues where it left off
 ```
 
@@ -75,7 +75,7 @@ response = agent.generate('Approved, continue')  # continues where it left off
 The `max_steps` class method caps the number of LLM call steps in the tool-use loop. When the step count reaches the limit, the loop interrupts automatically with reason `:max_steps`.
 
 - **When to use:** Safety net to prevent runaway tool-use loops — useful when agents have access to many tools or operate autonomously.
-- **Response:** `response.interrupted?` returns `true`, `response.interrupt_reason` is `:max_steps`.
+- **Response:** `response.outcome.reason` is `:max_steps`.
 - **Streaming:** Yields an `Interrupt` event with `reason: :max_steps`.
 - **Resumable:** Yes. Call `generate('Continue')` or `stream('Continue')` on the same agent instance to resume. For cross-process resume, pass persisted messages as an array to a new agent. Pending tool calls are automatically executed before the LLM loop resumes.
 
@@ -86,8 +86,7 @@ class MyAgent < Riffer::Agent
 end
 
 response = MyAgent.generate('Do a complex task')
-response.interrupted?      # => true (if 8 steps were reached)
-response.interrupt_reason  # => :max_steps
+response.outcome.reason    # => :max_steps (if 8 steps were reached)
 ```
 
 ### Unhandled Exceptions
@@ -101,6 +100,6 @@ If a guardrail, provider call, or other internal code raises an exception, it pr
 | Defined       | At class level (`guardrail :before`) | At instance level (`on_message`)     | At class level (`max_steps 8`)       |
 | Fires         | Automatically on every request       | When callback logic decides          | When step count reaches limit        |
 | Resumable     | No                                   | Yes (call `generate`/`stream` again) | Yes (call `generate`/`stream` again) |
-| Response flag | `blocked?`                           | `interrupted?`                       | `interrupted?`                       |
+| Outcome reason | `:guardrail_blocked`                | `:interrupted`                       | `:max_steps`                         |
 | Stream event  | `GuardrailTripwire`                  | `Interrupt`                          | `Interrupt`                          |
 | Purpose       | Policy enforcement                   | Flow control                         | Runaway loop prevention              |

data/docs/CONFIGURATION.md

@@ -198,19 +198,19 @@ Per file, riffer applies this policy, in order:
 
 1. **Already inline data** — nothing to download. If `sha256:` was given, it's verified against the existing bytes regardless of any other setting below.
 2. **Provider can't accept the file at all** — raises `Riffer::FileUnsupportedError`.
-3. **Provider accepts a URL as-is** — passed straight through, untouched, *unless* `sha256:` was given, in which case riffer downloads and verifies anyway (a caller who set `sha256:` is asking for integrity verification, not a passthrough).
+3. **Provider accepts a URL as-is** — passed straight through, untouched, _unless_ `sha256:` was given, in which case riffer downloads and verifies anyway (a caller who set `sha256:` is asking for integrity verification, not a passthrough).
 4. **Provider needs the bytes inline** — riffer downloads the file, verifying `sha256:` if given.
 
 Every download in step 3 or 4 is gated by `allow_downloads`; with it `false` (the default), reaching either of those steps raises `Riffer::FileDownloadsDisabledError` instead of fetching anything. This means upgrading to a riffer version with this feature never starts downloading arbitrary URLs on your behalf — you have to opt in.
 
-| Option            | Description                                                                                                                                                                                                       |
-| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `allow_downloads` | Whether riffer may download a `FilePart`'s URL. Accepts booleans or `'true'`/`'false'`/`'1'`/`'0'`. Defaults to `false`.                                                                                          |
-| `max_bytes`       | Maximum size, in bytes, of a downloaded file; the download is aborted once the streamed body exceeds this, independent of (and regardless of a missing/lying) `content-length` header. Defaults to `3_500_000`. |
-| `timeout`         | Open and read timeout, in seconds, for a single download attempt. Defaults to `60`.                                                                                                                               |
-| `max_per_message` | Maximum number of files allowed on a single user message; checked against each message as originally authored, before consecutive messages are merged. `nil` (default) means uncapped.                          |
-| `runner`          | A `Riffer::Runner` instance that resolves every file across a call's messages. Defaults to `Riffer::Runner::Sequential.new`; assign `Riffer::Runner::Threaded.new` (or `Riffer::Runner::Fibers.new` inside a fiber-based host) to resolve multiple files concurrently. |
-| `downloader`      | The object that fetches a URL's bytes; must respond to `#call(url, max_bytes:, timeout:)` returning the raw (not base64-encoded) file content. Riffer caches it as base64 or raw bytes, whichever the provider actually needs, rather than producing both. Defaults to `Riffer::Files::Downloader.new`, which fetches over HTTPS only, following up to 3 redirects. Assign your own to add logging/metrics, or to fetch from a non-HTTPS store (e.g. `s3://`).                          |
+| Option            | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `allow_downloads` | Whether riffer may download a `FilePart`'s URL. Accepts booleans or `'true'`/`'false'`/`'1'`/`'0'`. Defaults to `false`.                                                                                                                                                                                                                                                                                                                                       |
+| `max_bytes`       | Maximum size, in bytes, of a downloaded file; the download is aborted once the streamed body exceeds this, independent of (and regardless of a missing/lying) `content-length` header. Defaults to `3_500_000`.                                                                                                                                                                                                                                                |
+| `timeout`         | Open and read timeout, in seconds, for a single download attempt. Defaults to `60`.                                                                                                                                                                                                                                                                                                                                                                            |
+| `max_per_message` | Maximum number of files allowed on a single user message; checked against each message as originally authored, before consecutive messages are merged. `nil` (default) means uncapped.                                                                                                                                                                                                                                                                         |
+| `runner`          | A `Riffer::Runner` instance that resolves every file across a call's messages. Defaults to `Riffer::Runner::Sequential.new`; assign `Riffer::Runner::Threaded.new` (or `Riffer::Runner::Fibers.new` inside a fiber-based host) to resolve multiple files concurrently.                                                                                                                                                                                         |
+| `downloader`      | The object that fetches a URL's bytes; must respond to `#call(url, max_bytes:, timeout:)` returning the raw (not base64-encoded) file content. Riffer caches it as base64 or raw bytes, whichever the provider actually needs, rather than producing both. Defaults to `Riffer::Files::Downloader.new`, which fetches over HTTPS only, following up to 3 redirects. Assign your own to add logging/metrics, or to fetch from a non-HTTPS store (e.g. `s3://`). |
 
 A file that fails resolution raises a `Riffer::FileError` subclass — `Riffer::FileUnsupportedError`, `Riffer::FileDownloadsDisabledError`, `Riffer::TooManyFilesError`, `Riffer::FileChecksumMismatchError`, `Riffer::FileTooLargeError`, `Riffer::FileDownloadError`, or `Riffer::FileEncodingError` — so callers can `rescue Riffer::FileError` for any attachment problem, or a specific subclass to handle one case.
 
@@ -345,14 +345,15 @@ end
 
 ### Anthropic
 
-| Option        | Description                                 |
-| ------------- | ------------------------------------------- |
-| `temperature` | Sampling temperature                        |
-| `max_tokens`  | Maximum tokens in response                  |
-| `top_p`       | Nucleus sampling parameter                  |
-| `top_k`       | Top-k sampling parameter                    |
-| `thinking`    | Extended thinking config hash (Claude 3.7+) |
-| `web_search`  | Enable web search (`true` or config hash)   |
+| Option          | Description                                 |
+| --------------- | ------------------------------------------- |
+| `temperature`   | Sampling temperature                        |
+| `max_tokens`    | Maximum tokens in response                  |
+| `top_p`         | Nucleus sampling parameter                  |
+| `top_k`         | Top-k sampling parameter                    |
+| `thinking`      | Extended thinking config hash (Claude 3.7+) |
+| `output_config` | Output config hash (e.g. `effort`)          |
+| `web_search`    | Enable web search (`true` or config hash)   |
 
 ```ruby
 class MyAgent < Riffer::Agent
@@ -365,6 +366,12 @@ class ReasoningAgent < Riffer::Agent
   model 'anthropic/claude-haiku-4-5-20251001'
   model_options thinking: {type: "enabled", budget_tokens: 10000}
 end
+
+# With an output effort level
+class EffortAgent < Riffer::Agent
+  model 'anthropic/claude-opus-5'
+  model_options output_config: {effort: "high"}
+end
 ```
 
 ## Environment Variables

data/docs/GUARDRAILS.md

@@ -28,10 +28,10 @@ class MyAgent < Riffer::Agent
 end
 
 response = MyAgent.generate("Hello!")
-response.blocked?  # => false
+response.outcome.reason    # => :completed
 
 response = MyAgent.generate("You are a badword")
-response.blocked?          # => true
+response.outcome.reason    # => :guardrail_blocked
 response.tripwire.reason   # => "Profanity detected"
 ```
 
@@ -195,7 +195,7 @@ end
 response = MyAgent.generate("Hello")
 
 response.content        # The response text
-response.blocked?       # true if a guardrail blocked execution
+response.outcome.reason # :guardrail_blocked if a guardrail blocked execution
 response.tripwire       # Tripwire object with block details (if blocked)
 response.modified?      # true if any guardrail transformed data
 response.modifications  # Array of Modification records
@@ -206,7 +206,7 @@ response.modifications  # Array of Modification records
 ```ruby
 response = MyAgent.generate("Hello")
 
-if response.blocked?
+if response.outcome.reason == :guardrail_blocked
   puts "Blocked: #{response.tripwire.reason}"
   puts "Phase: #{response.tripwire.phase}"
   puts "Guardrail: #{response.tripwire.guardrail}"

data/docs/MESSAGES.md

@@ -49,7 +49,8 @@ msg.role           # => :assistant
 msg.content        # => "I'm doing well, thank you!"
 msg.tool_calls     # => []
 msg.token_usage    # => nil or Riffer::Providers::TokenUsage
-msg.finish_reason  # => nil or a normalized Symbol (see below)
+msg.finish_reason      # => nil or a normalized Symbol (see below)
+msg.finish_reason_raw  # => nil or the provider's raw wire value (e.g. "max_tokens")
 
 # Response with tool calls
 msg = Riffer::Messages::Assistant.new("", tool_calls: [
@@ -83,16 +84,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.        |
+| 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. Use it to detect truncation without parsing provider responses:
+`finish_reason` is `nil` when the provider doesn't report one. The provider's raw wire value travels alongside as `finish_reason_raw` on the message (round-tripped through `to_h` / `from_hash`), on the `FinishReasonDone` stream event, and as 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")
@@ -101,7 +104,7 @@ retry_with_higher_limit if agent.session.messages.last.finish_reason == :length
 
 #### Structured Output on Messages
 
-When an agent has `structured_output` configured, the final assistant message stores the parsed hash directly. The `structured_output?` predicate checks for a non-nil value:
+When an agent has `structured_output` configured, the final assistant message stores the parsed hash directly. The message holds the parsed JSON, not the schema-validated result; schema validation is reported on `response.outcome` (see [Agent Lifecycle — response.outcome](AGENT_LIFECYCLE.md#responseoutcome)). The `structured_output?` predicate checks for a non-nil value:
 
 ```ruby
 msg = Riffer::Messages::Assistant.new('{"sentiment":"positive"}', structured_output: {sentiment: "positive"})

data/docs/STREAM_EVENTS.md

@@ -215,7 +215,7 @@ Emitted when the agent loop is interrupted. This can happen in two ways:
 - An `on_message` callback calls `agent.interrupt!` or `throw :riffer_interrupt` (reason is a String or `nil`).
 - The `max_steps` limit is reached (reason is the Symbol `:max_steps`).
 
-This is the streaming equivalent of `Response#interrupted?` in generate mode.
+This is the streaming equivalent of `response.outcome.reason == :interrupted` (or `:max_steps`) in generate mode.
 
 ```ruby
 # Callback interrupt with a string reason

data/docs/TOOL_ADVANCED.md

@@ -220,6 +220,8 @@ end
 
 Fibers use cooperative scheduling — they yield control at I/O boundaries (network calls, file reads, sleep). CPU-bound tools will not benefit from the fibers runtime. Be mindful of fiber-local state (`Fiber.[]`) and note that `Thread.current[]` values are shared across all fibers in the same thread.
 
+The fibers runtime is safe to use inside an existing reactor. When called from plain Ruby it starts its own reactor and blocks until every tool call finishes. When the process is already inside an Async task — for example under Falcon, or inside an `Async do ... end` block — it joins the current task instead of starting a nested reactor, so it is safe to call from request handlers.
+
 ### Custom Runtimes
 
 Create a custom runtime by subclassing `Riffer::Tools::Runtime` and overriding the private `dispatch_tool_call` method:

data/docs/TRACING.md

@@ -113,6 +113,8 @@ Any tags passed to `#generate` / `#stream` via `tags:` are stamped on **all four
 | `gen_ai.usage.cache_read.input_tokens`     | int    | When the provider reported cache reads               |
 | `gen_ai.usage.cache_creation.input_tokens` | int    | When the provider reported cache writes              |
 | `riffer.cost`                              | float  | When every call in the run was priced                |
+| `riffer.outcome.reason`                    | string | Always — the `response.outcome.reason`               |
+| `riffer.outcome.detail`                    | string | When `response.outcome.detail` is present            |
 | `riffer.interrupt.reason`                  | string | On interrupt (e.g. approval needed, max steps)       |
 | `riffer.tripwire.guardrail`                | string | On a guardrail tripwire, when the guardrail is named |
 | `riffer.tripwire.reason`                   | string | On a guardrail tripwire                              |
@@ -153,7 +155,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
 
@@ -271,7 +273,7 @@ When enabled, content is serialized as GenAI-semconv JSON strings. File attachme
 The span and attribute shape is a public, versioned contract, in two tiers:
 
 - **`gen_ai.*`** tracks the OpenTelemetry GenAI semantic conventions, pinned to schema version `1.37.0`. That convention is still "Development" status upstream and its attribute names may change; Riffer absorbs such renames deliberately in a release, never silently, with a CHANGELOG entry.
-- **`riffer.*`** is Riffer-owned (`riffer.steps`, `riffer.cost`, `riffer.interrupt.reason`, `riffer.tripwire.*`, `riffer.guardrail.*`, `riffer.finish_reason.raw`) and changes only through a normal version bump and CHANGELOG entry.
+- **`riffer.*`** is Riffer-owned (`riffer.steps`, `riffer.cost`, `riffer.outcome.*`, `riffer.interrupt.reason`, `riffer.tripwire.*`, `riffer.guardrail.*`, `riffer.finish_reason.raw`) and changes only through a normal version bump and CHANGELOG entry.
 
 The semantic-convention schema version is a documented pin rather than a span attribute — the OpenTelemetry Ruby API can't attach a schema URL to a tracer. The runtime version signal is the instrumentation scope: every span carries scope name `riffer` at the gem version that emitted it. Pin the Riffer version your dashboards depend on, and watch the CHANGELOG for tracing entries before upgrading.
 

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/docs/providers/MOCK_PROVIDER.md

@@ -21,13 +21,14 @@ Use `stub_response` to queue responses:
 ```ruby
 # Get the provider instance from the agent
 agent = TestableAgent.new
-provider = agent.send(:provider_instance)
+provider = agent.provider
 
 # Stub a simple text response
 provider.stub_response("Hello, I'm here to help!")
 
 # Now generate will return the stubbed response
 response = agent.generate("Hi")
+response.content
 # => "Hello, I'm here to help!"
 ```
 
@@ -55,10 +56,10 @@ provider.stub_response("First response")
 provider.stub_response("Second response")
 provider.stub_response("Third response")
 
-agent.generate("Message 1")  # => "First response"
-agent.generate("Message 2")  # => "Second response"
-agent.generate("Message 3")  # => "Third response"
-agent.generate("Message 4")  # => "Mock response" (default)
+agent.generate("Message 1").content  # => "First response"
+agent.generate("Message 2").content  # => "Second response"
+agent.generate("Message 3").content  # => "Third response"
+agent.generate("Message 4").content  # => "Mock response" (default)
 ```
 
 ## Inspecting Calls
@@ -92,7 +93,7 @@ require 'minitest/autorun'
 class MyAgentTest < Minitest::Test
   def setup
     @agent = TestableAgent.new
-    @provider = @agent.send(:provider_instance)
+    @provider = @agent.provider
   end
 
   def test_generates_response
@@ -146,18 +147,24 @@ text_done = events.find { |e| e.is_a?(Riffer::StreamEvents::TextDone) }
 
 ## Web Search
 
-The test provider emits web search events when `web_search: true` is passed to the stream call:
+The mock provider emits web search events when `web_search: true` is set in the agent's `model_options`:
 
 ```ruby
-provider.stub_response("Here are the latest results.")
+class SearchingAgent < Riffer::Agent
+  model 'mock/any'
+  model_options web_search: true
+end
+
+agent = SearchingAgent.new
+agent.provider.stub_response("Here are the latest results.")
 
 events = []
-agent.stream("What's new in Ruby?", web_search: true).each { |e| events << e }
+agent.stream("What's new in Ruby?").each { |e| events << e }
 
 # Events include WebSearchStatus and WebSearchDone before text events
-search_deltas = events.select { |e| e.is_a?(Riffer::StreamEvents::WebSearchStatus) }
+search_statuses = events.select { |e| e.is_a?(Riffer::StreamEvents::WebSearchStatus) }
 search_done = events.find { |e| e.is_a?(Riffer::StreamEvents::WebSearchDone) }
-search_done.query    # => "test search query"
+search_done.query    # => "mock search query"
 search_done.sources  # => [{title: "Example", url: "https://example.com"}]
 ```
 

data/lib/riffer/agent/outcome.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# 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 = %i[stop tool_calls].freeze #: Array[Symbol]
+
+  # Derived from the provider vocabulary so a new finish reason becomes an
+  # outcome without a second list to update.
+  PROVIDER_STOP_REASONS = (Riffer::Providers::FinishReason::VALUES - NORMAL_FINISH_REASONS).freeze #: Array[Symbol]
+
+  # The vocabulary every run ends in.
+  VALUES = (%i[completed guardrail_blocked interrupted max_steps invalid_structured_output] +
+            PROVIDER_STOP_REASONS).freeze #: 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:, detail: nil)
+    unless VALUES.include?(reason)
+      raise Riffer::ArgumentError, "reason must be one of #{VALUES.inspect}, got #{reason.inspect}"
+    end
+
+    @reason = reason
+    @detail = detail
+  end
+
+  # Returns true when the run completed normally.
+  #
+  #--
+  #: () -> bool
+  def success?
+    reason == :completed
+  end
+end