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