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
@@ -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,21 +39,26 @@ 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
- content = extract_content(response)
49
- tool_calls = extract_tool_calls(response)
50
- reasoning = extract_reasoning(response)
59
+ parts = Riffer::Providers::DeferredToolGateway.unwrap_parts(extract_parts(response), gateway_tools)
60
+ content = parts.filter_map { |part| part.text if part.is_a?(Riffer::Messages::Assistant::TextPart) }.join
61
+ tool_calls = parts.grep(Riffer::Messages::Assistant::ToolCall) #: Array[Riffer::Messages::Assistant::ToolCall]
51
62
  token_usage = extract_token_usage(response)
52
63
  finish_reason = extract_finish_reason(response)
53
64
  structured_output = parse_structured_output(content) if options[:structured_output] && tool_calls.empty?
@@ -57,9 +68,7 @@ class Riffer::Providers::Base
57
68
  capture_output(span, content: content, tool_calls: tool_calls, finish_reason: finish_reason&.reason)
58
69
 
59
70
  Riffer::Messages::Assistant.new(
60
- content,
61
- tool_calls: tool_calls,
62
- reasoning: reasoning,
71
+ parts: parts,
63
72
  token_usage: token_usage,
64
73
  structured_output: structured_output,
65
74
  finish_reason: finish_reason&.reason,
@@ -72,14 +81,19 @@ class Riffer::Providers::Base
72
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]
73
82
  def stream_text(prompt: nil, system: nil, messages: nil, model: nil, files: nil, **options)
74
83
  validate_input!(prompt: prompt, system: system, messages: messages)
75
- @current_tools = options[:tools] || [] #: Array[singleton(Riffer::Tool)]
84
+ @current_tools = decodable_tools(options)
76
85
  @current_model = model
77
86
  messages = normalize_messages(prompt: prompt, system: system, messages: messages, files: files)
78
87
  validate_normalized_messages!(messages)
79
88
  Riffer::Files::Resolver.new(provider: self).resolve!(messages)
80
89
  messages = with_structured_output_prompt(merge_consecutive_messages(messages), options[:structured_output])
81
90
  options = apply_reasoning(model, options)
82
- 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
+ )
83
97
 
84
98
  # The enumerator body runs in its own fiber, where the fiber-local OTEL
85
99
  # context is empty — capture here so the chat span parents to the caller's
@@ -89,7 +103,8 @@ class Riffer::Providers::Base
89
103
  Riffer::Tracing.with_context(trace_context) do
90
104
  in_chat_span(model, messages, options) do |span|
91
105
  sink = span.recording? ? Riffer::Tracing::StreamRecorder.new(yielder) : yielder
92
- 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))
93
108
  record_stream_outcome(span, sink) if sink.is_a?(Riffer::Tracing::StreamRecorder)
94
109
  end
95
110
  end
@@ -132,6 +147,20 @@ class Riffer::Providers::Base
132
147
  raise NotImplementedError, "Subclasses must implement #build_client"
133
148
  end
134
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
+
135
164
  #--
136
165
  #: (String) -> String
137
166
  def encode_tool_name(name)
@@ -256,6 +285,17 @@ class Riffer::Providers::Base
256
285
  nil
257
286
  end
258
287
 
288
+ # Override when the provider interleaves blocks in one turn and needs them back in that order.
289
+ #--
290
+ #: (untyped) -> Array[Riffer::Messages::Assistant::TextPart | Riffer::Messages::Assistant::ReasoningPart | Riffer::Messages::Assistant::ToolCall | Riffer::Messages::Assistant::ServerToolPart]
291
+ def extract_parts(response)
292
+ Riffer::Messages::Assistant.new(
293
+ extract_content(response),
294
+ tool_calls: extract_tool_calls(response),
295
+ reasoning: extract_reasoning(response),
296
+ ).parts
297
+ end
298
+
259
299
  #--
260
300
  #: (untyped) -> Array[Riffer::Messages::Assistant::ReasoningPart]
261
301
  def extract_reasoning(_response)
@@ -436,7 +476,12 @@ class Riffer::Providers::Base
436
476
  #--
437
477
  #: (Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
438
478
  def request_options(options)
439
- 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?
440
485
  options[:structured_output]&.prompted? ? options.except(:structured_output) : options
441
486
  end
442
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
@@ -4,6 +4,9 @@
4
4
  class Riffer::Providers::OpenAI < Riffer::Providers::Base
5
5
  WEB_SEARCH_TOOL_TYPE = "web_search_preview" #: String
6
6
 
7
+ # Without this include, a web_search_call's search action carries no sources.
8
+ WEB_SEARCH_SOURCES_INCLUDE = "web_search_call.action.sources" #: String
9
+
7
10
  # The Responses API has no finish_reason field, and an +incomplete+ status is only meaningful
8
11
  # together with <tt>incomplete_details.reason</tt>.
9
12
  FINISH_REASONS = {
@@ -18,6 +21,12 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
18
21
  "queued" => :other,
19
22
  }.freeze #: Hash[String, Symbol | Hash[String, Symbol]]
20
23
 
24
+ #--
25
+ #: () -> bool
26
+ def self.supports_deferred_tools?
27
+ true
28
+ end
29
+
21
30
  #--
22
31
  #: () -> String
23
32
  def self.semconv_provider_name
@@ -72,13 +81,13 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
72
81
  tags = options[:tags] || {}
73
82
 
74
83
  params = {
75
- input: convert_messages_to_openai_format(messages),
84
+ input: convert_messages_to_openai_format(messages, deferred_tools: options[:deferred_tools] || []),
76
85
  model: model,
77
86
  reasoning: reasoning && {
78
87
  effort: reasoning,
79
88
  summary: "auto",
80
89
  },
81
- **options.except(:reasoning, :tools, :structured_output, :web_search, :tags),
90
+ **options.except(:reasoning, :tools, :structured_output, :web_search, :tags, :deferred_tools),
82
91
  } #: Hash[Symbol, untyped]
83
92
 
84
93
  unless tags.empty?
@@ -94,6 +103,7 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
94
103
  web_search_tool = { type: WEB_SEARCH_TOOL_TYPE }
95
104
  web_search_tool.merge!(web_search) if web_search.is_a?(Hash)
96
105
  openai_tools << web_search_tool
106
+ params[:include] = [*params[:include], WEB_SEARCH_SOURCES_INCLUDE].uniq(&:to_s)
97
107
  end
98
108
 
99
109
  if structured_output
@@ -195,6 +205,8 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
195
205
 
196
206
  typed_response.output.each do |item|
197
207
  next unless item.is_a?(::OpenAI::Models::Responses::ResponseFunctionToolCall)
208
+ # A call cut off by max_output_tokens has truncated arguments that can't be run.
209
+ next if item.status == :incomplete
198
210
 
199
211
  tool_calls << Riffer::Messages::Assistant::ToolCall.new(
200
212
  call_id: item.call_id,
@@ -247,7 +259,7 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
247
259
  def execute_stream(params, yielder)
248
260
  current_state = {
249
261
  text: nil,
250
- tool_info: {},
262
+ tool_names: {},
251
263
  } #: Hash[Symbol, untyped]
252
264
 
253
265
  stream_completed = false
@@ -266,8 +278,6 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
266
278
  handle_reasoning_summary_text_delta(event, state: current_state, yielder: yielder)
267
279
  when :"response.function_call_arguments.delta"
268
280
  handle_function_call_arguments_delta(event, state: current_state, yielder: yielder)
269
- when :"response.function_call_arguments.done"
270
- handle_function_call_arguments_done(event, state: current_state, yielder: yielder)
271
281
  when :"response.web_search_call.in_progress"
272
282
  handle_web_search_status(event, status: "in_progress", yielder: yielder)
273
283
  when :"response.web_search_call.searching"
@@ -276,6 +286,7 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
276
286
  handle_web_search_status(event, status: "completed", yielder: yielder)
277
287
  when :"response.output_item.done"
278
288
  case event.item&.type
289
+ when :function_call then handle_output_item_done_function_call(event, yielder: yielder)
279
290
  when :web_search_call then handle_output_item_done_web_search(event, yielder: yielder)
280
291
  when :reasoning then handle_output_item_done_reasoning(event, yielder: yielder)
281
292
  end
@@ -299,10 +310,7 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
299
310
  #--
300
311
  #: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
301
312
  def handle_output_item_added_function_call(event, state:, yielder:)
302
- state[:tool_info][event.item.id] = {
303
- name: decode_tool_name(event.item.name, tools: @current_tools),
304
- call_id: event.item.call_id,
305
- }
313
+ state[:tool_names][event.item.id] = decode_tool_name(event.item.name, tools: @current_tools)
306
314
  end
307
315
 
308
316
  #--
@@ -324,23 +332,26 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
324
332
  #--
325
333
  #: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
326
334
  def handle_function_call_arguments_delta(event, state:, yielder:)
327
- tracked = state[:tool_info][event.item_id] || {}
328
335
  yielder << Riffer::StreamEvents::ToolCallDelta.new(
329
336
  item_id: event.item_id,
330
- name: tracked[:name],
337
+ name: state[:tool_names][event.item_id],
331
338
  arguments_delta: event.delta,
332
339
  )
333
340
  end
334
341
 
342
+ # Emitted from the finished item rather than function_call_arguments.done, because only the
343
+ # item's status marks a call cut off by max_output_tokens, whose arguments can't be run.
335
344
  #--
336
- #: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
337
- def handle_function_call_arguments_done(event, state:, yielder:)
338
- tracked = state[:tool_info][event.item_id] || {}
345
+ #: (untyped, yielder: Riffer::Providers::_EventSink) -> void
346
+ def handle_output_item_done_function_call(event, yielder:)
347
+ item = event.item
348
+ return if item.status == :incomplete
349
+
339
350
  yielder << Riffer::StreamEvents::ToolCallDone.new(
340
- item_id: event.item_id,
341
- call_id: tracked[:call_id] || event.item_id,
342
- name: tracked[:name],
343
- arguments: event.arguments,
351
+ item_id: item.id,
352
+ call_id: item.call_id,
353
+ name: decode_tool_name(item.name, tools: @current_tools),
354
+ arguments: item.arguments,
344
355
  )
345
356
  end
346
357
 
@@ -387,8 +398,8 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
387
398
  end
388
399
 
389
400
  #--
390
- #: (Array[Riffer::Messages::Base]) -> Array[Hash[Symbol, untyped]]
391
- 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:)
392
403
  messages.flat_map do |message|
393
404
  case message
394
405
  when Riffer::Messages::System
@@ -402,13 +413,17 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
402
413
  { role: "user", content: content }
403
414
  end
404
415
  when Riffer::Messages::Assistant
405
- convert_assistant_to_openai_format(message)
416
+ convert_assistant_to_openai_format(message, deferred_tools: deferred_tools)
406
417
  when Riffer::Messages::Tool
407
- {
418
+ output = {
408
419
  type: "function_call_output",
409
420
  call_id: message.tool_call_id,
410
421
  output: message.content,
411
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)]
412
427
  else
413
428
  raise Riffer::ArgumentError, "unsupported message type: #{message.class}"
414
429
  end
@@ -416,8 +431,22 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
416
431
  end
417
432
 
418
433
  #--
419
- #: (Riffer::Messages::Assistant) -> Array[Hash[Symbol, untyped]]
420
- 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:)
421
450
  items = convert_reasoning_to_openai_format(message.reasoning)
422
451
 
423
452
  if message.tool_calls.empty?
@@ -428,12 +457,16 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
428
457
  content: message.content, }
429
458
  end
430
459
  message.tool_calls.each do |tc|
460
+ name = encode_tool_name(tc.name)
431
461
  items << {
432
462
  type: "function_call",
433
463
  call_id: tc.call_id,
434
- 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 }),
435
468
  arguments: tc.arguments,
436
- }
469
+ }.compact
437
470
  end
438
471
  end
439
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
  #--
@@ -0,0 +1,21 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ # Carries a server tool block for replay. WebSearchStatus and WebSearchDone are the events to
5
+ # display.
6
+ class Riffer::StreamEvents::ServerToolDone < Riffer::StreamEvents::Base
7
+ attr_reader :part #: Riffer::Messages::Assistant::ServerToolPart # @dynamic part
8
+
9
+ #--
10
+ #: (Riffer::Messages::Assistant::ServerToolPart, ?role: Symbol) -> void
11
+ def initialize(part, role: :assistant)
12
+ super(role: role)
13
+ @part = part
14
+ end
15
+
16
+ #--
17
+ #: () -> Hash[Symbol, untyped]
18
+ def to_h
19
+ { role: @role, part: part.to_h }
20
+ end
21
+ end
@@ -21,6 +21,12 @@ module Riffer::Testing
21
21
  build_stub(name, base: base, &body) #: singleton(Riffer::Tool)
22
22
  end
23
23
 
24
+ #--
25
+ #: [T] () { () -> T } -> T
26
+ def allow_deprecations(&)
27
+ Riffer::Deprecation.allow(&)
28
+ end
29
+
24
30
  #--
25
31
  #: () -> void
26
32
  def reset!