riffer 0.48.0 → 0.49.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5975a19de149eced0122ccf94f08666f66377c395b3a414db48158fcba352807
-  data.tar.gz: fe48ac55158f5bd1f4818651988b68ed2e45fa985c1ebe5a386d636decd15ff2
+  metadata.gz: b1bd95697d75079325d4a057c0f2bb17bc8fee9a3864c611967e78d8e1637ef8
+  data.tar.gz: 84ddb8c10cef0b5711b00793b3a19de2713fcf8d7985166dfaa248fa7bbe58f0
 SHA512:
-  metadata.gz: 7e506427c0b0272fb2c6f044def74b74d423e92bb23fbe95e02c5678d48b8b98ff2e8920807b23e4d8fb2db94d509937643813d9248eb109a51d03559a5ecd48
-  data.tar.gz: 3553da8e73fa137a4070baac5548fbd3a345316f0941e9f8b8490d2790d17a5e47b5eb154de6613897874a0a2bd3adaff4b1167d55fe21b99a1d0840d9786733
+  metadata.gz: 375f9c10e95e1dbd60da4acd0209bdc5707a30dff00e742815fb874cb00755b187602967433d5677444e790b9d94153c1408e9bc8f91a80e5879aa696de0a550
+  data.tar.gz: a05871a1bcd23100fa5d0018438810476560c19f87e82ebaaa6b7322e81b03577f12923845716792deb479c86f59a49127e65b2f862f4a84b95e11d75a6cb942

data/.claude/rules/comments.md

@@ -6,8 +6,6 @@ paths: ["**/*.rb", "**/*.rake", "**/Gemfile"]
 
 A comment exists to explain a **why** when the code itself cannot — never a **how**, and never a restatement of what the code already says. This bar governs all prose, from inline comments to docstrings.
 
-- **Internal and private code** — everything in an application, plus a library's non-exported internals — is self-documenting via clear names and strong types. A comment survives only when it explains something a competent reader cannot recover from the code alone: a non-local constraint, an external-system quirk, a deliberate non-obvious tradeoff. A description of _what_ the code does, or a why that's evident from reading it, gets cut.
-- **A published library's public surface** gets one verb-first sentence per exported symbol ("Serializes the definition to JSON."). An optional second sentence is reserved strictly for a why — a non-obvious constraint or rationale — never a second sentence of how. Needing more than one sentence to say _what_ it does is a smell the symbol does too much.
-- **Types are not prose's job.** Parameters, return values, and field types live in the type system (TypeScript types, rbs-inline `#:` annotations) — never restated in comments that duplicate them.
-- **Markers.** `TODO` / `FIXME` / `HACK` are tracked work and stay; `NOTE` / `REVIEW` meet the same why-bar as any other comment.
+- **The default is no comment.** Names, types, and structure carry the meaning; when they don't, fix them rather than explain them. Delete the comment and read the code cold: if the intent is still recoverable, it stays deleted. Keep only a _why_ the code can't show — a non-local constraint, an external quirk, a deliberate tradeoff, a safety invariant — and put it at the line it explains, not in a header.
+
 - **No history.** A comment describes the present, never how the code got there — no "was X, now Y", no story of the bug that revealed a constraint. State a still-true constraint in the present tense ("the API returns null for empty results — guard").

data/.claude/rules/rbs-inline.md

@@ -26,28 +26,18 @@ module Riffer
 end
 ```
 
-## RDoc Conventions
+## The `#--` stop directive
 
-**The `#--` stop directive.** Place `#--` on the line immediately before a **standalone** `#:` type annotation. Without it, RDoc treats `#:` as a label-list marker and corrupts the preceding description into a `<pre>` block. Inline `#:` on the same line as code (attributes, constants) does not need it.
+Place `#--` on the line immediately before a **standalone** `#:` type annotation, even when no comment precedes it. Without it, RDoc treats `#:` as a label-list marker and mangles the method's rendered docs. Inline `#:` on the same line as code (attributes, constants) does not need it.
 
 ```ruby
-# Serializes the agent definition to a transferable JSON payload.
 #--
 #: (Riffer::Agent) -> String
 def serialize(agent)
 
-# The agent's display name.
 attr_reader :name #: String
 ```
 
-**Raises.** Document a raise **only when it's part of the caller's contract** — something a caller should reasonably anticipate and handle. Skip programmer-error guards and "should never happen" assertions. When the raise condition merely restates the declared `#:` type, phrase it by intent ("Raises Riffer::ArgumentError on an invalid value") rather than re-listing the type union.
-
-**Examples.** Include an example only when a **consumer is likely to use the thing themselves** — a public entry point they construct, subclass, or call. Keep them sparing and write them as indented code blocks (2 extra spaces of indent). Usage walkthroughs belong in `docs/`.
-
-**Inline code formatting.** Use `+word+` for single-word inline code; for multi-word expressions (spaces, colons, brackets) use `<tt>multi word expression</tt>`.
-
-**Internal APIs.** Mark with `# :nodoc:` to exclude from generated documentation.
-
 ## Optional-dependency types (consumer-safe signatures)
 
 `sig/generated/` ships with the gem and is loaded by downstream projects (`rbs collection` / `rbs -r riffer`). rbs-inline copies a method's `#:` signature **verbatim** into the shipped sig, so **never name an optional-dependency type in a `#:` signature** — `OpenAI::*`, `Anthropic::*`, `Aws::*`, `MCP::*`, `Async::*`, `Zeitwerk::*`, etc. A consumer who installs riffer without that gem would hit `Cannot find type`, because those providers are pluggable and the gems ship no usable RBS of their own.

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.48.0"
+  ".": "0.49.0"
 }

data/.rubocop.yml

@@ -110,3 +110,8 @@ Performance/Sum:
     - lib/riffer/providers/base.rb
     - lib/riffer/evals/run_result.rb
     - lib/riffer/evals/scenario_result.rb
+
+# Each accessor carries its own trailing rbs-inline `#:` type; grouping them
+# onto one line drops every type but the first.
+Style/AccessorGrouping:
+  EnforcedStyle: separated

data/CHANGELOG.md

@@ -5,6 +5,25 @@ 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.49.0](https://github.com/janeapp/riffer/compare/riffer/v0.48.0...riffer/v0.49.0) (2026-09-27)
+
+
+### ⚠ BREAKING CHANGES
+
+* **config:** provider string settings must be a String or nil; evals.judge_model must be in "provider/model" form; mcp.credentials must respond to #call; mcp.discovery_runner must be a Riffer::Runner. Struct behaviour ([] / to_a / members / value equality) is gone from those sections. Riffer::Tracing.reset! is removed; the tracing backend is read from config on every call instead of being cached.
+* **agent:** Riffer.config.experimental_history_healing is removed, as are Response#healed_tool_call_ids and StreamEvents::Interrupt#healed_tool_call_ids (and its to_h key). Orphan pruning on Agent.new is now always on. Interrupts never fill placeholders; call agent.session.discard_pending_tool_calls instead and use its return value for the filled call ids.
+
+### Features
+
+* **agent:** always repair seeded sessions, add discard_pending_tool_calls ([#456](https://github.com/janeapp/riffer/issues/456)) ([b1e8933](https://github.com/janeapp/riffer/commit/b1e89330f2b2f59b74f794d5a21d31b833cb64d8))
+* **amazon_bedrock:** capture and replay reasoning content ([#459](https://github.com/janeapp/riffer/issues/459)) ([5048a8c](https://github.com/janeapp/riffer/commit/5048a8ce2aba35ad7af2eeee018dc381ca77eb00))
+* **open_router:** capture and replay reasoning_details ([#453](https://github.com/janeapp/riffer/issues/453)) ([a3e2523](https://github.com/janeapp/riffer/commit/a3e252324de97d3f03942c60a892126975bb1a60))
+
+
+### Code Refactoring
+
+* **config:** split Riffer::Config into one file per section ([#458](https://github.com/janeapp/riffer/issues/458)) ([c493684](https://github.com/janeapp/riffer/commit/c4936848c5c34903c160f90786e7493831ab21dd))
+
 ## [0.48.0](https://github.com/janeapp/riffer/compare/riffer/v0.47.2...riffer/v0.48.0) (2026-09-23)
 
 

data/docs/AGENTS.md

@@ -251,9 +251,7 @@ A `Hash` param requires a block, and an `Array` param requires a block or `of:`.
 
 Structured output is not compatible with streaming — calling `stream` on an agent with structured output configured raises `Riffer::ArgumentError`.
 
-### tool_runtime (Experimental)
-
-> **Warning:** This feature is experimental and may be removed or changed without warning in a future release.
+### tool_runtime
 
 Configures how tool calls are executed. Defaults to sequential (inline) execution:
 
@@ -265,7 +263,7 @@ class MyAgent < Riffer::Agent
 end
 ```
 
-Accepts a `Riffer::Tools::Runtime` subclass, a `Riffer::Tools::Runtime` instance, or a `Proc`. When unset, reads `Riffer.config.tool_runtime` at the point of use, so an agent that declares none follows a later change to the global. See [Tools — Tool Runtime](TOOL_ADVANCED.md#tool-runtime-experimental) for details.
+Accepts a `Riffer::Tools::Runtime` subclass, a `Riffer::Tools::Runtime` instance, or a `Proc`. When unset, reads `Riffer.config.tool_runtime` at the point of use, so an agent that declares none follows a later change to the global. See [Tools — Tool Runtime](TOOL_ADVANCED.md#tool-runtime) for details.
 
 ### guardrail
 
@@ -446,5 +444,5 @@ Riffer does not validate tag count, key/value length, or charset — it forwards
 | Add packaged capabilities     | Skills            | [Skills](SKILLS.md)                                               |
 | Control the tool-use loop     | Agent Loop        | [Agent Loop](AGENT_LOOP.md)                                       |
 | Human-in-the-loop approval    | Interrupts        | [Agent Lifecycle](AGENT_LIFECYCLE.md#interrupting-the-agent-loop) |
-| Run tools concurrently        | Tool Runtime      | [Advanced Tools](TOOL_ADVANCED.md#tool-runtime-experimental)      |
+| Run tools concurrently        | Tool Runtime      | [Advanced Tools](TOOL_ADVANCED.md#tool-runtime)                   |
 | Stream responses in real time | Streaming         | [Agent Lifecycle](AGENT_LIFECYCLE.md#stream)                      |

data/docs/AGENT_LIFECYCLE.md

@@ -8,7 +8,7 @@
 Agent.new(session: nil, context: nil)
 ```
 
-- **`session:`** — an existing `Riffer::Agent::Session`. When given, the agent uses it as-is (no system/skills seeding). Typical use case: cross-process resume from persisted history. With `Riffer.config.experimental_history_healing` on, a provided session is healed at construction time so the `tool_use` ↔ `tool_result` invariant holds before the next inference call.
+- **`session:`** — an existing `Riffer::Agent::Session`. When given, the agent uses it as-is (no system/skills seeding). Typical use case: cross-process resume from persisted history. A provided session is repaired at construction time so the `tool_use` ↔ `tool_result` invariant holds before the next inference call: orphaned `tool_use` exchanges (an assistant `tool_call` with no matching `Tool` result) and parentless `Tool` messages are dropped. Pending tool calls on the **resume boundary** — the last assistant whose tail is purely `Tool` results (or none) — are preserved so `generate`/`stream` can execute them.
 - **`context:`** — a `Hash` carried for the lifetime of the agent. Used to evaluate Proc-based `instructions`, `model`, `uses_tools`, and skill activation at construction time, and threaded through tool execution and guardrails on every `generate`/`stream` call.
 
 When `session:` is omitted, the agent constructs a fresh session and seeds it with `[instruction_message, skills_message].compact` eagerly. To swap context, construct a new agent — context is fixed for the lifetime of an agent instance.
@@ -187,7 +187,7 @@ end
 
 There are two ways to resume after an interrupt, depending on whether the agent is still in memory or you're restoring from persisted data.
 
-**In-memory resume** — call `generate` (or `stream`) again. With a prompt, the new user message is appended and the loop runs. Without a prompt, the loop runs against the current session — useful for picking up pending tool calls after the user has approved.
+**In-memory resume** — call `generate` (or `stream`) again. With a prompt, the new user message is appended and the loop runs; results for any pending tool calls are placed ahead of it, directly after the assistant message that requested them. Without a prompt, the loop runs against the current session — useful for picking up pending tool calls after the user has approved.
 
 ```ruby
 agent = MyAgent.new(context: {user_id: 123})
@@ -244,38 +244,36 @@ agent.session.on_message do |msg|
 end
 ```
 
-#### Healing pending tool results on interrupt (experimental)
+#### Discarding pending tool calls after an interrupt
 
-When an interrupt fires while the assistant has a `tool_use` block that hasn't been answered yet, the LLM will reject the next request unless every `tool_use` has a matching `tool_result`. By default, the next `generate` call re-executes those pending tools (see "Resuming an Interrupted Loop" above).
+An interrupt only stops the loop. Any `tool_use` the assistant emitted that hasn't been answered yet stays in history, and the next `generate`/`stream` call executes it (see "Resuming an Interrupted Loop" above). This applies to caller-issued `interrupt!` and the built-in `INTERRUPT_MAX_STEPS` ceiling alike.
 
-When the interrupt represents a course-change rather than a pause — e.g. a voice barge-in where the user has moved on — re-execution is the wrong behavior. Opt into history healing to have riffer fill any orphan `tool_use` with a placeholder `Riffer::Messages::Tool` carrying `error_type: :interrupted`, leaving history valid for the next turn:
+When the interrupt represents a course-change rather than a pause — e.g. a voice barge-in or a cancel where the user has moved on — re-execution is the wrong behavior. Call `agent.session.discard_pending_tool_calls` to answer every unanswered `tool_use` with a placeholder `Riffer::Messages::Tool` carrying `error_type: :interrupted`, leaving history valid for the next turn. It returns the filled `call_id`s:
 
 ```ruby
-Riffer.configure { |c| c.experimental_history_healing = true }
-
 agent.session.on_message do |msg|
   agent.interrupt!(:user_interrupt) if msg.is_a?(Riffer::Messages::Assistant) && barge_in?
 end
 
 response = agent.generate("Tell me a story")
-response.healed_tool_call_ids  # => ["call_abc123", ...]
+agent.session.discard_pending_tool_calls  # => ["call_abc123", ...]
+agent.generate("Actually, tell me a joke")
 ```
 
-The placeholder content is fixed: `"Tool call interrupted before completion."` with `error_type: :interrupted`. Each placeholder is inserted immediately after its parent assistant message. The list of filled `call_id`s is exposed on `response.healed_tool_call_ids` (and on `Riffer::StreamEvents::Interrupt#healed_tool_call_ids` when streaming).
+The placeholder content is fixed: `"Tool call interrupted before completion."` with `error_type: :interrupted`. Each placeholder is inserted immediately after its parent assistant message. When nothing is pending, the method returns `[]` and leaves history untouched.
 
-Healing covers all interrupts uniformly — caller-issued `interrupt!` and the built-in `INTERRUPT_MAX_STEPS` ceiling alike. When the flag is off (the default), orphans remain in history and `execute_pending_tool_calls` re-runs them on the next `generate` call.
+The method works purely on the session's current messages, so it also applies when a run was cancelled without going through riffer's interrupt handling (e.g. the surrounding task was stopped with `Async::Stop` or an exception escaped a callback).
 
-If you need finer control over placeholder content (per-call shape, structured metadata, etc.), use the `update` mutator below to upgrade a placeholder after the interrupt returns.
+If you need finer control over placeholder content (per-call shape, structured metadata, etc.), use the `update` mutator below to upgrade a placeholder afterwards.
 
 ### Mutating history
 
 The session exposes a small set of in-place mutators that enforce the `tool_use` ↔ `tool_result` invariant on every operation. Use these to align history with external state (persisted transcript, partial output that wasn't actually delivered, etc.) without rebuilding the agent.
 
 - **`agent.session.update(id:, **attrs)`** — In-place partial update. Looks up by message `id:`; builds a replacement of the same type with `attrs` overlaid on the existing fields. Use this to edit assistant content (`update(id:, content:)`), restate a system message, etc. When the target is an assistant and the update drops entries from `tool_calls`, matching `Tool` children are removed atomically.
-- **`agent.session.update(tool_call_id:, **attrs)`** — Same as above but looks up the tool result by `tool_call_id:`. Preserves `name` and `id`. Use this to upgrade an interrupt-time placeholder once the real result is available (`update(tool_call_id:, content:, error: nil, error_type: nil)`).
+- **`agent.session.update(tool_call_id:, **attrs)`** — Same as above but looks up the tool result by `tool_call_id:`. Preserves `name` and `id`. Use this to upgrade a `discard_pending_tool_calls` placeholder once the real result is available (`update(tool_call_id:, content:, error: nil, error_type: nil)`).
 - **`agent.session.remove(id:)`** — Removes a message; cascades to its `Tool` children when the target carries `tool_calls`. Raises if called on a `Tool` message (use `update(tool_call_id:, ...)` to rewrite a tool result instead).
-
-Bulk filling of orphan `tool_use` blocks is handled by `Riffer.config.experimental_history_healing` (see "Healing pending tool results on interrupt" above) — there is no public synthesizer hook.
+- **`agent.session.discard_pending_tool_calls`** — Answers every unanswered `tool_use` with an `:interrupted` placeholder result and returns the filled `call_id`s (see "Discarding pending tool calls after an interrupt" above).
 
 Lookup patterns that pair with the mutators (via `Enumerable`):
 
@@ -288,7 +286,7 @@ agent.session.orphaned_tool_call_ids
 
 Mutating history while a `stream` enumerator is being consumed is undefined; mutators are intended for use between turns.
 
-Mutators do **not** fire `on_message` — that callback is reserved for messages produced by inference (LLM responses, tool execution results). Healing placeholders bypass `on_message` for the same reason; consumers learn that healing happened via `Response#healed_tool_call_ids` (and `StreamEvents::Interrupt#healed_tool_call_ids`).
+Mutators do **not** fire `on_message` — that callback is reserved for messages produced by inference (LLM responses, tool execution results). Placeholders added by `discard_pending_tool_calls` bypass `on_message` for the same reason; use its return value to learn which calls were filled.
 
 ### context
 
@@ -320,7 +318,6 @@ agent.context[:skills]        # the Skills::Context, if skills configured
 | `modified?`            | `Boolean`                   | `true` if a guardrail modified the content                                                       |
 | `modifications`        | `Array`                     | List of guardrail modifications applied                                                          |
 | `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 |
 

data/docs/CONFIGURATION.md

@@ -18,6 +18,8 @@ end
 
 Providers take no constructor arguments — these settings are the only way to give a provider its credentials.
 
+Credential and endpoint settings — `amazon_bedrock.api_token` / `.region`, `anthropic.api_key`, `azure_openai.api_key` / `.endpoint`, `gemini.api_key`, `openai.api_key` / `.base_url`, `openrouter.api_key` — accept a `String` or `nil` and raise `Riffer::ArgumentError` naming the setting for anything else. An empty string is accepted; Amazon Bedrock treats it as unset. `client` is not validated (see [Provider Clients](#provider-clients)).
+
 ## Accessing Configuration
 
 Access the current configuration via `Riffer.config`:
@@ -101,10 +103,10 @@ The Gemini provider has no vendor SDK, so riffer ships its own transport: `Riffe
 
 Optional settings for [MCP server integrations](MCP.md):
 
-| Option             | Description                                                                                                     |
-| ------------------ | --------------------------------------------------------------------------------------------------------------- |
-| `credentials`      | Optional `Proc` for per-run `tools/call` HTTP headers: `->(manifest:, matched_tags:, context:) { Hash or nil }` |
-| `discovery_runner` | `Riffer::Runner` instance for tool discovery (default `Runner::Sequential.new`)                                 |
+| Option             | Description                                                                                                                                                                               |
+| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `credentials`      | Optional callable for per-run `tools/call` HTTP headers: `->(manifest:, matched_tags:, context:) { Hash or nil }`. Raises `Riffer::ArgumentError` unless `nil` or it responds to `#call`. |
+| `discovery_runner` | `Riffer::Runner` instance for tool discovery (default `Runner::Sequential.new`). Raises `Riffer::ArgumentError` for anything that isn't a `Riffer::Runner` instance.                      |
 
 ```ruby
 Riffer.configure do |config|
@@ -116,9 +118,17 @@ end
 
 See [MCP](MCP.md) for registration, tags, and agent `use_mcp`.
 
-### Tool Runtime (Experimental)
+### Evals
+
+```ruby
+Riffer.configure do |config|
+  config.evals.judge_model = "anthropic/claude-opus-4-5-20251101"
+end
+```
+
+`judge_model` is the default model evaluators use as the judge when they don't set their own. It must be a `provider/model` string or `nil` (the default); anything else raises `Riffer::ArgumentError`. See [Evals](EVALS.md).
 
-> **Warning:** This feature is experimental and may be removed or changed without warning in a future release.
+### Tool Runtime
 
 Configure the default tool runtime for all agents:
 
@@ -134,7 +144,7 @@ end
 | `Riffer::Tools::Runtime` instance | Custom runtime with specific options                                                                    |
 | `Proc`                            | Dynamic resolution                                                                                      |
 
-Per-agent configuration overrides this global default. See [Advanced Tool Configuration — Tool Runtime](TOOL_ADVANCED.md#tool-runtime-experimental) for details.
+Per-agent configuration overrides this global default. See [Advanced Tool Configuration — Tool Runtime](TOOL_ADVANCED.md#tool-runtime) for details.
 
 ### Skills
 
@@ -176,11 +186,11 @@ Riffer.configure do |config|
 end
 ```
 
-| Option             | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `enabled`          | The kill switch, consulted on every span — flipping it at runtime takes effect immediately, short-circuiting to a no-op ahead of the backend. Accepts booleans or `'true'`/`'false'`/`'1'`/`'0'`. Defaults to `true`.                                                                                                                                                                                                                                                                                                                                           |
-| `capture_messages` | Opt-in capture of full message content on LLM-call spans (`gen_ai.input.messages`, `gen_ai.output.messages`, `gen_ai.system_instructions`) as GenAI-semconv JSON. Defaults to `false` — message content routinely carries sensitive data. File attachments serialize as metadata-only stubs (media type and name, never bytes), and riffer applies no size limit of its own — cap oversized attributes with the OTEL SDK attribute length limits.                                                                                                               |
-| `backend`          | The backend riffer routes spans through. Assign `Riffer::Tracing::Otel.build` (pass `provider:` to override the global tracer provider — e.g. an in-memory provider in tests), or any object satisfying the duck-typed contract (`in_span` / `current_context` / `with_context`) to route into a non-OTEL system (e.g. Datadog APM). Defaults to `nil` — a no-op. Raises `Riffer::ArgumentError` unless the value is `nil` or responds to `in_span`. See [Tracing → Routing to a non-OpenTelemetry backend](TRACING.md#routing-to-a-non-opentelemetry-backend). |
+| Option             | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `enabled`          | The kill switch, consulted on every span — flipping it at runtime takes effect immediately, short-circuiting to a no-op ahead of the backend. Accepts booleans or `'true'`/`'false'`/`'1'`/`'0'`. Defaults to `true`.                                                                                                                                                                                                                                                                                                                                                                                         |
+| `capture_messages` | Opt-in capture of full message content on LLM-call spans (`gen_ai.input.messages`, `gen_ai.output.messages`, `gen_ai.system_instructions`) as GenAI-semconv JSON. Defaults to `false` — message content routinely carries sensitive data. File attachments serialize as metadata-only stubs (media type and name, never bytes), and riffer applies no size limit of its own — cap oversized attributes with the OTEL SDK attribute length limits.                                                                                                                                                             |
+| `backend`          | The backend riffer routes spans through. Assign `Riffer::Tracing::Otel.build` (pass `provider:` to override the global tracer provider — e.g. an in-memory provider in tests), or any object satisfying the duck-typed contract (`in_span` / `current_context` / `with_context`) to route into a non-OTEL system (e.g. Datadog APM). Defaults to `nil` — a no-op. Raises `Riffer::ArgumentError` unless the value is `nil` or responds to all of `in_span`, `current_context`, and `with_context`. See [Tracing → Routing to a non-OpenTelemetry backend](TRACING.md#routing-to-a-non-opentelemetry-backend). |
 
 ### File Downloads
 
@@ -270,27 +280,6 @@ When constructing a `Riffer::Agent::Session` from persisted history with the str
 
 See [Messages — IDs](MESSAGES.md#ids) for more details.
 
-### Experimental: History Healing
-
-> **Warning:** This feature is experimental and may change without notice.
-
-Opts the agent into keeping the `tool_use` ↔ `tool_result` invariant intact on its own:
-
-```ruby
-Riffer.configure do |config|
-  config.experimental_history_healing = true
-end
-```
-
-When enabled, two repairs run automatically:
-
-1. **Seeded session.** Passing a pre-populated `Riffer::Agent::Session` to `Agent.new(session: ...)` silently drops orphaned `tool_use` exchanges (assistant `tool_call` with no matching `Tool` result) and parentless `Tool` messages before the next inference call. Pending tool calls on the **resume boundary** — the last assistant whose tail is purely `Tool` results (or none) — are preserved; `execute_pending_tool_calls` runs them on the next LLM call.
-2. **Interrupts.** Any orphan `tool_use` left when the loop is interrupted (caller-issued `interrupt!` or the built-in `INTERRUPT_MAX_STEPS` ceiling) is filled with a placeholder `Riffer::Messages::Tool` carrying `error_type: :interrupted` and the content `"Tool call interrupted before completion."`. Filled `call_id`s are exposed on `Riffer::Agent::Response#healed_tool_call_ids` (and `Riffer::StreamEvents::Interrupt#healed_tool_call_ids` when streaming).
-
-Defaults to `false` — pre-healing behavior. Seeded sessions pass through untouched, and orphan `tool_use` left by an interrupt remain in history for `execute_pending_tool_calls` to re-run on the next call.
-
-There is no per-call override and no customizable placeholder. Callers needing finer control can call `agent.session.update(tool_call_id:, ...)` after the interrupt returns to upgrade a placeholder in place. See [Agent Lifecycle — Healing pending tool results on interrupt](AGENT_LIFECYCLE.md#healing-pending-tool-results-on-interrupt-experimental).
-
 ## Agent-Level Configuration
 
 Override global configuration at the agent level:

data/docs/TOOL_ADVANCED.md

@@ -112,9 +112,7 @@ For expected failures, return `error(...)` or raise `Riffer::ToolExecutionError`
 
 The LLM receives the error message and can decide how to respond (retry, apologize, ask for different input, etc.).
 
-## Tool Runtime (Experimental)
-
-> **Warning:** This feature is experimental and may be removed or changed without warning in a future release.
+## Tool Runtime
 
 By default, tool calls are executed sequentially in the current thread using `Riffer::Tools::Runtime::Inline`. You can change how tool calls are executed by configuring a different tool runtime.
 

data/docs/TRACING.md

@@ -58,7 +58,7 @@ Riffer.configure do |config|
 end
 ```
 
-The backend is duck-typed — any object satisfying the contract works, and the setter validates only that it responds to `in_span` (otherwise it raises `Riffer::ArgumentError`). It must respond to:
+The backend is duck-typed — any object satisfying the contract works, and the setter validates that it responds to `in_span`, `current_context`, and `with_context` (otherwise it raises `Riffer::ArgumentError`). It must respond to:
 
 - `in_span(name, attributes:, kind:) { |span| … }` — open a span around the block, yield a span object, and return the block's value.
 - `current_context` — return the active trace context (for re-attaching across fiber/thread boundaries), or `nil` when there is none.

data/docs/providers/AMAZON_BEDROCK.md

@@ -166,6 +166,37 @@ class AWSAgent < Riffer::Agent
 end
 ```
 
+## Reasoning Models
+
+Claude models on Bedrock can think before they answer. Enable extended thinking through `additional_model_request_fields`:
+
+```ruby
+class ThinkAgent < Riffer::Agent
+  model 'amazon_bedrock/us.anthropic.claude-haiku-4-5-20251001-v1:0'
+  model_options inference_config: {max_tokens: 2048},
+    additional_model_request_fields: {thinking: {type: "enabled", budget_tokens: 1024}}
+end
+
+ThinkAgent.new.stream('What is 2+2? Think step by step.').each do |event|
+  case event
+  when Riffer::StreamEvents::ReasoningDelta
+    print "[reasoning] #{event.content}"
+  when Riffer::StreamEvents::TextDelta
+    print event.content
+  end
+end
+```
+
+The reasoning is kept on the assistant message as [reasoning parts](../MESSAGES.md#reasoning), whether you call `generate` or `stream`. Read it with `response.reasoning`, or as plain text with `reasoning_text` on the message. Bedrock sometimes redacts part of Claude's reasoning. Those parts are stored and sent back like any other, but they have no readable text, so `reasoning_text` leaves them out.
+
+### Reasoning Replay
+
+Riffer sends the reasoning back to Bedrock on every later turn. How much of it Claude uses depends on the model; some only use the reasoning from the current tool-calling turn. For tool calls, sending it back is required: when thinking is enabled, Claude needs its earlier reasoning back to carry on after a tool result. You don't have to do anything; it happens as long as the assistant messages stay in the history.
+
+If you persist sessions, keep the `reasoning` key when you store messages (see [Messages — Reasoning](../MESSAGES.md#reasoning)). If you drop it, later turns lose the model's earlier reasoning, and a tool-calling turn with thinking enabled may be rejected.
+
+Only reasoning that Bedrock produced is sent back to Bedrock. A conversation that switches providers midway still works: reasoning from other providers is kept on the messages but left out of Bedrock requests.
+
 ## File Support
 
 Bedrock accepts file attachments either as raw bytes, or as `s3://` URIs passed straight through to Converse — Bedrock fetches the S3 object itself:

data/docs/providers/OPENROUTER.md

@@ -173,7 +173,7 @@ end
 
 ## Reasoning Models
 
-Reasoning models surface their thought process via OpenRouter's normalised `reasoning` field. Enable it with the `reasoning` option:
+Reasoning models surface their thought process via OpenRouter's normalised `reasoning_details` field. Enable it with the `reasoning` option:
 
 ```ruby
 class ThinkAgent < Riffer::Agent
@@ -191,6 +191,23 @@ ThinkAgent.new.stream('What is 2+2? Think step by step.').each do |event|
 end
 ```
 
+### Reasoning Replay
+
+Each entry in OpenRouter's `reasoning_details` becomes a [`ReasoningPart`](../MESSAGES.md#reasoning) on the assistant message, on both `generate_text` and `stream_text`, with nothing dropped:
+
+| `reasoning_details` field | `ReasoningPart` field                                                                                         |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `type`                    | `type`: `reasoning.text` → `:text`, `reasoning.summary` → `:summary`, `reasoning.encrypted` → `:encrypted` |
+| `text` / `summary`        | `text`                                                                                                        |
+| `data`                    | `data`                                                                                                        |
+| `signature`               | `signature`                                                                                                   |
+| `id`                      | `id`                                                                                                          |
+| `format`                  | `format` (e.g. `"anthropic-claude-v1"`, `"openai-responses-v1"`, `"unknown"`)                                 |
+
+When streaming, OpenRouter splits one block into many fragments that share an `index`. The provider concatenates their `text`, `summary`, and `data` and keeps the `signature`, `id`, and `format` that arrive along the way, so each block ends as one `ReasoningDone` part. Each non-empty `text` or `summary` fragment is also yielded as a `ReasoningDelta`. Detail types riffer doesn't know are skipped.
+
+On the next request, the assistant message's parts go back as `reasoning_details` in their original order and unchanged. This is what lets Anthropic and Gemini models continue signed thinking across a tool-call loop, and lets OpenAI models reuse their encrypted reasoning. Following the [replay contract](../MESSAGES.md#reasoning), only parts whose `format` is one OpenRouter documents are sent: `unknown`, `openai-responses-v1`, `azure-openai-responses-v1`, `bedrock-openai-responses-v1`, `bedrock-xai-responses-v1`, `xai-responses-v1`, `meta-responses-v1`, `anthropic-claude-v1`, and `google-gemini-v1` (listed in `Riffer::Providers::OpenRouter::REASONING_FORMATS`). Parts with no `format`, or one produced by another adapter such as `mock-v1`, are skipped. The `index` is not stored, since the parts' order already carries it.
+
 ## Routing & Fallbacks
 
 Survive an upstream outage by chaining models:

data/docs-site/build.rb

@@ -1,10 +1,6 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-# Builds the docs site — landing page, guide pages, 404, and assets — into
-# _site/ at the repo root. Pages are declared in manifest.yml; the build fails
-# if the manifest and docs/**/*.md ever disagree.
-
 require "erb"
 require "fileutils"
 require "yaml"
@@ -89,8 +85,6 @@ def build_groups(manifest)
   end
 end
 
-# Numbering restarts per docs/ subdirectory, so the providers pages read as
-# their own sequence rather than continuing the main chapters.
 def chapter_numbers(manifest)
   manifest.
     flat_map { |group| group[:pages] }.

data/docs-site/check.rb

@@ -1,9 +1,6 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-# Validates every internal link and anchor in the built _site/ HTML. Exits
-# non-zero with a list of broken links on failure.
-
 SITE = Pathname(__dir__).join("../_site").expand_path
 
 EXTERNAL = %r{\A(?:https?:|mailto:|//)}
@@ -33,11 +30,10 @@ def ids(html)
   html.scan(/\bid="([^"]+)"/).flatten
 end
 
-# Links into /api/ are skipped: RDoc builds that tree in a separate task, so
-# it is absent when only the site has been built.
 def page_errors(file, id_index)
   links(file.read).
     grep_v(EXTERNAL).
+    # RDoc builds /api/ in a separate task, so it is absent when only the site has been built.
     reject { |link| link.start_with?("/api/") }.
     filter_map { |link| link_error(file, link, id_index) }
 end

data/lib/riffer/agent/config.rb

@@ -1,46 +1,22 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Typed configuration object holding every class-level DSL setting on a
-# Riffer::Agent subclass. Procs are stored unresolved and resolved per-instance
-# later.
 class Riffer::Agent::Config
   DEFAULT_MAX_STEPS = 16 #: Integer
 
   # @rbs @tool_runtime: (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)?
 
-  # The configured agent identifier.
   attr_reader :identifier #: String? # @dynamic identifier
-
-  # The configured model.
   attr_reader :model #: (String | Proc)? # @dynamic model
-
-  # The configured instructions.
   attr_reader :instructions #: (String | Proc)? # @dynamic instructions
-
-  # Options passed to generate_text/stream_text.
   attr_accessor :model_options #: Hash[Symbol, untyped] # @dynamic model_options, model_options=
-
-  # The configured structured-output schema.
   attr_reader :structured_output #: Riffer::Params? # @dynamic structured_output
-
-  # The maximum number of LLM call steps in the tool-use loop.
   attr_accessor :max_steps #: Numeric? # @dynamic max_steps, max_steps=
-
-  # The configured tools.
   attr_accessor :tools_config #: (Array[singleton(Riffer::Tool)] | Proc)? # @dynamic tools_config, tools_config=
-
-  # The accumulated +use_mcp+ tag configurations.
   attr_reader :mcp_configs #: Array[Hash[Symbol, untyped]] # @dynamic mcp_configs
-
-  # The configured skills.
   attr_accessor :skills_config #: Riffer::Skills::Config? # @dynamic skills_config, skills_config=
-
-  # Registered guardrail entries keyed by phase.
   attr_reader :guardrails #: Hash[Symbol, Array[Hash[Symbol, untyped]]] # @dynamic guardrails
 
-  # Builds a new Config. Raises Riffer::ArgumentError if +model+ or
-  # +instructions+ is invalid (e.g. an empty string).
   #--
   #: (
   #    ?identifier: String?,
@@ -81,14 +57,12 @@ class Riffer::Agent::Config
     self.tool_runtime = tool_runtime if tool_runtime
   end
 
-  # Sets +identifier+, coercing the value to String.
   #--
   #: (untyped) -> String?
   def identifier=(value)
     @identifier = value&.to_s
   end
 
-  # Sets +structured_output+. Raises Riffer::ArgumentError on an invalid value.
   #--
   #: (Riffer::Params?) -> Riffer::Params?
   def structured_output=(value)
@@ -99,16 +73,14 @@ class Riffer::Agent::Config
     @structured_output = value
   end
 
-  # Returns the declared tool runtime, or +Riffer.config.tool_runtime+ when none
-  # was declared. Resolving the global here rather than at construction is what
-  # lets a copy tell an inherited runtime from a defaulted one.
   #--
   #: () -> (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)
   def tool_runtime
+    # Resolved here rather than at construction so a copy can tell an inherited
+    # runtime from a defaulted one.
     @tool_runtime || Riffer.config.tool_runtime
   end
 
-  # Sets +tool_runtime+. Raises Riffer::ArgumentError on an invalid value.
   #--
   #: ((singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)) -> (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)
   def tool_runtime=(value)
@@ -122,8 +94,6 @@ class Riffer::Agent::Config
     @tool_runtime = value
   end
 
-  # Sets +model+. Raises Riffer::ArgumentError on an invalid value (e.g. an
-  # empty string).
   #--
   #: ((String | Proc)?) -> (String | Proc)?
   def model=(value)
@@ -131,8 +101,6 @@ class Riffer::Agent::Config
     @model = value
   end
 
-  # Sets +instructions+. Raises Riffer::ArgumentError on an invalid value (e.g.
-  # an empty string).
   #--
   #: ((String | Proc)?) -> (String | Proc)?
   def instructions=(value)
@@ -140,8 +108,6 @@ class Riffer::Agent::Config
     @instructions = value
   end
 
-  # Appends an MCP tag entry to +mcp_configs+.
-  #
   #--
   #: (String | Symbol, ?progressive: bool) -> Array[Hash[Symbol, untyped]]
   def add_mcp(tag, progressive: true)
@@ -150,9 +116,6 @@ class Riffer::Agent::Config
     @mcp_configs << { tags: [tag.to_sym], progressive: progressive }
   end
 
-  # Appends a guardrail entry to +guardrails+ for the given phase; +:around+
-  # appends to both +:before+ and +:after+. Raises Riffer::ArgumentError unless
-  # +phase+ is :before, :after, or :around.
   #--
   #: (Symbol, klass: singleton(Riffer::Guardrail), ?options: Hash[Symbol, untyped]) -> void
   def add_guardrail(phase, klass:, options: {})
@@ -175,8 +138,6 @@ class Riffer::Agent::Config
     end
   end
 
-  # Returns the guardrail entries for the given phase, or +[]+ if none.
-  #
   #--
   #: (Symbol) -> Array[Hash[Symbol, untyped]]
   def guardrails_for(phase)
@@ -185,14 +146,12 @@ class Riffer::Agent::Config
 
   private
 
-  # +dup+ would leave the copy sharing every collection with this one, so a
-  # declaration on either would reach the other. The nesting runs deeper than one
-  # level: an mcp entry holds its own +:tags+ array, a guardrail entry its own
-  # +:options+ hash, and +model_options+ is arbitrary.
   #--
   #: (Riffer::Agent::Config) -> void
   def initialize_copy(source)
     super
+    # A shallow copy would share collections, letting a declaration on either
+    # config reach the other; entries nest (mcp +:tags+, guardrail +:options+).
     @model_options = Riffer::Helpers::DeepDup.call(source.model_options)
     @mcp_configs = Riffer::Helpers::DeepDup.call(source.mcp_configs)
     @guardrails = Riffer::Helpers::DeepDup.call(source.guardrails)