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::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;