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