riffer 0.31.0 → 0.32.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e3f857f2ab85b78d91685b84c1d239a0409291c6945f9cc7aae0b84a5dead2a6
-  data.tar.gz: 9ae3efd534a2b099de8268e0b0bc89e2c2682d6a7297ada4409a1056203cf9b3
+  metadata.gz: 0cddafa66f3f24980037c23be5e8584ec888b93c40b2b780c99e7205558d2593
+  data.tar.gz: 5aea2edfeb9d47a4246b15d3f4e16a7a3c1d7941a473355495267b9eb93bc3cc
 SHA512:
-  metadata.gz: bf1b4dbd17abdfb1873f48d7db5b4b13f6ebde5c7e0e40bad73d7e6ca96f51e0d10c1ed9fe50d8be4a0532bcde9d5eb0eebd3ee4d264b195dbbfa12d09e70f9a
-  data.tar.gz: 0226c06943e53b5386659917746d1cd256d83861ab340bd0377393d8a45310fd2da60dad090e15a4f6a23dfa1e865b4fdc84f3bd6c1e0df94eafdaf850e4b4ae
+  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.31.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,24 @@ 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)
 
 

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/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)

data/lib/riffer/agent/context.rb

@@ -1,38 +1,16 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Typed value object wrapping the runtime context Hash held by a
-# Riffer::Agent. Exposes first-class accessors for the framework-managed
-# entries — +skills+ and +token_usage+ — and preserves +#[]+ / +#dig+
-# reads so tools (which receive +context:+ as a keyword) keep working
-# with both built-in and caller-provided keys.
-#
-# Reserved keys (+:skills+, +:token_usage+) cannot be set by the caller
-# at construction; they are owned by Riffer and written through the typed
-# setters. Type invariants are enforced on write — +skills+ must be a
-# +Riffer::Skills::Context+ (or nil); +token_usage+ must be a
-# +Riffer::Providers::TokenUsage+ (or nil).
-#
-#   context = Riffer::Agent::Context.new(user_id: 42)
-#   context[:user_id]    # => 42
-#   context.skills       # => nil
-#   context.token_usage  # => nil
-#
+# Typed value object wrapping the runtime context Hash held by a Riffer::Agent.
+# Exposes typed +skills+, +token_usage+, +mcp_progressive_tools+, and
+# +discovered_tools+ accessors while preserving +#[]+ / +#dig+ for caller-provided keys.
 class Riffer::Agent::Context
   # @rbs @data: Hash[Symbol, untyped]
 
-  # Keys reserved for framework use. Passing any of these to the
-  # constructor raises +Riffer::ArgumentError+.
-  RESERVED_KEYS = [:skills, :token_usage].freeze #: Array[Symbol]
+  RESERVED_KEYS = [:skills, :token_usage, :mcp_progressive_tools, :discovered_tools].freeze #: Array[Symbol]
 
-  # Builds a new context.
-  #
-  # [data] caller-provided Hash passed as <tt>Agent.new(context:)</tt>.
-  #        Duped before storage so caller mutations do not affect the
-  #        agent. Must not contain any +RESERVED_KEYS+.
-  #
-  # Raises Riffer::ArgumentError when +data+ contains a reserved key.
-  #
+  # Builds a new context. The caller Hash is duped so later caller mutations
+  # don't leak in. Raises Riffer::ArgumentError if it contains a reserved key.
   #--
   #: (?Hash[Symbol, untyped]) -> void
   def initialize(data = {})
@@ -45,6 +23,8 @@ class Riffer::Agent::Context
     @data = data.dup
     @data[:skills] = nil
     @data[:token_usage] = nil
+    @data[:mcp_progressive_tools] = nil
+    @data[:discovered_tools] = nil
   end
 
   # The agent's resolved +Riffer::Skills::Context+, or +nil+ when skills
@@ -56,12 +36,8 @@ class Riffer::Agent::Context
     @data[:skills]
   end
 
-  # Sets the resolved skills context. Called once by +Riffer::Agent+
-  # during construction.
-  #
-  # Raises Riffer::ArgumentError if +value+ is neither +nil+ nor a
-  # +Riffer::Skills::Context+.
-  #
+  # Sets the resolved skills context. Raises Riffer::ArgumentError on an
+  # invalid value.
   #--
   #: (Riffer::Skills::Context?) -> Riffer::Skills::Context?
   def skills=(value)
@@ -81,12 +57,8 @@ class Riffer::Agent::Context
     @data[:token_usage]
   end
 
-  # Sets the cumulative token usage. Called by +Riffer::Agent::Run+ after
-  # each LLM response.
-  #
-  # Raises Riffer::ArgumentError if +value+ is neither +nil+ nor a
-  # +Riffer::Providers::TokenUsage+.
-  #
+  # Sets the cumulative token usage. Raises Riffer::ArgumentError on an invalid
+  # value.
   #--
   #: (Riffer::Providers::TokenUsage?) -> Riffer::Providers::TokenUsage?
   def token_usage=(value)
@@ -97,28 +69,76 @@ class Riffer::Agent::Context
     @data[:token_usage] = value
   end
 
-  # Hash-style read. Preserved so downstream tool runtimes pulling
-  # caller-provided keys via <tt>context[:agent]</tt> or
-  # <tt>context[:tenant]</tt> keep working unchanged.
-  #
+  # Hash-style read, preserved so tools can pull caller-provided keys via
+  # <tt>context[:agent]</tt>.
   #--
   #: (Symbol) -> untyped
   def [](key)
     @data[key]
   end
 
-  # Hash-style dig. Preserved for tools using
-  # <tt>context&.dig(:user_id)</tt>.
-  #
+  # Auth-wrapped MCP tool classes for progressive discovery, or +nil+.
+  #--
+  #: () -> Array[singleton(Riffer::Tool)]?
+  def mcp_progressive_tools
+    @data[:mcp_progressive_tools]
+  end
+
+  # Sets progressive MCP tools. Raises Riffer::ArgumentError on an invalid value.
+  #--
+  #: (Array[singleton(Riffer::Tool)]?) -> Array[singleton(Riffer::Tool)]?
+  def mcp_progressive_tools=(value)
+    valid = value.nil? || (
+      value.is_a?(Array) &&
+      value.all? { |tool| tool.is_a?(Class) && tool < Riffer::Tool }
+    )
+    unless valid
+      raise Riffer::ArgumentError,
+        "mcp_progressive_tools must be an Array of Riffer::Tool subclasses or nil, got #{value.class}"
+    end
+    @data[:mcp_progressive_tools] = value
+  end
+
+  # MCP tool classes discovered during progressive search. Accumulates across
+  # +generate+ calls and is merged into the active tool list on every LLM call.
+  #--
+  #: () -> Array[singleton(Riffer::Tool)]?
+  def discovered_tools
+    @data[:discovered_tools]
+  end
+
+  # Sets the discovered tools array. Raises Riffer::ArgumentError on an invalid value.
+  #--
+  #: (Array[singleton(Riffer::Tool)]?) -> Array[singleton(Riffer::Tool)]?
+  def discovered_tools=(value)
+    valid = value.nil? || (
+      value.is_a?(Array) &&
+      value.all? { |tool| tool.is_a?(Class) && tool < Riffer::Tool }
+    )
+    unless valid
+      raise Riffer::ArgumentError,
+        "discovered_tools must be an Array of Riffer::Tool subclasses or nil, got #{value.class}"
+    end
+    @data[:discovered_tools] = value
+  end
+
+  # Accumulates newly discovered MCP tool classes, deduplicating by name.
+  # Each call extends the existing set; calling multiple times is safe.
+  #--
+  #: (Array[singleton(Riffer::Tool)]) -> Array[singleton(Riffer::Tool)]
+  def discover_tools(tools)
+    existing = @data[:discovered_tools] || []
+    @data[:discovered_tools] = (existing + tools).uniq(&:name)
+  end
+
   #--
   #: (*Symbol) -> untyped
   def dig(*keys)
     @data.dig(*keys)
   end
 
-  # Returns a copy of the underlying Hash. Mutating the result does not
-  # affect this context.
-  #
+  # Returns a copy of the underlying Hash; mutating it does not affect this
+  # context.
   #--
   #: () -> Hash[Symbol, untyped]
   def to_h

data/lib/riffer/agent/response.rb

@@ -1,10 +1,8 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Wraps agent generation responses with optional tripwire information.
-#
-# When guardrails block execution, the response will contain a tripwire
-# with details about the block. The content will be empty for blocked responses.
+# Wraps an agent generation response. When a guardrail blocks execution,
+# +content+ is empty and +tripwire+ carries the block details.
 #
 #   response = agent.generate("Hello")
 #   if response.blocked?
@@ -33,24 +31,10 @@ class Riffer::Agent::Response
   # The full message history from the agent conversation.
   attr_reader :messages #: Array[Riffer::Messages::Base]
 
-  # Call ids of tool_use blocks that riffer filled with placeholder
-  # results during this turn — populated when an interrupt left them
-  # unanswered and +Riffer.config.experimental_history_healing+ is on.
-  # Empty otherwise.
+  # Call ids of tool_use blocks riffer filled with placeholder results this
+  # turn (when an interrupt left them unanswered and history healing is on).
   attr_reader :healed_tool_call_ids #: Array[String]
 
-  # Creates a new response.
-  #
-  # [content] the response content.
-  # [tripwire] optional tripwire for blocked responses.
-  # [modifications] guardrail modifications applied during processing.
-  # [interrupted] whether the agent loop was interrupted by a callback.
-  # [interrupt_reason] optional reason passed via <tt>throw :riffer_interrupt, reason</tt>.
-  # [structured_output] parsed structured output when structured output is configured.
-  # [messages] the full message history from the agent conversation.
-  # [healed_tool_call_ids] call ids filled with placeholder tool results
-  #   when history healing is enabled.
-  #
   #--
   #: (String, ?tripwire: Riffer::Guardrails::Tripwire?, ?modifications: Array[Riffer::Guardrails::Modification], ?interrupted: bool, ?interrupt_reason: (String | Symbol)?, ?structured_output: Hash[Symbol, untyped]?, ?messages: Array[Riffer::Messages::Base], ?healed_tool_call_ids: Array[String]) -> void
   def initialize(content, tripwire: nil, modifications: [], interrupted: false, interrupt_reason: nil, structured_output: nil, messages: [], healed_tool_call_ids: [])