riffer 0.56.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 (88) hide show
  1. checksums.yaml +4 -4
  2. data/.release-please-manifest.json +1 -1
  3. data/CHANGELOG.md +19 -0
  4. data/README.md +1 -1
  5. data/docs/AGENTS.md +105 -50
  6. data/docs/AGENT_LIFECYCLE.md +1 -1
  7. data/docs/CONFIGURATION.md +7 -3
  8. data/docs/EVALS.md +2 -0
  9. data/docs/MCP.md +36 -0
  10. data/docs/MESSAGES.md +13 -0
  11. data/docs/OVERVIEW.md +7 -7
  12. data/docs/SERIALIZATION.md +12 -2
  13. data/docs/SKILLS.md +1 -1
  14. data/docs/STABILITY.md +1 -1
  15. data/docs/TOOLS.md +93 -37
  16. data/docs/TOOL_ADVANCED.md +7 -0
  17. data/docs/providers/AMAZON_BEDROCK.md +6 -2
  18. data/docs/providers/ANTHROPIC.md +35 -2
  19. data/docs/providers/AZURE_OPENAI.md +9 -3
  20. data/docs/providers/CUSTOM_PROVIDERS.md +19 -0
  21. data/docs/providers/GEMINI.md +8 -4
  22. data/docs/providers/GOOGLE_CLOUD.md +9 -4
  23. data/docs/providers/MOCK_PROVIDER.md +2 -0
  24. data/docs/providers/OPENAI.md +25 -3
  25. data/docs/providers/OPENROUTER.md +11 -3
  26. data/docs/providers/PROVIDERS.md +1 -1
  27. data/docs-site/index.html.erb +1 -1
  28. data/lib/riffer/agent/config.rb +21 -0
  29. data/lib/riffer/agent/context.rb +36 -18
  30. data/lib/riffer/agent/run.rb +54 -8
  31. data/lib/riffer/agent/serializer.rb +5 -0
  32. data/lib/riffer/agent/session.rb +1 -0
  33. data/lib/riffer/agent.rb +43 -0
  34. data/lib/riffer/config/mcp.rb +17 -0
  35. data/lib/riffer/config/pricing.rb +2 -2
  36. data/lib/riffer/config.rb +12 -1
  37. data/lib/riffer/evals/evaluator.rb +8 -1
  38. data/lib/riffer/evals/evaluator_runner.rb +1 -0
  39. data/lib/riffer/evals/judge.rb +2 -2
  40. data/lib/riffer/evals.rb +2 -0
  41. data/lib/riffer/mcp/search_tool.rb +1 -1
  42. data/lib/riffer/mcp.rb +7 -0
  43. data/lib/riffer/messages/tool.rb +6 -2
  44. data/lib/riffer/params/any_of.rb +5 -8
  45. data/lib/riffer/params/boolean.rb +1 -1
  46. data/lib/riffer/params/param.rb +96 -67
  47. data/lib/riffer/params.rb +50 -71
  48. data/lib/riffer/providers/anthropic_compatible/messages_api/stream.rb +3 -10
  49. data/lib/riffer/providers/anthropic_compatible/messages_api.rb +88 -12
  50. data/lib/riffer/providers/base.rb +43 -7
  51. data/lib/riffer/providers/deferred_tool_gateway/sink.rb +54 -0
  52. data/lib/riffer/providers/deferred_tool_gateway/tool.rb +17 -0
  53. data/lib/riffer/providers/deferred_tool_gateway.rb +150 -0
  54. data/lib/riffer/providers/gemini.rb +5 -5
  55. data/lib/riffer/providers/mock.rb +6 -0
  56. data/lib/riffer/providers/open_ai.rb +38 -10
  57. data/lib/riffer/skills/activate_tool.rb +1 -1
  58. data/lib/riffer/tool.rb +92 -2
  59. data/lib/riffer/tools/response.rb +11 -2
  60. data/lib/riffer/version.rb +1 -1
  61. data/sig/generated/riffer/agent/config.rbs +13 -1
  62. data/sig/generated/riffer/agent/context.rbs +16 -0
  63. data/sig/generated/riffer/agent/run.rbs +14 -2
  64. data/sig/generated/riffer/agent.rbs +13 -0
  65. data/sig/generated/riffer/config/mcp.rbs +7 -0
  66. data/sig/generated/riffer/config.rbs +5 -1
  67. data/sig/generated/riffer/evals/evaluator.rbs +4 -0
  68. data/sig/generated/riffer/evals.rbs +1 -0
  69. data/sig/generated/riffer/mcp.rbs +1 -0
  70. data/sig/generated/riffer/messages/tool.rbs +4 -2
  71. data/sig/generated/riffer/params/any_of.rbs +4 -4
  72. data/sig/generated/riffer/params/boolean.rbs +1 -1
  73. data/sig/generated/riffer/params/param.rbs +28 -14
  74. data/sig/generated/riffer/params.rbs +20 -20
  75. data/sig/generated/riffer/providers/anthropic_compatible/messages_api/stream.rbs +2 -5
  76. data/sig/generated/riffer/providers/anthropic_compatible/messages_api.rbs +34 -2
  77. data/sig/generated/riffer/providers/base.rbs +13 -0
  78. data/sig/generated/riffer/providers/deferred_tool_gateway/sink.rbs +23 -0
  79. data/sig/generated/riffer/providers/deferred_tool_gateway/tool.rbs +4 -0
  80. data/sig/generated/riffer/providers/deferred_tool_gateway.rbs +58 -0
  81. data/sig/generated/riffer/providers/mock.rbs +4 -0
  82. data/sig/generated/riffer/providers/open_ai.rbs +16 -4
  83. data/sig/generated/riffer/tool.rbs +48 -2
  84. data/sig/generated/riffer/tools/response.rbs +9 -2
  85. data/sig/manual/riffer/providers/deferred_tool_gateway.rbs +5 -0
  86. metadata +8 -3
  87. data/lib/riffer/tools/toolable.rb +0 -113
  88. data/sig/generated/riffer/tools/toolable.rbs +0 -66
@@ -11,11 +11,14 @@ class Riffer::Providers::AnthropicCompatible::MessagesAPI < Riffer::Providers::B
11
11
  "tool_use" => :tool_calls,
12
12
  "refusal" => :content_filter,
13
13
  "model_context_window_exceeded" => :context_window,
14
- # A paused server-tool turn resumes only by re-sending the response; the
15
- # agent loop does not do that, so it has no normalized equivalent.
14
+ # Paused turns are continued here, so this surfaces only once
15
+ # PAUSE_TURN_CONTINUATIONS runs out.
16
16
  "pause_turn" => :other,
17
17
  }.freeze #: Hash[String, Symbol]
18
18
 
19
+ PAUSE_TURN_CONTINUATIONS = 8 #: Integer
20
+ private_constant :PAUSE_TURN_CONTINUATIONS
21
+
19
22
  # Only parts carrying this tag are replayed, so reasoning captured by another
20
23
  # adapter, whose signatures the Messages API may not accept, never reaches the
21
24
  # request. Server tool parts and text parts that keep their block carry it too.
@@ -27,6 +30,12 @@ class Riffer::Providers::AnthropicCompatible::MessagesAPI < Riffer::Providers::B
27
30
  Riffer::Skills::XmlAdapter
28
31
  end
29
32
 
33
+ #--
34
+ #: () -> bool
35
+ def self.supports_deferred_tools?
36
+ true
37
+ end
38
+
30
39
  private
31
40
 
32
41
  #--
@@ -53,12 +62,28 @@ class Riffer::Providers::AnthropicCompatible::MessagesAPI < Riffer::Providers::B
53
62
  #--
54
63
  #: (Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
55
64
  def execute_generate(params)
56
- client.post(messages_path(params[:model], stream: false), request_body(params, stream: false))
65
+ continue_paused_turn(params) do |request|
66
+ client.post(messages_path(request[:model], stream: false), request_body(request, stream: false))
67
+ end
57
68
  end
58
69
 
70
+ # The done events cover the whole turn, so they wait until every paused
71
+ # response has been continued.
59
72
  #--
60
73
  #: (Hash[Symbol, untyped], Riffer::Providers::_EventSink) -> void
61
74
  def execute_stream(params, yielder)
75
+ message = continue_paused_turn(params) { |request| stream_message(request, yielder) }
76
+
77
+ text = message[:content].filter_map { |block| block[:text] if block[:type] == "text" }.join
78
+ yielder << Riffer::StreamEvents::TextDone.new(text) unless text.empty?
79
+ yield_finish_reason(yielder, extract_finish_reason(message))
80
+ usage = extract_token_usage(message)
81
+ yielder << Riffer::StreamEvents::TokenUsageDone.new(token_usage: usage) if usage
82
+ end
83
+
84
+ #--
85
+ #: (Hash[Symbol, untyped], Riffer::Providers::_EventSink) -> Hash[Symbol, untyped]
86
+ def stream_message(params, yielder)
62
87
  stream = Stream.new(tools: @current_tools)
63
88
  decoder = Riffer::Wire::SSE.new
64
89
 
@@ -66,10 +91,43 @@ class Riffer::Providers::AnthropicCompatible::MessagesAPI < Riffer::Providers::B
66
91
  decoder.feed(chunk) { |data, _event| stream.handle(JSON.parse(data, symbolize_names: true), yielder) }
67
92
  end
68
93
 
69
- message = stream.finish!
70
- yield_finish_reason(yielder, extract_finish_reason(message))
71
- usage = extract_token_usage(message)
72
- yielder << Riffer::StreamEvents::TokenUsageDone.new(token_usage: usage) if usage
94
+ stream.finish!
95
+ end
96
+
97
+ # To resume a paused turn, resend the same request with the paused response's
98
+ # content array appended as an assistant message, copied as-is and with nothing after it.
99
+ #--
100
+ #: (Hash[Symbol, untyped]) { (Hash[Symbol, untyped]) -> Hash[Symbol, untyped] } -> Hash[Symbol, untyped]
101
+ def continue_paused_turn(params)
102
+ response = yield params
103
+
104
+ PAUSE_TURN_CONTINUATIONS.times do
105
+ return response unless response[:stop_reason] == "pause_turn"
106
+
107
+ paused = { role: "assistant", content: content_blocks(response) }
108
+ request = params.merge(messages: [*params[:messages], paused])
109
+ # The API creates a new sandbox for any request without a container id; pass the
110
+ # paused response's id so the continuation sees the files its code already wrote.
111
+ container_id = response.dig(:container, :id)
112
+ request[:container] = container_id if container_id
113
+ continuation = yield request
114
+ response = response.merge(continuation).merge(
115
+ content: content_blocks(response) + content_blocks(continuation),
116
+ usage: merge_usage(response[:usage], continuation[:usage]),
117
+ )
118
+ end
119
+
120
+ response
121
+ end
122
+
123
+ # Each request is billed for its own input and output, so the counts add up.
124
+ # A nil count in the later response would replace the running total, so it's dropped.
125
+ #--
126
+ #: (Hash[Symbol, untyped]?, Hash[Symbol, untyped]?) -> Hash[Symbol, untyped]?
127
+ def merge_usage(first, second)
128
+ return first || second unless first && second
129
+
130
+ first.merge(second.compact) { |_key, a, b| a.is_a?(Integer) && b.is_a?(Integer) ? a + b : b }
73
131
  end
74
132
 
75
133
  # Claude signs each thinking block over every block before it in the turn, so
@@ -141,8 +199,9 @@ class Riffer::Providers::AnthropicCompatible::MessagesAPI < Riffer::Providers::B
141
199
  #--
142
200
  #: (Array[Riffer::Messages::Base], String?, Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
143
201
  def build_request_params(messages, model, options)
144
- partitioned_messages = partition_messages(messages)
145
202
  tools = options[:tools]
203
+ deferred_tools = options[:deferred_tools] || []
204
+ partitioned_messages = partition_messages(messages, deferred_tools)
146
205
  structured_output = options[:structured_output]
147
206
  web_search = options[:web_search]
148
207
  tags = options[:tags] || {}
@@ -153,7 +212,7 @@ class Riffer::Providers::AnthropicCompatible::MessagesAPI < Riffer::Providers::B
153
212
  model: model,
154
213
  messages: partitioned_messages[:conversation],
155
214
  max_tokens: max_tokens,
156
- **options.except(:tools, :max_tokens, :structured_output, :web_search, :tags),
215
+ **options.except(:tools, :deferred_tools, :max_tokens, :structured_output, :web_search, :tags),
157
216
  } #: Hash[Symbol, untyped]
158
217
 
159
218
  params[:system] = partitioned_messages[:system] if partitioned_messages[:system]
@@ -164,6 +223,9 @@ class Riffer::Providers::AnthropicCompatible::MessagesAPI < Riffer::Providers::B
164
223
  api_tools = [] #: Array[Hash[Symbol, untyped]]
165
224
  api_tools.concat(tools.map { |t| convert_tool(t) }) if tools && !tools.empty?
166
225
  api_tools << web_search_tool(web_search) if web_search
226
+ # Every deferred tool goes on every request, loaded or not, so the tools
227
+ # array never changes and the prompt cache survives a load.
228
+ api_tools.concat(deferred_tools.map { |t| convert_tool(t).merge(defer_loading: true) })
167
229
 
168
230
  if structured_output
169
231
  # The format wins over caller output_config keys because the run loop
@@ -207,8 +269,9 @@ class Riffer::Providers::AnthropicCompatible::MessagesAPI < Riffer::Providers::B
207
269
  end
208
270
 
209
271
  #--
210
- #: (Array[Riffer::Messages::Base]) -> Hash[Symbol, untyped]
211
- def partition_messages(messages)
272
+ #: (Array[Riffer::Messages::Base], Array[singleton(Riffer::Tool)]) -> Hash[Symbol, untyped]
273
+ def partition_messages(messages, deferred_tools)
274
+ deferred_names = deferred_tools.map(&:name)
212
275
  system_prompts = [] #: Array[Hash[Symbol, untyped]]
213
276
  conversation_messages = [] #: Array[Hash[Symbol, untyped]]
214
277
 
@@ -232,7 +295,7 @@ class Riffer::Providers::AnthropicCompatible::MessagesAPI < Riffer::Providers::B
232
295
  content: [{
233
296
  type: "tool_result",
234
297
  tool_use_id: message.tool_call_id,
235
- content: message.content,
298
+ content: tool_result_content(message, deferred_names),
236
299
  }],
237
300
  }
238
301
  end
@@ -244,6 +307,19 @@ class Riffer::Providers::AnthropicCompatible::MessagesAPI < Riffer::Providers::B
244
307
  }
245
308
  end
246
309
 
310
+ # A load goes as tool_reference blocks alone, since the API rejects them mixed
311
+ # with text. Only this request's deferred tools are referenced: the API rejects
312
+ # a reference to a tool missing from +tools+, and a restored history may name
313
+ # tools the agent no longer defers.
314
+ #--
315
+ #: (Riffer::Messages::Tool, Array[String]) -> (String | Array[Hash[Symbol, untyped]])
316
+ def tool_result_content(message, deferred_names)
317
+ names = message.loaded_tools & deferred_names
318
+ return message.content if names.empty?
319
+
320
+ names.map { |name| { type: "tool_reference", tool_name: encode_tool_name(name) } }
321
+ end
322
+
247
323
  #--
248
324
  #: (Riffer::Messages::Assistant) -> Hash[Symbol, untyped]
249
325
  def convert_assistant(message)
@@ -17,6 +17,12 @@ class Riffer::Providers::Base
17
17
  Riffer::Skills::MarkdownAdapter
18
18
  end
19
19
 
20
+ #--
21
+ #: () -> bool
22
+ def self.supports_deferred_tools?
23
+ false
24
+ end
25
+
20
26
  #--
21
27
  #: () -> String
22
28
  def self.semconv_provider_name
@@ -33,19 +39,24 @@ class Riffer::Providers::Base
33
39
  #: (?prompt: String?, ?system: String?, ?messages: Array[Hash[Symbol, untyped] | Riffer::Messages::Base]?, ?model: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::User::FilePart]?, **untyped) -> Riffer::Messages::Assistant
34
40
  def generate_text(prompt: nil, system: nil, messages: nil, model: nil, files: nil, **options)
35
41
  validate_input!(prompt: prompt, system: system, messages: messages)
36
- @current_tools = options[:tools] || [] #: Array[singleton(Riffer::Tool)]
42
+ @current_tools = decodable_tools(options)
37
43
  @current_model = model
38
44
  messages = normalize_messages(prompt: prompt, system: system, messages: messages, files: files)
39
45
  validate_normalized_messages!(messages)
40
46
  Riffer::Files::Resolver.new(provider: self).resolve!(messages)
41
47
  messages = with_structured_output_prompt(merge_consecutive_messages(messages), options[:structured_output])
42
48
  options = apply_reasoning(model, options)
43
- params = build_request_params(messages, model, request_options(options))
49
+ gateway_tools = gateway_deferred_tools(options)
50
+ params = build_request_params(
51
+ Riffer::Providers::DeferredToolGateway.wrap_messages(messages, gateway_tools),
52
+ model,
53
+ request_options(options),
54
+ )
44
55
 
45
56
  in_chat_span(model, messages, options) do |span|
46
57
  response = execute_generate(params)
47
58
 
48
- parts = extract_parts(response)
59
+ parts = Riffer::Providers::DeferredToolGateway.unwrap_parts(extract_parts(response), gateway_tools)
49
60
  content = parts.filter_map { |part| part.text if part.is_a?(Riffer::Messages::Assistant::TextPart) }.join
50
61
  tool_calls = parts.grep(Riffer::Messages::Assistant::ToolCall) #: Array[Riffer::Messages::Assistant::ToolCall]
51
62
  token_usage = extract_token_usage(response)
@@ -70,14 +81,19 @@ class Riffer::Providers::Base
70
81
  #: (?prompt: String?, ?system: String?, ?messages: Array[Hash[Symbol, untyped] | Riffer::Messages::Base]?, ?model: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::User::FilePart]?, **untyped) -> Enumerator[Riffer::StreamEvents::Base, void]
71
82
  def stream_text(prompt: nil, system: nil, messages: nil, model: nil, files: nil, **options)
72
83
  validate_input!(prompt: prompt, system: system, messages: messages)
73
- @current_tools = options[:tools] || [] #: Array[singleton(Riffer::Tool)]
84
+ @current_tools = decodable_tools(options)
74
85
  @current_model = model
75
86
  messages = normalize_messages(prompt: prompt, system: system, messages: messages, files: files)
76
87
  validate_normalized_messages!(messages)
77
88
  Riffer::Files::Resolver.new(provider: self).resolve!(messages)
78
89
  messages = with_structured_output_prompt(merge_consecutive_messages(messages), options[:structured_output])
79
90
  options = apply_reasoning(model, options)
80
- params = build_request_params(messages, model, request_options(options))
91
+ gateway_tools = gateway_deferred_tools(options)
92
+ params = build_request_params(
93
+ Riffer::Providers::DeferredToolGateway.wrap_messages(messages, gateway_tools),
94
+ model,
95
+ request_options(options),
96
+ )
81
97
 
82
98
  # The enumerator body runs in its own fiber, where the fiber-local OTEL
83
99
  # context is empty — capture here so the chat span parents to the caller's
@@ -87,7 +103,8 @@ class Riffer::Providers::Base
87
103
  Riffer::Tracing.with_context(trace_context) do
88
104
  in_chat_span(model, messages, options) do |span|
89
105
  sink = span.recording? ? Riffer::Tracing::StreamRecorder.new(yielder) : yielder
90
- execute_stream(params, sink)
106
+ # Outside the recorder, so traces record the unwrapped calls too.
107
+ execute_stream(params, Riffer::Providers::DeferredToolGateway.unwrapping_sink(sink, gateway_tools))
91
108
  record_stream_outcome(span, sink) if sink.is_a?(Riffer::Tracing::StreamRecorder)
92
109
  end
93
110
  end
@@ -130,6 +147,20 @@ class Riffer::Providers::Base
130
147
  raise NotImplementedError, "Subclasses must implement #build_client"
131
148
  end
132
149
 
150
+ # The model calls a loaded deferred tool, and the gateway, by its wire name too.
151
+ #--
152
+ #: (Hash[Symbol, untyped]) -> Array[singleton(Riffer::Tool)]
153
+ def decodable_tools(options)
154
+ tools = (options[:tools] || []) + (options[:deferred_tools] || [])
155
+ gateway_deferred_tools(options).empty? ? tools : tools + [Riffer::Providers::DeferredToolGateway::Tool]
156
+ end
157
+
158
+ #--
159
+ #: (Hash[Symbol, untyped]) -> Array[singleton(Riffer::Tool)]
160
+ def gateway_deferred_tools(options)
161
+ options[:riffer_deferred_tools_strategy] == :gateway ? options[:deferred_tools] || [] : []
162
+ end
163
+
133
164
  #--
134
165
  #: (String) -> String
135
166
  def encode_tool_name(name)
@@ -445,7 +476,12 @@ class Riffer::Providers::Base
445
476
  #--
446
477
  #: (Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
447
478
  def request_options(options)
448
- options = options.except(:riffer_reasoning_level)
479
+ gateway = !gateway_deferred_tools(options).empty?
480
+ options = options.except(:riffer_reasoning_level, :riffer_deferred_tools_strategy)
481
+ # Every request with deferred tools carries the gateway, before a load and after, so the tool list never changes.
482
+ options = options.merge(tools: (options[:tools] || []) + [Riffer::Providers::DeferredToolGateway::Tool]) if gateway
483
+ # Providers splat unknown options into their SDK request, and a gateway request must not load natively too.
484
+ options = options.except(:deferred_tools) if gateway || !self.class.supports_deferred_tools?
449
485
  options[:structured_output]&.prompted? ? options.except(:structured_output) : options
450
486
  end
451
487
 
@@ -0,0 +1,54 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ class Riffer::Providers::DeferredToolGateway::Sink
5
+ # @rbs @sink: Riffer::Providers::_EventSink
6
+ # @rbs @deferred_tools: Array[singleton(Riffer::Tool)]
7
+ # @rbs @gateway_item_ids: Array[String]
8
+
9
+ #--
10
+ #: (Riffer::Providers::_EventSink, deferred_tools: Array[singleton(Riffer::Tool)]) -> void
11
+ def initialize(sink, deferred_tools:)
12
+ @sink = sink
13
+ @deferred_tools = deferred_tools
14
+ @gateway_item_ids = []
15
+ end
16
+
17
+ #--
18
+ #: (Riffer::StreamEvents::Base) -> self
19
+ def <<(event)
20
+ case event
21
+ when Riffer::StreamEvents::ToolCallDelta
22
+ # A gateway call's deltas are fragments of its own arguments, which only unwrap once the call is complete.
23
+ # Providers may name the call on its first delta alone, so the rest are matched by item id.
24
+ @gateway_item_ids |= [event.item_id] if event.name == Riffer::Providers::DeferredToolGateway::Tool.name
25
+ @sink << event unless @gateway_item_ids.include?(event.item_id)
26
+ when Riffer::StreamEvents::ToolCallDone
27
+ @sink << unwrap(event)
28
+ else
29
+ @sink << event
30
+ end
31
+ self
32
+ end
33
+
34
+ private
35
+
36
+ #--
37
+ #: (Riffer::StreamEvents::ToolCallDone) -> Riffer::StreamEvents::ToolCallDone
38
+ def unwrap(event)
39
+ tool_call = Riffer::Messages::Assistant::ToolCall.new(
40
+ call_id: event.call_id,
41
+ name: event.name,
42
+ arguments: event.arguments,
43
+ )
44
+ unwrapped = Riffer::Providers::DeferredToolGateway.unwrap_tool_call(tool_call, @deferred_tools)
45
+ return event if unwrapped.equal?(tool_call)
46
+
47
+ Riffer::StreamEvents::ToolCallDone.new(
48
+ item_id: event.item_id,
49
+ call_id: unwrapped.call_id,
50
+ name: unwrapped.name,
51
+ arguments: unwrapped.arguments,
52
+ )
53
+ end
54
+ end
@@ -0,0 +1,17 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ class Riffer::Providers::DeferredToolGateway::Tool < Riffer::Tool
5
+ identifier "riffer_gateway"
6
+ description "Calls a tool that another tool has loaded. The result of the tool that loaded it lists its name " \
7
+ "and parameters."
8
+
9
+ # The arguments are a string rather than an object, since strict mode rejects an object without fixed properties.
10
+ params do
11
+ required :name, :string, description: "The loaded tool's exact name, copied from the result that loaded it"
12
+ required :arguments, :string,
13
+ description: "The loaded tool's arguments as a JSON-encoded object string matching its parameters, " \
14
+ "such as \"{\\\"query\\\":\\\"red shoes\\\",\\\"limit\\\":5}\". Numbers and booleans " \
15
+ "stay unquoted inside it. Use \"{}\" for a tool without parameters."
16
+ end
17
+ end
@@ -0,0 +1,150 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ require "json"
5
+
6
+ module Riffer::Providers::DeferredToolGateway
7
+ extend self
8
+
9
+ # +deferred_tools+ are the ones the gateway carries for the request. With none there is no gateway, and every
10
+ # function here returns its input.
11
+ #--
12
+ #: (Array[Riffer::Messages::Base], Array[singleton(Riffer::Tool)]) -> Array[Riffer::Messages::Base]
13
+ def wrap_messages(messages, deferred_tools)
14
+ return messages if deferred_tools.empty?
15
+
16
+ deferred_names = deferred_tools.map(&:name)
17
+ messages.map do |message|
18
+ case message
19
+ when Riffer::Messages::Assistant then wrap_assistant(message, deferred_names)
20
+ when Riffer::Messages::Tool then wrap_tool_result(message, deferred_tools)
21
+ else message
22
+ end
23
+ end
24
+ end
25
+
26
+ #--
27
+ #: (Array[Riffer::Messages::Assistant::TextPart | Riffer::Messages::Assistant::ReasoningPart | Riffer::Messages::Assistant::ToolCall | Riffer::Messages::Assistant::ServerToolPart], Array[singleton(Riffer::Tool)]) -> Array[Riffer::Messages::Assistant::TextPart | Riffer::Messages::Assistant::ReasoningPart | Riffer::Messages::Assistant::ToolCall | Riffer::Messages::Assistant::ServerToolPart]
28
+ def unwrap_parts(parts, deferred_tools)
29
+ return parts if deferred_tools.empty?
30
+
31
+ parts.map { |part| part.is_a?(Riffer::Messages::Assistant::ToolCall) ? unwrap_tool_call(part, deferred_tools) : part }
32
+ end
33
+
34
+ # A gateway call without a string name and string arguments, or naming a tool that isn't deferred, stays a call to
35
+ # the gateway, which is never one of the agent's tools, so the model gets an +:unknown_tool+ error result. Only a
36
+ # deferred tool's call is wrapped again on the way out, so unwrapping any other name would replay its arguments
37
+ # to the provider as they came, unparseable JSON included.
38
+ #--
39
+ #: (Riffer::Messages::Assistant::ToolCall, Array[singleton(Riffer::Tool)]) -> Riffer::Messages::Assistant::ToolCall
40
+ def unwrap_tool_call(tool_call, deferred_tools)
41
+ return tool_call unless tool_call.name == Tool.name
42
+
43
+ call = parse_gateway_arguments(tool_call.arguments)
44
+ return tool_call unless call
45
+
46
+ name, arguments = call
47
+ # The model may name a loaded tool in the wire-safe form it sees on the agent's other tools.
48
+ decoded = Riffer::Wire.decode_tool_name(name, tools: deferred_tools)
49
+ return tool_call unless deferred_tools.any? { |tool| tool.name == decoded }
50
+
51
+ Riffer::Messages::Assistant::ToolCall.new(call_id: tool_call.call_id, name: decoded, arguments: arguments)
52
+ end
53
+
54
+ #--
55
+ #: (Riffer::Providers::_EventSink, Array[singleton(Riffer::Tool)]) -> Riffer::Providers::_EventSink
56
+ def unwrapping_sink(sink, deferred_tools)
57
+ deferred_tools.empty? ? sink : Sink.new(sink, deferred_tools: deferred_tools)
58
+ end
59
+
60
+ private
61
+
62
+ #--
63
+ #: (String) -> [String, String]?
64
+ def parse_gateway_arguments(arguments)
65
+ parsed = JSON.parse(arguments)
66
+ return unless parsed.is_a?(Hash)
67
+
68
+ name = parsed["name"]
69
+ tool_arguments = parsed["arguments"]
70
+ [name, tool_arguments] if name.is_a?(String) && tool_arguments.is_a?(String)
71
+ rescue JSON::ParserError
72
+ nil
73
+ end
74
+
75
+ #--
76
+ #: (Riffer::Messages::Assistant, Array[String]) -> Riffer::Messages::Assistant
77
+ def wrap_assistant(message, deferred_names)
78
+ return message if message.tool_calls.none? { |tool_call| deferred_names.include?(tool_call.name) }
79
+
80
+ Riffer::Messages::Assistant.new(
81
+ id: message.id,
82
+ parts: message.parts.map do |part|
83
+ part.is_a?(Riffer::Messages::Assistant::ToolCall) ? wrap_tool_call(part, deferred_names) : part
84
+ end,
85
+ token_usage: message.token_usage,
86
+ structured_output: message.structured_output,
87
+ finish_reason: message.finish_reason,
88
+ finish_reason_raw: message.finish_reason_raw,
89
+ )
90
+ end
91
+
92
+ #--
93
+ #: (Riffer::Messages::Assistant::ToolCall, Array[String]) -> Riffer::Messages::Assistant::ToolCall
94
+ def wrap_tool_call(tool_call, deferred_names)
95
+ return tool_call unless deferred_names.include?(tool_call.name)
96
+
97
+ Riffer::Messages::Assistant::ToolCall.new(
98
+ call_id: tool_call.call_id,
99
+ name: Tool.name,
100
+ arguments: JSON.generate({ name: tool_call.name, arguments: tool_call.arguments }),
101
+ )
102
+ end
103
+
104
+ # A result for a deferred tool is renamed along with its call, since Gemini sends the name with a function
105
+ # response and rejects one that names no declared function.
106
+ #--
107
+ #: (Riffer::Messages::Tool, Array[singleton(Riffer::Tool)]) -> Riffer::Messages::Tool
108
+ def wrap_tool_result(message, deferred_tools)
109
+ loaded = loaded_deferred_tools(message, deferred_tools)
110
+ deferred_call = deferred_tools.any? { |tool| tool.name == message.name }
111
+ return message if loaded.empty? && !deferred_call
112
+
113
+ Riffer::Messages::Tool.new(
114
+ loaded.empty? ? message.content : [message.content, describe_loaded_tools(loaded)].reject(&:empty?).join("\n\n"),
115
+ tool_call_id: message.tool_call_id,
116
+ name: deferred_call ? Tool.name : message.name,
117
+ id: message.id,
118
+ error: message.error,
119
+ error_type: message.error_type,
120
+ loaded_tools: message.loaded_tools,
121
+ )
122
+ end
123
+
124
+ #--
125
+ #: (Riffer::Messages::Tool, Array[singleton(Riffer::Tool)]) -> Array[singleton(Riffer::Tool)]
126
+ def loaded_deferred_tools(message, deferred_tools)
127
+ return [] if message.error?
128
+
129
+ deferred_tools.select { |tool| message.loaded_tools.include?(tool.name) }
130
+ end
131
+
132
+ # Deterministic, so an earlier tool result reads the same on every request and the prompt cache holds.
133
+ #--
134
+ #: (Array[singleton(Riffer::Tool)]) -> String
135
+ def describe_loaded_tools(tools)
136
+ entries = tools.map do |tool|
137
+ { name: tool.name, description: tool.description, parameters: tool.parameters_schema }
138
+ end
139
+ [loaded_tools_header, JSON.generate(entries)].join("\n\n")
140
+ end
141
+
142
+ #--
143
+ #: () -> String
144
+ def loaded_tools_header
145
+ "These tools are now loaded. They are not in your tool list, so calling one by its own name fails. Call each " \
146
+ "one through the #{Tool.name} tool: set name to the tool's name exactly as written below, and set arguments " \
147
+ "to a string holding its arguments as a JSON object that matches its parameters. Use \"{}\" as arguments for " \
148
+ "a tool without parameters."
149
+ end
150
+ end
@@ -164,7 +164,7 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
164
164
  fc = part[:functionCall]
165
165
  Riffer::Messages::Assistant::ToolCall.new(
166
166
  call_id: tool_call_id(part),
167
- name: fc[:name],
167
+ name: decode_tool_name(fc[:name], tools: @current_tools),
168
168
  arguments: encode_tool_arguments(fc[:args]),
169
169
  )
170
170
  end
@@ -300,7 +300,7 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
300
300
  yielder << Riffer::StreamEvents::ToolCallDone.new(
301
301
  item_id: call_id,
302
302
  call_id: call_id,
303
- name: fc[:name],
303
+ name: decode_tool_name(fc[:name], tools: @current_tools),
304
304
  arguments: arguments,
305
305
  )
306
306
  elsif part[:toolCall]
@@ -394,7 +394,7 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
394
394
  part = {
395
395
  functionResponse: {
396
396
  id: gemini_call_id(message.tool_call_id),
397
- name: message.name,
397
+ name: encode_tool_name(message.name),
398
398
  response: { result: message.content },
399
399
  }.compact,
400
400
  }
@@ -426,7 +426,7 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
426
426
  parts << {
427
427
  functionCall: {
428
428
  id: gemini_call_id(tc.call_id),
429
- name: tc.name,
429
+ name: encode_tool_name(tc.name),
430
430
  args: parse_tool_arguments(tc.arguments),
431
431
  }.compact,
432
432
  thoughtSignature: signature,
@@ -446,7 +446,7 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
446
446
  #: (singleton(Riffer::Tool)) -> Hash[Symbol, untyped]
447
447
  def convert_tool_to_gemini_format(tool)
448
448
  {
449
- name: tool.name,
449
+ name: encode_tool_name(tool.name),
450
450
  description: tool.description,
451
451
  parametersJsonSchema: tool.parameters_schema,
452
452
  }
@@ -15,6 +15,12 @@ class Riffer::Providers::Mock < Riffer::Providers::Base
15
15
  Riffer::Skills::MarkdownAdapter
16
16
  end
17
17
 
18
+ #--
19
+ #: () -> bool
20
+ def self.supports_deferred_tools?
21
+ true
22
+ end
23
+
18
24
  #--
19
25
  #: () -> String
20
26
  def self.semconv_provider_name
@@ -21,6 +21,12 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
21
21
  "queued" => :other,
22
22
  }.freeze #: Hash[String, Symbol | Hash[String, Symbol]]
23
23
 
24
+ #--
25
+ #: () -> bool
26
+ def self.supports_deferred_tools?
27
+ true
28
+ end
29
+
24
30
  #--
25
31
  #: () -> String
26
32
  def self.semconv_provider_name
@@ -75,13 +81,13 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
75
81
  tags = options[:tags] || {}
76
82
 
77
83
  params = {
78
- input: convert_messages_to_openai_format(messages),
84
+ input: convert_messages_to_openai_format(messages, deferred_tools: options[:deferred_tools] || []),
79
85
  model: model,
80
86
  reasoning: reasoning && {
81
87
  effort: reasoning,
82
88
  summary: "auto",
83
89
  },
84
- **options.except(:reasoning, :tools, :structured_output, :web_search, :tags),
90
+ **options.except(:reasoning, :tools, :structured_output, :web_search, :tags, :deferred_tools),
85
91
  } #: Hash[Symbol, untyped]
86
92
 
87
93
  unless tags.empty?
@@ -392,8 +398,8 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
392
398
  end
393
399
 
394
400
  #--
395
- #: (Array[Riffer::Messages::Base]) -> Array[Hash[Symbol, untyped]]
396
- def convert_messages_to_openai_format(messages)
401
+ #: (Array[Riffer::Messages::Base], deferred_tools: Array[singleton(Riffer::Tool)]) -> Array[Hash[Symbol, untyped]]
402
+ def convert_messages_to_openai_format(messages, deferred_tools:)
397
403
  messages.flat_map do |message|
398
404
  case message
399
405
  when Riffer::Messages::System
@@ -407,13 +413,17 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
407
413
  { role: "user", content: content }
408
414
  end
409
415
  when Riffer::Messages::Assistant
410
- convert_assistant_to_openai_format(message)
416
+ convert_assistant_to_openai_format(message, deferred_tools: deferred_tools)
411
417
  when Riffer::Messages::Tool
412
- {
418
+ output = {
413
419
  type: "function_call_output",
414
420
  call_id: message.tool_call_id,
415
421
  output: message.content,
416
422
  }
423
+ loaded = loaded_deferred_tools(message, deferred_tools)
424
+ # A repeat load is sent again: a load that brings no definitions leaves the model unsure it worked, and
425
+ # it keeps calling the loading tool instead of the loaded one.
426
+ loaded.empty? ? output : [output, convert_additional_tools_to_openai_format(loaded)]
417
427
  else
418
428
  raise Riffer::ArgumentError, "unsupported message type: #{message.class}"
419
429
  end
@@ -421,8 +431,22 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
421
431
  end
422
432
 
423
433
  #--
424
- #: (Riffer::Messages::Assistant) -> Array[Hash[Symbol, untyped]]
425
- def convert_assistant_to_openai_format(message)
434
+ #: (Riffer::Messages::Tool, Array[singleton(Riffer::Tool)]) -> Array[singleton(Riffer::Tool)]
435
+ def loaded_deferred_tools(message, deferred_tools)
436
+ return [] if message.error?
437
+
438
+ deferred_tools.select { |tool| message.loaded_tools.include?(tool.name) }
439
+ end
440
+
441
+ #--
442
+ #: (Array[singleton(Riffer::Tool)]) -> Hash[Symbol, untyped]
443
+ def convert_additional_tools_to_openai_format(tools)
444
+ { type: "additional_tools", role: "developer", tools: tools.map { |tool| convert_tool_to_openai_format(tool) } }
445
+ end
446
+
447
+ #--
448
+ #: (Riffer::Messages::Assistant, deferred_tools: Array[singleton(Riffer::Tool)]) -> Array[Hash[Symbol, untyped]]
449
+ def convert_assistant_to_openai_format(message, deferred_tools:)
426
450
  items = convert_reasoning_to_openai_format(message.reasoning)
427
451
 
428
452
  if message.tool_calls.empty?
@@ -433,12 +457,16 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
433
457
  content: message.content, }
434
458
  end
435
459
  message.tool_calls.each do |tc|
460
+ name = encode_tool_name(tc.name)
436
461
  items << {
437
462
  type: "function_call",
438
463
  call_id: tc.call_id,
439
- name: encode_tool_name(tc.name),
464
+ name: name,
465
+ # The API rejects a replayed call to a tool loaded through additional_tools unless it carries the
466
+ # namespace the model returned, which is always the tool's own name; it accepts one on an unloaded call too.
467
+ namespace: (name if deferred_tools.any? { |tool| tool.name == tc.name }),
440
468
  arguments: tc.arguments,
441
- }
469
+ }.compact
442
470
  end
443
471
  end
444
472
 
@@ -8,7 +8,7 @@ class Riffer::Skills::ActivateTool < Riffer::Tool
8
8
  timeout 1
9
9
 
10
10
  params do
11
- required :name, String, description: "The skill name to activate"
11
+ required :name, :string, description: "The skill name to activate"
12
12
  end
13
13
 
14
14
  #--