riffer 0.47.2 → 0.49.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b5e4c3861f4218fa075b5abd666be63eee6432db05c9a6fff3ab4285748ed7c5
-  data.tar.gz: a945c6c549c4c18b4e228cbcce1a03a48eb2b263a20bb18c9c1c51088c6a3e8c
+  metadata.gz: b1bd95697d75079325d4a057c0f2bb17bc8fee9a3864c611967e78d8e1637ef8
+  data.tar.gz: 84ddb8c10cef0b5711b00793b3a19de2713fcf8d7985166dfaa248fa7bbe58f0
 SHA512:
-  metadata.gz: 308010c98f1f44a9a13032b39fea4a2636977d9b6f232ccb9aa040ef6485f0b2d51ec3d66a69be0e4a522759cc86e42fa8b94eae6b2446a5c61ec6a3f6388892
-  data.tar.gz: dd7710eb0ed144e1dfaf49d063e5d4845068e590927092dd5b3f946b0cc0f49533262c3dc83e12dbb87fdc8356eb83890177ccf8eacc485028ca4ce7684ce01e
+  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.47.2"
+  ".": "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,48 @@ 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)
+
+
+### ⚠ BREAKING CHANGES
+
+* **messages:** Riffer::Messages::FilePart is renamed to Riffer::Messages::User::FilePart with no alias. ToolCall no longer responds to Struct-only methods such as [] or to_a; use its readers instead.
+
+### Features
+
+* **agent:** inherit configuration on subclass ([#440](https://github.com/janeapp/riffer/issues/440)) ([a45c457](https://github.com/janeapp/riffer/commit/a45c45756108cfac7970e88b9f6f5b64638896c8))
+* identify agents and evals with default tags ([#452](https://github.com/janeapp/riffer/issues/452)) ([22ab54c](https://github.com/janeapp/riffer/commit/22ab54c5225a45c38e255b1a2aa32be0ac28cb12))
+* **messages:** persist reasoning on assistant messages ([#446](https://github.com/janeapp/riffer/issues/446)) ([7fc64ab](https://github.com/janeapp/riffer/commit/7fc64ab416feb47ccff575518378c58bbcc74d63))
+
+
+### Bug Fixes
+
+* **messages:** preserve tool errors and token usage through from_hash ([#450](https://github.com/janeapp/riffer/issues/450)) ([6e2bd90](https://github.com/janeapp/riffer/commit/6e2bd90926d7c3c071ac95f708875652268c767f))
+
+
+### Code Refactoring
+
+* **messages:** make nested message objects follow one pattern ([#448](https://github.com/janeapp/riffer/issues/448)) ([e9e63db](https://github.com/janeapp/riffer/commit/e9e63dba16121692f734b476569b062c09cc959d))
+
 ## [0.47.2](https://github.com/janeapp/riffer/compare/riffer/v0.47.1...riffer/v0.47.2) (2026-09-21)
 
 

data/docs/AGENTS.md

@@ -126,7 +126,7 @@ end
 
 ### use_mcp
 
-Loads tools from registered [MCP](MCP.md) servers by tag. Like `uses_tools`, **`use_mcp` is not inherited**—add it on each subclass that should include MCP tools.
+Loads tools from registered [MCP](MCP.md) servers by tag.
 
 ### model_options
 
@@ -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, defaults to `Riffer.config.tool_runtime` (captured at agent class definition time). 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
 
@@ -304,6 +302,27 @@ MyAgent.config.max_steps  # => 8
 
 The DSL methods read and mutate this Config in place.
 
+### Inheritance
+
+A subclass starts from a copy of its parent's Config, so it inherits every setting the parent declared and overrides only what its own body declares:
+
+```ruby
+class BaseAgent < Riffer::Agent
+  model 'openai/gpt-5-mini'
+  max_steps 8
+end
+
+class TerseAgent < BaseAgent
+  max_steps 2
+end
+
+TerseAgent.config.model      # => 'openai/gpt-5-mini'
+TerseAgent.config.max_steps  # => 2
+BaseAgent.config.max_steps   # => 8
+```
+
+`identifier` is not inherited. A subclass derives its own from its class name, since two classes claiming one identifier would raise `Riffer::DuplicateIdentifierError` at the first lookup.
+
 For advanced composition or testing, build a Config directly and pass it via `config:` to bypass class-level DSL entirely:
 
 ```ruby
@@ -372,13 +391,24 @@ agent.generate("Summarize this ticket.",
 agent.stream("...", tags: {team: "growth", environment: "production"})
 ```
 
-Keys and values may be `String` or `Symbol`; both are stringified, and entries with a `nil` value are dropped. An omitted or empty `tags:` is a complete no-op.
+Keys and values may be `String` or `Symbol`; both are stringified, and entries with a `nil` value are dropped.
 
 Tags propagate to **two** places:
 
 1. The provider's native per-request metadata field (see the mapping below).
 2. Observability — stamped as `riffer.tag.<key>` on **every** span the call emits (`invoke_agent`, `chat`, `execute_tool`, `execute_guardrail`). See [Tracing](TRACING.md).
 
+### Default tags
+
+Every call also carries two tags riffer adds itself, so a provider can tell who the call is on behalf of:
+
+| Tag     | Value                                                                   |
+| ------- | ----------------------------------------------------------------------- |
+| `kind`  | `"agent"` (`"judge"` for [evaluator](EVALS.md) judge calls)             |
+| `agent` | The agent's `identifier` (the evaluator's `identifier` for judge calls) |
+
+A tag you pass with the same key wins. The default tags count towards the provider limits below.
+
 ### Reserved key: `user_id`
 
 `user_id` is a reserved tag. Beyond appearing like any other tag, it maps to the provider's native end-user identifier where one exists (see the table).
@@ -393,6 +423,8 @@ Tags propagate to **two** places:
 | Anthropic             | `metadata.user_id` **only**   | The only tag forwarded                  |
 | Gemini                | _(none — observability only)_ | Tag only; no request field              |
 
+If `model_options` already sets the native field (`metadata` or `request_metadata`), the tags are merged into it; a tag wins on a shared key.
+
 **Anthropic silently drops non-`user_id` tags.** The Messages API has no free-form request-metadata field — only `metadata.user_id`. So for Anthropic, `user_id` is forwarded as `metadata: {user_id: …}` and **every other tag is dropped from the request** (it still appears on spans). This is intentional.
 
 **Gemini is observability-only.** Riffer's Gemini adapter targets the Gemini Developer API (`generativelanguage.googleapis.com`), whose `generateContent` request has **no** `labels` field — sending unknown fields is rejected. So tags are **not** added to the Gemini request; they propagate to spans only. Native request labels (`labels`, lowercase `[a-z0-9_-]`, ≤63 chars each) are a Vertex AI feature and would arrive with a future Vertex adapter.
@@ -412,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
 
@@ -315,11 +313,11 @@ agent.context[:skills]        # the Skills::Context, if skills configured
 | `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)                                               |
+| `reasoning`            | `Array[ReasoningPart]`      | The [reasoning parts](MESSAGES.md#reasoning) on the final assistant message (else `[]`)          |
 | `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                                                          |
 | `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,15 +186,15 @@ 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
 
-File-attachment-download policy lives under `config.files`. Before an LLM call, riffer resolves every `Riffer::Messages::FilePart` attached to a user message against the provider's own capability — some providers accept a URL as-is, some need the bytes inline, and some can't take an attachment at all. See [Messages — File Parts](MESSAGES.md#file-parts) for `FilePart` itself and its `sha256:` field.
+File-attachment-download policy lives under `config.files`. Before an LLM call, riffer resolves every `Riffer::Messages::User::FilePart` attached to a user message against the provider's own capability — some providers accept a URL as-is, some need the bytes inline, and some can't take an attachment at all. See [Messages — File Parts](MESSAGES.md#file-parts) for `FilePart` itself and its `sha256:` field.
 
 ```ruby
 Riffer.configure do |config|
@@ -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/EVALS.md

@@ -194,11 +194,12 @@ Class methods:
 - `instructions(value)` - Evaluation criteria and scoring rubric (enables default `evaluate`)
 - `higher_is_better(value)` - Whether higher scores are better (default: true)
 - `judge_model(value)` - Override the global judge model
+- `identifier(value)` - Override the identifier sent with judge calls (default: the snake_cased class name, or `riffer/judge` for an anonymous class)
 
 Instance methods:
 
 - `evaluate(input:, output:, ground_truth:, messages:)` - Override for custom logic; default calls judge with `instructions`
-- `judge` - Returns a Judge instance for LLM-as-judge calls
+- `judge` - Returns a Judge instance for LLM-as-judge calls. Its calls carry the [default tags](AGENTS.md#default-tags) `kind: "judge"` and `agent: <identifier>`
 - `result(score:, reason:, metadata:, token_usage:)` - Helper to build Result objects
 
 ### Advanced: Custom Evaluate Override

data/docs/MCP.md

@@ -89,10 +89,6 @@ MCP tools are appended after any tools declared with `uses_tools`.
 
 Tool names must be unique across `uses_tools` and all included MCP servers; duplicate names raise `Riffer::ArgumentError` when tools are resolved.
 
-### Subclassing
-
-Like [`uses_tools`](AGENTS.md#uses_tools), **`use_mcp` is not inherited** from the superclass. Declare `use_mcp` on each agent class that should load MCP tools.
-
 ## Progressive Tool Discovery
 
 Progressive discovery is the default. The `use_mcp` instruction exposes **`mcp_search`** instead of flooding the context with every tool schema up front.