riffer 0.55.0 → 0.57.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (114) hide show
  1. checksums.yaml +4 -4
  2. data/.release-please-manifest.json +1 -1
  3. data/CHANGELOG.md +37 -0
  4. data/README.md +3 -2
  5. data/UPGRADING.md +3 -0
  6. data/docs/AGENTS.md +105 -50
  7. data/docs/AGENT_LIFECYCLE.md +2 -2
  8. data/docs/CONFIGURATION.md +54 -3
  9. data/docs/EVALS.md +2 -0
  10. data/docs/GUARDRAILS.md +2 -0
  11. data/docs/MCP.md +36 -0
  12. data/docs/MESSAGES.md +125 -15
  13. data/docs/OVERVIEW.md +7 -7
  14. data/docs/SERIALIZATION.md +12 -2
  15. data/docs/SKILLS.md +1 -1
  16. data/docs/STABILITY.md +32 -0
  17. data/docs/STREAM_EVENTS.md +16 -0
  18. data/docs/TESTING.md +22 -1
  19. data/docs/TOOLS.md +93 -37
  20. data/docs/TOOL_ADVANCED.md +7 -0
  21. data/docs/providers/AMAZON_BEDROCK.md +7 -3
  22. data/docs/providers/ANTHROPIC.md +53 -16
  23. data/docs/providers/AZURE_OPENAI.md +9 -3
  24. data/docs/providers/CUSTOM_PROVIDERS.md +43 -0
  25. data/docs/providers/GEMINI.md +9 -5
  26. data/docs/providers/GOOGLE_CLOUD.md +10 -5
  27. data/docs/providers/MOCK_PROVIDER.md +4 -0
  28. data/docs/providers/OPENAI.md +28 -4
  29. data/docs/providers/OPENROUTER.md +11 -3
  30. data/docs/providers/PROVIDERS.md +1 -1
  31. data/docs-site/index.html.erb +1 -1
  32. data/docs-site/manifest.yml +3 -0
  33. data/lib/riffer/agent/config.rb +21 -0
  34. data/lib/riffer/agent/context.rb +36 -18
  35. data/lib/riffer/agent/run.rb +82 -21
  36. data/lib/riffer/agent/serializer.rb +5 -0
  37. data/lib/riffer/agent/session.rb +34 -10
  38. data/lib/riffer/agent.rb +43 -0
  39. data/lib/riffer/config/future.rb +53 -0
  40. data/lib/riffer/config/mcp.rb +17 -0
  41. data/lib/riffer/config/pricing.rb +5 -15
  42. data/lib/riffer/config.rb +28 -1
  43. data/lib/riffer/deprecation/event.rb +25 -0
  44. data/lib/riffer/deprecation.rb +60 -0
  45. data/lib/riffer/evals/evaluator.rb +8 -1
  46. data/lib/riffer/evals/evaluator_runner.rb +1 -0
  47. data/lib/riffer/evals/judge.rb +2 -2
  48. data/lib/riffer/evals.rb +2 -0
  49. data/lib/riffer/mcp/search_tool.rb +1 -1
  50. data/lib/riffer/mcp.rb +7 -0
  51. data/lib/riffer/messages/assistant/server_tool_part.rb +73 -0
  52. data/lib/riffer/messages/assistant/text_part.rb +52 -0
  53. data/lib/riffer/messages/assistant.rb +64 -17
  54. data/lib/riffer/messages/tool.rb +6 -2
  55. data/lib/riffer/params/any_of.rb +5 -8
  56. data/lib/riffer/params/boolean.rb +1 -1
  57. data/lib/riffer/params/param.rb +96 -67
  58. data/lib/riffer/params.rb +50 -71
  59. data/lib/riffer/providers/anthropic_compatible/messages_api/stream.rb +28 -11
  60. data/lib/riffer/providers/anthropic_compatible/messages_api.rb +136 -38
  61. data/lib/riffer/providers/base.rb +57 -12
  62. data/lib/riffer/providers/deferred_tool_gateway/sink.rb +54 -0
  63. data/lib/riffer/providers/deferred_tool_gateway/tool.rb +17 -0
  64. data/lib/riffer/providers/deferred_tool_gateway.rb +150 -0
  65. data/lib/riffer/providers/gemini.rb +5 -5
  66. data/lib/riffer/providers/mock.rb +6 -0
  67. data/lib/riffer/providers/open_ai.rb +59 -26
  68. data/lib/riffer/skills/activate_tool.rb +1 -1
  69. data/lib/riffer/stream_events/server_tool_done.rb +21 -0
  70. data/lib/riffer/testing.rb +6 -0
  71. data/lib/riffer/tool.rb +92 -2
  72. data/lib/riffer/tools/response.rb +11 -2
  73. data/lib/riffer/version.rb +1 -1
  74. data/lib/riffer.rb +2 -0
  75. data/sig/generated/riffer/agent/config.rbs +13 -1
  76. data/sig/generated/riffer/agent/context.rbs +16 -0
  77. data/sig/generated/riffer/agent/run.rbs +19 -2
  78. data/sig/generated/riffer/agent/session.rbs +6 -0
  79. data/sig/generated/riffer/agent.rbs +13 -0
  80. data/sig/generated/riffer/config/future.rbs +29 -0
  81. data/sig/generated/riffer/config/mcp.rbs +7 -0
  82. data/sig/generated/riffer/config/pricing.rbs +0 -9
  83. data/sig/generated/riffer/config.rbs +13 -1
  84. data/sig/generated/riffer/deprecation/event.rbs +17 -0
  85. data/sig/generated/riffer/deprecation.rbs +27 -0
  86. data/sig/generated/riffer/evals/evaluator.rbs +4 -0
  87. data/sig/generated/riffer/evals.rbs +1 -0
  88. data/sig/generated/riffer/mcp.rbs +1 -0
  89. data/sig/generated/riffer/messages/assistant/server_tool_part.rbs +44 -0
  90. data/sig/generated/riffer/messages/assistant/text_part.rbs +35 -0
  91. data/sig/generated/riffer/messages/assistant.rbs +24 -11
  92. data/sig/generated/riffer/messages/tool.rbs +4 -2
  93. data/sig/generated/riffer/params/any_of.rbs +4 -4
  94. data/sig/generated/riffer/params/boolean.rbs +1 -1
  95. data/sig/generated/riffer/params/param.rbs +28 -14
  96. data/sig/generated/riffer/params.rbs +20 -20
  97. data/sig/generated/riffer/providers/anthropic_compatible/messages_api/stream.rbs +12 -5
  98. data/sig/generated/riffer/providers/anthropic_compatible/messages_api.rbs +50 -9
  99. data/sig/generated/riffer/providers/base.rbs +18 -0
  100. data/sig/generated/riffer/providers/deferred_tool_gateway/sink.rbs +23 -0
  101. data/sig/generated/riffer/providers/deferred_tool_gateway/tool.rbs +4 -0
  102. data/sig/generated/riffer/providers/deferred_tool_gateway.rbs +58 -0
  103. data/sig/generated/riffer/providers/mock.rbs +4 -0
  104. data/sig/generated/riffer/providers/open_ai.rbs +23 -6
  105. data/sig/generated/riffer/stream_events/server_tool_done.rbs +15 -0
  106. data/sig/generated/riffer/testing.rbs +4 -0
  107. data/sig/generated/riffer/tool.rbs +48 -2
  108. data/sig/generated/riffer/tools/response.rbs +9 -2
  109. data/sig/generated/riffer.rbs +3 -0
  110. data/sig/manual/riffer/deprecation.rbs +5 -0
  111. data/sig/manual/riffer/providers/deferred_tool_gateway.rbs +5 -0
  112. metadata +23 -3
  113. data/lib/riffer/tools/toolable.rb +0 -113
  114. data/sig/generated/riffer/tools/toolable.rbs +0 -66
@@ -150,8 +150,8 @@ class S3ListTool < Riffer::Tool
150
150
  description "Lists objects in an S3 bucket"
151
151
 
152
152
  params do
153
- required :bucket, String, description: "The S3 bucket name"
154
- optional :prefix, String, description: "Object prefix filter"
153
+ required :bucket, :string, description: "The S3 bucket name"
154
+ optional :prefix, :string, description: "Object prefix filter"
155
155
  end
156
156
 
157
157
  def call(context:, bucket:, prefix: nil)
@@ -166,6 +166,10 @@ class AWSAgent < Riffer::Agent
166
166
  end
167
167
  ```
168
168
 
169
+ ## Deferred Tools (experimental)
170
+
171
+ Converse has no native deferred loading, so an agent with [deferred tools](../AGENTS.md#deferred_tools-experimental) on Bedrock needs the [gateway strategy](../AGENTS.md#deferred-tools-strategy-experimental), `deferred_tools [...], strategy: :gateway`; without it, building the agent raises `Riffer::ArgumentError`. Every request then has one extra tool in `tool_config.tools`, the [gateway](../TOOLS.md#the-gateway-strategy), and the model calls a loaded tool through it, so the tool list stays the same and a load keeps the [`cache_control`](#cache_control) prompt cache. Calls come back under the real tool's name.
172
+
169
173
  ## Reasoning Models
170
174
 
171
175
  Claude models on Bedrock can think before they answer. Enable extended thinking through `additional_model_request_fields`:
@@ -195,7 +199,7 @@ The agent-level [`reasoning`](../AGENTS.md#reasoning) setting defaults to Claude
195
199
 
196
200
  Riffer sends the reasoning back to Bedrock on every later turn. How much of it Claude uses depends on the model; some only use the reasoning from the current tool-calling turn. For tool calls, sending it back is required: when thinking is enabled, Claude needs its earlier reasoning back to carry on after a tool result. You don't have to do anything; it happens as long as the assistant messages stay in the history.
197
201
 
198
- If you persist sessions, keep the `reasoning` key when you store messages (see [Messages — Reasoning](../MESSAGES.md#reasoning)). If you drop it, later turns lose the model's earlier reasoning, and a tool-calling turn with thinking enabled may be rejected.
202
+ If you persist sessions, keep the reasoning when you store messages (see [Messages — Reasoning](../MESSAGES.md#reasoning)). If you drop it, later turns lose the model's earlier reasoning, and a tool-calling turn with thinking enabled may be rejected.
199
203
 
200
204
  Only reasoning that Bedrock produced is sent back to Bedrock. A conversation that switches providers midway still works: reasoning from other providers is kept on the messages but left out of Bedrock requests.
201
205
 
@@ -29,12 +29,12 @@ Riffer.configure do |config|
29
29
  end
30
30
  ```
31
31
 
32
- | Option | Default | Description |
33
- | ------------ | -------------------------------------- | ------------------------------------------------------------------- |
34
- | `api_key` | required | Sent as `Authorization: Bearer <api_key>` |
35
- | `base_url` | `https://api.anthropic.com` | API origin; requests go to `<base_url>/v1/messages` |
36
- | `headers` | `{}` | Sent on every request; replaces riffer's headers of the same name |
37
- | `connection` | Faraday defaults, 10s open / 600s read | Your own `Faraday::Connection`; see [Connections][connections] |
32
+ | Option | Default | Description |
33
+ | ------------ | -------------------------------------- | ----------------------------------------------------------------- |
34
+ | `api_key` | required | Sent as `Authorization: Bearer <api_key>` |
35
+ | `base_url` | `https://api.anthropic.com` | API origin; requests go to `<base_url>/v1/messages` |
36
+ | `headers` | `{}` | Sent on every request; replaces riffer's headers of the same name |
37
+ | `connection` | Faraday defaults, 10s open / 600s read | Your own `Faraday::Connection`; see [Connections][connections] |
38
38
 
39
39
  Timeouts, retries, proxies, beta headers and errors are covered in [Configuration → Connections][connections]. An API error becomes a `Riffer::APIError` whose message carries the Anthropic error type, e.g. `Anthropic API error (401): authentication_error: Invalid bearer token`. No requests are retried unless your connection adds retries.
40
40
 
@@ -139,8 +139,8 @@ class WeatherTool < Riffer::Tool
139
139
  description "Gets the current weather for a location"
140
140
 
141
141
  params do
142
- required :city, String, description: "The city name"
143
- optional :unit, String, description: "Temperature unit (celsius or fahrenheit)"
142
+ required :city, :string, description: "The city name"
143
+ optional :unit, :string, description: "Temperature unit (celsius or fahrenheit)"
144
144
  end
145
145
 
146
146
  def call(context:, city:, unit: "celsius")
@@ -189,9 +189,11 @@ The reasoning is kept on the assistant message as [reasoning parts](../MESSAGES.
189
189
 
190
190
  ### Reasoning Replay
191
191
 
192
- Riffer sends the reasoning back to Anthropic on every later turn, as `thinking` and `redacted_thinking` blocks ahead of the message's text and `tool_use` blocks, in their original order and unchanged. For tool calls, sending it back is required: when thinking is enabled, Claude needs its earlier thinking blocks back to carry on after a tool result. You don't have to do anything; it happens as long as the assistant messages stay in the history.
192
+ Riffer sends every earlier turn back to Anthropic as the API returned it: the `thinking`, `redacted_thinking`, text, web search and `tool_use` blocks, in their original order and unchanged (see [Messages — Parts](../MESSAGES.md#parts)). Order matters because Claude signs each thinking block over everything before it, including earlier blocks of the same turn. A turn sent back in a different order loses that reasoning, or is rejected with a 400 on accounts that enforce the binding. For tool calls, sending the reasoning back is required: when thinking is enabled, Claude needs its earlier thinking blocks back to carry on after a tool result. You don't have to do anything; it happens as long as the assistant messages stay in the history.
193
193
 
194
- If you persist sessions, keep the `reasoning` key when you store messages (see [Messages — Reasoning](../MESSAGES.md#reasoning)). If you drop it, later turns lose the model's earlier reasoning, and a tool-calling turn with thinking enabled may be rejected.
194
+ If you persist sessions, `to_h` keeps the web search results and the turn's block order (see [Messages — Parts](../MESSAGES.md#parts)). Dropping the reasoning loses the model's earlier thinking, and a tool-calling turn with thinking enabled may be rejected.
195
+
196
+ If you change a turn's text, drop that turn's reasoning yourself; see [Editing a turn](../MESSAGES.md#parts).
195
197
 
196
198
  Only reasoning that this provider produced is sent back to Anthropic. A conversation that switches providers midway still works: reasoning from other providers (including OpenRouter's `anthropic-claude-v1` parts) is kept on the messages but left out of Anthropic requests.
197
199
 
@@ -222,16 +224,51 @@ end
222
224
 
223
225
  Anthropic emits sources with `title` and `url` on the `WebSearchDone` event.
224
226
 
227
+ Each `server_tool_use` block and its result block (`web_search_tool_result`, or `code_execution_tool_result` when a newer web search version runs the search from code execution) is kept on the assistant message as a `ServerToolPart` (see [Messages — Parts](../MESSAGES.md#parts)), and a streamed one also arrives as a `ServerToolDone` event. With `generate`, text blocks with citations keep their block too; a streamed turn keeps the text without its citations. Later turns send them back in place, so Claude reuses the results instead of searching again.
228
+
229
+ ### Paused turns
230
+
231
+ When a server tool loop reaches its iteration limit, Anthropic stops with `stop_reason: "pause_turn"`. Riffer sends the paused content back unchanged as the last message and continues the turn, up to 8 times per call, for `generate_text` and `stream_text` alike. If the response names a `container`, its id goes with the next request, so the turn keeps the same container and its files. You get one assistant message: every response's parts in order, the summed token usage and the last response's finish reason. A stream yields one `TextDone`, `FinishReasonDone` and `TokenUsageDone` for the whole turn.
232
+
233
+ A turn still paused after 8 continuations ends with finish reason `:other` (`finish_reason_raw` is `"pause_turn"`). Its last server tool call may have no result, and Anthropic rejects a request that adds a user message after it. Call `generate` or `stream` with no prompt to send the turn back and let Claude carry on.
234
+
235
+ A turn that stops on `max_tokens` is not continued.
236
+
237
+ ## Deferred Tools
238
+
239
+ The provider supports [deferred tools](../AGENTS.md#deferred_tools-experimental) through the Messages API's own deferred loading, with no beta header and no tool search tool:
240
+
241
+ ```ruby
242
+ class Assistant < Riffer::Agent
243
+ model 'anthropic/claude-haiku-5-5'
244
+ instructions "If you need a tool you don't have, use find_tools."
245
+
246
+ uses_tools [FindTools]
247
+ deferred_tools [ListEvents, CreateEvent]
248
+ end
249
+ ```
250
+
251
+ - Every deferred tool is sent on every request with `defer_loading: true`, after the agent's other tools, whether it has been loaded or not. The `tools` array stays the same for the whole conversation, so a load doesn't break the prompt cache.
252
+ - A tool result that [loads tools](../TOOLS.md#loading-deferred-tools-experimental) is sent as `tool_reference` blocks only, one per loaded tool. From then on Claude sees those tools' definitions and calls them by their own names. A load that names a tool the agent no longer defers, for example in a restored history, leaves that tool out, since the API rejects a reference to a tool that isn't in the request.
253
+
254
+ Things to know:
255
+
256
+ - At least one tool in the request must not be deferred, or the API returns a 400 (`All tools cannot be deferred`). An agent needs a tool in `uses_tools` to load its deferred tools anyway.
257
+ - A deferred tool can't carry `cache_control` (400). Riffer never sets it on a tool; the top-level `model_options cache_control: {type: "ephemeral"}` works with deferred tools.
258
+ - Deferred loading needs Claude Haiku 4.5, Sonnet 4.5, Opus 4.5 or a later model. An older model gets the API's own error.
259
+
260
+ With the [gateway strategy](../AGENTS.md#deferred-tools-strategy-experimental), `deferred_tools [...], strategy: :gateway`, riffer sends the [gateway](../TOOLS.md#the-gateway-strategy) instead of loading them natively.
261
+
225
262
  ## Message Format
226
263
 
227
264
  The provider converts Riffer messages to Anthropic format:
228
265
 
229
- | Riffer Message | Anthropic Format |
230
- | -------------- | --------------------------------------------------------------- |
231
- | `System` | Added to `system` array as `{type: "text", text: ...}` |
232
- | `User` | `{role: "user", content: "..."}` |
233
- | `Assistant` | `{role: "assistant", content: [...]}` with text/tool_use blocks |
234
- | `Tool` | `{role: "user", content: [{type: "tool_result", ...}]}` |
266
+ | Riffer Message | Anthropic Format |
267
+ | -------------- | ------------------------------------------------------------------------ |
268
+ | `System` | Added to `system` array as `{type: "text", text: ...}` |
269
+ | `User` | `{role: "user", content: "..."}` |
270
+ | `Assistant` | `{role: "assistant", content: [...]}`, one block per part, in part order |
271
+ | `Tool` | `{role: "user", content: [{type: "tool_result", ...}]}` |
235
272
 
236
273
  ## Direct Provider Usage
237
274
 
@@ -133,9 +133,9 @@ class CalculatorTool < Riffer::Tool
133
133
  description "Performs basic math operations"
134
134
 
135
135
  params do
136
- required :operation, String, enum: ["add", "subtract", "multiply", "divide"]
137
- required :a, Float, description: "First number"
138
- required :b, Float, description: "Second number"
136
+ required :operation, :string, enum: ["add", "subtract", "multiply", "divide"]
137
+ required :a, :number, description: "First number"
138
+ required :b, :number, description: "Second number"
139
139
  end
140
140
 
141
141
  def call(context:, operation:, a:, b:)
@@ -155,6 +155,12 @@ class MathAgent < Riffer::Agent
155
155
  end
156
156
  ```
157
157
 
158
+ ## Deferred Tools (experimental)
159
+
160
+ [Deferred tools](../AGENTS.md#deferred_tools-experimental) load the same way as on the [OpenAI provider](OPENAI.md#deferred-tools-experimental), through `additional_tools` input items. Microsoft documents these items for the Azure OpenAI Responses API in [Use tool search with the Azure OpenAI Responses API](https://learn.microsoft.com/en-us/azure/foundry/openai/how-to/tool-search#add-tools-at-a-specific-point-in-the-input), but riffer hasn't been tested against Azure. Which deployments accept them is up to Azure, and one that doesn't returns Azure's own error.
161
+
162
+ With the [gateway strategy](../AGENTS.md#deferred-tools-strategy-experimental), `deferred_tools [...], strategy: :gateway`, riffer sends the [gateway](../TOOLS.md#the-gateway-strategy) instead of loading them natively.
163
+
158
164
  ## Direct Provider Usage
159
165
 
160
166
  ```ruby
@@ -233,6 +233,25 @@ def convert_tool(tool)
233
233
  end
234
234
  ```
235
235
 
236
+ ### Deferred tools (experimental)
237
+
238
+ The `supports_deferred_tools?` class method says whether your provider loads [deferred tools](../AGENTS.md#deferred_tools-experimental) natively. The default is false, and riffer raises `Riffer::ArgumentError` when an agent with deferred tools and the default `:native` [strategy](../AGENTS.md#deferred-tools-strategy-experimental) is built on your provider. A provider that returns true receives `options[:deferred_tools]`, every deferred tool whether loaded or not, next to `options[:tools]`, and works out what each tool result loaded from its `loaded_tools`.
239
+
240
+ An agent with `strategy: :gateway` works on your provider either way, through the [gateway](../TOOLS.md#the-gateway-strategy), with no code in your provider. It never sees `options[:deferred_tools]`, even if `supports_deferred_tools?` returns true. Instead, `build_request_params` receives:
241
+
242
+ - `options[:tools]` with `Riffer::Providers::DeferredToolGateway::Tool` on the end, on every request of an agent with deferred tools. It's an ordinary `Riffer::Tool` named `riffer_gateway`, so your tool conversion handles it, strict mode included.
243
+ - Messages where each call to a deferred tool is a call to the gateway, its result is named after the gateway, and a result that loaded tools has their descriptions appended to its content.
244
+
245
+ The model's calls to the gateway that you return from `extract_tool_calls`, or stream as `ToolCallDone` events, are turned back into calls to the real tools before they leave the provider, and the `ToolCallDelta` events you stream for them are dropped.
246
+
247
+ This hook is experimental too: `supports_deferred_tools?` and the `options[:deferred_tools]` it gates can change or be replaced in any minor release, for example by a capability in the [model catalog](../CATALOG.md) (see [Stability](../STABILITY.md#experimental-features)).
248
+
249
+ ```ruby
250
+ def self.supports_deferred_tools?
251
+ true
252
+ end
253
+ ```
254
+
236
255
  ## Stream Events
237
256
 
238
257
  Use the appropriate stream event classes in `execute_stream`:
@@ -259,6 +278,9 @@ Riffer::StreamEvents::ToolCallDone.new(
259
278
  Riffer::StreamEvents::ReasoningDelta.new("thinking...")
260
279
  Riffer::StreamEvents::ReasoningDone.new(part)
261
280
 
281
+ # Server tool blocks (if supported); see the Ordered Parts section
282
+ Riffer::StreamEvents::ServerToolDone.new(server_tool_part)
283
+
262
284
  # Web search (if supported)
263
285
  Riffer::StreamEvents::WebSearchStatus.new("searching", query: "search query")
264
286
  Riffer::StreamEvents::WebSearchDone.new(
@@ -343,6 +365,27 @@ yielder << Riffer::StreamEvents::ReasoningDone.new(part)
343
365
 
344
366
  If your adapter surfaces reasoning text but cannot yet replay it, call `yield_reasoning_done(yielder, text)` instead. It wraps the text in a `:text` part with no `format`, which persists for display and is skipped on replay.
345
367
 
368
+ ## Ordered Parts
369
+
370
+ By default the base class builds the assistant message's [parts](../MESSAGES.md#parts) from `extract_reasoning`, `extract_content` and `extract_tool_calls`, in that order. If your provider interleaves blocks in one turn and needs them back in that order, override `extract_parts` instead and return every block as a part, in response order:
371
+
372
+ ```ruby
373
+ def extract_parts(response)
374
+ response.blocks.filter_map do |block|
375
+ case block.type
376
+ when "text" then Riffer::Messages::Assistant::TextPart.new(block.text)
377
+ when "thinking" then Riffer::Messages::Assistant::ReasoningPart.new(type: :text, text: block.text, signature: block.signature, format: "my-provider-v1")
378
+ when "tool_call" then Riffer::Messages::Assistant::ToolCall.new(call_id: block.id, name: block.name, arguments: block.arguments)
379
+ when "search" then Riffer::Messages::Assistant::ServerToolPart.new(name: "web_search", kind: :call, id: block.id, data: block.to_json, format: "my-provider-v1")
380
+ end
381
+ end
382
+ end
383
+ ```
384
+
385
+ Then replay by walking `message.parts` rather than reading `content`, `tool_calls` and `reasoning` separately, and skip parts whose `format` you don't recognize.
386
+
387
+ For streaming, emit `ServerToolDone` for each server tool block, and keep text deltas, `ReasoningDone` and `ToolCallDone` in the order the blocks arrive. The agent loop builds the parts in that order.
388
+
346
389
  ## Reasoning Level
347
390
 
348
391
  When an agent sets [`reasoning`](../AGENTS.md#reasoning), riffer resolves the level to `model_options` params before calling `build_request_params`, so your provider receives ordinary options and never sees the level itself. It uses the model's [catalog](../CATALOG.md#reasoning) entry under your registration key first, then your provider's default. Override the private `default_reasoning_options` to supply one:
@@ -132,8 +132,8 @@ end
132
132
 
133
133
  ```ruby
134
134
  params = Riffer::Params.new
135
- params.required(:sentiment, String)
136
- params.required(:score, Float)
135
+ params.required(:sentiment, :string)
136
+ params.required(:score, :number)
137
137
  structured_output = Riffer::Agent::StructuredOutput.new(params)
138
138
 
139
139
  response = provider.generate_text(
@@ -146,7 +146,7 @@ puts response.structured_output
146
146
 
147
147
  Structured output is sent as `responseFormat`, which needs a gemini-3 model or later. gemini-2.x models ignore it and return prose.
148
148
 
149
- The schema is sent in strict form: every field is listed as required, and an optional field is nullable, so the model can return `null` for a value it doesn't know instead of making one up. A `Hash` param needs a block and an `Array` param a block or `of:` (see [Structured Output Limitations](../AGENTS.md#limitations)).
149
+ The schema is sent in strict form: every field is listed as required, and an optional field is nullable, so the model can return `null` for a value it doesn't know instead of making one up. An `:object` param needs a block and an `:array` param a block or `of:` (see [Structured Output Limitations](../AGENTS.md#limitations)).
150
150
 
151
151
  ### Tool Calling
152
152
 
@@ -154,7 +154,7 @@ The schema is sent in strict form: every field is listed as required, and an opt
154
154
  class WeatherTool < Riffer::Tool
155
155
  description "Gets weather"
156
156
  params do
157
- required :city, String
157
+ required :city, :string
158
158
  end
159
159
  def call(context:, city:)
160
160
  text("Sunny in #{city}")
@@ -170,13 +170,17 @@ response = provider.generate_text(
170
170
 
171
171
  Gemini's own call ids are short, so riffer gives each tool call its own `call_id` (`gemini_call_<hex>`) and appends Gemini's id when there is one. On later turns riffer sends that id back on the function call and its result, so Gemini can match results to parallel calls of the same tool.
172
172
 
173
+ ### Deferred Tools (experimental)
174
+
175
+ Gemini has no native deferred loading, so an agent with [deferred tools](../AGENTS.md#deferred_tools-experimental) on Gemini needs the [gateway strategy](../AGENTS.md#deferred-tools-strategy-experimental), `deferred_tools [...], strategy: :gateway`; without it, building the agent raises `Riffer::ArgumentError`. Every request then has one extra function in `functionDeclarations`, the [gateway](../TOOLS.md#the-gateway-strategy), and the model calls a loaded tool through it, so the declarations stay the same and a load keeps the prompt cache. Calls come back under the real tool's name.
176
+
173
177
  ### Thought Signatures
174
178
 
175
179
  Gemini 3 models attach an opaque `thoughtSignature` to the first function call of each step, and to the last text part of an answer. A later request that sends a function call back without its signature is rejected with a 400.
176
180
 
177
181
  Riffer keeps each signature on the assistant message as the `data` of an `:encrypted` [reasoning part](../MESSAGES.md#reasoning) tagged `format: "gemini-generate-content-v1"` (`Riffer::Providers::Gemini::REASONING_FORMAT`). A signature from a function call carries that tool call's `call_id` as its `id`; the text signature has no `id`. Streams emit them as `ReasoningDone` events. On later turns riffer puts each signature back on the part it came from. You don't have to do anything as long as the assistant messages stay in the history.
178
182
 
179
- A function call that Gemini didn't sign, such as one another provider made before the conversation switched to Gemini, goes out with Gemini's placeholder signature (`skip_thought_signature_validator`), which Gemini accepts in place of a real one. That covers the first call of each step when that call has no signature for this provider. Google warns that a call without its real signature may degrade the model's answer, so if you persist sessions, keep the `reasoning` key when you store messages.
183
+ A function call that Gemini didn't sign, such as one another provider made before the conversation switched to Gemini, goes out with Gemini's placeholder signature (`skip_thought_signature_validator`), which Gemini accepts in place of a real one. That covers the first call of each step when that call has no signature for this provider. Google warns that a call without its real signature may degrade the model's answer, so if you persist sessions, keep the reasoning when you store messages.
180
184
 
181
185
  ### Web Search
182
186
 
@@ -224,8 +224,8 @@ end
224
224
 
225
225
  ```ruby
226
226
  params = Riffer::Params.new
227
- params.required(:sentiment, String)
228
- params.required(:score, Float)
227
+ params.required(:sentiment, :string)
228
+ params.required(:score, :number)
229
229
  structured_output = Riffer::Agent::StructuredOutput.new(params)
230
230
 
231
231
  response = provider.generate_text(
@@ -236,7 +236,7 @@ response = provider.generate_text(
236
236
  puts response.structured_output
237
237
  ```
238
238
 
239
- The schema is sent in strict form: every field is listed as required, and an optional field is nullable, so the model can return `null` for a value it doesn't know instead of making one up. A `Hash` param needs a block and an `Array` param a block or `of:` (see [Structured Output Limitations](../AGENTS.md#limitations)).
239
+ The schema is sent in strict form: every field is listed as required, and an optional field is nullable, so the model can return `null` for a value it doesn't know instead of making one up. An `:object` param needs a block and an `:array` param a block or `of:` (see [Structured Output Limitations](../AGENTS.md#limitations)).
240
240
 
241
241
  ### Tool Calling
242
242
 
@@ -244,7 +244,7 @@ The schema is sent in strict form: every field is listed as required, and an opt
244
244
  class WeatherTool < Riffer::Tool
245
245
  description "Gets weather"
246
246
  params do
247
- required :city, String
247
+ required :city, :string
248
248
  end
249
249
  def call(context:, city:)
250
250
  text("Sunny in #{city}")
@@ -260,13 +260,17 @@ response = provider.generate_text(
260
260
 
261
261
  Riffer gives each tool call its own `call_id` (`gemini_call_<hex>`) and appends the model's id when there is one. On later turns riffer sends that id back on the function call and its result, so the model can match results to parallel calls of the same tool.
262
262
 
263
+ ### Deferred Tools (experimental)
264
+
265
+ Gemini models have no native deferred loading, so on `google_cloud` an agent with [deferred tools](../AGENTS.md#deferred_tools-experimental) needs the [gateway strategy](../AGENTS.md#deferred-tools-strategy-experimental), the same way as on [Gemini → Deferred Tools](GEMINI.md#deferred-tools-experimental). Claude models on `anthropic_vertex` load them natively.
266
+
263
267
  ### Thought Signatures
264
268
 
265
269
  Gemini 3 models attach an opaque `thoughtSignature` to the first function call of each step, and to the last text part of an answer. A later request that sends a function call back without its signature is rejected with a 400.
266
270
 
267
271
  Riffer keeps each signature on the assistant message as the `data` of an `:encrypted` [reasoning part](../MESSAGES.md#reasoning) tagged `format: "google-cloud-generate-content-v1"` (`Riffer::Providers::GoogleCloud::REASONING_FORMAT`). A signature from a function call carries that tool call's `call_id` as its `id`; the text signature has no `id`. Streams emit them as `ReasoningDone` events. On later turns riffer puts each signature back on the part it came from. You don't have to do anything as long as the assistant messages stay in the history.
268
272
 
269
- A function call without an Agent Platform signature goes out with Google's placeholder signature (`skip_thought_signature_validator`), which Agent Platform accepts in place of a real one. That happens when the call came from another provider, or from the Gemini Developer API, whose signatures Agent Platform rejects. It covers the first call of each step when that call has no signature for this provider. Google warns that a call without its real signature may degrade the model's answer, so if you persist sessions, keep the `reasoning` key when you store messages.
273
+ A function call without an Agent Platform signature goes out with Google's placeholder signature (`skip_thought_signature_validator`), which Agent Platform accepts in place of a real one. That happens when the call came from another provider, or from the Gemini Developer API, whose signatures Agent Platform rejects. It covers the first call of each step when that call has no signature for this provider. Google warns that a call without its real signature may degrade the model's answer, so if you persist sessions, keep the reasoning when you store messages.
270
274
 
271
275
  ### Web Search
272
276
 
@@ -349,6 +353,7 @@ Claude models on Agent Platform behave as they do on the Anthropic provider:
349
353
  - **Reasoning** is captured as [reasoning parts](../MESSAGES.md#reasoning) tagged `format: "anthropic-messages-v1"` and sent back on later turns, as described in [Anthropic → Reasoning Replay](ANTHROPIC.md#reasoning-replay). Thinking signatures are accepted by both APIs, so a conversation can move between `anthropic` and `anthropic_vertex`. The agent-level [`reasoning`](../AGENTS.md#reasoning) setting uses the Anthropic default; [catalog](../CATALOG.md#reasoning) entries go under `anthropic_vertex/...` keys.
350
354
  - **Web search:** `web_search: true` (or a hash of options) adds the `web_search_20250305` server tool and streams `WebSearchStatus` / `WebSearchDone` events.
351
355
  - **Structured output** is sent as a strict `output_config.format` JSON schema.
356
+ - **Deferred tools** are loaded natively, the same way as on [Anthropic → Deferred Tools](ANTHROPIC.md#deferred-tools).
352
357
  - **Skills** are rendered with the XML skills adapter.
353
358
  - **Tags:** only the reserved `user_id` tag is sent, as `metadata.user_id`.
354
359
  - **Incomplete streams:** a stream that ends without a `message_stop` event raises `Riffer::IncompleteStreamError`.
@@ -96,6 +96,10 @@ provider.calls
96
96
  expect(provider.calls.last[:messages].last[:content]).to eq("Hi")
97
97
  ```
98
98
 
99
+ Each message is recorded as its `to_h`, so an assistant message has `parts` rather than `content` (see [Messages — Parts](../MESSAGES.md#parts)).
100
+
101
+ The Mock provider loads [deferred tools](../AGENTS.md#deferred_tools-experimental) natively, so you can test them without a real provider. For an agent with deferred tools, each recorded call also has `deferred_tools:`, every deferred tool whether loaded or not. With the [gateway strategy](../AGENTS.md#deferred-tools-strategy-experimental) it doesn't load them natively: recorded calls have no `deferred_tools:`, the gateway is last in `tools:`, the messages are as the gateway sends them, and a stubbed call to the gateway (`Riffer::Providers::DeferredToolGateway::Tool.name`) comes back as a call to the real tool.
102
+
99
103
  ## Clearing State
100
104
 
101
105
  Reset stubbed responses:
@@ -96,7 +96,7 @@ Each `reasoning` item in a Responses API output becomes [reasoning parts](../MES
96
96
 
97
97
  The `:encrypted` part is always present, even when the response carried no `encrypted_content`, so the item's `id` is kept. When streaming, the parts are yielded as `ReasoningDone` events once the item completes; summary text still arrives as `ReasoningDelta` events before that.
98
98
 
99
- On the next request, parts sharing an `id` go back as one `reasoning` item, ahead of the assistant's text and function calls, in their original order and unchanged. This lets reasoning models carry their reasoning across turns and tool-call loops. You don't have to do anything as long as the assistant messages stay in the history; if you persist sessions, keep the `reasoning` key when you store them.
99
+ On the next request, parts sharing an `id` go back as one `reasoning` item, ahead of the assistant's text and function calls, in their original order and unchanged. This lets reasoning models carry their reasoning across turns and tool-call loops. You don't have to do anything as long as the assistant messages stay in the history; if you persist sessions, keep the reasoning when you store them.
100
100
 
101
101
  With `store` left on (the API default), OpenAI can resolve a replayed item from its `id` alone. With `model_options store: false`, the item can only be replayed from its encrypted payload, so request it explicitly:
102
102
 
@@ -118,6 +118,8 @@ model_options web_search: true
118
118
  model_options web_search: {search_context_size: "medium"}
119
119
  ```
120
120
 
121
+ With web search on, riffer also adds `"web_search_call.action.sources"` to the request's `include`, keeping any entries you pass, so `WebSearchDone` carries the sources OpenAI searched.
122
+
121
123
  ## Example
122
124
 
123
125
  ```ruby
@@ -160,9 +162,9 @@ class CalculatorTool < Riffer::Tool
160
162
  description "Performs basic math operations"
161
163
 
162
164
  params do
163
- required :operation, String, enum: ["add", "subtract", "multiply", "divide"]
164
- required :a, Float, description: "First number"
165
- required :b, Float, description: "Second number"
165
+ required :operation, :string, enum: ["add", "subtract", "multiply", "divide"]
166
+ required :a, :number, description: "First number"
167
+ required :b, :number, description: "Second number"
166
168
  end
167
169
 
168
170
  def call(context:, operation:, a:, b:)
@@ -182,6 +184,28 @@ class MathAgent < Riffer::Agent
182
184
  end
183
185
  ```
184
186
 
187
+ ## Deferred Tools (experimental)
188
+
189
+ The OpenAI provider loads [deferred tools](../AGENTS.md#deferred_tools-experimental) natively:
190
+
191
+ ```ruby
192
+ class Assistant < Riffer::Agent
193
+ model 'openai/gpt-5.4-mini'
194
+ instructions "If you need a calendar tool you don't have, call connect_calendar first."
195
+
196
+ uses_tools [ConnectCalendar]
197
+ deferred_tools [ListEvents, CreateEvent]
198
+ end
199
+ ```
200
+
201
+ A deferred tool is left out of the request's `tools`. When a tool [loads it](../TOOLS.md#loading-deferred-tools-experimental), its full definition is sent in an `additional_tools` input item placed right after that tool's `function_call_output`, and the model can call it from its next turn. `tools` stays the same for the whole conversation and earlier input items never change, so loading a tool keeps the prompt cache. The loading tool's own output is empty.
202
+
203
+ Riffer rebuilds the `additional_tools` items from the `loaded_tools` on the conversation's [tool messages](../MESSAGES.md#tool) on every request, so a restored session, or one started on another provider, loads the same tools. A tool loaded again is sent again, after each result that loaded it: without fresh definitions, a model that reloads a tool it already has can keep calling the loading tool instead of the loaded one.
204
+
205
+ OpenAI returns a call to a loaded tool with a `namespace` field, and rejects a later request that replays the call without it. That namespace is always the tool's own name as sent to OpenAI, so riffer adds it back to every replayed call to a deferred tool and never stores it. Tools, the session, callbacks and traces see an ordinary tool call.
206
+
207
+ With the [gateway strategy](../AGENTS.md#deferred-tools-strategy-experimental), `deferred_tools [...], strategy: :gateway`, riffer sends the [gateway](../TOOLS.md#the-gateway-strategy) instead of loading them natively.
208
+
185
209
  ## Web Search
186
210
 
187
211
  Web search allows the model to search the web for up-to-date information. When enabled, the provider injects the `web_search_preview` tool into the request.
@@ -151,9 +151,9 @@ Tools are converted to OpenAI Chat Completions function format. The provider han
151
151
  class CalculatorTool < Riffer::Tool
152
152
  description 'Performs basic math'
153
153
  params do
154
- required :operation, String, enum: ['add', 'subtract', 'multiply', 'divide']
155
- required :a, Float
156
- required :b, Float
154
+ required :operation, :string, enum: ['add', 'subtract', 'multiply', 'divide']
155
+ required :a, :number
156
+ required :b, :number
157
157
  end
158
158
 
159
159
  def call(context:, operation:, a:, b:)
@@ -173,6 +173,14 @@ class MathAgent < Riffer::Agent
173
173
  end
174
174
  ```
175
175
 
176
+ ## Deferred Tools (experimental)
177
+
178
+ OpenRouter has no native deferred loading, so an agent with [deferred tools](../AGENTS.md#deferred_tools-experimental) on OpenRouter needs the [gateway strategy](../AGENTS.md#deferred-tools-strategy-experimental), `deferred_tools [...], strategy: :gateway`; without it, building the agent raises `Riffer::ArgumentError`. Every request then has one extra function in `tools`, the [gateway](../TOOLS.md#the-gateway-strategy), and the model calls a loaded tool through it, so `tools` stays the same and a load keeps the prompt cache. Calls come back under the real tool's name.
179
+
180
+ The gateway is sent with `strict: true`, like every other tool. Its parameters are two required strings, `name` and `arguments` (the loaded tool's arguments, JSON-encoded), with no additional properties, so the schema is valid in strict mode; riffer checks the arguments against the real tool's `params` when it runs.
181
+
182
+ The tool list holding steady keeps the cache valid, but whether the next request reads it is up to OpenRouter's routing. A model served by several upstreams can have its requests spread across them, and they share no cache, so the turn after a load may miss. Pin one upstream with [`provider`](#provider-routing-preferences) (`provider: {order: ['coreweave'], allow_fallbacks: false}`) when cache hits matter.
183
+
176
184
  ## Reasoning Models
177
185
 
178
186
  Reasoning models surface their thought process via OpenRouter's normalised `reasoning_details` field. Enable it with the `reasoning` option:
@@ -149,7 +149,7 @@ Providers convert tools to their native format:
149
149
  class WeatherTool < Riffer::Tool
150
150
  description "Gets weather"
151
151
  params do
152
- required :city, String
152
+ required :city, :string
153
153
  end
154
154
  def call(context:, city:)
155
155
  text("Sunny in #{city}")
@@ -84,7 +84,7 @@
84
84
  description <span class="s">'Current weather for a city'</span>
85
85
 
86
86
  params <span class="k">do</span>
87
- required :city, <span class="c">String</span>, description: <span class="s">'City name'</span>
87
+ required :city, :string, description: <span class="s">'City name'</span>
88
88
  <span class="k">end</span>
89
89
 
90
90
  <span class="k">def</span> call(context:, city:)
@@ -69,6 +69,9 @@ groups:
69
69
  - source: TRACING.md
70
70
  slug: tracing
71
71
  description: OpenTelemetry spans
72
+ - source: STABILITY.md
73
+ slug: stability
74
+ description: What's safe to depend on and how upgrades work
72
75
 
73
76
  - label: Providers
74
77
  tone: jane
@@ -4,6 +4,7 @@
4
4
  class Riffer::Agent::Config
5
5
  DEFAULT_MAX_STEPS = 16 #: Integer
6
6
  STRUCTURED_OUTPUT_STRATEGIES = %i[native prompted].freeze #: Array[Symbol]
7
+ DEFERRED_TOOLS_STRATEGIES = %i[native gateway].freeze #: Array[Symbol]
7
8
 
8
9
  REASONING_LEVELS = %i[off low medium high xhigh max].freeze #: Array[Symbol]
9
10
 
@@ -18,6 +19,8 @@ class Riffer::Agent::Config
18
19
  attr_accessor :max_steps #: Numeric? # @dynamic max_steps, max_steps=
19
20
  attr_reader :reasoning #: Symbol? # @dynamic reasoning
20
21
  attr_accessor :tools_config #: (Array[singleton(Riffer::Tool)] | Proc)? # @dynamic tools_config, tools_config=
22
+ attr_accessor :deferred_tools_config #: (Array[singleton(Riffer::Tool)] | Proc)? # @dynamic deferred_tools_config, deferred_tools_config=
23
+ attr_reader :deferred_tools_strategy #: Symbol # @dynamic deferred_tools_strategy
21
24
  attr_reader :mcp_configs #: Array[Hash[Symbol, untyped]] # @dynamic mcp_configs
22
25
  attr_accessor :skills_config #: Riffer::Skills::Config? # @dynamic skills_config, skills_config=
23
26
  attr_reader :guardrails #: Hash[Symbol, Array[Hash[Symbol, untyped]]] # @dynamic guardrails
@@ -33,6 +36,8 @@ class Riffer::Agent::Config
33
36
  # ?max_steps: Numeric?,
34
37
  # ?reasoning: (Symbol | String)?,
35
38
  # ?tools_config: (Array[singleton(Riffer::Tool)] | Proc)?,
39
+ # ?deferred_tools_config: (Array[singleton(Riffer::Tool)] | Proc)?,
40
+ # ?deferred_tools_strategy: Symbol,
36
41
  # ?mcp_configs: Array[Hash[Symbol, untyped]],
37
42
  # ?tool_runtime: (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)?,
38
43
  # ?skills_config: Riffer::Skills::Config?,
@@ -48,6 +53,8 @@ class Riffer::Agent::Config
48
53
  max_steps: DEFAULT_MAX_STEPS,
49
54
  reasoning: nil,
50
55
  tools_config: nil,
56
+ deferred_tools_config: nil,
57
+ deferred_tools_strategy: :native,
51
58
  mcp_configs: [],
52
59
  tool_runtime: nil,
53
60
  skills_config: nil,
@@ -56,6 +63,7 @@ class Riffer::Agent::Config
56
63
  @model_options = model_options
57
64
  @max_steps = max_steps
58
65
  @tools_config = tools_config
66
+ @deferred_tools_config = deferred_tools_config
59
67
  @mcp_configs = mcp_configs
60
68
  @skills_config = skills_config
61
69
  @guardrails = guardrails
@@ -64,6 +72,7 @@ class Riffer::Agent::Config
64
72
  self.instructions = instructions
65
73
  self.structured_output = structured_output
66
74
  self.structured_output_strategy = structured_output_strategy
75
+ self.deferred_tools_strategy = deferred_tools_strategy
67
76
  self.reasoning = reasoning
68
77
  self.tool_runtime = tool_runtime if tool_runtime
69
78
  end
@@ -95,6 +104,17 @@ class Riffer::Agent::Config
95
104
  @structured_output_strategy = value
96
105
  end
97
106
 
107
+ #--
108
+ #: (Symbol) -> Symbol
109
+ def deferred_tools_strategy=(value)
110
+ unless DEFERRED_TOOLS_STRATEGIES.include?(value)
111
+ raise Riffer::ArgumentError,
112
+ "deferred_tools_strategy must be one of #{DEFERRED_TOOLS_STRATEGIES.inspect}, got #{value.inspect}"
113
+ end
114
+
115
+ @deferred_tools_strategy = value
116
+ end
117
+
98
118
  #--
99
119
  #: ((Symbol | String)?) -> Symbol?
100
120
  def reasoning=(value)
@@ -189,6 +209,7 @@ class Riffer::Agent::Config
189
209
  @mcp_configs = Riffer::Helpers::DeepDup.call(source.mcp_configs)
190
210
  @guardrails = Riffer::Helpers::DeepDup.call(source.guardrails)
191
211
  @tools_config = Riffer::Helpers::DeepDup.call(source.tools_config)
212
+ @deferred_tools_config = Riffer::Helpers::DeepDup.call(source.deferred_tools_config)
192
213
  @skills_config = source.skills_config&.dup
193
214
  @structured_output = source.structured_output&.dup
194
215
  end
@@ -15,12 +15,14 @@ class Riffer::Agent::Context
15
15
  raise Riffer::ArgumentError,
16
16
  "Reserved keys cannot be passed in context: #{reserved.join(', ')}"
17
17
  end
18
+ warn_deferred_tools_key if data.key?(:deferred_tools)
18
19
 
19
20
  @data = data.dup
20
21
  @data[:skills] = nil
21
22
  @data[:token_usage] = nil
22
23
  @data[:mcp_progressive_tools] = nil
23
24
  @data[:discovered_tools] = nil
25
+ @deferred_tools = nil
24
26
  end
25
27
 
26
28
  #--
@@ -71,15 +73,7 @@ class Riffer::Agent::Context
71
73
  #--
72
74
  #: (Array[singleton(Riffer::Tool)]?) -> Array[singleton(Riffer::Tool)]?
73
75
  def mcp_progressive_tools=(value)
74
- valid = value.nil? || (
75
- value.is_a?(Array) &&
76
- value.all? { |tool| tool.is_a?(Class) && tool < Riffer::Tool }
77
- )
78
- unless valid
79
- raise Riffer::ArgumentError,
80
- "mcp_progressive_tools must be an Array of Riffer::Tool subclasses or nil, got #{value.class}"
81
- end
82
- @data[:mcp_progressive_tools] = value
76
+ @data[:mcp_progressive_tools] = validate_tool_classes(:mcp_progressive_tools, value)
83
77
  end
84
78
 
85
79
  #--
@@ -91,15 +85,15 @@ class Riffer::Agent::Context
91
85
  #--
92
86
  #: (Array[singleton(Riffer::Tool)]?) -> Array[singleton(Riffer::Tool)]?
93
87
  def discovered_tools=(value)
94
- valid = value.nil? || (
95
- value.is_a?(Array) &&
96
- value.all? { |tool| tool.is_a?(Class) && tool < Riffer::Tool }
97
- )
98
- unless valid
99
- raise Riffer::ArgumentError,
100
- "discovered_tools must be an Array of Riffer::Tool subclasses or nil, got #{value.class}"
101
- end
102
- @data[:discovered_tools] = value
88
+ @data[:discovered_tools] = validate_tool_classes(:discovered_tools, value)
89
+ end
90
+
91
+ attr_reader :deferred_tools #: Array[singleton(Riffer::Tool)]? # @dynamic deferred_tools
92
+
93
+ #--
94
+ #: (Array[singleton(Riffer::Tool)]?) -> Array[singleton(Riffer::Tool)]?
95
+ def deferred_tools=(value)
96
+ @deferred_tools = validate_tool_classes(:deferred_tools, value)
103
97
  end
104
98
 
105
99
  #--
@@ -120,4 +114,28 @@ class Riffer::Agent::Context
120
114
  def to_h
121
115
  @data.dup
122
116
  end
117
+
118
+ private
119
+
120
+ #--
121
+ #: (Symbol, Array[singleton(Riffer::Tool)]?) -> Array[singleton(Riffer::Tool)]?
122
+ def validate_tool_classes(name, value)
123
+ valid = value.nil? || (value.is_a?(Array) && value.all? { |tool| tool.is_a?(Class) && tool < Riffer::Tool })
124
+ unless valid
125
+ raise Riffer::ArgumentError,
126
+ "#{name} must be an Array of Riffer::Tool subclasses or nil, got #{value.class}"
127
+ end
128
+
129
+ value
130
+ end
131
+
132
+ #--
133
+ #: () -> void
134
+ def warn_deferred_tools_key
135
+ Riffer::Deprecation.warn(
136
+ id: :context_deferred_tools_key,
137
+ message: "Passing :deferred_tools in context: is deprecated; a future breaking release reserves the key " \
138
+ "for the agent's deferred tools (context.deferred_tools). Rename the key.",
139
+ )
140
+ end
123
141
  end