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;