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