riffer 0.30.0 → 0.32.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7557c63ca04fa006d66a61a53bef6b1f7069ebab67439f00104fbb877d1aceda
-  data.tar.gz: 39bbe45b7e111ae343e32c54b9769db17dd7d8d9b98cd5cb7d42338aa5e4179c
+  metadata.gz: 0cddafa66f3f24980037c23be5e8584ec888b93c40b2b780c99e7205558d2593
+  data.tar.gz: 5aea2edfeb9d47a4246b15d3f4e16a7a3c1d7941a473355495267b9eb93bc3cc
 SHA512:
-  metadata.gz: 61694198a05d63d831dca9b4b37e38b6cacbd7b67214fa47c2027a0a7e1636ee07e5f85641f9fe00ee597d66dfdb0a6fccd0e494b6ec670a84a2020907cfdd0b
-  data.tar.gz: fbff4457d39da36a1c77e9cb7ea86ccb5e96f0887ba982f6a8a960557ee4beceda3a604011fcfd20951f9baedd59eadbf188832cb6bcc8fcf71e256d93e8cdc3
+  metadata.gz: fad79dcfd8036c3249ea17be785cb6acb193e3a1677f23ee052c89daf39fe97840369a4718e65ebb515bbddeb866608a532b8076a89e2f6c724ddd74d2131e85
+  data.tar.gz: 0c7b1bdb7383c6f9a2b053d2d811a7c4aa29142f8a44aa3fd07071d88b0dac722268f036c9f45887bbf3b10591cb3067193540c2cff766d6ab91aa4644f0dcb8

data/.agents/code-style.md

@@ -24,11 +24,66 @@ class MyCustomError < Riffer::Error
 end
 ```
 
-## Comments
+## Comments & Documentation
 
-- Only add comments when the code is ambiguous or not semantically obvious
-- Explain **why** something is done, not **what** is being done
-- Comments should add value beyond what the code already expresses
+A comment exists to explain a **why** 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 RDoc descriptions on the public API. Types are not prose's job: parameters, return values, and attribute/constant types live in rbs-inline `#:` annotations (see [rbs-inline.md](rbs-inline.md)).
+
+**What's a comment (in scope):** RDoc descriptions and inline `#` explanations. **Not comments (never touched):** rbs-inline `#:` annotations, magic comments (`frozen_string_literal`, `rbs_inline`), and RDoc directives (`:nodoc:`, `:nocov:`).
+
+### Public surface
+
+Everything public — classes, modules, constants, attributes, public methods, and `protected` subclass-contract methods (e.g. the `pass` / `transform` / `block` helpers a custom `Riffer::Guardrail` calls) — gets **at minimum a very brief description**:
+
+- **One verb-first sentence, one line.** `Creates a new agent.`, `Serializes the definition to JSON.`
+- An optional **second sentence is reserved strictly for a "why"** — a non-obvious constraint or rationale the code can't convey. Never a second sentence of "how".
+- If a description needs more than one sentence to say _what_ it does, that's a smell the method does too much.
+- **Exempt:** a constant whose name and value already carry the full meaning (`VERSION = "0.30.0"`, `PHASES = %i[before after]`) — describe a constant only when its name doesn't; an empty namespace module (a Zeitwerk placeholder with no usable members of its own, e.g. `module Riffer::Messages; end`) — its children are documented individually; and a constructor (`initialize`) — the class doc and RDoc's `::new` already cover plain construction, so describe it only when it carries a contract or non-obvious construction behavior (a raise, a dup guard).
+
+Do not document parameters or return values in prose — the `#:` line is the single source of truth for types. Attributes and constants still carry a brief description on the line above their inline `#:`.
+
+```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
+```
+
+### Private methods
+
+A comment survives on a private method **only** if it explains a why a competent reader cannot recover from the code and names alone — a non-local constraint, an external-system quirk, a deliberate non-obvious tradeoff. A description of what it does, or a why that's evident from the code, gets cut.
+
+### Inline comments
+
+Same bar: kept only to explain the why of something genuinely ambiguous. `TODO` / `FIXME` / `HACK` markers are tracked work and stay; `NOTE` / `REVIEW` are subject to the why-rule.
+
+### No history
+
+A comment describes the present, never how the code got there. Change narration — "was X, now Y", "previously used Z" — has no place; the reader cares about what is, not what was. The one thing worth stating is a still-true constraint, and it belongs in the present tense ("the API returns null for empty results — guard"), never told as the story of the bug that revealed it.
+
+### RDoc mechanics
+
+**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.
+
+**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. Reserved for public methods. 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 — but keep the runtime constraints a type can't express (enum value sets, coercion rules, validation failure).
+
+```ruby
+# Builds a param from a schema hash.
+# Raises Riffer::ArgumentError if the schema is missing a +type+.
+```
+
+**Examples.** Include an example only when a **consumer is likely to use the thing themselves** — a public entry point they construct, subclass, or call (an `Agent` subclass, `Riffer::Mcp.register`, the `params` DSL). Skip examples on framework-internal types even though they're technically public (value objects the framework constructs and hands back, internal engines). When included, keep them sparing — only when they teach something the signature can't — 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>`, e.g. `Equivalent to <tt>throw :riffer_interrupt, reason</tt>`.
+
+**Internal APIs.** Mark with `:nodoc:` to exclude from generated documentation:
+
+```ruby
+def internal_method # :nodoc:
+end
+```
 
 ## Hash Key Convention
 
@@ -37,6 +92,10 @@ end
 - String keys are only used at serialization boundaries (JSON Schema output, external API payloads)
 - Do not write dual-access patterns like `hash[:key] || hash["key"]` — normalize to symbol keys at the boundary instead
 
+## Reserved Tool Identifiers
+
+- Internal-use-only tools use plain descriptive names without a prefix (e.g. `mcp_search`, `mcp_call`, `evaluation`, `skill_activate`)
+
 ## Module Structure
 
 ```ruby

data/.agents/rbs-inline.md

@@ -4,12 +4,7 @@ Type annotations are added directly in Ruby source files using [rbs-inline](http
 
 ## Magic Comment
 
-Every `lib/**/*.rb` file must include the `rbs_inline: enabled` comment on line 2:
-
-```ruby
-# frozen_string_literal: true
-# rbs_inline: enabled
-```
+rbs-inline only processes a file when `rbs_inline: enabled` is present on line 2. It ships as part of the required header on every `lib/**/*.rb` file — see [Required Header](code-style.md#required-header).
 
 ## Annotation Syntax
 

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.30.0"
+  ".": "0.32.0"
 }

data/AGENTS.md

@@ -14,8 +14,7 @@ Ruby gem framework for building AI-powered agents with LLM provider adapters.
 
 - [Architecture](.agents/architecture.md) - Core components and project structure
 - [Testing](.agents/testing.md) - Minitest spec DSL and VCR cassettes
-- [Code Style](.agents/code-style.md) - StandardRB and comment conventions
-- [RDoc](.agents/rdoc.md) - Documentation format for public APIs
+- [Code Style](.agents/code-style.md) - StandardRB, comment, and RDoc conventions
 - [Providers](.agents/providers.md) - Adding new LLM provider adapters
 - [RBS Inline](.agents/rbs-inline.md) - Type annotations with rbs-inline
 

data/CHANGELOG.md

@@ -5,6 +5,31 @@ 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.32.0](https://github.com/janeapp/riffer/compare/riffer/v0.31.0...riffer/v0.32.0) (2026-06-08)
+
+
+### ⚠ BREAKING CHANGES
+
+* `TokenUsage#cache_creation_tokens` is renamed to `cache_write_tokens` (also reflected in `TokenUsage#to_h`). Update any code reading that attribute or hash key.
+* apply module/class conventions consistently ([#298](https://github.com/janeapp/riffer/issues/298))
+
+### Features
+
+* add Bedrock prompt caching and surface cached tokens ([#300](https://github.com/janeapp/riffer/issues/300)) ([407390b](https://github.com/janeapp/riffer/commit/407390b505a3af6b881c5204d856a8e9ceddbed9))
+* add progressive discovery for MCP tools by default ([0a37485](https://github.com/janeapp/riffer/commit/0a37485dd59e08a0ba0ca8d1046e3313914f72a5))
+
+
+### Code Refactoring
+
+* apply module/class conventions consistently ([#298](https://github.com/janeapp/riffer/issues/298)) ([76a3131](https://github.com/janeapp/riffer/commit/76a3131f800ba026c07cc194ab2879279134e865))
+
+## [0.31.0](https://github.com/janeapp/riffer/compare/riffer/v0.30.0...riffer/v0.31.0) (2026-06-03)
+
+
+### Features
+
+* forward session: through Agent.from_h/from_json for history seeding ([#295](https://github.com/janeapp/riffer/issues/295)) ([0b2eaa2](https://github.com/janeapp/riffer/commit/0b2eaa27f5154bfd61891d4e93b8938f7dce2ce6))
+
 ## [0.30.0](https://github.com/janeapp/riffer/compare/riffer/v0.29.1...riffer/v0.30.0) (2026-06-03)
 
 

data/docs/08_MESSAGES.md

@@ -196,7 +196,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::Converter#convert_to_message_object` or your own adapter (e.g. jane's `to_riffer`).
+`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.
 
 ### Accessing Message History
 

data/docs/14_MCP.md

@@ -36,8 +36,9 @@ When **`Riffer.config.mcp.credentials`** is set to a Proc, each MCP `tools/call`
 ```ruby
 Riffer.configure do |config|
   config.mcp.credentials = lambda do |manifest:, matched_tags:, context:|
-    # return nil to omit this server's tools for this agent run (at resolve time)
-    # return Hash<String,String> headers for tools/call (e.g. Authorization)
+    # when caller does not have an integration, return nil to omit this server's tools for this run
+    # when server is unauthenticated or local, return {} to include this server's tools with no extra headers
+    # when authorization headers are required, return Hash<String,String> headers
   end
 end
 ```
@@ -46,9 +47,9 @@ end
 - **`matched_tags`** — intersection of the agent's `use_mcp` tags and `manifest.tags` for this registration (unioned across multiple `use_mcp` lines).
 - **`context`** — the same hash passed to `generate` / `stream` for this run.
 
-**Resolve time:** Before tools are exposed to the model, the proc is invoked once per matching registration. If it returns **`nil`**, that server's tools are omitted for this run (e.g. tenant has no integration).
+**Resolve time:** The proc is invoked once per matching registration before tools are exposed to the model.
 
-**Call time:** Authenticated tool wrappers invoke the proc again for each execution. If it returns **`nil`**, `Riffer::Mcp::CredentialsDeniedError` is raised.
+**Call time:** Authenticated tool wrappers invoke the proc again for each execution. If it returns `nil`, then `Riffer::Mcp::CredentialsDeniedError` is raised.
 
 If **`credentials` is unset**, discovery and `tools/call` share one client built from `discovery_headers` (same behaviour as a single static token for both list and call).
 
@@ -71,6 +72,8 @@ class ResearchAgent < Riffer::Agent
 end
 ```
 
+By default, `use_mcp` uses **progressive discovery**. The agent receives `mcp_search` rather than every schema up front. See [Progressive Tool Discovery](#progressive-tool-discovery).
+
 `use_mcp` accepts any tag registered via `Riffer::Mcp.register`. Multiple calls accumulate — the agent receives tools from all matching servers:
 
 ```ruby
@@ -90,6 +93,48 @@ Tool names must be unique across `uses_tools` and all included MCP servers; dupl
 
 Like [`uses_tools`](03_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.
+
+```ruby
+class ResearchAgent < Riffer::Agent
+  model "openai/gpt-4o"
+
+  use_mcp :github                        # default: tools discoverable on demand
+  use_mcp :jira, progressive: false      # opt-out: all Jira tools injected directly
+end
+```
+
+Only use `progressive: false` when the server has a small, stable set of tools you always want available.
+
+**`mcp_search`** — Search for available tools by name or description.
+- `query` (required, non-empty) — filter by name or description substring.
+
+On a successful search, matching tools are injected into the agent's active tool list. The model calls them natively on the next turn — no proxy or JSON-encoded arguments.
+
+**Example flow:**
+
+1. Agent starts — only `mcp_search` appears in the tool list.
+2. LLM calls `mcp_search` with `query: "create pull request"`.
+3. Riffer injects `github__create_pr` into the active tool list and returns an acknowledgment.
+4. LLM calls `github__create_pr` directly with its real schema (e.g. `title:`, `body:`, `base:`).
+5. The provider validates the arguments; the tool executes with all credential handling intact.
+
+Injected tools accumulate across turns — tools discovered in one search remain available for subsequent calls without re-searching.
+
+**Multiple progressive `use_mcp` calls:** All matching registrations are combined into one `mcp_search`:
+
+```ruby
+use_mcp :connectors_a   # both default to progressive
+use_mcp :connectors_b
+# → one mcp_search exposing tools from both registrations
+```
+
+**Credential handling:** Progressive tools follow the same credential rules as regular tools — see [Session credentials callback](#session-credentials-callback).
+
+**Tool access in tools:** The full discovery pool is available via `context[:mcp_progressive_tools]` and injected tools via `context[:injected_tools]` (both `Array[Riffer::Tool subclass]`). These keys are framework-managed — treat them as read-only from application code.
+
 ## Unregistering a Server
 
 ```ruby
@@ -130,7 +175,7 @@ All inherit from `Riffer::Mcp::Error < Riffer::Error`.
 
 - **Tool results:** `tools/call` responses are reduced to joined **text** content from MCP `content` items. Non-text parts (e.g. images, embedded resources) are not surfaced in this release.
 - **Session credentials:** When `Riffer.config.mcp.credentials` is set, authenticated tool wrappers may build a **new HTTP client per tool invocation** so headers stay fresh; there is no connection pooling in this release.
-- **Context window / progressive disclosure:** Discovery registers **all** tools from each server; matching agents see the full set in one shot. There is no built-in lazy listing or prompt-size budgeting yet. Tighter control may require application-level filtering, MCP server design, or future Riffer APIs.
+- **Context window / progressive disclosure:** `use_mcp` defaults to progressive mode — tools are discovered via `mcp_search` and injected natively for subsequent calls. Use `progressive: false` to inject all schemas directly. See [Progressive Tool Discovery](#progressive-tool-discovery).
 
 ## Requirements
 

data/docs/15_SERIALIZATION.md

@@ -1,28 +1,39 @@
 # Serialization
 
-`Riffer::Agent::Serializer` turns a **resolved agent** into a self-contained, provider-neutral data dict (`to_h`) and reconstructs a **runnable agent** from that dict (`from_h`). Use it to persist agent definitions outside of code, or to transfer them across a process/service boundary.
+`Riffer::Agent::Serializer` turns a **resolved agent** into a self-contained, provider-neutral data hash (`to_h`) and reconstructs a **runnable agent** from that hash (`from_h`). Use it to persist agent definitions outside of code, or to transfer them across a process/service boundary.
 
 You normally reach it through the delegators on `Riffer::Agent`:
 
 ```ruby
-dict    = agent.to_h          # snapshot
-rebuilt = Riffer::Agent.from_h(dict) # reconstruct
+data    = agent.to_h          # snapshot
+rebuilt = Riffer::Agent.from_h(data) # reconstruct
 ```
 
-The dict is plain data — symbol-keyed, JSON-safe. For the wire, use the JSON helpers, which handle generating and parsing for you:
+The hash is plain data — symbol-keyed, JSON-safe. For the wire, use the JSON helpers, which handle generating and parsing for you:
 
 ```ruby
 json    = agent.to_json       # or Riffer::Agent::Serializer.to_json(agent:)
 rebuilt = Riffer::Agent.from_json(json)
 ```
 
-The hash forms (`to_h` / `from_h`) are public too, if you want to embed the dict in a larger payload. `from_h` expects symbol keys, so parse with `JSON.parse(str, symbolize_names: true)` — or just use `from_json`, which does that for you.
+The hash forms (`to_h` / `from_h`) are public too, if you want to embed the hash in a larger payload. `from_h` expects symbol keys, so parse with `JSON.parse(str, symbolize_names: true)` — or just use `from_json`, which does that for you.
 
 ### Runtime context
 
 `from_h` / `from_json` accept an optional `context:` — the rebuilt agent's **runtime** context, exactly the value you'd pass to `Agent.new(context:)`. It is **not** used to re-resolve the serialized definition (that's already resolved); it's threaded into tool dispatch and read by tools/runtimes at call time. Pass it when a tool or a remote runtime needs per-call data — e.g. `context: { tenant: "acme" }` for multi-tenant dispatch, or Maestro passing `context: { agent: self }` so its runtime can call back. Omit it (defaults to empty) when nothing downstream reads context.
 
-## What the dict carries
+### Seeding conversation history
+
+The hash carries the agent **definition**, not its conversation history (see [What does not transfer](#what-does-not-transfer)). To resume a persisted conversation, pass a `session:` — exactly the value you'd pass to `Agent.new(session:)`:
+
+```ruby
+rebuilt = Riffer::Agent.from_h(data, session: persisted_session)
+rebuilt.generate # continues from the seeded history
+```
+
+The session is used **as-is**: the rebuilt agent does not prepend anything to it, so the caller owns its full contents — **including the system instruction message**. Omit `session:` and the rebuilt agent builds a fresh session, seeded with the hash's `instructions` and an empty history. Because a supplied session is authoritative, the hash's `instructions` are not re-injected into it — make sure your persisted session already contains the system message.
+
+## What the hash carries
 
 ```ruby
 {
@@ -41,7 +52,7 @@ The hash forms (`to_h` / `from_h`) are public too, if you want to embed the dict
 
 ### Resolved snapshot
 
-`to_h` reads the agent's **resolved** state, not its raw configuration. By the time you call it, `Agent.new` has already evaluated any `Proc`-based `model`, `instructions`, or `uses_tools` against the agent's own context — so the dict carries plain strings and data, never Procs. The receiver's `context:` drives runtime behavior (tool dispatch); it does **not** re-evaluate baked-in fields.
+`to_h` reads the agent's **resolved** state, not its raw configuration. By the time you call it, `Agent.new` has already evaluated any `Proc`-based `model`, `instructions`, or `uses_tools` against the agent's own context — so the hash carries plain strings and data, never Procs. The receiver's `context:` drives runtime behavior (tool dispatch); it does **not** re-evaluate baked-in fields.
 
 ### Structured output
 
@@ -56,7 +67,7 @@ Tools cross as `{name, description, parameters_schema, timeout}` descriptors —
 When the rebuilt agent runs in the **same** codebase that defined the tools (e.g. persisting an agent definition and rehydrating it later), resolve each descriptor back to its real class:
 
 ```ruby
-rebuilt = Riffer::Agent.from_h(dict,
+rebuilt = Riffer::Agent.from_h(data,
   tool_resolver: ->(descriptor) { MyToolRegistry.fetch(descriptor[:name]) })
 ```
 
@@ -67,7 +78,7 @@ The real classes carry their `#call` bodies, so the agent runs on the default `I
 When the receiver holds **only the Riffer gem**, the default `tool_resolver` synthesizes body-less **tool shells**. A shell advertises the tool's schema to the LLM but has no `#call` — invoking it in-process raises. Pair the default resolver with a remote `Riffer::Tools::Runtime` that forwards each call back to the origin:
 
 ```ruby
-rebuilt = Riffer::Agent.from_h(dict,
+rebuilt = Riffer::Agent.from_h(data,
   tool_runtime: MyRemoteToolRuntime.new(client: rpc_client))
 ```
 
@@ -77,12 +88,12 @@ You own what a resolved tool does: a resolver may return real in-process classes
 
 ## `max_steps`
 
-Unlimited steps are `nil` at the agent level — set it with `max_steps nil`. On the wire, the serializer encodes that as **`-1`** (and decodes `-1` back to `nil`), so the dict stays portable across transports where JSON `null` is awkward — proto3, for one, can't distinguish `null` from an absent field. The `-1` is purely a wire detail: the DSL and your code only ever see `nil`, and the encode/decode handles the translation at the boundary.
+Unlimited steps are `nil` at the agent level — set it with `max_steps nil`. On the wire, the serializer encodes that as **`-1`** (and decodes `-1` back to `nil`), so the hash stays portable across transports where JSON `null` is awkward — proto3, for one, can't distinguish `null` from an absent field. The `-1` is purely a wire detail: the DSL and your code only ever see `nil`, and the encode/decode handles the translation at the boundary.
 
 - **DSL** — integer = bounded, `nil` = unlimited, omitted = `Config`'s default (16).
 - **Wire** — integer = bounded, `-1` = unlimited, omitted = default (16).
 
-A finite integer round-trips as-is; a dict missing the key falls back to the default rather than running unbounded.
+A finite integer round-trips as-is; a hash missing the key falls back to the default rather than running unbounded.
 
 ## Versioning
 
@@ -90,7 +101,7 @@ A finite integer round-trips as-is; a dict missing the key falls back to the def
 
 ## Secrets
 
-`provider_options` and `model_options` **ride on the wire as plain data** — they are part of the dict and _will_ transfer. Prefer configuring API keys via environment/global provider configuration rather than `provider_options`. **Never serialize an agent whose options carry sensitive values** — and if a serialized definition ever does, handle it as a secret (encrypt it, keep it out of logs).
+`provider_options` and `model_options` **ride on the wire as plain data** — they are part of the hash and _will_ transfer. Prefer configuring API keys via environment/global provider configuration rather than `provider_options`. **Never serialize an agent whose options carry sensitive values** — and if a serialized definition ever does, handle it as a secret (encrypt it, keep it out of logs).
 
 ## What does **not** transfer
 

data/docs/providers/02_AMAZON_BEDROCK.md

@@ -83,6 +83,20 @@ model_options additional_model_request_fields: {
 }
 ```
 
+### cache_control
+
+Enable prompt caching for models that support it (Claude, Nova). Riffer appends a single Converse `cachePoint` to the stable prefix — after the system array, or after the tools when there is no system prompt — so system instructions and tool definitions are reused across the calls in an agent loop and across conversation turns. The volatile message tail is never cached.
+
+```ruby
+# 5-minute TTL (default)
+model_options cache_control: {type: "ephemeral"}
+
+# 1-hour TTL (model-dependent; Bedrock validates support)
+model_options cache_control: {type: "ephemeral", ttl: "1h"}
+```
+
+Caching is opt-in: omit `cache_control` and no cachePoint is sent. The breakpoint is only honored once the prefix clears the model's minimum token count; on models that don't support `cachePoint`, the Converse request errors. Verify hits via `response.token_usage.cache_read_tokens`.
+
 ## Example
 
 ```ruby

data/lib/riffer/agent/config.rb

@@ -2,38 +2,49 @@
 # rbs_inline: enabled
 
 # Typed configuration object holding every class-level DSL setting on a
-# Riffer::Agent subclass.
-#
-# Each subclass of Riffer::Agent owns one Config, accessible via the class
-# method <tt>config</tt>. The class-level DSL (+model+, +instructions+, +uses_tools+,
-# etc.) reads and mutates this Config in place. Append-style DSL methods
-# (+use_mcp+, +guardrail+) are handled by the +add_mcp+ and +add_guardrail+
-# helpers below.
-#
-# Config stores Procs unresolved. Per-instance resolution happens elsewhere
-# (instructions, model, tools, tool runtime, skills).
+# 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?
+
+  # The configured model.
   attr_reader :model #: (String | Proc)?
+
+  # The configured instructions.
   attr_reader :instructions #: (String | Proc)?
+
+  # Options passed to the provider client.
   attr_accessor :provider_options #: Hash[Symbol, untyped]
+
+  # Options passed to generate_text/stream_text.
   attr_accessor :model_options #: Hash[Symbol, untyped]
+
+  # The configured structured-output schema.
   attr_reader :structured_output #: Riffer::Params?
+
+  # The maximum number of LLM call steps in the tool-use loop.
   attr_accessor :max_steps #: Numeric?
+
+  # The configured tools.
   attr_accessor :tools_config #: (Array[singleton(Riffer::Tool)] | Proc)?
+
+  # The accumulated +use_mcp+ tag configurations.
   attr_reader :mcp_configs #: Array[Hash[Symbol, untyped]]
+
+  # The configured tool runtime.
   attr_reader :tool_runtime #: (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)
+
+  # The configured skills.
   attr_accessor :skills_config #: Riffer::Skills::Config?
+
+  # Registered guardrail entries keyed by phase.
   attr_reader :guardrails #: Hash[Symbol, Array[Hash[Symbol, untyped]]]
 
-  # Builds a new Config. All fields are optional; unset fields take the
-  # documented defaults.
-  #
-  # Raises Riffer::ArgumentError if +model+ or +instructions+ is provided
-  # as a non-String, non-Proc value (or as an empty String).
-  #
+  # Builds a new Config. Raises Riffer::ArgumentError if +model+ or
+  # +instructions+ is invalid (e.g. an empty string).
   #--
   #: (?identifier: String?, ?model: (String | Proc)?, ?instructions: (String | Proc)?, ?provider_options: Hash[Symbol, untyped], ?model_options: Hash[Symbol, untyped], ?structured_output: Riffer::Params?, ?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), ?skills_config: Riffer::Skills::Config?, ?guardrails: Hash[Symbol, Array[Hash[Symbol, untyped]]]) -> void
   def initialize(
@@ -64,18 +75,14 @@ class Riffer::Agent::Config
     self.tool_runtime = tool_runtime
   end
 
-  # Sets +identifier+. Accepts +nil+ or any value, coerced to String.
-  #
+  # Sets +identifier+, coercing the value to String.
   #--
   #: (untyped) -> String?
   def identifier=(value)
     @identifier = value&.to_s
   end
 
-  # Sets +structured_output+. Accepts a Riffer::Params instance or +nil+.
-  #
-  # Raises Riffer::ArgumentError on any other type.
-  #
+  # Sets +structured_output+. Raises Riffer::ArgumentError on an invalid value.
   #--
   #: (Riffer::Params?) -> Riffer::Params?
   def structured_output=(value)
@@ -83,11 +90,7 @@ class Riffer::Agent::Config
     @structured_output = value
   end
 
-  # Sets +tool_runtime+. Accepts a Riffer::Tools::Runtime subclass, a
-  # Riffer::Tools::Runtime instance, or a Proc.
-  #
-  # Raises Riffer::ArgumentError on any other type.
-  #
+  # Sets +tool_runtime+. Raises Riffer::ArgumentError on an invalid value.
   #--
   #: ((singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)) -> (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)
   def tool_runtime=(value)
@@ -96,10 +99,8 @@ class Riffer::Agent::Config
     @tool_runtime = value
   end
 
-  # Sets +model+. Accepts a String ("provider/model"), a Proc, or +nil+.
-  #
-  # Raises Riffer::ArgumentError on non-String, non-Proc, or empty-String values.
-  #
+  # Sets +model+. Raises Riffer::ArgumentError on an invalid value (e.g. an
+  # empty string).
   #--
   #: ((String | Proc)?) -> (String | Proc)?
   def model=(value)
@@ -107,10 +108,8 @@ class Riffer::Agent::Config
     @model = value
   end
 
-  # Sets +instructions+. Accepts a String, a Proc, or +nil+.
-  #
-  # Raises Riffer::ArgumentError on non-String, non-Proc, or empty-String values.
-  #
+  # Sets +instructions+. Raises Riffer::ArgumentError on an invalid value (e.g.
+  # an empty string).
   #--
   #: ((String | Proc)?) -> (String | Proc)?
   def instructions=(value)
@@ -121,20 +120,15 @@ class Riffer::Agent::Config
   # Appends an MCP tag entry to +mcp_configs+.
   #
   #--
-  #: (String | Symbol) -> Array[Hash[Symbol, untyped]]
-  def add_mcp(tag)
-    @mcp_configs << {tags: [tag.to_sym]}
+  #: (String | Symbol, ?progressive: bool) -> Array[Hash[Symbol, untyped]]
+  def add_mcp(tag, progressive: true)
+    raise Riffer::ArgumentError, "progressive must be a boolean" unless progressive == true || progressive == false
+    @mcp_configs << {tags: [tag.to_sym], progressive: progressive}
   end
 
-  # Appends a guardrail entry to +guardrails+ for the given phase.
-  #
-  # [phase] +:before+, +:after+, or +:around+. +:around+ appends to both
-  #   +:before+ and +:after+.
-  # [klass] the Riffer::Guardrail subclass to register.
-  # [options] options forwarded to the guardrail at runtime.
-  #
-  # Raises Riffer::ArgumentError on an invalid phase or non-Guardrail class.
-  #
+  # 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: {})
@@ -164,6 +158,7 @@ class Riffer::Agent::Config
 
   private
 
+  #--
   #: (untyped, String) -> void
   def validate_string_or_proc!(value, name)
     return if value.nil? || value.is_a?(Proc)