rig-agent 0.47.0

Rig's classic agent runtime.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
//! Streamed-turn assembly and early invalid-call diagnostics for [`super::AgentRun`].
//!
//! Drivers ingest a completion stream's items, resolve invalid calls before
//! continuing, and finish with the response the stream folded into. The
//! assembler performs no I/O and returns forwarding instructions as
//! [`StreamedTurnEvent`].
//!
//! ```
//! use rig_agent::run::streamed::StreamedTurnAssembler;
//! let assembler = StreamedTurnAssembler::new(Default::default());
//! assert_eq!(assembler.excluded_assistant_content(), 0);
//! ```

use std::collections::BTreeMap;

use serde::{Deserialize, Serialize};

use rig_core::completion::Message;
use rig_core::error::ProviderError;
use rig_core::message::{AssistantContent, AssistantMessage, ToolCall, ToolName};
use rig_core::streaming::{Item, PartKind, StreamEvent};
use rig_core::tool::feedback::invalid_call_feedback;

use super::policy::TurnPolicy;

/// Detect unknown payloads containing assistant content that assembly would lose:
/// tagged assistant blocks or text with a malformed provider item.
fn unknown_payload_loses_assistant_content(payload: &serde_json::Value) -> bool {
    // Read by reference to avoid cloning large unknown payloads.
    if rig_core::json_utils::from_value::<AssistantContent>(payload).is_ok() {
        return true;
    }
    // Malformed metadata must not hide the loss of an otherwise valid text field.
    payload
        .get("text")
        .is_some_and(serde_json::Value::is_string)
        && payload.get("native").is_some()
}

/// One invalid tool call surfaced mid-stream, awaiting a resolution from
/// `AgentRun::resolve_streamed_invalid_tool_call`.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct StreamedInvalidToolCall {
    /// The rejected tool call.
    pub tool_call: ToolCall,
    /// Raw argument payload for diagnostics, when available.
    pub args: Option<String>,
    /// The tool policy of the turn the call was judged under.
    pub policy: TurnPolicy,
}

/// Snapshot of a streamed turn at the moment an invalid tool call appeared.
/// Used by the machine to build diagnostics and rollback messages from
/// exactly what the model has produced so far.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct PartialStreamedTurn {
    /// The turn the reply began, with no content: its origin, so a rolled
    /// back turn is known to come from its model. A reply cut before its end
    /// keeps no provider item, so the rolled back turn replays canonically.
    #[serde(default)]
    pub head: AssistantMessage,
    /// The parts that arrived so far, in the order they started, text still
    /// streaming included.
    pub content: Vec<AssistantContent>,
    /// Tool calls already validated (or repaired) this turn.
    pub pending_tool_calls: Vec<ToolCall>,
}

impl PartialStreamedTurn {
    /// The assistant message representing this partial turn, in arrival
    /// order: each validated call as validated, `current_tool_call` in its
    /// own place, and any other call left out. A call keeps a provider item
    /// only where the partial reply kept it, which a reply cut before its
    /// end never does. `None` when the turn has produced no representable
    /// content.
    pub fn assistant_message(&self, current_tool_call: Option<ToolCall>) -> Option<Message> {
        let (content, _) = self.content_with(current_tool_call);
        if content.is_empty() {
            return None;
        }
        Some(Message::Assistant(self.head.clone().with_content(content)))
    }

    /// The content of [`Self::assistant_message`], and the position in it
    /// of `current_tool_call`. Each call part takes the first call still
    /// unmatched with its id, so calls sharing an id pair in arrival order.
    fn content_with(
        &self,
        current_tool_call: Option<ToolCall>,
    ) -> (Vec<AssistantContent>, Option<usize>) {
        let current_slot = self.pending_tool_calls.len();
        let mut calls: Vec<(usize, ToolCall)> = self
            .pending_tool_calls
            .iter()
            .cloned()
            .chain(current_tool_call)
            .enumerate()
            .collect();
        let mut content = Vec::new();
        let mut current = None;
        let mut push_call = |content: &mut Vec<AssistantContent>,
                             (slot, call): (usize, ToolCall)| {
            if slot == current_slot {
                current = Some(content.len());
            }
            content.push(AssistantContent::ToolCall(call));
        };
        for part in &self.content {
            match part {
                AssistantContent::ToolCall(call) => {
                    let Some(at) = calls.iter().position(|(_, kept)| kept.id == call.id) else {
                        continue;
                    };
                    let (slot, mut kept) = calls.remove(at);
                    kept.native.clone_from(&call.native);
                    push_call(&mut content, (slot, kept));
                }
                part if !part.is_blank() => content.push(part.clone()),
                _ => {}
            }
        }
        for (slot, mut call) in calls {
            call.native = None;
            push_call(&mut content, (slot, call));
        }
        (content, current)
    }

    /// Rollback messages for a retried or skipped streamed turn: the partial
    /// assistant turn plus a user message carrying `feedback` for the invalid
    /// call and a synthetic "not executed" result for each validated peer.
    pub fn rollback_messages(&self, invalid_tool_call: ToolCall, feedback: String) -> [Message; 2] {
        // `content_with` always places the call it is given, so `invalid_at` is set.
        let (content, invalid_at) = self.content_with(Some(invalid_tool_call));
        let results = invalid_call_feedback(&content, invalid_at.unwrap_or(usize::MAX), &feedback);
        let assistant_message = Message::Assistant(self.head.clone().with_content(content));
        [assistant_message, Message::User { content: results }]
    }
}

/// The assembled streamed turn, fed to
/// `AgentRun::streamed_turn`.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct StreamedTurn {
    /// The turn's origin, stop and provider message, without content.
    pub head: AssistantMessage,
    /// The assistant content to record in history, in the order its parts
    /// started, with ignored calls left out and repaired calls renamed.
    pub choice: Vec<AssistantContent>,
    /// The tool policy the turn was prepared with.
    pub policy: TurnPolicy,
    /// The positions in [`Self::choice`] of the calls the reply was cut off
    /// in the middle of
    /// ([`CompletionResponse::cut_off_calls`](rig_core::completion::CompletionResponse::cut_off_calls)).
    /// Each is answered as cut off and never run, whatever its name.
    pub cut_off: Vec<usize>,
}

/// Resolution a driver must apply to a mid-stream invalid tool call.
#[derive(Debug)]
pub enum StreamedResolution {
    /// The tool name was repaired. Apply it via
    /// [`StreamedTurnAssembler::resolve_pending_invalid`] and keep consuming
    /// the provider stream.
    Repaired {
        /// The validated replacement tool name.
        tool_name: String,
    },
    /// The turn was rolled back (retry) or the call skipped; corrective
    /// messages, the skip's tool results among them, are already in the
    /// history, where [`project`](crate::run::project) reads them. Finish the
    /// provider stream for usage, record the completion call, then call
    /// `AgentRun::next_step`.
    TurnAbandoned,
    /// The invalid call is dropped and the turn goes on without it: the
    /// run's `UnhandledInvalidToolCall::Ignore` on the streaming
    /// surface. Apply it via
    /// [`StreamedTurnAssembler::resolve_pending_invalid`] and keep consuming
    /// the provider stream; nothing of the call enters the run.
    Ignored,
}

/// Required driver action after ingesting a stream item.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[non_exhaustive]
pub enum StreamedTurnEvent {
    /// Forward the ingested item to the consumer as-is.
    EmitIngested,
    /// Forward the ingested argument fragment of a call to an allowed tool,
    /// once the tool-call delta hooks let it through. The call is not
    /// executable until its end.
    EmitToolCallDelta,
    /// Hold the ingested item back: it belongs to a call naming a tool the
    /// turn does not allow, which is resolved at its end.
    HoldToolCall,
    /// Forward the held items of the call that just ended, then its end
    /// carrying `call` (the call as validated, with a repaired name).
    EmitToolCall {
        /// The validated call.
        call: ToolCall,
    },
    /// The model emitted an unknown or disallowed tool call. Resolve it via
    /// `AgentRun::resolve_streamed_invalid_tool_call`, then apply the
    /// outcome with [`StreamedTurnAssembler::resolve_pending_invalid`].
    InvalidToolCall(StreamedInvalidToolCall),
}

/// A tool call still streaming: the tool it named as it started, and
/// whether its items stream live.
#[derive(Clone, Serialize, Deserialize)]
struct OpenCall {
    name: Option<ToolName>,
    live: bool,
}

/// A tool call that ended this turn and was settled without abandoning it.
#[derive(Clone, Serialize, Deserialize)]
struct EndedCall {
    /// The call as validated, with a repaired name.
    call: ToolCall,
    /// Whether a [`StreamedResolution::Ignored`] dropped it.
    ignored: bool,
}

/// Serializable accumulator for one streamed turn. Persisted state requires the
/// same library version; it does not itself resume a provider connection.
/// Drivers must resolve pending invalid calls before ingesting more events.
/// Dropping warns once if assistant content was excluded, otherwise stays silent.
#[derive(Clone, Serialize, Deserialize)]
pub struct StreamedTurnAssembler {
    policy: TurnPolicy,
    /// Tool calls still streaming, by the part's position.
    #[serde(default)]
    open_calls: BTreeMap<usize, OpenCall>,
    /// The calls that ended, in the order they ended. The stream's
    /// response still carries ignored calls and original names;
    /// [`Self::resolved`] applies these to it.
    ended_calls: Vec<EndedCall>,
    /// A complete tool call with a disallowed name, awaiting resolution.
    pending_invalid: Option<ToolCall>,
    /// Replayed assistant blocks excluded from assembly this turn (see
    /// [`unknown_payload_loses_assistant_content`]): counted per item,
    /// surfaced as one warning when the guard drops.
    excluded_assistant_content: ExclusionCount,
}

/// Persisted count of excluded assistant blocks. Each clone warns once on drop
/// when nonzero, including cancellation and error paths. A separate drop guard
/// leaves the assembler's fields movable.
#[derive(Default, Clone, Serialize, Deserialize)]
#[serde(transparent)]
struct ExclusionCount(usize);

impl Drop for ExclusionCount {
    fn drop(&mut self) {
        if self.0 > 0 {
            tracing::warn!(
                excluded = self.0,
                "stream items matching rig's tagged assistant-content \
                 serialization were excluded from the assembled assistant \
                 message — replayed assistant blocks are not stream-item \
                 shapes, and their content is lost from assembled history"
            );
        }
    }
}

impl StreamedTurnAssembler {
    /// Create an assembler for one streamed turn with the policy the turn
    /// was prepared with.
    pub fn new(policy: TurnPolicy) -> Self {
        Self {
            policy,
            open_calls: BTreeMap::new(),
            ended_calls: Vec::new(),
            pending_invalid: None,
            excluded_assistant_content: ExclusionCount::default(),
        }
    }

    /// Replayed assistant blocks excluded from assembly so far this turn.
    /// Zero on well-formed provider streams; non-zero means transcript
    /// content was lost (one warning summarizes the count).
    pub fn excluded_assistant_content(&self) -> usize {
        self.excluded_assistant_content.0
    }

    /// The tool the streaming call at part `index` named as it started.
    pub fn streaming_tool_name(&self, index: usize) -> Option<&ToolName> {
        self.open_calls
            .get(&index)
            .and_then(|call| call.name.as_ref())
    }

    /// Ingest one provider stream item and return what the driver must do.
    ///
    /// # Errors
    /// Returns an error when an invalid tool call is still awaiting
    /// resolution.
    pub fn ingest(&mut self, item: &Item<StreamEvent>) -> Result<StreamedTurnEvent, ProviderError> {
        if self.pending_invalid.is_some() {
            return Err(ProviderError::Response(
                "streamed turn ingested while an invalid tool call awaits resolution".to_string(),
            ));
        }
        let event = match item {
            Item::Event(event) => event,
            Item::Unknown(payload) => {
                // Unknown items have no assistant-content representation. Count lost
                // assistant blocks for one warning without exposing payloads or flooding logs.
                if unknown_payload_loses_assistant_content(payload.value()) {
                    self.excluded_assistant_content.0 += 1;
                    tracing::debug!(
                        excluded = self.excluded_assistant_content.0,
                        "stream item is a replayed assistant block, not a \
                         stream-item shape; excluded from assembly"
                    );
                }
                return Ok(StreamedTurnEvent::EmitIngested);
            }
        };
        match event {
            StreamEvent::Text { .. } | StreamEvent::Reasoning { .. } => {
                Ok(StreamedTurnEvent::EmitIngested)
            }
            StreamEvent::Start {
                part,
                kind: PartKind::ToolCall,
                name,
            } => {
                let live = name
                    .as_ref()
                    .is_some_and(|name| self.policy.allows(name.as_str()));
                let name = name.clone();
                self.open_calls
                    .insert(part.index(), OpenCall { name, live });
                Ok(if live {
                    StreamedTurnEvent::EmitIngested
                } else {
                    StreamedTurnEvent::HoldToolCall
                })
            }
            StreamEvent::Arguments { part, .. } => {
                let live = self
                    .open_calls
                    .get(&part.index())
                    .is_some_and(|call| call.live);
                Ok(if live {
                    StreamedTurnEvent::EmitToolCallDelta
                } else {
                    StreamedTurnEvent::HoldToolCall
                })
            }
            StreamEvent::End {
                part,
                content: AssistantContent::ToolCall(tool_call),
            } => {
                self.open_calls.remove(&part.index());
                if !self.policy.allows(tool_call.function.name.as_str()) {
                    let invalid = StreamedInvalidToolCall {
                        tool_call: tool_call.clone(),
                        args: Some(tool_call.function.arguments_json()),
                        policy: self.policy.clone(),
                    };
                    self.pending_invalid = Some(tool_call.clone());
                    return Ok(StreamedTurnEvent::InvalidToolCall(invalid));
                }
                self.ended_calls.push(EndedCall {
                    call: tool_call.clone(),
                    ignored: false,
                });
                Ok(StreamedTurnEvent::EmitToolCall {
                    call: tool_call.clone(),
                })
            }
            StreamEvent::Start { .. } | StreamEvent::End { .. } => {
                Ok(StreamedTurnEvent::EmitIngested)
            }
        }
    }

    /// Apply the machine's resolution for the invalid tool call surfaced by
    /// the last [`StreamedTurnEvent::InvalidToolCall`]. A repaired call is
    /// returned to forward under its new name.
    pub fn resolve_pending_invalid(
        &mut self,
        resolution: &StreamedResolution,
    ) -> Option<StreamedTurnEvent> {
        let mut tool_call = self.pending_invalid.take()?;
        match resolution {
            StreamedResolution::Repaired { tool_name } => {
                if let Ok(tool_name) = ToolName::new(tool_name.clone()) {
                    tool_call.function.name = tool_name;
                }
                self.ended_calls.push(EndedCall {
                    call: tool_call.clone(),
                    ignored: false,
                });
                Some(StreamedTurnEvent::EmitToolCall { call: tool_call })
            }
            StreamedResolution::TurnAbandoned => None,
            StreamedResolution::Ignored => {
                self.ended_calls.push(EndedCall {
                    call: tool_call,
                    ignored: true,
                });
                None
            }
        }
    }

    /// Keep the invalid tool call surfaced by the last
    /// [`StreamedTurnEvent::InvalidToolCall`] in the turn as it is, for a
    /// call the reply was cut off in (one of its response's
    /// [`cut_off_calls`](rig_core::completion::CompletionResponse::cut_off_calls)).
    /// The run answers it as cut off, so it is not resolved as invalid. The
    /// call is returned to forward like any ended call.
    pub fn keep_pending_cut_off(&mut self) -> Option<StreamedTurnEvent> {
        let tool_call = self.pending_invalid.take()?;
        self.ended_calls.push(EndedCall {
            call: tool_call.clone(),
            ignored: false,
        });
        Some(StreamedTurnEvent::EmitToolCall { call: tool_call })
    }

    /// Snapshot of the turn so far, for diagnostics and rollback messages:
    /// `partial` is what the stream folded so far
    /// ([`Streamed::partial`](rig_core::streaming::Streamed::partial)).
    pub fn partial_turn(
        &self,
        partial: &rig_core::completion::CompletionResponse,
    ) -> PartialStreamedTurn {
        PartialStreamedTurn {
            head: partial.continued(Vec::new()),
            content: self.resolved(&partial.choice),
            pending_tool_calls: self
                .ended_calls
                .iter()
                .filter(|ended| !ended.ignored)
                .map(|ended| ended.call.clone())
                .collect(),
        }
    }

    /// Assemble the completed turn from the response the stream folded
    /// into: its choice in start order, with the calls this turn ignored
    /// left out and the ones it repaired renamed.
    pub fn finish(self, response: &rig_core::completion::CompletionResponse) -> StreamedTurn {
        let choice = self.resolved(&response.choice);
        // A response names its cut-off calls by id, and a folded reply's
        // calls have distinct ids, so each id is one position.
        let cut_off = choice
            .iter()
            .enumerate()
            .filter_map(|(at, content)| match content {
                AssistantContent::ToolCall(call)
                    if response.cut_off_calls().any(|cut| cut.id == call.id) =>
                {
                    Some(at)
                }
                _ => None,
            })
            .collect();
        StreamedTurn {
            head: response.head(),
            choice,
            policy: self.policy,
            cut_off,
        }
    }

    /// `choice` with the calls this turn ignored left out and the ones it
    /// repaired renamed. Each call part takes the first ended call still
    /// unmatched with its id, so calls sharing an id pair in the order they
    /// ended, which is the order a reply restated whole lists them in.
    fn resolved(&self, choice: &[AssistantContent]) -> Vec<AssistantContent> {
        let mut ended: Vec<&EndedCall> = self.ended_calls.iter().collect();
        choice
            .iter()
            .filter_map(|content| {
                let AssistantContent::ToolCall(call) = content else {
                    return Some(content.clone());
                };
                let Some(at) = ended.iter().position(|ended| ended.call.id == call.id) else {
                    return Some(content.clone());
                };
                let ended = ended.remove(at);
                (!ended.ignored).then(|| {
                    let mut call = call.clone();
                    call.function.name.clone_from(&ended.call.function.name);
                    AssistantContent::ToolCall(call)
                })
            })
            .collect()
    }
}

#[cfg(test)]
mod tests;