Skip to main content

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;