riffer 0.47.1 → 0.48.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4ac69c8c20b892c53242b0fb792aee2ee1ce5da1ab02b1c53536fa8d1c006f08
-  data.tar.gz: 0fa02ebc739e1968167e517a41d4f0a2cabff5a5845862ac78980d207638c6cd
+  metadata.gz: 5975a19de149eced0122ccf94f08666f66377c395b3a414db48158fcba352807
+  data.tar.gz: fe48ac55158f5bd1f4818651988b68ed2e45fa985c1ebe5a386d636decd15ff2
 SHA512:
-  metadata.gz: 5c0363ce9dad27ccfc899d6c7f4e71123eaa9ae5ceec8e50387575f0642c7696f07de37cb987c45099aee999fe5ac39c8635f07f36efb784c3341bd8a4c6a6aa
-  data.tar.gz: 4b5d6209255a46d9abd52275021709740bf0e87676c20c3bd9240f12acddc7768a050391530970c2a2ed407dbdd27fb50a1b03e43caff8361ad6f28cc67884db
+  metadata.gz: 7e506427c0b0272fb2c6f044def74b74d423e92bb23fbe95e02c5678d48b8b98ff2e8920807b23e4d8fb2db94d509937643813d9248eb109a51d03559a5ecd48
+  data.tar.gz: 3553da8e73fa137a4070baac5548fbd3a345316f0941e9f8b8490d2790d17a5e47b5eb154de6613897874a0a2bd3adaff4b1167d55fe21b99a1d0840d9786733

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

@@ -78,7 +78,11 @@ end
 
 ### Where stubs and stdlib deps live
 
-- `sig/_private/` — signatures that must **not** ship. RBS **skips** `_`-prefixed directories in library mode, so consumers never load them; riffer's own `steep check` does (via the `Steepfile`). Two kinds, by predictable path: external-gem signatures are named by gem at the top level (`async.rbs`, `mcp.rbs`, `zeitwerk.rbs`, `openai.rbs`, `anthropic.rbs`, `aws-sdk-core/*` — full stubs for RBS-less gems plus arity patches for the provider SDKs); riffer's own hidden stubs mirror `lib/` under `riffer/` (e.g. `riffer/providers/anthropic.rbs` narrows the private `client` method to the SDK-typed client).
+Dependency signatures come from [`rbs collection`](https://github.com/ruby/gem_rbs_collection): `rbs_collection.yaml` pins the upstream repo to a commit SHA, the gem set is derived from `Gemfile.lock`, and `rbs_collection.lock.yaml` is committed (the installed `.gem_rbs_collection/` is gitignored). Steep auto-detects the config, so the `Steepfile` declares no `library` lines. `yaml` is the one hand-listed entry under `gems:` — it's stdlib, so it never appears in `Gemfile.lock`.
+
+`bin/typecheck` runs `rbs collection update` before `steep check`, keeping the lock in sync with `Gemfile.lock`; CI fails on lock drift. So after a Dependabot gem bump, run `bin/typecheck` and commit the refreshed lock. To pull newer upstream stubs, bump `revision` in `rbs_collection.yaml` and run `bin/typecheck` — pinning is what makes `update` deterministic.
+
+- `sig/_private/` — signatures that must **not** ship. RBS **skips** `_`-prefixed directories in library mode, so consumers never load them; riffer's own `steep check` does (via the `Steepfile`). Two kinds, by predictable path: external-gem signatures are named by gem at the top level — full stubs for the gems upstream has nothing for (`mcp.rbs`, `zeitwerk.rbs`, `opentelemetry.rbs`, `rspec.rbs`, `aws-sdk-core/*`) plus arity patches for the provider SDKs (`openai.rbs`, `anthropic.rbs`); riffer's own hidden stubs mirror `lib/` under `riffer/` (e.g. `riffer/providers/anthropic.rbs` narrows the private `client` method to the SDK-typed client). A stub must be **deleted** once the collection covers that gem, or RBS raises `DuplicatedMethodDefinitionError`.
 - `sig/manual/` — hand-written riffer-only signatures that are **safe to ship**, for the few things rbs-inline can't generate _at all_ (mirroring `lib/`). In practice that's `extend self` modules (`riffer/agent/run.rbs`, `riffer/helpers/call_or_value.rbs`) and modeling an include applied dynamically (`riffer/tools/toolable.rbs`). SDK-free ivars are **not** hand-written here — declare them inline with `# @rbs` (see "Annotation Conventions"). SDK-typed signatures can't ship, so they go in `_private/riffer/providers/` (the narrowed `client`).
 - `sig/manifest.yaml` — declares the **stdlib** RBS the shipped sigs reference (`uri`, `net-http`) so `rbs -r riffer` resolves them.
 

data/.release-please-manifest.json

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

data/CHANGELOG.md

@@ -5,6 +5,37 @@ 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.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)
+
+
+### Bug Fixes
+
+* **providers:** raise IncompleteStreamError when a stream ends without its terminal event ([#445](https://github.com/janeapp/riffer/issues/445)) ([d142e23](https://github.com/janeapp/riffer/commit/d142e23e80d30ce73e81474eee35c71df1856c40))
+* stop relying on the transitive cgi gem for CGI.escapeHTML ([#443](https://github.com/janeapp/riffer/issues/443)) ([821f3e3](https://github.com/janeapp/riffer/commit/821f3e3e405845b2cc275f86344e526cc2cf183a))
+
 ## [0.47.1](https://github.com/janeapp/riffer/compare/riffer/v0.47.0...riffer/v0.47.1) (2026-09-11)
 
 

data/Rakefile

@@ -58,7 +58,7 @@ end
 namespace :steep do
   desc "Run Steep type checker"
   task :check do
-    sh "bundle exec steep check"
+    sh "bin/typecheck"
   end
 end
 

data/Steepfile

@@ -9,19 +9,5 @@ target :lib do
 
   check "lib"
 
-  library "anthropic"
-  library "aws-sdk-bedrockruntime"
-  library "aws-sdk-core"
-  library "base64"
-  library "cgi"
-  library "digest"
-  library "json"
-  library "logger"
-  library "net-http"
-  library "openai"
-  library "securerandom"
-  library "uri"
-  library "yaml"
-
-  configure_code_diagnostics(D::Ruby.strict)
+  configure_code_diagnostics(D::Ruby.all_error)
 end

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
 
@@ -265,7 +265,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-experimental) for details.
 
 ### guardrail
 
@@ -304,6 +304,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 +393,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. Passing a non-`Hash` raises `Riffer::ArgumentError`. 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 +425,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.

data/docs/AGENT_LIFECYCLE.md

@@ -315,6 +315,7 @@ 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                                                          |

data/docs/CONFIGURATION.md

@@ -184,7 +184,7 @@ end
 
 ### 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|

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.

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:
@@ -272,6 +276,29 @@ event.to_h               # => {role: :assistant, finish_reason: :length, raw_fin
 
 The agent loop stamps this value onto the accumulated assistant message's `finish_reason`.
 
+## Incomplete Streams
+
+If a provider's stream ends before its terminal event, the enumerator raises `Riffer::IncompleteStreamError` (a `Riffer::Error` subclass) instead of finishing normally, so a truncated or empty response is never returned as a complete message. Events already yielded before the raise were delivered as usual, but nothing from the failed step is added to the session: there is no partial assistant message to resume from, and messages from earlier completed steps (tool calls and their results) are untouched.
+
+Supported on Amazon Bedrock, Anthropic, and OpenAI / Azure OpenAI.
+
+The user prompt is added to the session before the run starts and stays there after the failure, so retry with `agent.stream` and no prompt. Passing the prompt again would add a second user turn.
+
+```ruby
+attempts = 0
+prompt = "Tell me a story"
+begin
+  agent.stream(prompt).each do |event|
+    print event.content if event.is_a?(Riffer::StreamEvents::TextDelta)
+  end
+rescue Riffer::IncompleteStreamError => e
+  warn "stream ended early: #{e.message}"
+  prompt = nil # already in the session; re-run on the existing history
+  retry if (attempts += 1) < 3
+  raise
+end
+```
+
 ## Streaming with Tools
 
 When an agent uses tools during streaming, the flow is:

data/docs/TRACING.md

@@ -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

@@ -171,7 +171,7 @@ end
 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")
@@ -274,6 +274,60 @@ For streaming, emit a `FinishReasonDone` event near the end of `execute_stream`:
 yielder << Riffer::StreamEvents::FinishReasonDone.new(finish_reason: :stop, raw_finish_reason: "done")
 ```
 
+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:
@@ -328,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: