riffer 0.45.0 → 0.46.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b166b910624129bd5b64b9443caba3b5c781b691a7453b5640cd132c21cd72c2
-  data.tar.gz: d64178e66b49945647393430b57f84a501ec7c0bfbe866b20f6f1b6af44ef570
+  metadata.gz: ac304f75fface8720f1e2565ea2064b643abb2f1c29f5a9dfe5281820e9d3986
+  data.tar.gz: de5695cffa30697e0356de921227caffdab12ff806e143166369c36e3ae010d6
 SHA512:
-  metadata.gz: 36ce62e6539e22a01c5f8523278203b0307a2753c8e3af8e683133b741144417b360721862249d2c64fb118211f134e7b968d681e4c31e20f9ca051768e9aef6
-  data.tar.gz: 39ac8834695876cd923e3dffe7065045f7296e418056e18eae9da4811ba04c886b546342a4a4586d92ac529ec456a18e0b272b0598eb70c72371af2dbefebce3
+  metadata.gz: dfe9da5a5cb0a8a1147846766acc79b518a9f7025d1d95fbfddce3604e2315afafc04762b339879eee2db875aba5cc296056045f213f47a17cb9f730e17f3e07
+  data.tar.gz: b548a4b44b001b79ee295969af5a868f50d0e847a183dc9433e5b23d4b1e7c9effed3ea64a76a8f5022db959a65394d8f8ff28bba9a6d46484841322483ebe02

data/.release-please-manifest.json

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

data/CHANGELOG.md

@@ -5,6 +5,23 @@ 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)
 
 

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: [
@@ -94,7 +95,7 @@ The cache buckets are subsets of `input_tokens`, never additions to it — summi
 | `: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:
+`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")
@@ -103,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                              |
@@ -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/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

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

@@ -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/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/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.0" #: 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

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/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.45.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