riffer 0.47.2 → 0.49.0

data/docs/MESSAGES.md

@@ -32,9 +32,9 @@ msg.to_h     # => {role: :user, content: "Hello, how are you?"}
 User messages can include file attachments:
 
 ```ruby
-file = Riffer::Messages::FilePart.from_path("photo.jpg")
+file = Riffer::Messages::User::FilePart.from_path("photo.jpg")
 msg = Riffer::Messages::User.new("Describe this image", files: [file])
-msg.files    # => [#<Riffer::Messages::FilePart ...>]
+msg.files    # => [#<Riffer::Messages::User::FilePart ...>]
 msg.to_h     # => {role: :user, content: "Describe this image", files: [{...}]}
 ```
 
@@ -67,6 +67,19 @@ if msg.token_usage
 end
 ```
 
+#### Tool Calls
+
+`Riffer::Messages::Assistant::ToolCall` is the normalized container riffer stores a requested tool invocation in. Each call carries `call_id` (the provider's identifier, passed back as the tool result's `tool_call_id`), `name`, and `arguments` (the JSON-encoded argument string exactly as the provider emitted it); `to_h` serializes all three.
+
+```ruby
+tool_call = Riffer::Messages::Assistant::ToolCall.new(call_id: "call_123", name: "weather_tool", arguments: '{"city":"Tokyo"}')
+msg = Riffer::Messages::Assistant.new("", tool_calls: [tool_call])
+
+msg.has_tool_calls?        # => true
+msg.tool_calls.first.name  # => "weather_tool"
+tool_call.to_h             # => {call_id: "call_123", name: "weather_tool", arguments: '{"city":"Tokyo"}'}
+```
+
 #### Token Usage Semantics
 
 `TokenUsage` buckets carry the same meaning for every provider, regardless of how the provider reports its raw usage:
@@ -84,16 +97,16 @@ The cache buckets are subsets of `input_tokens`, never additions to it — summi
 
 `finish_reason` carries the same meaning for every provider — each adapter maps its raw wire value (Anthropic's `end_turn`, OpenAI's response status, Gemini's `STOP`, …) into a normalized vocabulary:
 
-| Value               | Meaning                                                                                                                 |
-| ------------------- | ----------------------------------------------------------------------------------------------------------------------- |
-| `:stop`             | The model finished its turn naturally (or hit a stop sequence).                                                         |
-| `:length`           | Output was truncated at the max-token limit.                                                                            |
-| `:tool_calls`       | The model stopped to call tools.                                                                                        |
-| `:content_filter`   | A provider safety system blocked or cut the response.                                                                   |
-| `:context_window`   | Input plus output hit the model's context window; trim or compact history rather than raising `max_tokens`.             |
+| Value               | Meaning                                                                                                                      |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `:stop`             | The model finished its turn naturally (or hit a stop sequence).                                                              |
+| `:length`           | Output was truncated at the max-token limit.                                                                                 |
+| `:tool_calls`       | The model stopped to call tools.                                                                                             |
+| `:content_filter`   | A provider safety system blocked or cut the response.                                                                        |
+| `:context_window`   | Input plus output hit the model's context window; trim or compact history rather than raising `max_tokens`.                  |
 | `:malformed_output` | The model emitted output the provider could not parse, such as an invalid tool call; retry or nudge rather than backing off. |
-| `:error`            | The provider reported an error finish.                                                                                  |
-| `:other`            | A provider-specific value with no normalized equivalent.                                                                |
+| `: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 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:
 
@@ -124,6 +137,61 @@ msg = Riffer::Messages::Assistant.new('{"sentiment":"positive"}', structured_out
 msg.to_h  # => {role: :assistant, content: '{"sentiment":"positive"}', structured_output: {sentiment: "positive"}}
 ```
 
+#### Reasoning
+
+Reasoning models emit thinking blocks alongside their answer, and several providers require those blocks back on the next turn of a tool-calling loop. `Riffer::Messages::Assistant::ReasoningPart` is the normalized container riffer stores them in: a list of parts on the assistant message, in the order the provider emitted them.
+
+```ruby
+summary = Riffer::Messages::Assistant::ReasoningPart.new(type: :summary, text: "The user wants the answer.", format: "mock-v1")
+opaque = Riffer::Messages::Assistant::ReasoningPart.new(type: :encrypted, data: "b3BhcXVl", format: "mock-v1")
+msg = Riffer::Messages::Assistant.new("42", reasoning: [summary, opaque])
+
+msg.reasoning?            # => true
+msg.reasoning_text        # => "The user wants the answer."
+msg.reasoning.first.type  # => :summary
+```
+
+A readable part next to an opaque one is the common shape, not a contrived one: OpenAI's Responses API returns a reasoning item as summary text plus an encrypted payload, and Anthropic pairs a `thinking` block with a `redacted_thinking` block when it redacts part of the chain of thought.
+
+`reasoning:` takes `ReasoningPart`s; `Riffer::Messages::Base.from_hash` is what turns persisted hashes back into parts.
+
+Each part carries:
+
+| Field       | Type      | Description                                                                                                     |
+| ----------- | --------- | --------------------------------------------------------------------------------------------------------------- |
+| `type`      | `Symbol`  | One of `:text` (readable reasoning), `:summary` (a provider-condensed digest), `:encrypted` (an opaque payload) |
+| `text`      | `String?` | The reasoning prose, for `:text` and `:summary` parts                                                           |
+| `data`      | `String?` | The opaque payload, for `:encrypted` parts                                                                      |
+| `signature` | `String?` | The provider's signature over the part, when it issues one                                                      |
+| `id`        | `String?` | The provider's identifier for the part, when it issues one                                                      |
+| `format`    | `String?` | The wire format, owned by the adapter that produced the part (e.g. `"anthropic-claude-v1"`)                     |
+
+A `type` outside the three values raises `Riffer::ArgumentError`. `format` is a free string riffer never validates — it exists so an adapter can tell its own parts apart from another adapter's.
+
+`reasoning?` is true when the message carries any part. `reasoning_text` joins the `text` of the `:text` and `:summary` parts with blank lines, skipping `:encrypted` parts, and is `nil` when there is nothing to join. The run's final assistant message projects its parts onto `response.reasoning` (see [Agent Lifecycle — Response Attributes](AGENT_LIFECYCLE.md#response-attributes)).
+
+Parts round-trip through `to_h` / `from_hash` like every other message field, so an application that persists sessions can store and replay them. The `reasoning` key is absent from `to_h` when the message has no parts, and each part omits the fields it doesn't carry:
+
+```ruby
+msg.to_h
+# => {role: :assistant, content: "42", reasoning: [
+#      {type: :summary, text: "The user wants the answer.", format: "mock-v1"},
+#      {type: :encrypted, data: "b3BhcXVl", format: "mock-v1"}
+#    ]}
+
+Riffer::Messages::Base.from_hash(msg.to_h).reasoning  # => [ReasoningPart, ReasoningPart]
+```
+
+**The replay contract.** A provider adapter replays only the parts whose `format` it recognizes and silently skips the rest, so history that travelled through another provider is never rejected. A part with no `format` is never replayed; adapters that surface reasoning text but cannot yet send it back emit their parts that way, so the text is kept for display without risking a rejected request. Parts are never reordered, merged, or edited — riffer treats them as opaque, because the provider's signature covers their exact bytes.
+
+An application that would rather not store parts can leave the key out when it serializes:
+
+```ruby
+msg.to_h.except(:reasoning)
+```
+
+To drop parts from the in-memory session mid-run instead, `Session#update(id:, reasoning: [])` rewrites the message in place; it needs [message ids](#ids) enabled to address it.
+
 ### Tool
 
 Tool messages contain the results of tool executions:
@@ -155,7 +223,7 @@ msg.error_type  # => :execution_error
 
 ## File Parts
 
-`Riffer::Messages::FilePart` represents a file attachment (image or document) that can be included with user messages.
+`Riffer::Messages::User::FilePart` represents a file attachment (image or document) that can be included with user messages.
 
 ### Supported Media Types
 
@@ -167,21 +235,21 @@ msg.error_type  # => :execution_error
 
 ```ruby
 # From a file path (reads eagerly, detects media type from extension)
-file = Riffer::Messages::FilePart.from_path("photo.jpg")
+file = Riffer::Messages::User::FilePart.from_path("photo.jpg")
 file.media_type  # => "image/jpeg"
 file.filename    # => "photo.jpg"
 file.image?      # => true
 
 # From a URL (stored directly, resolved lazily if provider needs bytes)
-file = Riffer::Messages::FilePart.from_url("https://example.com/doc.pdf")
+file = Riffer::Messages::User::FilePart.from_url("https://example.com/doc.pdf")
 file.url?        # => true
 file.document?   # => true
 
 # From raw base64 data
-file = Riffer::Messages::FilePart.new(media_type: "image/png", data: base64_string, filename: "chart.png")
+file = Riffer::Messages::User::FilePart.new(media_type: "image/png", data: base64_string, filename: "chart.png")
 
 # With an expected sha256 checksum of the file's contents
-file = Riffer::Messages::FilePart.from_url(
+file = Riffer::Messages::User::FilePart.from_url(
   "https://example.com/doc.pdf",
   sha256: "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
 )
@@ -243,7 +311,7 @@ agent = MyAgent.new(session: session)
 response = agent.generate   # session already carries the last user turn
 ```
 
-`Riffer::Agent::Session.new(messages:)` accepts `Riffer::Messages::Base` objects. If your persistence layer hands back hashes, normalize them first via `Riffer::Messages::Base.from_hash` or your own adapter.
+`Riffer::Agent::Session.new(messages:)` accepts `Riffer::Messages::Base` objects. If your persistence layer hands back hashes, normalize them first via `Riffer::Messages::Base.from_hash` (which dispatches on `:role`), a role's own `from_hash` such as `Riffer::Messages::User.from_hash` when the role is already known, or your own adapter.
 
 ### Accessing Message History
 

data/docs/STREAM_EVENTS.md

@@ -105,14 +105,18 @@ event.content  # => "Let me think about "
 
 ### ReasoningDone
 
-Emitted when reasoning is complete:
+Emitted when one reasoning block is complete:
 
 ```ruby
-event = Riffer::StreamEvents::ReasoningDone.new("Let me think about this step by step...")
-event.role     # => :assistant
-event.content  # => "Let me think about this step by step..."
+part = Riffer::Messages::Assistant::ReasoningPart.new(type: :text, text: "Let me think about this step by step...", format: "mock-v1")
+event = Riffer::StreamEvents::ReasoningDone.new(part)
+event.role       # => :assistant
+event.part       # => the ReasoningPart
+event.part.text  # => "Let me think about this step by step..."
 ```
 
+`part` is the [reasoning part](MESSAGES.md#reasoning) the preceding `ReasoningDelta` events added up to, and the agent loop accumulates it onto the assistant message. Adapters that cannot yet replay their reasoning emit it as a `:text` part with no `format`, so it is stored for display but never sent back to the provider.
+
 ### WebSearchStatus
 
 Emitted during web search progress with status updates:

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.
@@ -95,7 +95,7 @@ The contract promise is: **when present**, a key carries the documented meaning
 
 ### Per-call tags (`riffer.tag.*`)
 
-Any tags passed to `#generate` / `#stream` via `tags:` are stamped on **all four** span types as `riffer.tag.<key>` (string), so the per-span tables below omit them. They appear on every span the tagged call emits and are absent otherwise. Example: `tags: {team: "growth"}` adds `riffer.tag.team` → `"growth"` to the `invoke_agent`, `chat`, `execute_tool`, and `execute_guardrail` spans. See [Per-Call Tags](AGENTS.md#per-call-tags) for the full surface and the per-provider request-metadata mapping.
+Any tags passed to `#generate` / `#stream` via `tags:` are stamped on **all four** span types as `riffer.tag.<key>` (string), so the per-span tables below omit them. They appear on every span the tagged call emits and are absent otherwise. Example: `tags: {team: "growth"}` adds `riffer.tag.team` → `"growth"` to the `invoke_agent`, `chat`, `execute_tool`, and `execute_guardrail` spans. The [default tags](AGENTS.md#default-tags) are always present, e.g. `riffer.tag.kind` → `"agent"` and `riffer.tag.agent` → the agent identifier. See [Per-Call Tags](AGENTS.md#per-call-tags) for the full surface and the per-provider request-metadata mapping.
 
 ## `invoke_agent {agent}` — the run span
 

data/docs/providers/AMAZON_BEDROCK.md

@@ -166,12 +166,43 @@ 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:
 
 ```ruby
-file = Riffer::Messages::FilePart.from_url("s3://my-bucket/document.pdf", media_type: "application/pdf")
+file = Riffer::Messages::User::FilePart.from_url("s3://my-bucket/document.pdf", media_type: "application/pdf")
 response = provider.generate_text(
   prompt: "Summarize this document",
   model: "us.anthropic.claude-haiku-4-5-20251001-v1:0",

data/docs/providers/CUSTOM_PROVIDERS.md

@@ -24,7 +24,7 @@ class Riffer::Providers::MyProvider < Riffer::Providers::Base
     params = {
       model: model,
       messages: convert_messages(messages),
-      **options.except(:tools)
+      **options.except(:tools, :tags)
     }
 
     if tools && !tools.empty?
@@ -220,9 +220,9 @@ Riffer::StreamEvents::ToolCallDone.new(
   arguments: '{"complete":"args"}'
 )
 
-# Reasoning (if supported)
+# Reasoning (if supported); see the Reasoning section for building the part
 Riffer::StreamEvents::ReasoningDelta.new("thinking...")
-Riffer::StreamEvents::ReasoningDone.new("complete reasoning")
+Riffer::StreamEvents::ReasoningDone.new(part)
 
 # Web search (if supported)
 Riffer::StreamEvents::WebSearchStatus.new("searching", query: "search query")
@@ -276,6 +276,58 @@ yielder << Riffer::StreamEvents::FinishReasonDone.new(finish_reason: :stop, raw_
 
 Also have `execute_stream` raise `Riffer::IncompleteStreamError` when the stream ends without the provider's terminal event, rather than returning normally. Otherwise a connection that drops mid-response looks identical to a finished one, and the agent loop accepts a truncated message as complete.
 
+## Reasoning
+
+`extract_reasoning` is the optional hook for reasoning models — return the response's thinking blocks as [`Riffer::Messages::Assistant::ReasoningPart`s](../MESSAGES.md#reasoning) and the base class attaches them to the assistant message, where your application can persist them and hand them back on the next turn:
+
+```ruby
+def extract_reasoning(response)
+  response.thinking_blocks.map do |block|
+    Riffer::Messages::Assistant::ReasoningPart.new(
+      type: :encrypted,
+      data: block.data,
+      signature: block.signature,
+      format: "my-provider-v1"
+    )
+  end
+end
+```
+
+The base class defaults to `[]`, so a provider without reasoning stays valid.
+
+Your adapter owns its `format` string: pick one value per wire shape, replay only the parts carrying a value you recognize, and skip the rest — history that travelled through another provider must never make a request fail. Never reorder or edit a part; the provider's signature covers its exact bytes.
+
+For streaming, emit one `ReasoningDone` per block, carrying the part so the agent loop can accumulate it:
+
+```ruby
+part = Riffer::Messages::Assistant::ReasoningPart.new(type: :text, text: "complete reasoning", format: "my-provider-v1")
+
+yielder << Riffer::StreamEvents::ReasoningDelta.new("thinking...")
+yielder << Riffer::StreamEvents::ReasoningDone.new(part)
+```
+
+If your adapter surfaces reasoning text but cannot yet replay it, call `yield_reasoning_done(yielder, text)` instead. It wraps the text in a `:text` part with no `format`, which persists for display and is skipped on replay.
+
+## Tags
+
+Every agent and judge call passes a `:tags` option: a flat `String => String` hash of the caller's [per-call tags](../AGENTS.md#per-call-tags) plus the [default tags](../AGENTS.md#default-tags). `kind` (`"agent"` or `"judge"`) and `agent` (the agent or evaluator identifier) tell you who the call is on behalf of:
+
+```ruby
+def build_request_params(messages, model, options)
+  tags = options[:tags] || {}
+
+  {
+    agent: tags["agent"],
+    user: tags["user_id"],
+    messages: convert_messages(messages),
+    model: model,
+    **options.except(:tools, :tags),
+  }
+end
+```
+
+Map tags to your service's native request field, or drop them, but don't pass `:tags` on to an SDK verbatim.
+
 ## Trace Provider Name
 
 LLM-call and agent-run spans stamp `gen_ai.provider.name` from the `semconv_provider_name` class method. The default is your snake_cased class name; override it when a [GenAI semconv well-known value](https://opentelemetry.io/docs/specs/semconv/gen-ai/) exists for your provider:
@@ -330,7 +382,7 @@ class Riffer::Providers::MyProvider < Riffer::Providers::Base
       messages: convert_messages(conversation),
       system: system_message,
       max_tokens: options[:max_tokens] || 4096,
-      **options.except(:tools, :max_tokens)
+      **options.except(:tools, :max_tokens, :tags)
     }
 
     if tools && !tools.empty?

data/docs/providers/GEMINI.md

@@ -148,7 +148,7 @@ response = provider.generate_text(
 Gemini's API only accepts inline base64-encoded files (images and documents), never a URL reference:
 
 ```ruby
-file = Riffer::Messages::FilePart.new(data: base64_data, media_type: "image/png")
+file = Riffer::Messages::User::FilePart.new(data: base64_data, media_type: "image/png")
 response = provider.generate_text(
   prompt: "Describe this image",
   model: "gemini-2.5-flash-lite",

data/docs/providers/MOCK_PROVIDER.md

@@ -47,6 +47,23 @@ provider.stub_response("Based on the tool result, here's my answer.")
 response = agent.generate("Use the tool")
 ```
 
+## Stubbing Reasoning
+
+Stub [reasoning parts](../MESSAGES.md#reasoning) to exercise your application's persistence of them. Hashes are normalized into `Riffer::Messages::Assistant::ReasoningPart`s:
+
+```ruby
+provider.stub_response("42", reasoning: [
+  {type: :text, text: "The user wants the answer.", format: "mock-v1"},
+  {type: :encrypted, data: "b3BhcXVl", signature: "sig", format: "mock-v1"}
+])
+
+response = agent.generate("What is the answer?")
+response.reasoning.map(&:type)  # => [:text, :encrypted]
+agent.session.messages.last.reasoning_text  # => "The user wants the answer."
+```
+
+When streaming, each part is emitted as a `ReasoningDelta` (only when it carries `text`) followed by a `ReasoningDone` carrying the part, ahead of the text events.
+
 ## Queueing Multiple Responses
 
 Responses are consumed in order:

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,47 +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
 
-  # The configured agent identifier.
-  attr_reader :identifier #: String? # @dynamic identifier
+  # @rbs @tool_runtime: (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)?
 
-  # The configured model.
+  attr_reader :identifier #: String? # @dynamic identifier
   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 tool runtime.
-  attr_reader :tool_runtime #: (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc) # @dynamic tool_runtime
-
-  # 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?,
@@ -52,7 +27,7 @@ class Riffer::Agent::Config
   #    ?max_steps: Numeric?,
   #    ?tools_config: (Array[singleton(Riffer::Tool)] | Proc)?,
   #    ?mcp_configs: Array[Hash[Symbol, untyped]],
-  #    ?tool_runtime: (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc),
+  #    ?tool_runtime: (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)?,
   #    ?skills_config: Riffer::Skills::Config?,
   #    ?guardrails: Hash[Symbol, Array[Hash[Symbol, untyped]]]
   #  ) -> void
@@ -65,7 +40,7 @@ class Riffer::Agent::Config
     max_steps: DEFAULT_MAX_STEPS,
     tools_config: nil,
     mcp_configs: [],
-    tool_runtime: Riffer.config.tool_runtime,
+    tool_runtime: nil,
     skills_config: nil,
     guardrails: { before: [], after: [] }
   )
@@ -79,17 +54,15 @@ class Riffer::Agent::Config
     self.model = model
     self.instructions = instructions
     self.structured_output = structured_output
-    self.tool_runtime = tool_runtime
+    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)
@@ -100,7 +73,14 @@ class Riffer::Agent::Config
     @structured_output = value
   end
 
-  # Sets +tool_runtime+. Raises Riffer::ArgumentError on an invalid value.
+  #--
+  #: () -> (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
+
   #--
   #: ((singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)) -> (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)
   def tool_runtime=(value)
@@ -114,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)
@@ -123,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)
@@ -132,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)
@@ -142,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: {})
@@ -167,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)
@@ -177,6 +146,20 @@ class Riffer::Agent::Config
 
   private
 
+  #--
+  #: (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)
+    @tools_config = Riffer::Helpers::DeepDup.call(source.tools_config)
+    @skills_config = source.skills_config&.dup
+    @structured_output = source.structured_output&.dup
+  end
+
   #--
   #: (untyped, String) -> void
   def validate_string_or_proc!(value, name)