rig_agent/run/streamed.rs
1//! Streamed-turn assembly and early invalid-call diagnostics for [`super::AgentRun`].
2//!
3//! Drivers ingest a completion stream's items, resolve invalid calls before
4//! continuing, and finish with the response the stream folded into. The
5//! assembler performs no I/O and returns forwarding instructions as
6//! [`StreamedTurnEvent`].
7//!
8//! ```
9//! use rig_agent::run::streamed::StreamedTurnAssembler;
10//! let assembler = StreamedTurnAssembler::new(Default::default(), Default::default());
11//! assert!(assembler.aggregated_text().is_empty());
12//! ```
13
14use std::collections::{BTreeMap, BTreeSet};
15
16use serde::{Deserialize, Serialize};
17
18use rig_core::completion::{FinishReason, Message};
19use rig_core::error::ProviderError;
20use rig_core::json_utils;
21use rig_core::message::{
22 AssistantContent, CallId, Reasoning, Sealed, ToolCall, ToolFunction, ToolName, ToolResult,
23};
24use rig_core::streaming::{Item, PartKind, StreamEvent};
25
26use super::policy::InvalidToolCallReason;
27use super::transcript::{TOOL_NOT_EXECUTED_DUE_TO_INVALID_PEER, tool_result_message};
28
29/// Detect unknown payloads containing assistant content that assembly would lose:
30/// tagged assistant blocks or text with malformed additional parameters.
31fn unknown_payload_loses_assistant_content(payload: &serde_json::Value) -> bool {
32 // Deserialize by reference to avoid cloning large unknown payloads.
33 if AssistantContent::deserialize(payload).is_ok() {
34 return true;
35 }
36 // Malformed metadata must not hide the loss of an otherwise valid text field.
37 payload
38 .get("text")
39 .is_some_and(serde_json::Value::is_string)
40 && payload.get("additional_params").is_some()
41}
42
43/// One invalid tool call surfaced mid-stream, awaiting a resolution from
44/// `AgentRun::resolve_streamed_invalid_tool_call`.
45#[derive(Debug, Clone, Serialize, Deserialize)]
46pub struct StreamedInvalidToolCall {
47 /// The rejected tool call. For malformed arguments its `arguments` is
48 /// `Null`: no object was ever parsed, and fabricating one would
49 /// misrepresent the wire.
50 pub tool_call: ToolCall,
51 /// Raw argument payload for diagnostics, when available.
52 pub args: Option<String>,
53 /// Executable Rig tools advertised to the provider for this turn.
54 pub executable_tool_names: BTreeSet<String>,
55 /// Tools allowed by the active tool choice for this turn.
56 pub allowed_tool_names: BTreeSet<String>,
57 /// Why the call was rejected.
58 pub reason: InvalidToolCallReason,
59}
60
61/// Snapshot of a streamed turn at the moment an invalid tool call appeared.
62/// Used by the machine to build diagnostics and rollback messages from
63/// exactly what the model has produced so far.
64#[derive(Debug, Clone, Serialize, Deserialize)]
65pub struct PartialStreamedTurn {
66 /// Provider-assigned assistant message ID, when already known.
67 pub message_id: Option<String>,
68 /// Aggregated assistant text, when any text was streamed this turn.
69 pub text: Option<String>,
70 /// The reasoning parts that ended so far, sealed to their issuer.
71 pub reasoning: Vec<Sealed<Reasoning>>,
72 /// Tool calls already validated (or repaired) this turn.
73 pub pending_tool_calls: Vec<ToolCall>,
74}
75
76impl PartialStreamedTurn {
77 /// The assistant message representing this partial turn (reasoning, then
78 /// text, then calls), including `current_tool_call` when provided.
79 /// `None` when the turn has produced no representable content.
80 pub fn assistant_message(&self, current_tool_call: Option<ToolCall>) -> Option<Message> {
81 let content = self
82 .reasoning
83 .iter()
84 .cloned()
85 .map(AssistantContent::Reasoning)
86 .chain(
87 self.text
88 .as_ref()
89 .filter(|text| !text.is_empty())
90 .map(|text| AssistantContent::text(text.clone())),
91 )
92 .chain(
93 self.pending_tool_calls
94 .iter()
95 .cloned()
96 .chain(current_tool_call)
97 .map(AssistantContent::ToolCall),
98 )
99 .collect::<Vec<_>>();
100 if content.is_empty() {
101 return None;
102 }
103 Some(Message::Assistant {
104 id: self.message_id.clone(),
105 content,
106 })
107 }
108
109 /// Rollback messages for a retried or skipped streamed turn: the partial
110 /// assistant turn plus a user message carrying `feedback` for the invalid
111 /// call and a synthetic "not executed" result for each validated peer.
112 pub fn rollback_messages(
113 &self,
114 invalid_tool_call: ToolCall,
115 feedback: String,
116 ) -> Option<(Message, Message)> {
117 // Preserve call IDs so synthetic results correlate with their diagnostic calls.
118 let assistant_message = self.assistant_message(Some(invalid_tool_call.clone()))?;
119
120 let mut retry_results = self
121 .pending_tool_calls
122 .iter()
123 .map(|tool_call| {
124 tool_result_message(
125 tool_call.id.clone(),
126 tool_call.function.name.clone(),
127 TOOL_NOT_EXECUTED_DUE_TO_INVALID_PEER.to_string(),
128 )
129 })
130 .collect::<Vec<_>>();
131 retry_results.push(tool_result_message(
132 invalid_tool_call.id,
133 invalid_tool_call.function.name,
134 feedback,
135 ));
136
137 let user_message = Message::User {
138 content: retry_results,
139 };
140
141 Some((assistant_message, user_message))
142 }
143}
144
145/// The assembled streamed turn, fed to
146/// `AgentRun::streamed_turn`.
147#[derive(Debug, Clone, Serialize, Deserialize)]
148pub struct StreamedTurn {
149 /// Provider-assigned assistant message ID, when available.
150 pub message_id: Option<String>,
151 /// The assistant content to record in history, in the order its parts
152 /// started, with ignored calls left out and repaired calls renamed.
153 pub choice: Vec<AssistantContent>,
154 /// Executable Rig tools advertised to the provider for this turn.
155 pub executable_tool_names: BTreeSet<String>,
156 /// Tools allowed by the active tool choice for this turn.
157 pub allowed_tool_names: BTreeSet<String>,
158 /// Provider-reported terminal reason for this turn, when available.
159 pub finish_reason: Option<FinishReason>,
160}
161
162/// Resolution a driver must apply to a mid-stream invalid tool call.
163#[derive(Debug)]
164pub enum StreamedResolution {
165 /// The tool name was repaired. Apply it via
166 /// [`StreamedTurnAssembler::resolve_pending_invalid`] and keep consuming
167 /// the provider stream.
168 Repaired {
169 /// The validated replacement tool name.
170 tool_name: String,
171 },
172 /// The turn was rolled back (retry) or the call skipped; corrective
173 /// messages are already in the history. Finish the provider stream for
174 /// usage, record the completion call, then call
175 /// `AgentRun::next_step`.
176 TurnAbandoned {
177 /// For a skipped call, the synthetic tool result to surface to the
178 /// consumer stream.
179 skipped_tool_result: Option<ToolResult>,
180 },
181 /// The invalid call is dropped and the turn goes on without it: the
182 /// runner's `UnhandledInvalidToolCall::Ignore` on the streaming
183 /// surface. Apply it via
184 /// [`StreamedTurnAssembler::resolve_pending_invalid`] and keep consuming
185 /// the provider stream; nothing of the call enters the run.
186 Ignored,
187}
188
189/// Required driver action after ingesting a stream item.
190#[derive(Debug, Clone, Serialize, Deserialize)]
191pub enum StreamedTurnEvent {
192 /// Forward the ingested item to the consumer as-is.
193 EmitIngested,
194 /// Hold the ingested item back: it belongs to a tool call that is not
195 /// validated until its end.
196 HoldToolCall,
197 /// Forward the held items of the call that just ended, then its end
198 /// carrying `call` (the call as validated, with a repaired name).
199 EmitToolCall {
200 /// The validated call.
201 call: ToolCall,
202 },
203 /// The model emitted an unknown or disallowed tool call, or one whose
204 /// arguments are not JSON. Resolve it via
205 /// `AgentRun::resolve_streamed_invalid_tool_call`, then apply the
206 /// outcome with [`StreamedTurnAssembler::resolve_pending_invalid`].
207 InvalidToolCall(StreamedInvalidToolCall),
208}
209
210#[derive(Clone, Serialize, Deserialize)]
211enum PendingInvalid {
212 /// A complete tool call with a disallowed name.
213 Call { tool_call: ToolCall },
214 /// A tool call whose arguments were not JSON. The reply ended with it,
215 /// so the only resolutions are abandon or fail.
216 MalformedArgs { tool_call: ToolCall },
217}
218
219/// Serializable accumulator for one streamed turn. Persisted state requires the
220/// same library version; it does not itself resume a provider connection.
221/// Drivers must resolve pending invalid calls before ingesting more events.
222/// Dropping warns once if assistant content was excluded, otherwise stays silent.
223#[derive(Clone, Serialize, Deserialize)]
224pub struct StreamedTurnAssembler {
225 executable_tool_names: BTreeSet<String>,
226 allowed_tool_names: BTreeSet<String>,
227 text: String,
228 /// Reasoning text per part, by the part's position.
229 reasoning: BTreeMap<usize, String>,
230 pending_tool_calls: Vec<ToolCall>,
231 pending_invalid: Option<PendingInvalid>,
232 /// Calls an [`StreamedResolution::Ignored`] dropped: the stream's
233 /// response still carries them, and [`Self::finish`] leaves them out.
234 ignored_calls: Vec<CallId>,
235 /// Calls a [`StreamedResolution::Repaired`] renamed, applied to the
236 /// stream's response at [`Self::finish`].
237 repaired_calls: Vec<(CallId, ToolName)>,
238 /// Replayed assistant blocks excluded from assembly this turn (see
239 /// [`unknown_payload_loses_assistant_content`]): counted per item,
240 /// surfaced as one warning when the guard drops.
241 excluded_assistant_content: ExclusionCount,
242}
243
244/// Persisted count of excluded assistant blocks. Each clone warns once on drop
245/// when nonzero, including cancellation and error paths. A separate drop guard
246/// leaves the assembler's fields movable.
247#[derive(Default, Clone, Serialize, Deserialize)]
248#[serde(transparent)]
249struct ExclusionCount(usize);
250
251impl Drop for ExclusionCount {
252 fn drop(&mut self) {
253 if self.0 > 0 {
254 tracing::warn!(
255 excluded = self.0,
256 "stream items matching rig's tagged assistant-content \
257 serialization were excluded from the assembled assistant \
258 message — replayed assistant blocks are not stream-item \
259 shapes, and their content is lost from assembled history"
260 );
261 }
262 }
263}
264
265impl StreamedTurnAssembler {
266 /// Create an assembler for one streamed turn with the tool names
267 /// advertised to the provider for that turn.
268 pub fn new(
269 executable_tool_names: BTreeSet<String>,
270 allowed_tool_names: BTreeSet<String>,
271 ) -> Self {
272 Self {
273 executable_tool_names,
274 allowed_tool_names,
275 text: String::new(),
276 reasoning: BTreeMap::new(),
277 pending_tool_calls: Vec::new(),
278 pending_invalid: None,
279 ignored_calls: Vec::new(),
280 repaired_calls: Vec::new(),
281 excluded_assistant_content: ExclusionCount::default(),
282 }
283 }
284
285 /// Replayed assistant blocks excluded from assembly so far this turn.
286 /// Zero on well-formed provider streams; non-zero means transcript
287 /// content was lost (one warning summarizes the count).
288 pub fn excluded_assistant_content(&self) -> usize {
289 self.excluded_assistant_content.0
290 }
291
292 /// Aggregated assistant text streamed so far this turn.
293 pub fn aggregated_text(&self) -> &str {
294 &self.text
295 }
296
297 /// The reasoning text accumulated so far for the part at `index`.
298 pub fn aggregated_reasoning(&self, index: usize) -> Option<&str> {
299 self.reasoning.get(&index).map(String::as_str)
300 }
301
302 /// Ingest one provider stream item and return what the driver must do.
303 ///
304 /// # Errors
305 /// Returns an error when an invalid tool call is still awaiting
306 /// resolution.
307 pub fn ingest(
308 &mut self,
309 item: &Item<StreamEvent>,
310 ) -> Result<Vec<StreamedTurnEvent>, ProviderError> {
311 if self.pending_invalid.is_some() {
312 return Err(ProviderError::Response(
313 "streamed turn ingested while an invalid tool call awaits resolution".to_string(),
314 ));
315 }
316 let event = match item {
317 Item::Event(event) => event,
318 Item::Unknown(payload) => {
319 // Unknown items have no assistant-content representation. Count lost
320 // assistant blocks for one warning without exposing payloads or flooding logs.
321 if unknown_payload_loses_assistant_content(payload.value()) {
322 self.excluded_assistant_content.0 += 1;
323 tracing::debug!(
324 excluded = self.excluded_assistant_content.0,
325 "stream item is a replayed assistant block, not a \
326 stream-item shape; excluded from assembly"
327 );
328 }
329 return Ok(vec![StreamedTurnEvent::EmitIngested]);
330 }
331 };
332 match event {
333 StreamEvent::Text { text, .. } => {
334 self.text.push_str(text);
335 Ok(vec![StreamedTurnEvent::EmitIngested])
336 }
337 StreamEvent::Reasoning { part, text } => {
338 self.reasoning
339 .entry(part.index())
340 .or_default()
341 .push_str(text);
342 Ok(vec![StreamedTurnEvent::EmitIngested])
343 }
344 StreamEvent::Start {
345 kind: PartKind::ToolCall,
346 ..
347 }
348 | StreamEvent::Arguments { .. } => Ok(vec![StreamedTurnEvent::HoldToolCall]),
349 StreamEvent::End {
350 content: AssistantContent::ToolCall(tool_call),
351 ..
352 } => {
353 if !self
354 .allowed_tool_names
355 .contains(tool_call.function.name.as_str())
356 {
357 return Ok(self.surface_invalid_call(
358 tool_call.clone(),
359 Some(json_utils::serialize_json_value(
360 &tool_call.function.arguments,
361 )),
362 PendingInvalid::Call {
363 tool_call: tool_call.clone(),
364 },
365 InvalidToolCallReason::UnknownTool,
366 ));
367 }
368 self.pending_tool_calls.push(tool_call.clone());
369 Ok(vec![StreamedTurnEvent::EmitToolCall {
370 call: tool_call.clone(),
371 }])
372 }
373 StreamEvent::Start { .. } | StreamEvent::End { .. } => {
374 Ok(vec![StreamedTurnEvent::EmitIngested])
375 }
376 }
377 }
378
379 /// Apply the machine's resolution for the invalid tool call surfaced by
380 /// the last [`StreamedTurnEvent::InvalidToolCall`]. A repaired call is
381 /// returned to forward under its new name.
382 pub fn resolve_pending_invalid(
383 &mut self,
384 resolution: &StreamedResolution,
385 ) -> Vec<StreamedTurnEvent> {
386 let Some(pending) = self.pending_invalid.take() else {
387 return Vec::new();
388 };
389
390 match (resolution, pending) {
391 (
392 StreamedResolution::Repaired { tool_name },
393 PendingInvalid::Call { mut tool_call },
394 ) => {
395 if let Ok(tool_name) = ToolName::new(tool_name.clone()) {
396 self.repaired_calls
397 .push((tool_call.id.clone(), tool_name.clone()));
398 tool_call.function.name = tool_name;
399 }
400 self.pending_tool_calls.push(tool_call.clone());
401 vec![StreamedTurnEvent::EmitToolCall { call: tool_call }]
402 }
403 // Repair is rejected upstream for malformed arguments (the run
404 // fails closed); reaching here would be a protocol violation, so
405 // the call is simply not resurrected.
406 (StreamedResolution::Repaired { .. }, PendingInvalid::MalformedArgs { .. })
407 | (StreamedResolution::TurnAbandoned { .. }, _) => Vec::new(),
408 (
409 StreamedResolution::Ignored,
410 PendingInvalid::Call { tool_call } | PendingInvalid::MalformedArgs { tool_call },
411 ) => {
412 self.ignored_calls.push(tool_call.id);
413 Vec::new()
414 }
415 }
416 }
417
418 /// Snapshot of the turn so far, for diagnostics and rollback messages.
419 /// `ended` is what the stream folded so far; its reasoning parts are the
420 /// snapshot's.
421 pub fn partial_turn(
422 &self,
423 message_id: Option<String>,
424 ended: &[AssistantContent],
425 ) -> PartialStreamedTurn {
426 PartialStreamedTurn {
427 message_id,
428 text: (!self.text.is_empty()).then(|| self.text.clone()),
429 reasoning: ended
430 .iter()
431 .filter_map(|content| match content {
432 AssistantContent::Reasoning(reasoning) => Some(reasoning.clone()),
433 _ => None,
434 })
435 .collect(),
436 pending_tool_calls: self.pending_tool_calls.clone(),
437 }
438 }
439
440 /// Assemble the completed turn from the response the stream folded
441 /// into: its choice in start order, with the calls this turn ignored
442 /// left out and the ones it repaired renamed.
443 pub fn finish(
444 self,
445 message_id: Option<String>,
446 response: &rig_core::completion::CompletionResponse,
447 ) -> StreamedTurn {
448 let choice = response
449 .choice
450 .iter()
451 .filter(|content| match content {
452 AssistantContent::ToolCall(call) => !self.ignored_calls.contains(&call.id),
453 AssistantContent::Text(_)
454 | AssistantContent::Reasoning(_)
455 | AssistantContent::Image(_) => true,
456 })
457 .cloned()
458 .map(|content| match content {
459 AssistantContent::ToolCall(mut call) => {
460 if let Some((_, name)) =
461 self.repaired_calls.iter().find(|(id, _)| *id == call.id)
462 {
463 call.function.name = name.clone();
464 }
465 AssistantContent::ToolCall(call)
466 }
467 other => other,
468 })
469 .collect();
470
471 StreamedTurn {
472 message_id,
473 choice,
474 executable_tool_names: self.executable_tool_names.clone(),
475 allowed_tool_names: self.allowed_tool_names.clone(),
476 finish_reason: response.finish_reason(),
477 }
478 }
479
480 /// Park resolution on `pending` and surface the rejected call to the
481 /// caller as an [`StreamedTurnEvent::InvalidToolCall`].
482 fn surface_invalid_call(
483 &mut self,
484 tool_call: ToolCall,
485 args: Option<String>,
486 pending: PendingInvalid,
487 reason: InvalidToolCallReason,
488 ) -> Vec<StreamedTurnEvent> {
489 let invalid = StreamedInvalidToolCall {
490 tool_call,
491 args,
492 executable_tool_names: self.executable_tool_names.clone(),
493 allowed_tool_names: self.allowed_tool_names.clone(),
494 reason,
495 };
496 self.pending_invalid = Some(pending);
497 vec![StreamedTurnEvent::InvalidToolCall(invalid)]
498 }
499
500 /// Surface a call whose arguments were not JSON, the error that ended
501 /// the reply, for resolution. Retains raw argument text and call
502 /// identity, with `Null` parsed arguments.
503 pub fn surface_malformed_input(
504 &mut self,
505 detail: &rig_core::error::MalformedToolInput,
506 ) -> Vec<StreamedTurnEvent> {
507 let Ok(name) = ToolName::new(detail.name.clone()) else {
508 return Vec::new();
509 };
510 let tool_call = ToolCall::new(
511 detail.id.clone(),
512 ToolFunction::new(name, serde_json::Value::Null),
513 );
514 self.surface_invalid_call(
515 tool_call.clone(),
516 Some(detail.raw.clone()),
517 PendingInvalid::MalformedArgs { tool_call },
518 InvalidToolCallReason::MalformedArguments {
519 error: detail.error.clone(),
520 },
521 )
522 }
523}
524
525#[cfg(test)]
526mod tests;