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
@@ -129,9 +129,9 @@ module Riffer::Agent::Run
129
129
  #--
130
130
  #: (Riffer::Agent, Enumerator::Yielder, ?Hash[String, String]) -> Riffer::Messages::Assistant
131
131
  def accumulate_streamed_response(agent, stream_yielder, tags = {})
132
- accumulated_content = +""
133
- accumulated_tool_calls = [] #: Array[Riffer::Messages::Assistant::ToolCall]
134
- accumulated_reasoning = [] #: Array[Riffer::Messages::Assistant::ReasoningPart]
132
+ # Text deltas between two non-text events form one text part.
133
+ parts = [] #: Array[String | Riffer::Messages::Assistant::ReasoningPart | Riffer::Messages::Assistant::ToolCall | Riffer::Messages::Assistant::ServerToolPart]
134
+ final_text = nil #: String?
135
135
  accumulated_token_usage = nil #: Riffer::Providers::TokenUsage?
136
136
  accumulated_finish_reason = nil #: Symbol?
137
137
  accumulated_finish_reason_raw = nil #: String?
@@ -141,21 +141,20 @@ module Riffer::Agent::Run
141
141
 
142
142
  case event
143
143
  when Riffer::StreamEvents::TextDelta
144
+ last = parts.last
144
145
  # << rather than +=, which copies the whole buffer per delta (O(n^2)
145
146
  # over a stream).
146
- accumulated_content << event.content
147
+ last.is_a?(String) ? last << event.content : parts << event.content.dup
147
148
  when Riffer::StreamEvents::TextDone
148
- # replace, not =, so a later delta's << can never mutate the string
149
- # this event holds.
150
- accumulated_content.replace(event.content)
149
+ final_text = event.content
151
150
  when Riffer::StreamEvents::ToolCallDone
152
- accumulated_tool_calls << Riffer::Messages::Assistant::ToolCall.new(
151
+ parts << Riffer::Messages::Assistant::ToolCall.new(
153
152
  call_id: event.call_id,
154
153
  name: event.name,
155
154
  arguments: event.arguments,
156
155
  )
157
- when Riffer::StreamEvents::ReasoningDone
158
- accumulated_reasoning << event.part
156
+ when Riffer::StreamEvents::ReasoningDone, Riffer::StreamEvents::ServerToolDone
157
+ parts << event.part
159
158
  when Riffer::StreamEvents::TokenUsageDone
160
159
  accumulated_token_usage = event.token_usage
161
160
  when Riffer::StreamEvents::FinishReasonDone
@@ -165,15 +164,31 @@ module Riffer::Agent::Run
165
164
  end
166
165
 
167
166
  Riffer::Messages::Assistant.new(
168
- accumulated_content,
169
- tool_calls: accumulated_tool_calls,
170
- reasoning: accumulated_reasoning,
167
+ parts: streamed_parts(parts, final_text),
171
168
  token_usage: accumulated_token_usage,
172
169
  finish_reason: accumulated_finish_reason,
173
170
  finish_reason_raw: accumulated_finish_reason_raw,
174
171
  )
175
172
  end
176
173
 
174
+ # TextDone is the adapter's authoritative full text, so it wins over the deltas.
175
+ #--
176
+ #: (Array[String | Riffer::Messages::Assistant::ReasoningPart | Riffer::Messages::Assistant::ToolCall | Riffer::Messages::Assistant::ServerToolPart], String?) -> Array[Riffer::Messages::Assistant::TextPart | Riffer::Messages::Assistant::ReasoningPart | Riffer::Messages::Assistant::ToolCall | Riffer::Messages::Assistant::ServerToolPart]
177
+ def streamed_parts(parts, final_text)
178
+ streamed_text = parts.grep(String).join
179
+ if final_text && final_text != streamed_text
180
+ index = parts.index { |part| part.is_a?(String) } || parts.length
181
+ parts = parts.grep_v(String)
182
+ parts.insert(index, final_text)
183
+ end
184
+
185
+ parts.filter_map do |part|
186
+ next part unless part.is_a?(String)
187
+
188
+ Riffer::Messages::Assistant::TextPart.new(part) unless part.empty?
189
+ end
190
+ end
191
+
177
192
  #--
178
193
  #: (Enumerator::Yielder?, Array[Riffer::Guardrails::Modification], Array[Riffer::Guardrails::Modification]) -> void
179
194
  def record_modifications!(stream_yielder, all_modifications, new_modifications)
@@ -262,17 +277,29 @@ module Riffer::Agent::Run
262
277
  def execute_tool_calls(agent, assistant_message, tool_calls: assistant_message.tool_calls, tags: {})
263
278
  return if tool_calls.empty?
264
279
 
265
- results = agent.tool_runtime.execute(
266
- tool_calls,
267
- tools: effective_tools(agent),
280
+ # Only from earlier turns: the model made every call in this one before seeing any of its loads, even when a
281
+ # resumed turn already has some of its results in the session.
282
+ earlier = agent.session.messages.take_while { |message| !message.equal?(assistant_message) }
283
+ loaded = loaded_tools(earlier, agent.deferred_tools)
284
+ unloaded_names = (agent.deferred_tools - loaded).map(&:name)
285
+ # Refused here rather than by the runtime, since a custom runtime may ignore +tools:+.
286
+ refused, callable = tool_calls.partition { |tool_call| unloaded_names.include?(tool_call.name) }
287
+
288
+ dispatched = agent.tool_runtime.execute(
289
+ callable,
290
+ tools: effective_tools(agent) + loaded,
268
291
  context: agent.context,
269
292
  assistant_message: assistant_message,
270
293
  tags: tags,
271
- )
294
+ ).to_h { |tool_call, result| [tool_call, reject_invalid_load(agent, result)] }
272
295
 
273
- inject_discovered_tools(agent, results)
296
+ inject_discovered_tools(agent, dispatched)
297
+
298
+ results = dispatched.merge(refused.to_h { |tool_call| [tool_call, tool_not_loaded(tool_call)] })
299
+ tool_calls.each do |tool_call|
300
+ result = results.fetch(tool_call, nil)
301
+ next unless result
274
302
 
275
- results.each do |tool_call, result|
276
303
  agent.session.add(
277
304
  Riffer::Messages::Tool.new(
278
305
  result.content,
@@ -280,15 +307,45 @@ module Riffer::Agent::Run
280
307
  name: tool_call.name,
281
308
  error: result.error_message,
282
309
  error_type: result.error_type,
310
+ loaded_tools: result.loaded_tools.map(&:name),
283
311
  ),
284
312
  )
285
313
  end
286
314
  end
287
315
 
288
316
  #--
289
- #: (Riffer::Agent, Array[[Riffer::Messages::Assistant::ToolCall, Riffer::Tools::Response]]) -> void
317
+ #: (Array[Riffer::Messages::Base], Array[singleton(Riffer::Tool)]) -> Array[singleton(Riffer::Tool)]
318
+ def loaded_tools(messages, deferred_tools)
319
+ return [] if deferred_tools.empty?
320
+
321
+ tool_messages = messages.grep(Riffer::Messages::Tool) #: Array[Riffer::Messages::Tool]
322
+ names = tool_messages.reject(&:error?).flat_map(&:loaded_tools)
323
+ # By name, since an agent rebuilt with +from_h+ holds body-less shells rather than the original classes.
324
+ deferred_tools.select { |tool| names.include?(tool.name) }
325
+ end
326
+
327
+ #--
328
+ #: (Riffer::Agent, Riffer::Tools::Response) -> Riffer::Tools::Response
329
+ def reject_invalid_load(agent, result)
330
+ invalid = result.loaded_tools.map(&:name) - agent.deferred_tools.map(&:name)
331
+ return result if invalid.empty?
332
+
333
+ Riffer::Tools::Response.error(
334
+ "Cannot load #{invalid.join(', ')}: only this agent's deferred tools can be loaded",
335
+ type: :invalid_tool_load,
336
+ )
337
+ end
338
+
339
+ #--
340
+ #: (Riffer::Messages::Assistant::ToolCall) -> Riffer::Tools::Response
341
+ def tool_not_loaded(tool_call)
342
+ Riffer::Tools::Response.error("Tool '#{tool_call.name}' has not been loaded", type: :tool_not_loaded)
343
+ end
344
+
345
+ #--
346
+ #: (Riffer::Agent, Hash[Riffer::Messages::Assistant::ToolCall, Riffer::Tools::Response]) -> void
290
347
  def inject_discovered_tools(agent, results)
291
- to_inject = results.flat_map do |_, result|
348
+ to_inject = results.values.flat_map do |result|
292
349
  result.is_a?(Riffer::Mcp::SearchTool::Result) ? result.discovered_tools : [] #: Array[singleton(Riffer::Tool)]
293
350
  end
294
351
  return if to_inject.empty?
@@ -356,6 +413,10 @@ module Riffer::Agent::Run
356
413
  opts[:structured_output] = agent.structured_output if agent.structured_output
357
414
  reasoning = agent.config.reasoning
358
415
  opts[:riffer_reasoning_level] = reasoning if reasoning
416
+ unless agent.deferred_tools.empty?
417
+ opts[:deferred_tools] = agent.deferred_tools
418
+ opts[:riffer_deferred_tools_strategy] = agent.config.deferred_tools_strategy
419
+ end
359
420
  # Providers extract :tags for native request metadata; it never reaches an
360
421
  # SDK call verbatim.
361
422
  opts[:tags] = tags unless tags.empty?
@@ -30,6 +30,8 @@ module Riffer::Agent::Serializer
30
30
  structured_output_strategy: config.structured_output_strategy,
31
31
  reasoning: config.reasoning,
32
32
  tools: agent.tools.map { |tool_class| tool_descriptor(tool_class) },
33
+ deferred_tools: agent.deferred_tools.map { |tool_class| tool_descriptor(tool_class) },
34
+ deferred_tools_strategy: config.deferred_tools_strategy,
33
35
  }
34
36
  end
35
37
 
@@ -71,6 +73,7 @@ module Riffer::Agent::Serializer
71
73
  #: (Hash[Symbol, untyped], context: Hash[Symbol, untyped]?, session: Riffer::Agent::Session?, tool_resolver: ^(Hash[Symbol, untyped]) -> singleton(Riffer::Tool), tool_runtime: (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)?) -> Riffer::Agent
72
74
  def decode_v1(hash, context:, session:, tool_resolver:, tool_runtime:)
73
75
  tools = Array(hash[:tools]).map { |descriptor| tool_resolver.call(descriptor) }
76
+ deferred_tools = Array(hash[:deferred_tools]).map { |descriptor| tool_resolver.call(descriptor) }
74
77
 
75
78
  config_args = {
76
79
  identifier: hash[:identifier],
@@ -82,6 +85,8 @@ module Riffer::Agent::Serializer
82
85
  max_steps: decode_max_steps(hash),
83
86
  reasoning: hash[:reasoning],
84
87
  tools_config: tools,
88
+ deferred_tools_config: deferred_tools,
89
+ deferred_tools_strategy: (hash[:deferred_tools_strategy] || :native).to_sym,
85
90
  } #: Hash[Symbol, untyped]
86
91
  # Config#tool_runtime= rejects nil.
87
92
  config_args[:tool_runtime] = tool_runtime if tool_runtime
@@ -191,16 +191,7 @@ class Riffer::Agent::Session
191
191
  def rebuild_message(old, attrs)
192
192
  case old
193
193
  when Riffer::Messages::Assistant
194
- Riffer::Messages::Assistant.new(
195
- attrs.fetch(:content, old.content),
196
- id: attrs.fetch(:id, old.id),
197
- tool_calls: attrs.fetch(:tool_calls, old.tool_calls),
198
- reasoning: attrs.fetch(:reasoning, old.reasoning),
199
- token_usage: attrs.fetch(:token_usage, old.token_usage),
200
- structured_output: attrs.fetch(:structured_output, old.structured_output),
201
- finish_reason: attrs.fetch(:finish_reason, old.finish_reason),
202
- finish_reason_raw: attrs.fetch(:finish_reason_raw, old.finish_reason_raw),
203
- )
194
+ rebuild_assistant(old, attrs)
204
195
  when Riffer::Messages::Tool
205
196
  Riffer::Messages::Tool.new(
206
197
  attrs.fetch(:content, old.content),
@@ -209,6 +200,7 @@ class Riffer::Agent::Session
209
200
  id: attrs.fetch(:id, old.id),
210
201
  error: attrs.fetch(:error, old.error),
211
202
  error_type: attrs.fetch(:error_type, old.error_type),
203
+ loaded_tools: attrs.fetch(:loaded_tools, old.loaded_tools),
212
204
  )
213
205
  when Riffer::Messages::User
214
206
  Riffer::Messages::User.new(
@@ -223,4 +215,36 @@ class Riffer::Agent::Session
223
215
  )
224
216
  end
225
217
  end
218
+
219
+ # A +content+, +tool_calls+ or +reasoning+ edit rebuilds the parts in the default order, which
220
+ # drops server tool parts; +parts:+ replaces them as given.
221
+ #--
222
+ #: (Riffer::Messages::Assistant, Hash[Symbol, untyped]) -> Riffer::Messages::Assistant
223
+ def rebuild_assistant(old, attrs)
224
+ options = {
225
+ id: attrs.fetch(:id, old.id),
226
+ token_usage: attrs.fetch(:token_usage, old.token_usage),
227
+ structured_output: attrs.fetch(:structured_output, old.structured_output),
228
+ finish_reason: attrs.fetch(:finish_reason, old.finish_reason),
229
+ finish_reason_raw: attrs.fetch(:finish_reason_raw, old.finish_reason_raw),
230
+ } #: Hash[Symbol, untyped]
231
+ field_edit = attrs.key?(:content) || attrs.key?(:tool_calls) || attrs.key?(:reasoning)
232
+
233
+ if attrs.key?(:parts) || !field_edit
234
+ return Riffer::Messages::Assistant.new(
235
+ attrs[:content],
236
+ parts: attrs.fetch(:parts, old.parts),
237
+ tool_calls: attrs.fetch(:tool_calls, []),
238
+ reasoning: attrs.fetch(:reasoning, []),
239
+ **options,
240
+ )
241
+ end
242
+
243
+ Riffer::Messages::Assistant.new(
244
+ attrs.fetch(:content, old.content),
245
+ tool_calls: attrs.fetch(:tool_calls, old.tool_calls),
246
+ reasoning: attrs.fetch(:reasoning, old.reasoning),
247
+ **options,
248
+ )
249
+ end
226
250
  end
data/lib/riffer/agent.rb CHANGED
@@ -86,10 +86,25 @@ class Riffer::Agent
86
86
  value.nil? ? config.tools_config : (config.tools_config = value)
87
87
  end
88
88
 
89
+ #--
90
+ #: (?(Array[singleton(Riffer::Tool)] | Proc)?, ?strategy: Symbol?) -> (Array[singleton(Riffer::Tool)] | Proc)?
91
+ def self.deferred_tools(value = nil, strategy: nil)
92
+ config.deferred_tools_config = value if value
93
+ config.deferred_tools_strategy = strategy if strategy
94
+ config.deferred_tools_config
95
+ end
96
+
97
+ # @deprecated MCP client support will be removed; wrap the +mcp+ gem in your own Riffer::Tool (see docs/MCP.md).
89
98
  # +progressive+ exposes +mcp_search+ instead of every tool schema up front.
90
99
  #--
91
100
  #: (String | Symbol, ?progressive: bool) -> void
92
101
  def self.use_mcp(tag, progressive: true)
102
+ Riffer::Deprecation.warn(
103
+ id: :use_mcp,
104
+ message: "use_mcp is deprecated; MCP client support will be removed in a future release. " \
105
+ "Wrap the mcp gem in your own Riffer::Tool instead (see docs/MCP.md).",
106
+ )
107
+
93
108
  config.add_mcp(tag, progressive: progressive)
94
109
  end
95
110
 
@@ -203,6 +218,7 @@ class Riffer::Agent
203
218
 
204
219
  @structured_output = resolve_structured_output
205
220
  @tools = resolve_tools
221
+ @context.deferred_tools = resolve_deferred_tools
206
222
  @tool_runtime = resolve_tool_runtime
207
223
 
208
224
  @instruction_message = build_instruction_message
@@ -220,6 +236,12 @@ class Riffer::Agent
220
236
  config.identifier || self.class.identifier
221
237
  end
222
238
 
239
+ #--
240
+ #: () -> Array[singleton(Riffer::Tool)]
241
+ def deferred_tools
242
+ @context.deferred_tools || []
243
+ end
244
+
223
245
  #--
224
246
  #: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::User::FilePart]?, ?tags: Hash[(String | Symbol), untyped]) -> Riffer::Agent::Response
225
247
  def generate(prompt = nil, files: nil, tags: {})
@@ -362,6 +384,27 @@ class Riffer::Agent
362
384
  tools
363
385
  end
364
386
 
387
+ #--
388
+ #: () -> Array[singleton(Riffer::Tool)]
389
+ def resolve_deferred_tools
390
+ deferred = Riffer::Helpers::CallOrValue.resolve(@config.deferred_tools_config, context: @context, default: [])
391
+ return deferred if deferred.empty?
392
+
393
+ gateway = @config.deferred_tools_strategy == :gateway
394
+ unless gateway || @provider.class.supports_deferred_tools?
395
+ raise Riffer::ArgumentError,
396
+ "Provider #{@provider_name} does not support deferred tools natively; " \
397
+ "use deferred_tools(..., strategy: :gateway) to load them through a gateway tool"
398
+ end
399
+
400
+ tools = @tools + (@context.mcp_progressive_tools || []) + deferred
401
+ # The gateway goes on every request alongside the agent's tools, so no tool can share its name.
402
+ tools += [Riffer::Providers::DeferredToolGateway::Tool] if gateway
403
+ assert_distinct_tool_names!(tools)
404
+ deferred.each(&:validate_as_tool!)
405
+ deferred
406
+ end
407
+
365
408
  #--
366
409
  #: () -> Riffer::Tools::Runtime
367
410
  def resolve_tool_runtime
@@ -0,0 +1,53 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ class Riffer::Config::Future
5
+ # Steep can't type an empty literal; drop the ignore once FLAGS has an entry.
6
+ # steep:ignore:start
7
+ FLAGS = {}.freeze #: Hash[Symbol, { default: bool }]
8
+ # steep:ignore:end
9
+
10
+ # @rbs @flags: Hash[Symbol, { default: bool }]
11
+ # @rbs @enabled: Hash[Symbol, bool]
12
+
13
+ #--
14
+ #: (?flags: Hash[Symbol, { default: bool }]) -> void
15
+ def initialize(flags: FLAGS)
16
+ @flags = flags
17
+ @enabled = {}
18
+ flags.each_key { |name| define_singleton_method(:"#{name}=") { |value| set(name, value) } }
19
+ end
20
+
21
+ #--
22
+ #: (Symbol) -> bool
23
+ def enabled?(name)
24
+ flag(name)[:default] || @enabled.fetch(name, false)
25
+ end
26
+
27
+ private
28
+
29
+ #--
30
+ #: (Symbol, untyped) -> void
31
+ def set(name, value)
32
+ graduated = flag(name)[:default]
33
+ enabled = Riffer::Helpers::Boolean.coerce(value, attribute: "config.future.#{name}")
34
+
35
+ if graduated
36
+ Riffer::Deprecation.warn(
37
+ id: :"future_#{name}",
38
+ message: "config.future.#{name} is now the default and setting it has no effect; remove it.",
39
+ )
40
+ end
41
+
42
+ @enabled[name] = enabled
43
+ end
44
+
45
+ #--
46
+ #: (Symbol) -> { default: bool }
47
+ def flag(name)
48
+ @flags.fetch(name) do
49
+ known = @flags.empty? ? "none" : @flags.keys.map(&:inspect).join(", ")
50
+ raise Riffer::ArgumentError, "unknown future flag #{name.inspect} (known flags: #{known})"
51
+ end
52
+ end
53
+ end
@@ -1,6 +1,7 @@
1
1
  # frozen_string_literal: true
2
2
  # rbs_inline: enabled
3
3
 
4
+ # @deprecated MCP client support will be removed; wrap the +mcp+ gem in your own Riffer::Tool (see docs/MCP.md).
4
5
  class Riffer::Config::Mcp
5
6
  attr_reader :credentials #: untyped # @dynamic credentials
6
7
 
@@ -16,6 +17,8 @@ class Riffer::Config::Mcp
16
17
  #--
17
18
  #: (untyped) -> void
18
19
  def credentials=(value)
20
+ warn_deprecated
21
+
19
22
  unless value.nil? || value.respond_to?(:call)
20
23
  raise Riffer::ArgumentError, "credentials must respond to #call or be nil"
21
24
  end
@@ -26,6 +29,20 @@ class Riffer::Config::Mcp
26
29
  #--
27
30
  #: (untyped) -> void
28
31
  def discovery_runner=(value)
32
+ warn_deprecated
33
+
29
34
  @discovery_runner = Riffer::Helpers::Validate.runner(value, attribute: "discovery_runner")
30
35
  end
36
+
37
+ private
38
+
39
+ #--
40
+ #: () -> void
41
+ def warn_deprecated
42
+ Riffer::Deprecation.warn(
43
+ id: :config_mcp,
44
+ message: "config.mcp is deprecated; MCP client support will be removed in a future release. " \
45
+ "Wrap the mcp gem in your own Riffer::Tool instead (see docs/MCP.md).",
46
+ )
47
+ end
31
48
  end
@@ -4,11 +4,7 @@
4
4
  # @deprecated Set pricing in a catalog file instead (see docs/CATALOG.md).
5
5
  # A catalog entry's pricing wins over rates registered here.
6
6
  class Riffer::Config::Pricing
7
- DEPRECATION_MESSAGE = "riffer: config.pricing is deprecated; move rates into a catalog file " \
8
- "listed in config.catalog_files (see docs/CATALOG.md)" #: String
9
-
10
7
  # @rbs @rates: Hash[String, Riffer::Catalog::Rates]
11
- # @rbs self.@warned: bool
12
8
 
13
9
  #--
14
10
  #: () -> void
@@ -19,7 +15,11 @@ class Riffer::Config::Pricing
19
15
  #--
20
16
  #: ((String | Array[String]), input: Numeric, output: Numeric, ?cache_read: Numeric?, ?cache_write: Numeric?) -> void
21
17
  def set(models, input:, output:, cache_read: nil, cache_write: nil)
22
- self.class.warn_deprecated
18
+ Riffer::Deprecation.warn(
19
+ id: :config_pricing,
20
+ message: "config.pricing is deprecated and will be removed in a future version; move rates into a catalog " \
21
+ "file listed in config.catalog_files (see docs/CATALOG.md).",
22
+ )
23
23
 
24
24
  ids = models.is_a?(Array) ? models : [models]
25
25
  raise Riffer::ArgumentError, "at least one model id is required" if ids.empty?
@@ -41,14 +41,4 @@ class Riffer::Config::Pricing
41
41
  def empty?
42
42
  @rates.empty?
43
43
  end
44
-
45
- # Once per process, so a boot that sets many models logs one line.
46
- #--
47
- #: () -> void
48
- def self.warn_deprecated
49
- return if @warned
50
-
51
- @warned = true
52
- Kernel.warn(DEPRECATION_MESSAGE)
53
- end
54
44
  end
data/lib/riffer/config.rb CHANGED
@@ -20,7 +20,18 @@ class Riffer::Config
20
20
 
21
21
  attr_reader :openrouter #: Riffer::Config::OpenRouter # @dynamic openrouter
22
22
 
23
- attr_reader :evals #: Riffer::Config::Evals # @dynamic evals
23
+ # @rbs @evals: Riffer::Config::Evals
24
+
25
+ #--
26
+ #: () -> Riffer::Config::Evals
27
+ def evals
28
+ Riffer::Deprecation.warn(
29
+ id: :config_evals,
30
+ message: "config.evals is deprecated and will move out of riffer into the riffer-evals gem " \
31
+ "(see docs/EVALS.md).",
32
+ )
33
+ @evals
34
+ end
24
35
 
25
36
  attr_reader :mcp #: Riffer::Config::Mcp # @dynamic mcp
26
37
 
@@ -45,6 +56,8 @@ class Riffer::Config
45
56
 
46
57
  attr_reader :files #: Riffer::Config::Files # @dynamic files
47
58
 
59
+ attr_reader :future #: Riffer::Config::Future # @dynamic future
60
+
48
61
  # @deprecated Use +catalog_files+.
49
62
  attr_reader :pricing #: Riffer::Config::Pricing # @dynamic pricing
50
63
 
@@ -86,6 +99,18 @@ class Riffer::Config
86
99
  @message_id_strategy = value
87
100
  end
88
101
 
102
+ attr_reader :deprecations #: (Symbol | ^(Riffer::Deprecation::Event) -> void) # @dynamic deprecations
103
+
104
+ #--
105
+ #: ((Symbol | ^(Riffer::Deprecation::Event) -> void)) -> void
106
+ def deprecations=(value)
107
+ unless Riffer::Deprecation::MODES.include?(value) || value.respond_to?(:call)
108
+ raise Riffer::ArgumentError,
109
+ "deprecations must be one of #{Riffer::Deprecation::MODES.inspect} or a callable, got #{value.inspect}"
110
+ end
111
+ @deprecations = value
112
+ end
113
+
89
114
  #--
90
115
  #: () -> void
91
116
  def initialize
@@ -102,9 +127,11 @@ class Riffer::Config
102
127
  @skills = Skills.new
103
128
  @tracing = Tracing.new
104
129
  @files = Files.new
130
+ @future = Future.new
105
131
  @pricing = Pricing.new
106
132
  no_files = [] #: Array[String]
107
133
  @catalog_files = no_files.freeze
108
134
  @message_id_strategy = :none
135
+ @deprecations = :warn
109
136
  end
110
137
  end
@@ -0,0 +1,25 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ class Riffer::Deprecation::Event
5
+ attr_reader :id #: Symbol # @dynamic id
6
+
7
+ attr_reader :message #: String # @dynamic message
8
+
9
+ attr_reader :location #: String? # @dynamic location
10
+
11
+ #--
12
+ #: (id: Symbol, message: String, location: String?) -> void
13
+ def initialize(id:, message:, location:)
14
+ @id = id
15
+ @message = message
16
+ @location = location
17
+ end
18
+
19
+ #--
20
+ #: () -> String
21
+ def to_s
22
+ text = "riffer: #{message}"
23
+ location ? "#{text} Called from #{location}." : text
24
+ end
25
+ end
@@ -0,0 +1,60 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ module Riffer::Deprecation
5
+ extend self
6
+
7
+ # @rbs @mutex: Thread::Mutex
8
+ # @rbs @reported: Set[[Symbol, String?]]
9
+
10
+ MODES = %i[warn raise silence].freeze #: Array[Symbol]
11
+
12
+ LIB_DIR = "#{File.dirname(__FILE__, 2)}/".freeze #: String
13
+ ALLOWED_KEY = :riffer_deprecations_allowed #: Symbol
14
+ private_constant :LIB_DIR, :ALLOWED_KEY
15
+
16
+ @mutex = Mutex.new
17
+ @reported = Set.new
18
+
19
+ #--
20
+ #: (id: Symbol, message: String) -> void
21
+ def warn(id:, message:)
22
+ return if Fiber[ALLOWED_KEY]
23
+
24
+ frame = caller_locations&.find { |location| !location.path.to_s.start_with?(LIB_DIR) }
25
+ location = frame && "#{frame.path}:#{frame.lineno}"
26
+ event = Event.new(id: id, message: message, location: location)
27
+
28
+ case (handler = Riffer.config.deprecations)
29
+ when :silence then nil
30
+ # Every call, not once per line, so a suite in :raise mode fails on each offending test.
31
+ when :raise then raise Riffer::DeprecationError, event.to_s
32
+ when :warn then Kernel.warn(event.to_s) if first_report?(event)
33
+ else
34
+ callable = handler #: ^(Event) -> void
35
+ callable.call(event) if first_report?(event)
36
+ end
37
+ end
38
+
39
+ #--
40
+ #: [T] () { () -> T } -> T
41
+ def allow
42
+ previous = Fiber[ALLOWED_KEY] #: bool?
43
+ # Fiber storage is inherited by threads and fibers spawned inside the block,
44
+ # so work the block fans out stays silenced while other threads are not.
45
+ Fiber[ALLOWED_KEY] = true
46
+ begin
47
+ yield
48
+ ensure
49
+ Fiber[ALLOWED_KEY] = previous
50
+ end
51
+ end
52
+
53
+ private
54
+
55
+ #--
56
+ #: (Event) -> bool
57
+ def first_report?(event)
58
+ !@mutex.synchronize { @reported.add?([event.id, event.location]) }.nil?
59
+ end
60
+ end
@@ -49,6 +49,13 @@ class Riffer::Evals::Evaluator
49
49
 
50
50
  private
51
51
 
52
+ #--
53
+ #: (Class) -> void
54
+ def inherited(subclass)
55
+ super
56
+ Riffer::Deprecation.warn(id: :evals, message: Riffer::Evals::DEPRECATION_MESSAGE)
57
+ end
58
+
52
59
  #--
53
60
  #: () -> String
54
61
  def derived_identifier
@@ -100,7 +107,7 @@ class Riffer::Evals::Evaluator
100
107
  #: () -> Riffer::Evals::Judge
101
108
  def judge
102
109
  @judge ||= begin
103
- model = self.class.judge_model || Riffer.config.evals.judge_model
110
+ model = Riffer::Deprecation.allow { self.class.judge_model || Riffer.config.evals.judge_model }
104
111
  unless model
105
112
  raise Riffer::ArgumentError,
106
113
  "No judge model configured. Set judge_model on the evaluator or Riffer.config.evals.judge_model"
@@ -7,6 +7,7 @@ module Riffer::Evals::EvaluatorRunner
7
7
  #--
8
8
  #: (agent: singleton(Riffer::Agent), scenarios: Array[Hash[Symbol, untyped]], evaluators: Array[singleton(Riffer::Evals::Evaluator)], ?context: Hash[Symbol, untyped]?) -> Riffer::Evals::RunResult
9
9
  def run(agent:, scenarios:, evaluators:, context: nil)
10
+ Riffer::Deprecation.warn(id: :evals, message: Riffer::Evals::DEPRECATION_MESSAGE)
10
11
  validate_agent!(agent)
11
12
  validate_evaluators!(evaluators)
12
13
 
@@ -13,8 +13,8 @@ class Riffer::Evals::Judge
13
13
  description "Submit your evaluation score and reasoning"
14
14
 
15
15
  params do
16
- required :score, Float, description: "Evaluation score between 0.0 and 1.0"
17
- required :reason, String, description: "Brief explanation for the score"
16
+ required :score, :number, description: "Evaluation score between 0.0 and 1.0"
17
+ required :reason, :string, description: "Brief explanation for the score"
18
18
  end
19
19
 
20
20
  #--
data/lib/riffer/evals.rb CHANGED
@@ -2,4 +2,6 @@
2
2
  # rbs_inline: enabled
3
3
 
4
4
  module Riffer::Evals
5
+ DEPRECATION_MESSAGE = "Riffer::Evals is deprecated and will move out of riffer into the riffer-evals gem " \
6
+ "(see docs/EVALS.md)." #: String
5
7
  end
@@ -19,7 +19,7 @@ class Riffer::Mcp::SearchTool < Riffer::Tool
19
19
  description "Search for available MCP tools by name or description."
20
20
 
21
21
  params do
22
- required :query, String, description: "Non-empty substring to filter tools by name or description."
22
+ required :query, :string, description: "Non-empty substring to filter tools by name or description."
23
23
  end
24
24
 
25
25
  #--