riffer 0.40.0 → 0.42.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6c89776aeb032fbf837df103366fed830edcc20769cc9d4958a3a9bfa56a7803
-  data.tar.gz: 2153cf2967b9b70366987aeb9e59b215ff641bcd44668525c07d822ff9757579
+  metadata.gz: eabed1a1a6844787d92f31be0a72e210117005c19b4dd5e021a905121f83e8e1
+  data.tar.gz: 4cc6b6bde7e4b474d7ca6fb2672a3e115d4584b096f1de5d967a2b1a751f49ba
 SHA512:
-  metadata.gz: edfb2a10f17e1c0f6fb0630f5c2244370e01c5f32d05e9f065183da0b5b2d2cfec2453cac9a08714bd921716cd747609e4db61fb105a57769d79ab2f8988356a
-  data.tar.gz: 7d6dcdbab4be152033fcf75581252d3c9bda60c9e49825e75028d19670bae0490087ee8a90267a2af2f4fd8daabb5f370c8c2b7bb7cdcffe77a75b94a6b190ff
+  metadata.gz: 220febe23864053fa767e3eecc6850dc0c25ebdcb363a86d5daa58cd317c5500d08f2b50f499f133a77d7b4cf5182485c6faf0ddf36550099b22b7dd203af0c6
+  data.tar.gz: d231a4b0dc8c0468f4cba1abf9e3ace390852efc4b6adf5c23229c6729d4ad71fb0afdd5ae5b50540a188b79ec519ef58f95972357fb9854398570d0de058781

data/{AGENTS.md → .claude/CLAUDE.md}

@@ -10,14 +10,6 @@ Ruby gem framework for building AI-powered agents with LLM provider adapters.
 - **Model format**: `provider/model` (e.g., `openai/gpt-4`)
 - **Docs**: when adding a public config option or message attribute, update the matching page in `docs/` (e.g., `docs/CONFIGURATION.md`, `docs/MESSAGES.md`). Adding a NEW page under `docs/` also requires a `docs-site/manifest.yml` entry — the site build fails without one. RDoc ≠ user docs.
 
-## Topic Guides
-
-- [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) - RuboCop, comment, and RDoc conventions
-- [Providers](.agents/providers.md) - Adding new LLM provider adapters
-- [RBS Inline](.agents/rbs-inline.md) - Type annotations with rbs-inline
-
 ## Commands
 
 All wrappers `exec bundle exec …` under the hood.

data/.claude/rules/comments.md

@@ -0,0 +1,13 @@
+---
+paths: ["**/*.rb", "**/*.rake", "**/Gemfile"]
+---
+
+# Comments
+
+A comment exists to explain a **why** when the code itself cannot — never a **how**, and never a restatement of what the code already says. This bar governs all prose, from inline comments to docstrings.
+
+- **Internal and private code** — everything in an application, plus a library's non-exported internals — is self-documenting via clear names and strong types. A comment survives only when it explains something a competent reader cannot recover from the code alone: a non-local constraint, an external-system quirk, a deliberate non-obvious tradeoff. A description of _what_ the code does, or a why that's evident from reading it, gets cut.
+- **A published library's public surface** gets one verb-first sentence per exported symbol ("Serializes the definition to JSON."). An optional second sentence is reserved strictly for a why — a non-obvious constraint or rationale — never a second sentence of how. Needing more than one sentence to say _what_ it does is a smell the symbol does too much.
+- **Types are not prose's job.** Parameters, return values, and field types live in the type system (TypeScript types, rbs-inline `#:` annotations) — never restated in comments that duplicate them.
+- **Markers.** `TODO` / `FIXME` / `HACK` are tracked work and stay; `NOTE` / `REVIEW` meet the same why-bar as any other comment.
+- **No history.** A comment describes the present, never how the code got there — no "was X, now Y", no story of the bug that revealed a constraint. State a still-true constraint in the present tense ("the API returns null for empty results — guard").

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

@@ -0,0 +1,93 @@
+---
+paths: ["lib/**/*.rb", "sig/**/*"]
+---
+
+# RBS Inline
+
+Type annotations are added directly in Ruby source files using [rbs-inline](https://github.com/soutaro/rbs-inline).
+
+## Required Header
+
+Every `lib/**/*.rb` file starts with the two-line header `# frozen_string_literal: true` + `# rbs_inline: enabled` — rbs-inline silently skips any file missing the magic comment on line 2.
+
+## Annotation Conventions
+
+The **`#:`** prefix is used — standalone lines above methods (RBS method signatures) or inline on the same line (attributes, constants).
+
+`# @rbs` is used **only** for ivar declarations; everything else uses `#:`. The `#:` shorthand on an assignment is a Steep _assertion_ — it types the expression but does **not declare the ivar**. To declare an ivar's type, use a `# @rbs` comment inside the class body:
+
+```ruby
+class Riffer::Agent::Session
+  # @rbs @callbacks: Array[^(Riffer::Messages::Base) -> void]   # instance ivar
+end
+
+module Riffer
+  # @rbs self.@config: Riffer::Config?                          # class/module-level ivar
+end
+```
+
+## RDoc Conventions
+
+**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.
+
+```ruby
+# Serializes the agent definition to a transferable JSON payload.
+#--
+#: (Riffer::Agent) -> String
+def serialize(agent)
+
+# The agent's display name.
+attr_reader :name #: String
+```
+
+**Raises.** Document a raise **only when it's part of the caller's contract** — something a caller should reasonably anticipate and handle. Skip programmer-error guards and "should never happen" assertions. When the raise condition merely restates the declared `#:` type, phrase it by intent ("Raises Riffer::ArgumentError on an invalid value") rather than re-listing the type union.
+
+**Examples.** Include an example only when a **consumer is likely to use the thing themselves** — a public entry point they construct, subclass, or call. Keep them sparing and write them as indented code blocks (2 extra spaces of indent). Usage walkthroughs belong in `docs/`.
+
+**Inline code formatting.** Use `+word+` for single-word inline code; for multi-word expressions (spaces, colons, brackets) use `<tt>multi word expression</tt>`.
+
+**Internal APIs.** Mark with `# :nodoc:` to exclude from generated documentation.
+
+## Optional-dependency types (consumer-safe signatures)
+
+`sig/generated/` ships with the gem and is loaded by downstream projects (`rbs collection` / `rbs -r riffer`). rbs-inline copies a method's `#:` signature **verbatim** into the shipped sig, so **never name an optional-dependency type in a `#:` signature** — `OpenAI::*`, `Anthropic::*`, `Aws::*`, `MCP::*`, `Async::*`, `Zeitwerk::*`, etc. A consumer who installs riffer without that gem would hit `Cannot find type`, because those providers are pluggable and the gems ship no usable RBS of their own.
+
+**Workaround — assert the type inside the method body instead.** An inline assertion (`local = arg #: OpenAI::Models::…`) is a Steep-only hint that rbs-inline does **not** emit into the signature. Leave the SDK param/return `untyped` in the `#:` line, keep every riffer/stdlib param and return typed, and recover the SDK type with a body assertion:
+
+```ruby
+#: (untyped) -> String
+def extract_content(response)
+  message = response #: Anthropic::Models::Message
+  message.content&.first&.text || ""        # fully type-checked against the SDK type
+end
+
+#: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+def handle_stream_chunk(chunk, state:, yielder:)
+  typed = chunk #: OpenAI::Models::Chat::ChatCompletionChunk
+  # ...
+end
+
+# When the return value IS the SDK object, type the return `untyped` (no body assertion needed):
+#: (Hash[Symbol, untyped]) -> untyped
+def execute_generate(params)
+  @client.messages.create(**params)
+end
+```
+
+`test/shipped_signatures_test.rb` enforces this — it fails if any optional-dependency type appears in `sig/generated/` or `sig/manual/`.
+
+### 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).
+- `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.
+
+## Workflow
+
+After changing type annotations:
+
+1. Run `bin/rbs` to regenerate `sig/generated/` files
+2. Commit both the source changes and the generated `.rbs` files
+3. CI checks for drift between source annotations and committed `.rbs` files
+
+Use `bin/rbs-watch` during development to auto-regenerate on file changes.

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.40.0"
+  ".": "0.42.0"
 }

data/CHANGELOG.md

@@ -5,6 +5,28 @@ 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.42.0](https://github.com/janeapp/riffer/compare/riffer/v0.41.0...riffer/v0.42.0) (2026-08-25)
+
+
+### ⚠ BREAKING CHANGES
+
+* duplicate identifiers among named direct subclasses of Riffer::Tool or Riffer::Agent now raise Riffer::DuplicateIdentifierError on lookup. Agent.find/.all (and the new Tool.find/.all) cover named direct subclasses only - anonymous classes are excluded even with an explicit identifier. Riffer::Helpers::ClassNameConverter is removed; use Riffer::Helpers::Identifier.derive (the separator: keyword is dropped).
+
+### Features
+
+* one identifier registry pattern for tools and agents ([#406](https://github.com/janeapp/riffer/issues/406)) ([72fa7d6](https://github.com/janeapp/riffer/commit/72fa7d6377f903e4a88f9f5ec0e27e51b46dc293))
+
+## [0.41.0](https://github.com/janeapp/riffer/compare/riffer/v0.40.0...riffer/v0.41.0) (2026-08-14)
+
+
+### ⚠ BREAKING CHANGES
+
+* Inference providers no longer support extra configuration parameters (e.g. timeouts). Instead, a provider client object can be defined in the riffer config directly. Credential and endpoint parameters are still supported.
+
+### Features
+
+* config-injected provider clients, retire provider_options ([#391](https://github.com/janeapp/riffer/issues/391)) ([72fa0e3](https://github.com/janeapp/riffer/commit/72fa0e32ff6cfeee29bae9e2618d001cbc387d99))
+
 ## [0.40.0](https://github.com/janeapp/riffer/compare/riffer/v0.39.0...riffer/v0.40.0) (2026-08-12)
 
 

data/README.md

@@ -45,31 +45,31 @@ puts agent.generate('Hello world')
 
 ## Documentation
 
-Comprehensive guides live at [docs.riffer.ai](https://docs.riffer.ai):
-
-- [Overview](https://docs.riffer.ai/guides/overview/) - Core concepts and architecture
-- [Getting Started](https://docs.riffer.ai/guides/getting-started/) - Installation and first steps
-- [Agents](https://docs.riffer.ai/guides/agents/) - Defining and configuring agents
-- [Agent Lifecycle](https://docs.riffer.ai/guides/agent-lifecycle/) - Generate, stream, and responses
-- [Agent Loop](https://docs.riffer.ai/guides/agent-loop/) - Tool execution flow and stopping
-- [Tools](https://docs.riffer.ai/guides/tools/) - Creating tools for agents
-- [Advanced Tools](https://docs.riffer.ai/guides/advanced-tools/) - Timeouts, runtime, and registration
-- [Messages](https://docs.riffer.ai/guides/messages/) - Message types and formats
-- [Stream Events](https://docs.riffer.ai/guides/stream-events/) - Streaming responses
-- [Configuration](https://docs.riffer.ai/guides/configuration/) - Framework configuration
-- [Evals](https://docs.riffer.ai/guides/evals/) - Evaluating agent quality
-- [Guardrails](https://docs.riffer.ai/guides/guardrails/) - Input/output validation
-- [Skills](https://docs.riffer.ai/guides/skills/) - Packaged agent capabilities
-- [MCP](https://docs.riffer.ai/guides/mcp/) - Integrating third-party MCP servers
-- [Serialization](https://docs.riffer.ai/guides/serialization/) - Persisting and transferring agent definitions
-- [Tracing](https://docs.riffer.ai/guides/tracing/) - OpenTelemetry span contract and host wiring
-- [Providers](https://docs.riffer.ai/guides/providers/overview/) - LLM provider adapters
+Comprehensive guides live at [riffer.ai](https://riffer.ai):
+
+- [Overview](https://riffer.ai/guides/overview/) - Core concepts and architecture
+- [Getting Started](https://riffer.ai/guides/getting-started/) - Installation and first steps
+- [Agents](https://riffer.ai/guides/agents/) - Defining and configuring agents
+- [Agent Lifecycle](https://riffer.ai/guides/agent-lifecycle/) - Generate, stream, and responses
+- [Agent Loop](https://riffer.ai/guides/agent-loop/) - Tool execution flow and stopping
+- [Tools](https://riffer.ai/guides/tools/) - Creating tools for agents
+- [Advanced Tools](https://riffer.ai/guides/advanced-tools/) - Timeouts, runtime, and registration
+- [Messages](https://riffer.ai/guides/messages/) - Message types and formats
+- [Stream Events](https://riffer.ai/guides/stream-events/) - Streaming responses
+- [Configuration](https://riffer.ai/guides/configuration/) - Framework configuration
+- [Evals](https://riffer.ai/guides/evals/) - Evaluating agent quality
+- [Guardrails](https://riffer.ai/guides/guardrails/) - Input/output validation
+- [Skills](https://riffer.ai/guides/skills/) - Packaged agent capabilities
+- [MCP](https://riffer.ai/guides/mcp/) - Integrating third-party MCP servers
+- [Serialization](https://riffer.ai/guides/serialization/) - Persisting and transferring agent definitions
+- [Tracing](https://riffer.ai/guides/tracing/) - OpenTelemetry span contract and host wiring
+- [Providers](https://riffer.ai/guides/providers/overview/) - LLM provider adapters
 
 The guide sources are in the [docs](docs/) directory.
 
 ### API Reference
 
-The full API reference is published at [docs.riffer.ai/api](https://docs.riffer.ai/api/). Preview the site locally with:
+The full API reference is published at [riffer.ai/api](https://riffer.ai/api/). Preview the site locally with:
 
 ```bash
 bin/rake docs:serve
@@ -140,7 +140,3 @@ All notable changes to this project are documented in `CHANGELOG.md`.
 ## License
 
 Licensed under the MIT License. See `LICENSE.txt` for details.
-
-## Maintainers
-
-- Jake Bottrall - https://github.com/bottrall

data/docs/AGENTS.md

@@ -128,17 +128,6 @@ end
 
 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.
 
-### provider_options
-
-Passes options to the provider client:
-
-```ruby
-class MyAgent < Riffer::Agent
-  model 'openai/gpt-5-mini'
-  provider_options api_key: ENV['CUSTOM_OPENAI_KEY']
-end
-```
-
 ### model_options
 
 Passes options to each LLM request:
@@ -317,6 +306,27 @@ agent.generate('Hello')
 
 When `config:` is supplied, the class-level configuration is ignored for that instance.
 
+## Looking Up Agents
+
+Look up an agent by identifier with `Riffer::Agent.find`, or list every agent with `Riffer::Agent.all`:
+
+```ruby
+class SupportAgent < Riffer::Agent
+  model 'openai/gpt-5-mini'
+end
+
+Riffer::Agent.find('support_agent')   # => SupportAgent
+Riffer::Agent.find(:support_agent)    # symbols work too
+Riffer::Agent.find('missing')         # => nil
+Riffer::Agent.all                     # => [SupportAgent, ...]
+```
+
+Only **named direct subclasses** are found:
+
+- Grandchildren are not visible to a grandparent's `find` or `all`. If your app defines an intermediate base class (`class ApplicationAgent < Riffer::Agent`), call `find`/`all` on the intermediate class to look up its subclasses.
+- Anonymous classes (`Class.new(Riffer::Agent)`) are never findable, even when they set an explicit `identifier`.
+- Two subclasses sharing an identifier raise `Riffer::DuplicateIdentifierError` at the first lookup.
+
 ## Per-Call Tags
 
 `#generate` and `#stream` accept an optional `tags:` hash — a flat map of attribution labels scoped to that single call (for cost/usage attribution, filtering audit logs, slicing telemetry). It is **per-call only**.
@@ -359,10 +369,10 @@ Riffer does not validate tag count, key/value length, or charset — it forwards
 
 ## Expand Your Agent
 
-| Goal                          | Feature           | Guide                                                                |
-| ----------------------------- | ----------------- | -------------------------------------------------------------------- |
+| Goal                          | Feature           | Guide                                                             |
+| ----------------------------- | ----------------- | ----------------------------------------------------------------- |
 | Call APIs or run functions    | Tools             | [Tools](TOOLS.md)                                                 |
-| Return structured JSON        | Structured Output | [structured_output](#structured_output)                              |
+| Return structured JSON        | Structured Output | [structured_output](#structured_output)                           |
 | Validate or filter content    | Guardrails        | [Guardrails](GUARDRAILS.md)                                       |
 | Measure output quality        | Evals             | [Evals](EVALS.md)                                                 |
 | Add packaged capabilities     | Skills            | [Skills](SKILLS.md)                                               |

data/docs/AGENT_LIFECYCLE.md

@@ -347,7 +347,7 @@ See [Messages — Structured Output on Messages](MESSAGES.md#structured-output-o
 
 ### find
 
-Find an agent class by identifier:
+Find an agent class by identifier (named direct subclasses only — see [Agents — Looking Up Agents](AGENTS.md#looking-up-agents)):
 
 ```ruby
 agent_class = Riffer::Agent.find('my_agent')
@@ -356,7 +356,7 @@ agent = agent_class.new
 
 ### all
 
-List all agent subclasses:
+List all registered agent subclasses (named direct subclasses only):
 
 ```ruby
 Riffer::Agent.all.each do |agent_class|

data/docs/CONFIGURATION.md

@@ -9,12 +9,15 @@ Use `Riffer.configure` to set up provider credentials:
 ```ruby
 Riffer.configure do |config|
   config.openai.api_key = ENV['OPENAI_API_KEY']
+  config.openai.base_url = ENV['OPENAI_BASE_URL'] # Optional — gateways, proxies
   config.amazon_bedrock.region = 'us-east-1'
   config.amazon_bedrock.api_token = ENV['BEDROCK_API_TOKEN']
   config.anthropic.api_key = ENV['ANTHROPIC_API_KEY']
 end
 ```
 
+Providers take no constructor arguments — these settings are the only way to give a provider its credentials.
+
 ## Accessing Configuration
 
 Access the current configuration via `Riffer.config`:
@@ -34,6 +37,66 @@ Riffer.config.anthropic.api_key
 
 For provider credentials and setup, see the individual [Provider guides](providers/PROVIDERS.md).
 
+### Provider Clients
+
+Out of the box, each provider builds a default SDK client from its configured credentials. For anything beyond credentials — timeouts, retries, proxies, gateways — assign your own client to `config.<provider>.client`:
+
+```ruby
+Riffer.configure do |config|
+  config.openai.client = OpenAI::Client.new(
+    api_key: ENV['OPENAI_API_KEY'],
+    timeout: 30,
+    max_retries: 4
+  )
+  config.gemini.client = Riffer::Providers::Gemini::Client.new(
+    api_key: ENV['GEMINI_API_KEY'],
+    read_timeout: 120
+  )
+end
+```
+
+Every provider accepts a client instance or a `Proc` returning one:
+
+| Provider       | Setting                        | Default client built from credentials                         |
+| -------------- | ------------------------------ | ------------------------------------------------------------- |
+| OpenAI         | `config.openai.client`         | `OpenAI::Client`                                              |
+| Azure OpenAI   | `config.azure_openai.client`   | `OpenAI::Client` (with the Azure endpoint as `base_url`)      |
+| Anthropic      | `config.anthropic.client`      | `Anthropic::Client`                                           |
+| Amazon Bedrock | `config.amazon_bedrock.client` | `Aws::BedrockRuntime::Client`                                 |
+| Gemini         | `config.gemini.client`         | `Riffer::Providers::Gemini::Client` (riffer-owned, see below) |
+| OpenRouter     | `config.openrouter.client`     | `OpenAI::Client` (pinned to the OpenRouter endpoint)          |
+
+A `Proc` takes **no arguments** and is resolved on **every LLM call**, never cached by riffer — memoize inside the Proc when construction is expensive. This makes the Proc the right tool for:
+
+- **Fork safety** (Puma clustered, Sidekiq swarm): a client built at boot holds sockets that break across `fork`; build (and cache) per process instead.
+- **Expiring credentials** (Azure AD tokens, STS-vended keys): re-resolve before they go stale.
+
+```ruby
+Riffer.configure do |config|
+  # Fork-safe shared client: one per process, built on first use after fork.
+  config.anthropic.client = -> {
+    ClientRegistry.anthropic_for(Process.pid)
+  }
+
+  # Re-resolved before the token goes stale.
+  config.azure_openai.client = -> {
+    OpenAI::Client.new(api_key: AzureAd.current_token, base_url: ENV['AZURE_OPENAI_ENDPOINT'])
+  }
+end
+```
+
+Because the Proc receives no arguments, it can only vary the client by process-wide state — it cannot route per agent or per request. Client selection is a global concern; to talk to different accounts or endpoints from different agents, register a provider subclass with its own config (see [Multiple Configurations](#multiple-configurations)).
+
+A configured client always wins over configured credentials: once `config.<provider>.client` is set, the credential members are unused, since riffer no longer builds the client.
+
+### Falling through to the SDK
+
+A credential you leave unset in riffer is omitted from the default client rather than passed as `nil`, so each vendor SDK still applies its own resolution. `OPENAI_API_KEY` / `OPENAI_BASE_URL`, `ANTHROPIC_API_KEY`, and the AWS chains — region from `AWS_REGION` / `AWS_DEFAULT_REGION` / shared config, credentials from the environment, the shared credentials file, or an instance/task IAM role — all work with no riffer configuration at all.
+
+Two providers deliberately opt out: `OpenRouter` and `AzureOpenAI` borrow `OpenAI::Client` to reach a **different** vendor, so they always pass their credential and endpoint explicitly. Falling through would let the OpenAI SDK pick up `OPENAI_API_KEY` / `OPENAI_BASE_URL` and send an OpenAI credential to `openrouter.ai` or your Azure endpoint. With nothing configured they raise instead — set `config.openrouter.api_key` / `OPENROUTER_API_KEY`, or `config.azure_openai.api_key` and `.endpoint` / `AZURE_OPENAI_API_KEY` and `AZURE_OPENAI_ENDPOINT`.
+
+The Gemini provider has no vendor SDK, so riffer ships its own transport: `Riffer::Providers::Gemini::Client` exposes `base_url`, `open_timeout`, `read_timeout`, `write_timeout`, and `proxy_address`/`proxy_port`. Anything implementing its two-method contract (`post`, `post_stream`) can be assigned to `config.gemini.client` — see [Gemini](providers/GEMINI.md).
+
 ### MCP (Model Context Protocol)
 
 Optional settings for [MCP server integrations](MCP.md):
@@ -113,10 +176,10 @@ Riffer.configure do |config|
 end
 ```
 
-| Option             | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `enabled`          | The kill switch, consulted on every span — flipping it at runtime takes effect immediately, short-circuiting to a no-op ahead of the backend. Accepts booleans or `'true'`/`'false'`/`'1'`/`'0'`. Defaults to `true`.                                                                                                                                                                                                                                                                                                                                              |
-| `capture_messages` | Opt-in capture of full message content on LLM-call spans (`gen_ai.input.messages`, `gen_ai.output.messages`, `gen_ai.system_instructions`) as GenAI-semconv JSON. Defaults to `false` — message content routinely carries sensitive data. File attachments serialize as metadata-only stubs (media type and name, never bytes), and riffer applies no size limit of its own — cap oversized attributes with the OTEL SDK attribute length limits.                                                                                                                  |
+| Option             | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `enabled`          | The kill switch, consulted on every span — flipping it at runtime takes effect immediately, short-circuiting to a no-op ahead of the backend. Accepts booleans or `'true'`/`'false'`/`'1'`/`'0'`. Defaults to `true`.                                                                                                                                                                                                                                                                                                                                           |
+| `capture_messages` | Opt-in capture of full message content on LLM-call spans (`gen_ai.input.messages`, `gen_ai.output.messages`, `gen_ai.system_instructions`) as GenAI-semconv JSON. Defaults to `false` — message content routinely carries sensitive data. File attachments serialize as metadata-only stubs (media type and name, never bytes), and riffer applies no size limit of its own — cap oversized attributes with the OTEL SDK attribute length limits.                                                                                                               |
 | `backend`          | The backend riffer routes spans through. Assign `Riffer::Tracing::Otel.build` (pass `provider:` to override the global tracer provider — e.g. an in-memory provider in tests), or any object satisfying the duck-typed contract (`in_span` / `current_context` / `with_context`) to route into a non-OTEL system (e.g. Datadog APM). Defaults to `nil` — a no-op. Raises `Riffer::ArgumentError` unless the value is `nil` or responds to `in_span`. See [Tracing → Routing to a non-OpenTelemetry backend](TRACING.md#routing-to-a-non-opentelemetry-backend). |
 
 ### Pricing
@@ -200,19 +263,6 @@ There is no per-call override and no customizable placeholder. Callers needing f
 
 Override global configuration at the agent level:
 
-### provider_options
-
-Pass options directly to the provider client:
-
-```ruby
-class MyAgent < Riffer::Agent
-  model 'openai/gpt-5-mini'
-
-  # Override API key for this agent only
-  provider_options api_key: ENV['CUSTOM_OPENAI_KEY']
-end
-```
-
 ### model_options
 
 Pass options to each LLM request:
@@ -305,17 +355,51 @@ end
 
 ## Multiple Configurations
 
-For different environments or use cases, use agent-level overrides:
+Provider credentials and clients are **global**, resolved per process. For different environments, branch at boot:
+
+```ruby
+Riffer.configure do |config|
+  config.openai.client = if Rails.env.production?
+    OpenAI::Client.new(api_key: ENV['PRODUCTION_OPENAI_KEY'], max_retries: 4)
+  else
+    OpenAI::Client.new(api_key: ENV['DEV_OPENAI_KEY'], timeout: 10)
+  end
+end
+```
+
+When a single process has to reach two different accounts or endpoints, give the second one its own provider class and config, then register it under its own identifier:
+
+```ruby
+class InternalOpenAI < Riffer::Providers::OpenAI
+  InternalConfig = Struct.new(:api_key, :base_url, :client)
+
+  def self.config
+    @config ||= InternalConfig.new(ENV.fetch('INTERNAL_OPENAI_KEY'), ENV.fetch('INTERNAL_GATEWAY'))
+  end
+
+  private
+
+  def global_client
+    self.class.config.client
+  end
+
+  def build_client
+    ::OpenAI::Client.new(api_key: self.class.config.api_key, base_url: self.class.config.base_url)
+  end
+end
+
+Riffer::Providers::Repository.register(:internal_openai) { InternalOpenAI }
+```
+
+Agents then select it by model prefix (`model 'internal_openai/gpt-5-mini'`), and the two accounts never interfere. What _can_ vary per agent is the model and the generation parameters:
 
 ```ruby
 class ProductionAgent < Riffer::Agent
   model 'openai/gpt-5-mini'
-  provider_options api_key: ENV['PRODUCTION_OPENAI_KEY']
 end
 
 class DevelopmentAgent < Riffer::Agent
   model 'openai/gpt-5-mini'
-  provider_options api_key: ENV['DEV_OPENAI_KEY']
-  model_options temperature: 0.0  # Deterministic for testing
+  model_options temperature: 0.0 # Deterministic for testing
 end
 ```

data/docs/SERIALIZATION.md

@@ -1,6 +1,6 @@
 # Serialization
 
-`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.
+`Riffer::Agent::Serializer` turns a **resolved agent** into a provider-neutral data hash (`to_h`) and rebuilds an agent from that hash (`from_h`). The hash carries the agent **definition** — not the credentials or client it needs to reach a provider (see [Secrets](#secrets)). 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`:
 
@@ -43,7 +43,6 @@ The session is used **as-is**: the rebuilt agent does not prepend anything to it
   model:             "openai/gpt-4o",         # resolved "provider/model" string
   instructions:      "You are…",              # resolved system prompt
   model_options:     { temperature: 0.2 },
-  provider_options:  { … },                   # see the secrets warning below
   max_steps:         8,                        # integer; -1 = unlimited (see below)
   structured_output: { type: "object", … },   # JSON Schema, or null
   tools: [ { name:, description:, parameters_schema:, timeout: }, … ]
@@ -101,7 +100,9 @@ A finite integer round-trips as-is; a hash 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 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).
+`model_options` **rides on the wire as plain data** — it is part of the hash and _will_ transfer. Keep sensitive values out of it; credentials live in global provider configuration and never serialize.
+
+The hash describes the agent, not how to authenticate as one. The destination process configures the provider itself — `config.<provider>.client`, or the credentials riffer builds a default client from. Clients resolve lazily on the first LLM call, so `from_h` succeeds in a process with no provider configuration; the `generate` is what fails. See [Configuration](CONFIGURATION.md).
 
 ## What does **not** transfer
 

data/docs/TOOLS.md

@@ -108,7 +108,7 @@ Options:
 | `String`                   | `string`         |
 | `Integer`                  | `integer`        |
 | `Float`                    | `number`         |
-| `Riffer::Params::Boolean`          | `boolean`        |
+| `Riffer::Params::Boolean`  | `boolean`        |
 | `TrueClass` / `FalseClass` | `boolean`        |
 | `Array`                    | `array`          |
 | `Hash`                     | `object`         |
@@ -143,6 +143,23 @@ class CreateOrderTool < Riffer::Tool
 end
 ```
 
+## Looking Up Tools
+
+Look up a tool by identifier with `Riffer::Tool.find`, or list every tool with `Riffer::Tool.all`:
+
+```ruby
+Riffer::Tool.find('kb_search')   # => SearchTool
+Riffer::Tool.find(:kb_search)    # symbols work too
+Riffer::Tool.find('missing')     # => nil
+Riffer::Tool.all                 # => [SearchTool, ...]
+```
+
+Only **named direct subclasses** are found:
+
+- Grandchildren are not visible to a grandparent's `find` or `all`. If your app defines an intermediate base class (`class ApplicationTool < Riffer::Tool`), call `find`/`all` on the intermediate class to look up its subclasses.
+- Anonymous classes (`Class.new(Riffer::Tool)`) are never findable, even when they set an explicit `identifier`.
+- Two subclasses sharing an identifier raise `Riffer::DuplicateIdentifierError` at the first lookup.
+
 ## The call Method
 
 Every tool must implement the `call` method and return a `Riffer::Tools::Response`:

data/docs/providers/AMAZON_BEDROCK.md

@@ -22,6 +22,8 @@ Riffer.configure do |config|
 end
 ```
 
+`region` resolves in order: `Riffer.config.amazon_bedrock.region` → the AWS SDK's own resolution (`AWS_REGION`, `AWS_DEFAULT_REGION`, shared config). Leaving it unset in riffer defers to the SDK rather than failing.
+
 ### Bearer Token Authentication
 
 For API token authentication:
@@ -33,15 +35,22 @@ Riffer.configure do |config|
 end
 ```
 
-Or per-agent:
+### Custom client
+
+AWS auth beyond the bearer token or default credential chain (profiles, STS, IRSA), plus retries, timeouts, and endpoints, is configured on your own `Aws::BedrockRuntime::Client`:
 
 ```ruby
-class MyAgent < Riffer::Agent
-  model 'amazon_bedrock/us.anthropic.claude-haiku-4-5-20251001-v1:0'
-  provider_options region: 'us-west-2', api_token: ENV['BEDROCK_API_TOKEN']
+Riffer.configure do |config|
+  config.amazon_bedrock.client = Aws::BedrockRuntime::Client.new(
+    region: 'us-east-1',
+    credentials: Aws::AssumeRoleCredentials.new(role_arn: ENV['BEDROCK_ROLE_ARN'], role_session_name: 'riffer'),
+    retry_limit: 5
+  )
 end
 ```
 
+The setting accepts a client instance or a no-argument `Proc`, resolved on every LLM call — see [Configuration → Provider Clients](../CONFIGURATION.md#provider-clients).
+
 ## Supported Models
 
 Use Bedrock model IDs in the `amazon_bedrock/model` format:
@@ -168,10 +177,7 @@ The provider converts Riffer messages to Bedrock format:
 ## Direct Provider Usage
 
 ```ruby
-provider = Riffer::Providers::AmazonBedrock.new(
-  region: 'us-east-1',
-  api_token: ENV['BEDROCK_API_TOKEN']  # Optional
-)
+provider = Riffer::Providers::AmazonBedrock.new
 
 response = provider.generate_text(
   prompt: "Hello!",

data/docs/providers/ANTHROPIC.md

@@ -20,15 +20,19 @@ Riffer.configure do |config|
 end
 ```
 
-Or per-agent:
+For anything beyond the API key — timeouts, retries, proxies — supply your own `Anthropic::Client`:
 
 ```ruby
-class MyAgent < Riffer::Agent
-  model 'anthropic/claude-haiku-4-5-20251001'
-  provider_options api_key: ENV['ANTHROPIC_API_KEY']
+Riffer.configure do |config|
+  config.anthropic.client = Anthropic::Client.new(
+    api_key: ENV['ANTHROPIC_API_KEY'],
+    timeout: 60
+  )
 end
 ```
 
+The setting accepts a client instance or a no-argument `Proc`, resolved on every LLM call — see [Configuration → Provider Clients](../CONFIGURATION.md#provider-clients).
+
 ## Supported Models
 
 Use Anthropic model IDs in the `anthropic/model` format:
@@ -224,9 +228,7 @@ The provider converts Riffer messages to Anthropic format:
 ## Direct Provider Usage
 
 ```ruby
-provider = Riffer::Providers::Anthropic.new(
-  api_key: ENV['ANTHROPIC_API_KEY']
-)
+provider = Riffer::Providers::Anthropic.new
 
 response = provider.generate_text(
   prompt: "Hello!",