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
data/lib/riffer/params.rb CHANGED
@@ -29,46 +29,18 @@ class Riffer::Params
29
29
  end
30
30
 
31
31
  #--
32
- #: (Symbol, singleton(Riffer::Params::AnyOf), ?description: String?) { (Riffer::Params::AnyOf) [self: Riffer::Params::AnyOf] -> void } -> void
33
- #: (Symbol, Module, ?description: String?, ?enum: Array[untyped]?, ?format: String?, ?of: (Module | Array[untyped])?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> void
32
+ #: (Symbol, :any_of | singleton(Riffer::Params::AnyOf), ?description: String?) { (Riffer::Params::AnyOf) [self: Riffer::Params::AnyOf] -> void } -> void
33
+ #: (Symbol, Symbol | Module, ?description: String?, ?enum: Array[untyped]?, ?format: String?, ?of: (Symbol | Module | Array[untyped])?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> void
34
34
  def required(name, type, description: nil, enum: nil, format: nil, of: nil, &)
35
- item_type, dimensions = unwrap_of(of)
36
- nested = build_nested(type, item_type, enum, &) unless type == Riffer::Params::AnyOf
37
- variants = build_variants(name, of, enum, &) if type == Riffer::Params::AnyOf
38
- @parameters << Riffer::Params::Param.new(
39
- name: name,
40
- type: type,
41
- required: true,
42
- description: description,
43
- enum: enum,
44
- format: format,
45
- item_type: item_type,
46
- dimensions: dimensions,
47
- nested_params: nested,
48
- variants: variants,
49
- )
35
+ add_param(name, type, required: true, description: description, enum: enum, format: format, of: of, &)
50
36
  end
51
37
 
52
38
  #--
53
- #: (Symbol, singleton(Riffer::Params::AnyOf), ?description: String?, ?default: untyped) { (Riffer::Params::AnyOf) [self: Riffer::Params::AnyOf] -> void } -> void
54
- #: (Symbol, Module, ?description: String?, ?enum: Array[untyped]?, ?format: String?, ?default: untyped, ?of: (Module | Array[untyped])?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> void
39
+ #: (Symbol, :any_of | singleton(Riffer::Params::AnyOf), ?description: String?, ?default: untyped) { (Riffer::Params::AnyOf) [self: Riffer::Params::AnyOf] -> void } -> void
40
+ #: (Symbol, Symbol | Module, ?description: String?, ?enum: Array[untyped]?, ?format: String?, ?default: untyped, ?of: (Symbol | Module | Array[untyped])?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> void
55
41
  def optional(name, type, description: nil, enum: nil, format: nil, default: nil, of: nil, &)
56
- item_type, dimensions = unwrap_of(of)
57
- nested = build_nested(type, item_type, enum, &) unless type == Riffer::Params::AnyOf
58
- variants = build_variants(name, of, enum, &) if type == Riffer::Params::AnyOf
59
- @parameters << Riffer::Params::Param.new(
60
- name: name,
61
- type: type,
62
- required: false,
63
- description: description,
64
- enum: enum,
65
- format: format,
66
- default: default,
67
- item_type: item_type,
68
- dimensions: dimensions,
69
- nested_params: nested,
70
- variants: variants,
71
- )
42
+ add_param(name, type,
43
+ required: false, description: description, enum: enum, format: format, default: default, of: of, &)
72
44
  end
73
45
 
74
46
  #--
@@ -138,7 +110,30 @@ class Riffer::Params
138
110
  end
139
111
 
140
112
  #--
141
- #: ((Module | Array[untyped])?, ?Integer) -> [Module?, Integer]
113
+ #: (Symbol, untyped, required: bool, description: String?, enum: Array[untyped]?, format: String?, ?default: untyped, of: (Symbol | Module | Array[untyped])?) ?{ (untyped) [self: untyped] -> void } -> void
114
+ def add_param(name, type, required:, description:, enum:, format:, of:, default: nil, &)
115
+ type = Riffer::Params::Param.resolve_type!(type, "type", Riffer::Params::Param::TYPES)
116
+ of_type, dimensions = unwrap_of(of)
117
+ item_type = Riffer::Params::Param.resolve_type!(of_type, "of:", Riffer::Params::Param::PRIMITIVE_TYPES) if of_type
118
+ nested = build_nested(type, item_type, enum, &) unless type == :any_of
119
+ variants = build_variants(name, of, enum, &) if type == :any_of
120
+ @parameters << Riffer::Params::Param.new(
121
+ name: name,
122
+ type: type,
123
+ required: required,
124
+ description: description,
125
+ enum: enum,
126
+ format: format,
127
+ default: default,
128
+ item_type: item_type,
129
+ dimensions: dimensions,
130
+ nested_params: nested,
131
+ variants: variants,
132
+ )
133
+ end
134
+
135
+ #--
136
+ #: ((Symbol | Module | Array[untyped])?, ?Integer) -> [(Symbol | Module)?, Integer]
142
137
  def unwrap_of(of, dimensions = 1)
143
138
  return [of, dimensions] unless of.is_a?(Array)
144
139
  raise Riffer::ArgumentError, "of: must nest exactly one type, got #{of.inspect}" unless of.size == 1 && of.first
@@ -147,25 +142,21 @@ class Riffer::Params
147
142
  end
148
143
 
149
144
  #--
150
- #: (Module, Module?, Array[untyped]?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> Riffer::Params?
145
+ #: (Symbol, Symbol?, Array[untyped]?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> Riffer::Params?
151
146
  def build_nested(type, of, enum, &block)
152
147
  raise Riffer::ArgumentError, "cannot use both of: and a block" if of && block
153
- raise Riffer::ArgumentError, "enum: cannot be used with Hash" if enum && type == Hash
154
- raise Riffer::ArgumentError, "enum: with Array requires of:" if enum && type == Array && !of
148
+ raise Riffer::ArgumentError, "enum: cannot be used with :object" if enum && type == :object
149
+ raise Riffer::ArgumentError, "enum: with :array requires of:" if enum && type == :array && !of
155
150
 
156
151
  if of
157
- raise Riffer::ArgumentError, "of: can only be used with Array type, got #{type}" unless type == Array
152
+ raise Riffer::ArgumentError, "of: can only be used with :array, got #{type.inspect}" unless type == :array
158
153
 
159
- unless Riffer::Params::Param::PRIMITIVE_TYPES.include?(of)
160
- primitives = Riffer::Params::Param::PRIMITIVE_TYPES.map(&:name).join(", ")
161
- raise Riffer::ArgumentError, "of: must be a primitive type (#{primitives}), got #{of}"
162
- end
163
154
  return nil
164
155
  end
165
156
 
166
157
  return unless block
167
- unless [Hash, Array].include?(type)
168
- raise Riffer::ArgumentError, "block can only be used with Hash or Array type, got #{type}"
158
+ unless %i[object array].include?(type)
159
+ raise Riffer::ArgumentError, "block can only be used with :object or :array, got #{type.inspect}"
169
160
  end
170
161
 
171
162
  nested = Riffer::Params.new
@@ -174,15 +165,15 @@ class Riffer::Params
174
165
  end
175
166
 
176
167
  #--
177
- #: (Symbol, (Module | Array[untyped])?, Array[untyped]?) ?{ (Riffer::Params::AnyOf) [self: Riffer::Params::AnyOf] -> void } -> Array[Riffer::Params | Riffer::Params::Param]
168
+ #: (Symbol, (Symbol | Module | Array[untyped])?, Array[untyped]?) ?{ (Riffer::Params::AnyOf) [self: Riffer::Params::AnyOf] -> void } -> Array[Riffer::Params | Riffer::Params::Param]
178
169
  def build_variants(name, of, enum, &block)
179
- raise Riffer::ArgumentError, "of: cannot be used with AnyOf" if of
180
- raise Riffer::ArgumentError, "enum: cannot be used with AnyOf" if enum
181
- raise Riffer::ArgumentError, "AnyOf requires a block defining its variants" unless block
170
+ raise Riffer::ArgumentError, "of: cannot be used with :any_of" if of
171
+ raise Riffer::ArgumentError, "enum: cannot be used with :any_of" if enum
172
+ raise Riffer::ArgumentError, ":any_of requires a block defining its variants" unless block
182
173
 
183
174
  any_of = Riffer::Params::AnyOf.new(name)
184
175
  any_of.instance_eval(&block)
185
- raise Riffer::ArgumentError, "AnyOf requires at least two variants" if any_of.variants.size < 2
176
+ raise Riffer::ArgumentError, ":any_of requires at least two variants" if any_of.variants.size < 2
186
177
 
187
178
  any_of.variants
188
179
  end
@@ -203,13 +194,13 @@ class Riffer::Params
203
194
  #--
204
195
  #: (Riffer::Params::Param, untyped, Array[String]) -> untyped
205
196
  def validate_nested(param, value, errors)
206
- if param.type == Riffer::Params::AnyOf
197
+ if param.type == :any_of
207
198
  validate_any_of(param, value, errors)
208
- elsif param.type == Hash && param.nested_params
199
+ elsif param.type == :object && param.nested_params
209
200
  validate_nested_hash(param, value, errors)
210
- elsif param.type == Array && param.nested_params
201
+ elsif param.type == :array && param.nested_params
211
202
  validate_nested_array_of_objects(param, value, errors)
212
- elsif param.type == Array && param.item_type
203
+ elsif param.type == :array && param.item_type
213
204
  validate_typed_array(param, value, errors)
214
205
  else
215
206
  value
@@ -322,8 +313,8 @@ class Riffer::Params
322
313
  next item
323
314
  end
324
315
 
325
- unless valid_item?(item_type, item)
326
- errors << "#{item_path} must be a #{Riffer::Params::Param::TYPE_MAPPINGS[item_type]}"
316
+ unless Riffer::Params::Param.value_of_type?(item_type, item)
317
+ errors << "#{item_path} must be a #{item_type.name}"
327
318
  next item
328
319
  end
329
320
 
@@ -342,23 +333,11 @@ class Riffer::Params
342
333
  end
343
334
 
344
335
  #--
345
- #: (Module, untyped) -> bool
346
- def valid_item?(type, item)
347
- if [Riffer::Params::Boolean, TrueClass, FalseClass].include?(type)
348
- [true, false].include?(item)
349
- elsif type == Float
350
- item.is_a?(Numeric)
351
- else
352
- item.is_a?(type)
353
- end
354
- end
355
-
356
- #--
357
- #: (Module, untyped) -> untyped
336
+ #: (Symbol, untyped) -> untyped
358
337
  def coerce_value(type, value)
359
338
  # JSON Schema "number" accepts integers; callers shouldn't get a type that
360
339
  # depends on whether the model wrote a decimal point.
361
- return value.to_f if type == Float
340
+ return value.to_f if type == :number
362
341
 
363
342
  value
364
343
  end
@@ -10,6 +10,12 @@ class Riffer::Providers::AnthropicCompatible::MessagesAPI::Stream
10
10
  # @rbs @web_search_query: String?
11
11
  # @rbs @completed: bool
12
12
 
13
+ # Each server tool has its own result type (web search run from code execution returns
14
+ # +code_execution_tool_result+ blocks too), and the API rejects a server_tool_use sent back
15
+ # without its result. +mcp_tool_result+ pairs with +mcp_tool_use+, which riffer drops, so
16
+ # its result is dropped too.
17
+ SERVER_TOOL_RESULT_TYPE = /\A(?!mcp_)\w+_tool_result\z/ #: Regexp
18
+
13
19
  #--
14
20
  #: (Hash[Symbol, untyped]) -> Riffer::Messages::Assistant::ReasoningPart?
15
21
  def self.reasoning_part(block)
@@ -28,6 +34,20 @@ class Riffer::Providers::AnthropicCompatible::MessagesAPI::Stream
28
34
  end
29
35
  end
30
36
 
37
+ #--
38
+ #: (Hash[Symbol, untyped]) -> Riffer::Messages::Assistant::ServerToolPart
39
+ def self.server_tool_part(block)
40
+ call = block[:type] == "server_tool_use"
41
+
42
+ Riffer::Messages::Assistant::ServerToolPart.new(
43
+ name: call ? block[:name] : block[:type].delete_suffix("_tool_result"),
44
+ kind: call ? :call : :result,
45
+ data: JSON.generate(block),
46
+ id: call ? block[:id] : block[:tool_use_id],
47
+ format: Riffer::Providers::AnthropicCompatible::MessagesAPI::REASONING_FORMAT,
48
+ )
49
+ end
50
+
31
51
  #--
32
52
  #: (tools: Array[singleton(Riffer::Tool)]) -> void
33
53
  def initialize(tools:)
@@ -48,12 +68,13 @@ class Riffer::Providers::AnthropicCompatible::MessagesAPI::Stream
48
68
  when "content_block_delta" then apply_delta(event, yielder)
49
69
  when "content_block_stop" then stop_block(event, yielder)
50
70
  when "message_delta" then apply_message_delta(event)
51
- when "message_stop" then stop_message(yielder)
71
+ when "message_stop" then @completed = true
52
72
  when "error" then raise_stream_error(event)
53
73
  end
54
74
  end
55
75
 
56
- # The caller reads finish reason and usage from here so it can price the usage.
76
+ # The caller reads the text, finish reason and usage from here, since one turn
77
+ # can take several streams.
57
78
  #--
58
79
  #: () -> Hash[Symbol, untyped]
59
80
  def finish!
@@ -137,11 +158,15 @@ class Riffer::Providers::AnthropicCompatible::MessagesAPI::Stream
137
158
  yielder << Riffer::StreamEvents::ReasoningDone.new(part)
138
159
  when "server_tool_use"
139
160
  block[:input] = parse_input(@partial_json.delete(index).to_s) || {}
161
+ yielder << Riffer::StreamEvents::ServerToolDone.new(self.class.server_tool_part(block))
140
162
  return unless block[:name] == "web_search"
141
163
 
142
164
  @web_search_query = block[:input]["query"]
143
165
  yielder << Riffer::StreamEvents::WebSearchStatus.new("searching", query: @web_search_query)
144
- when "web_search_tool_result"
166
+ when SERVER_TOOL_RESULT_TYPE
167
+ yielder << Riffer::StreamEvents::ServerToolDone.new(self.class.server_tool_part(block))
168
+ return unless block[:type] == "web_search_tool_result"
169
+
145
170
  yielder << Riffer::StreamEvents::WebSearchDone.new(@web_search_query || "", sources: web_search_sources(block))
146
171
  @web_search_query = nil
147
172
  end
@@ -156,14 +181,6 @@ class Riffer::Providers::AnthropicCompatible::MessagesAPI::Stream
156
181
  @message[:usage] = (@message[:usage] || {}).merge(usage.compact) if usage
157
182
  end
158
183
 
159
- #--
160
- #: (Riffer::Providers::_EventSink) -> void
161
- def stop_message(yielder)
162
- @completed = true
163
- text = @message[:content].filter_map { |block| block[:text] if block[:type] == "text" }.join
164
- yielder << Riffer::StreamEvents::TextDone.new(text) unless text.empty?
165
- end
166
-
167
184
  #--
168
185
  #: (Hash[Symbol, untyped]) -> void
169
186
  def raise_stream_error(event)
@@ -11,14 +11,17 @@ 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
- # request.
24
+ # request. Server tool parts and text parts that keep their block carry it too.
22
25
  REASONING_FORMAT = "anthropic-messages-v1" #: String
23
26
 
24
27
  #--
@@ -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,36 +91,74 @@ 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!
73
95
  end
74
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.
75
99
  #--
76
- #: (Hash[Symbol, untyped]) -> String
77
- def extract_content(response)
78
- content_blocks(response).filter_map { |block| block[:text] if block[:type] == "text" }.join
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
79
121
  end
80
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.
81
125
  #--
82
- #: (Hash[Symbol, untyped]) -> Array[Riffer::Messages::Assistant::ToolCall]
83
- def extract_tool_calls(response)
84
- content_blocks(response).filter_map do |block|
85
- next unless block[:type] == "tool_use"
126
+ #: (Hash[Symbol, untyped]?, Hash[Symbol, untyped]?) -> Hash[Symbol, untyped]?
127
+ def merge_usage(first, second)
128
+ return first || second unless first && second
86
129
 
87
- Riffer::Messages::Assistant::ToolCall.new(
88
- call_id: block[:id],
89
- name: decode_tool_name(block[:name], tools: @current_tools),
90
- arguments: (block[:input] || {}).to_json,
91
- )
130
+ first.merge(second.compact) { |_key, a, b| a.is_a?(Integer) && b.is_a?(Integer) ? a + b : b }
131
+ end
132
+
133
+ # Claude signs each thinking block over every block before it in the turn, so
134
+ # the blocks go back in the order they came.
135
+ #--
136
+ #: (Hash[Symbol, untyped]) -> Array[Riffer::Messages::Assistant::TextPart | Riffer::Messages::Assistant::ReasoningPart | Riffer::Messages::Assistant::ToolCall | Riffer::Messages::Assistant::ServerToolPart]
137
+ def extract_parts(response)
138
+ content_blocks(response).filter_map do |block|
139
+ case block[:type]
140
+ when "text" then text_part(block)
141
+ when "tool_use"
142
+ Riffer::Messages::Assistant::ToolCall.new(
143
+ call_id: block[:id],
144
+ name: decode_tool_name(block[:name], tools: @current_tools),
145
+ arguments: (block[:input] || {}).to_json,
146
+ )
147
+ when "server_tool_use", Stream::SERVER_TOOL_RESULT_TYPE then Stream.server_tool_part(block)
148
+ else Stream.reasoning_part(block)
149
+ end
92
150
  end
93
151
  end
94
152
 
153
+ # The block is kept only when it carries citations, which point into the
154
+ # search results and go back with the text.
95
155
  #--
96
- #: (Hash[Symbol, untyped]) -> Array[Riffer::Messages::Assistant::ReasoningPart]
97
- def extract_reasoning(response)
98
- content_blocks(response).filter_map { |block| Stream.reasoning_part(block) }
156
+ #: (Hash[Symbol, untyped]) -> Riffer::Messages::Assistant::TextPart
157
+ def text_part(block)
158
+ citations = block[:citations]
159
+ return Riffer::Messages::Assistant::TextPart.new(block[:text].to_s) if citations.nil? || citations.empty?
160
+
161
+ Riffer::Messages::Assistant::TextPart.new(block[:text].to_s, data: JSON.generate(block), format: REASONING_FORMAT)
99
162
  end
100
163
 
101
164
  #--
@@ -136,8 +199,9 @@ class Riffer::Providers::AnthropicCompatible::MessagesAPI < Riffer::Providers::B
136
199
  #--
137
200
  #: (Array[Riffer::Messages::Base], String?, Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
138
201
  def build_request_params(messages, model, options)
139
- partitioned_messages = partition_messages(messages)
140
202
  tools = options[:tools]
203
+ deferred_tools = options[:deferred_tools] || []
204
+ partitioned_messages = partition_messages(messages, deferred_tools)
141
205
  structured_output = options[:structured_output]
142
206
  web_search = options[:web_search]
143
207
  tags = options[:tags] || {}
@@ -148,7 +212,7 @@ class Riffer::Providers::AnthropicCompatible::MessagesAPI < Riffer::Providers::B
148
212
  model: model,
149
213
  messages: partitioned_messages[:conversation],
150
214
  max_tokens: max_tokens,
151
- **options.except(:tools, :max_tokens, :structured_output, :web_search, :tags),
215
+ **options.except(:tools, :deferred_tools, :max_tokens, :structured_output, :web_search, :tags),
152
216
  } #: Hash[Symbol, untyped]
153
217
 
154
218
  params[:system] = partitioned_messages[:system] if partitioned_messages[:system]
@@ -159,6 +223,9 @@ class Riffer::Providers::AnthropicCompatible::MessagesAPI < Riffer::Providers::B
159
223
  api_tools = [] #: Array[Hash[Symbol, untyped]]
160
224
  api_tools.concat(tools.map { |t| convert_tool(t) }) if tools && !tools.empty?
161
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) })
162
229
 
163
230
  if structured_output
164
231
  # The format wins over caller output_config keys because the run loop
@@ -202,8 +269,9 @@ class Riffer::Providers::AnthropicCompatible::MessagesAPI < Riffer::Providers::B
202
269
  end
203
270
 
204
271
  #--
205
- #: (Array[Riffer::Messages::Base]) -> Hash[Symbol, untyped]
206
- 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)
207
275
  system_prompts = [] #: Array[Hash[Symbol, untyped]]
208
276
  conversation_messages = [] #: Array[Hash[Symbol, untyped]]
209
277
 
@@ -227,7 +295,7 @@ class Riffer::Providers::AnthropicCompatible::MessagesAPI < Riffer::Providers::B
227
295
  content: [{
228
296
  type: "tool_result",
229
297
  tool_use_id: message.tool_call_id,
230
- content: message.content,
298
+ content: tool_result_content(message, deferred_names),
231
299
  }],
232
300
  }
233
301
  end
@@ -239,24 +307,54 @@ class Riffer::Providers::AnthropicCompatible::MessagesAPI < Riffer::Providers::B
239
307
  }
240
308
  end
241
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
+
242
323
  #--
243
324
  #: (Riffer::Messages::Assistant) -> Hash[Symbol, untyped]
244
325
  def convert_assistant(message)
245
- content = message.reasoning.filter_map do |part|
246
- convert_reasoning_part(part) if part.format == REASONING_FORMAT
247
- end
248
- content << { type: "text", text: message.content } if message.content && !message.content.empty?
326
+ { role: "assistant", content: message.parts.filter_map { |part| convert_part(part) } }
327
+ end
249
328
 
250
- message.tool_calls.each do |tc|
251
- content << {
329
+ #--
330
+ #: (Riffer::Messages::Assistant::TextPart | Riffer::Messages::Assistant::ReasoningPart | Riffer::Messages::Assistant::ToolCall | Riffer::Messages::Assistant::ServerToolPart) -> Hash[Symbol, untyped]?
331
+ def convert_part(part)
332
+ case part
333
+ when Riffer::Messages::Assistant::TextPart then convert_text_part(part)
334
+ when Riffer::Messages::Assistant::ToolCall
335
+ {
252
336
  type: "tool_use",
253
- id: tc.call_id,
254
- name: encode_tool_name(tc.name),
255
- input: parse_tool_arguments(tc.arguments),
337
+ id: part.call_id,
338
+ name: encode_tool_name(part.name),
339
+ input: parse_tool_arguments(part.arguments),
256
340
  }
341
+ when Riffer::Messages::Assistant::ServerToolPart
342
+ JSON.parse(part.data, symbolize_names: true) if part.format == REASONING_FORMAT
343
+ when Riffer::Messages::Assistant::ReasoningPart
344
+ convert_reasoning_part(part) if part.format == REASONING_FORMAT
257
345
  end
346
+ end
347
+
348
+ # The API rejects text blocks that are empty or only whitespace.
349
+ #--
350
+ #: (Riffer::Messages::Assistant::TextPart) -> Hash[Symbol, untyped]?
351
+ def convert_text_part(part)
352
+ return nil if part.text.strip.empty?
353
+
354
+ data = part.data
355
+ return JSON.parse(data, symbolize_names: true) if data && part.format == REASONING_FORMAT
258
356
 
259
- { role: "assistant", content: content }
357
+ { type: "text", text: part.text }
260
358
  end
261
359
 
262
360
  #--