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;