rig_agent/run/mod.rs
1//! Serializable, sans-I/O state machine for model turns, tool recovery, and history.
2//!
3//! Drivers act on [`AgentRunStep`] and supply responses or tool results before
4//! advancing. A run owns no models, tools, or hooks; drivers
5//! provide those services and lifecycle policy.
6//!
7//! ```
8//! use rig_agent::run::{AgentRun, AgentRunStep};
9//! let mut run = AgentRun::new("What is 2+2?").max_turns(3);
10//! assert!(matches!(run.next_step()?, AgentRunStep::CallModel { turn: 1, .. }));
11//! # Ok::<(), rig_agent::run::PromptError>(())
12//! ```
13
14mod calls;
15mod committed;
16pub mod output;
17pub mod patch;
18pub mod prepare;
19pub mod spec;
20pub use spec::UnhandledInvalidToolCall;
21pub(crate) mod transcript;
22
23mod batch;
24use batch::{ToolBatch, ToolSlot};
25
26pub use calls::{ExecCall, MalformedCall, PendingToolCall, ToolAnswer};
27pub use committed::{CommittedItem, project};
28pub use output::OutputMode;
29pub use patch::RequestPatch;
30pub use prepare::{PreparedRequest, prepare_request};
31pub use spec::RunSpec;
32
33use std::collections::BTreeMap;
34use std::sync::Arc;
35
36use serde::{Deserialize, Serialize};
37
38use rig_core::completion::{CompletionResponse, FinishReason, ToolDefinition};
39use rig_core::error::ProviderError;
40
41use rig_core::conversation::Aside;
42use rig_core::message::{AssistantContent, AssistantMessage, ToolCall, ToolName, UserContent};
43use rig_core::tool::feedback::{
44 invalid_arguments_feedback, invalid_call_feedback, not_executed, output_limit_feedback,
45 tool_result_message,
46};
47
48use calls::AnswerKind;
49
50use rig_core::completion::{Message, ResponseIdentity, Usage};
51pub mod policy;
52pub mod response;
53pub mod streamed;
54
55pub use policy::{
56 InvalidToolCallAction, InvalidToolCallContext, InvalidToolCallReason, RetryRequest, TurnPolicy,
57};
58pub use response::{CompletionCall, PromptError, PromptResponse};
59use rig_core::completion::message::turn_failure;
60use rig_core::structured_output;
61use rig_core::tool::validate::Problem;
62use transcript::{assistant_message, assistant_turn};
63
64pub use streamed::{
65 PartialStreamedTurn, StreamedInvalidToolCall, StreamedResolution, StreamedTurn,
66 StreamedTurnAssembler, StreamedTurnEvent,
67};
68
69enum ValidatedInvalidToolCallAction {
70 Retry { feedback: String },
71 Repair { tool_name: String },
72 Skip { reason: String },
73}
74
75/// Required driver action to advance an [`AgentRun`].
76#[derive(Debug, Clone, Serialize, Deserialize)]
77pub enum AgentRunStep {
78 /// Send a completion request to the model and feed the result back via
79 /// [`AgentRun::model_response`]. Emitted again for the same attempt
80 /// after a restart; see [`AgentRun::next_step`] for what a re-issue
81 /// requires of the driver.
82 CallModel {
83 /// The prompt message for this turn (the latest message in the run).
84 prompt: Arc<Message>,
85 /// The chat history preceding `prompt`: the caller-provided input
86 /// history followed by messages accumulated by earlier turns,
87 /// shared with the run.
88 history: Vec<Arc<Message>>,
89 /// One-based index of this model call within the run.
90 turn: usize,
91 },
92 /// Execute these tool calls and feed each answer back via
93 /// [`AgentRun::answer`] (or several at once via [`AgentRun::answer_all`]).
94 CallTools {
95 /// The current assistant turn's unanswered tool calls, in emission order.
96 calls: Vec<PendingToolCall>,
97 },
98 /// The run is complete.
99 Done(PromptResponse),
100}
101
102/// A completed model turn fed back to [`AgentRun::model_response`].
103#[derive(Debug, Clone, Serialize, Deserialize)]
104pub struct ModelTurn {
105 /// The turn's origin, stop and provider message, without content.
106 pub head: AssistantMessage,
107 /// The response and transport request ids this attempt reported.
108 #[serde(flatten)]
109 pub identity: ResponseIdentity,
110 /// The assistant content returned by the model.
111 pub choice: Vec<AssistantContent>,
112 /// Token usage reported by the provider for this completion request.
113 pub usage: Usage,
114 /// The tool policy this attempt was prepared with.
115 pub policy: TurnPolicy,
116 /// Provider-reported terminal reason for this attempt, when available.
117 pub finish_reason: Option<FinishReason>,
118 /// This attempt's decoded provider response, recorded on its [`CompletionCall`].
119 pub raw: serde_json::Value,
120}
121
122impl ModelTurn {
123 /// Convert a response using the same attempt's prepared policy and the
124 /// response's normalized finish reason. `policy` must be the
125 /// [`PreparedRequest::policy`](prepare::PreparedRequest::policy) of this
126 /// attempt: it alone carries the turn's tool choice to the Skip gate and
127 /// the invalid-call context.
128 pub fn from_policy(resp: &CompletionResponse, policy: TurnPolicy) -> Self {
129 Self {
130 head: resp.head(),
131 identity: resp.identity(),
132 choice: resp.choice.clone(),
133 usage: resp.usage,
134 policy,
135 finish_reason: resp.finish_reason(),
136 raw: resp.raw.clone(),
137 }
138 }
139
140 /// Create a model turn from response parts, the policy the turn was
141 /// prepared with, and the provider's own response `raw` (see
142 /// [`Self::raw`]).
143 pub fn new(
144 head: AssistantMessage,
145 choice: Vec<AssistantContent>,
146 usage: Usage,
147 policy: TurnPolicy,
148 raw: serde_json::Value,
149 ) -> Self {
150 Self {
151 head,
152 identity: ResponseIdentity::default(),
153 choice,
154 usage,
155 policy,
156 finish_reason: None,
157 raw,
158 }
159 }
160}
161
162/// Driver action after ingesting a model turn or resolving an invalid call.
163#[derive(Debug, Clone, Serialize, Deserialize)]
164pub enum ModelTurnOutcome {
165 /// The turn was accepted. Unless `response_hook_suppressed` is set, the
166 /// driver should run its completion-response hook now, then call
167 /// [`AgentRun::next_step`].
168 ///
169 /// `response_hook_suppressed` is set when invalid tool-call recovery
170 /// (repair or skip) modified the turn, matching the agent loop's behavior
171 /// of not firing the completion's outcome hook (`on_outcome`) for
172 /// recovered turns.
173 Continue {
174 /// Whether the driver should suppress the completion's outcome hook.
175 response_hook_suppressed: bool,
176 },
177 /// The model emitted a tool call that is unknown or disallowed for this
178 /// turn. The driver must decide how to recover (typically by asking its
179 /// invalid tool-call hook) and answer via
180 /// [`AgentRun::resolve_invalid_tool_call`].
181 NeedsResolution(InvalidToolCallContext),
182 /// The turn was rolled back with corrective feedback appended to the
183 /// history. Call [`AgentRun::next_step`] to obtain the retry
184 /// [`AgentRunStep::CallModel`].
185 TurnRetried,
186}
187
188#[derive(Debug, Clone, Serialize, Deserialize)]
189struct ResolvingState {
190 /// The turn being accepted. Its `items` are the working copy of the
191 /// assistant content, where repairs rename tool calls.
192 turn: TurnState,
193 /// The unmodified model output, used for diagnostic histories and retry
194 /// messages (repairs are never reflected in those).
195 original_choice: Vec<AssistantContent>,
196 /// Index of the next item to validate.
197 next_index: usize,
198 recovered: bool,
199 any_skipped: bool,
200}
201
202impl ResolvingState {
203 /// The position in `original_choice` of the item at `next_index`. Ignored
204 /// calls are removed from `turn.items` only at `next_index`, so each one came
205 /// before it.
206 fn original_position(&self) -> usize {
207 let kept = self.turn.items.len();
208 self.next_index + self.original_choice.len().saturating_sub(kept)
209 }
210}
211
212/// The invalid tool call resolution is currently parked on, if any: the item
213/// at `next_index` when it is a tool call outside the allowed set.
214fn pending_invalid_call(resolving: &ResolvingState) -> Option<&ToolCall> {
215 match resolving.turn.items.get(resolving.next_index) {
216 Some(AssistantContent::ToolCall(tool_call))
217 if !resolving
218 .turn
219 .policy
220 .allows(tool_call.function.name.as_str()) =>
221 {
222 Some(tool_call)
223 }
224 _ => None,
225 }
226}
227
228fn has_tool_calls(items: &[AssistantContent]) -> bool {
229 items
230 .iter()
231 .any(|item| matches!(item, AssistantContent::ToolCall(_)))
232}
233
234#[derive(Debug, Clone, Serialize, Deserialize)]
235struct TurnState {
236 head: AssistantMessage,
237 items: Vec<AssistantContent>,
238 /// Synthetic results keyed by position in `items`, so repeated call IDs
239 /// cannot assign a skipped result to a different call.
240 skipped: BTreeMap<usize, UserContent>,
241 /// Kept until the turn's calls are answered, so an invalid-call context
242 /// raised in the tool step reports the policy the turn was judged by.
243 policy: TurnPolicy,
244 /// The positions in `items` of the calls the reply was
245 /// [cut off](CompletionResponse::cut_off_calls) in the middle of.
246 cut_off: Vec<usize>,
247}
248
249#[derive(Debug, Clone, Serialize, Deserialize)]
250enum RunState {
251 /// Ready to emit [`AgentRunStep::CallModel`]. `rollback_owed` is set by a
252 /// streamed rollback whose completion call is still to be recorded; see
253 /// [`AgentRun::record_streamed_completion_call`].
254 PreparingRequest { rollback_owed: bool },
255 /// Waiting for [`AgentRun::model_response`] or a streamed turn;
256 /// `recorded` once the streamed attempt's completion call is recorded.
257 AwaitingModel { recorded: bool },
258 /// Scanning the model turn's tool calls for validity; may be waiting for
259 /// [`AgentRun::resolve_invalid_tool_call`].
260 ResolvingToolCalls(ResolvingState),
261 /// The turn was accepted; ready to emit [`AgentRunStep::CallTools`] or
262 /// [`AgentRunStep::Done`].
263 AwaitingAdvance(TurnState),
264 /// Waiting for results for these tool calls. Carrying the calls and the
265 /// answers so far keeps a serialized run self-contained: a resumed
266 /// process re-obtains the unanswered calls from [`AgentRun::next_step`].
267 ExecutingTools(ToolBatch, TurnPolicy),
268 /// Terminal: the run completed successfully.
269 Done(PromptResponse),
270 /// Terminal: the run returned an error.
271 Failed,
272}
273
274impl RunState {
275 const READY: Self = Self::PreparingRequest {
276 rollback_owed: false,
277 };
278}
279
280/// The sans-IO agent loop state machine. See the [module docs](self) for the
281/// driving protocol.
282/// The persisted envelope is versioned: [`RUN_FORMAT`] is written on every
283/// serialization and checked on every deserialization, and an unknown key
284/// is refused. State written by another format is refused by name rather
285/// than loaded with defaults filled in.
286#[derive(Debug, Clone, Serialize, Deserialize)]
287#[serde(deny_unknown_fields)]
288pub struct AgentRun {
289 /// The envelope format ([`RUN_FORMAT`]).
290 #[serde(deserialize_with = "run_format")]
291 format: u32,
292 max_turns: usize,
293 max_invalid_tool_call_retries: usize,
294 /// See [`RunSpec::max_consecutive_malformed_tool_calls`].
295 max_consecutive_malformed_tool_calls: Option<usize>,
296 /// See [`RunSpec::unhandled_invalid_tool_call`].
297 unhandled_invalid_tool_call: UnhandledInvalidToolCall,
298 /// Synthetic output-tool name, pinned by the first turn whose policy
299 /// names one. Its first call finalizes with arguments as output instead
300 /// of executing tools.
301 output_tool_name: Option<String>,
302 /// Schema every final answer is checked against before finalization.
303 output_schema: Option<serde_json::Value>,
304 /// Budget for re-prompting the model when its answer misses the output
305 /// schema: text or output-tool arguments that do not satisfy it.
306 /// Exhausting it fails the run.
307 max_output_retries: usize,
308 output_retries: usize,
309 chat_history: Option<Vec<Arc<Message>>>,
310 /// Append-only: see [`project`].
311 #[serde(rename = "new_messages")]
312 history: committed::CommittedLog,
313 current_turn: usize,
314 usage: Usage,
315 completion_calls: Vec<CompletionCall>,
316 completion_call_index: usize,
317 invalid_tool_call_retries: usize,
318 /// Consecutive tool steps that answered at least one call whose
319 /// arguments are not a JSON object.
320 malformed_tool_call_retries: usize,
321 /// The model behind the run's preceding issued completion attempt, as
322 /// the driver advances it immediately before the attempt is issued
323 /// (a stop or a preparation failure leaves it unchanged; a provider
324 /// error still counts). Persisted so a resumed run's model-selection
325 /// hook sees the model the run last asked, as a fresh run's would,
326 /// rather than a run that has asked none.
327 previous_model: Option<rig_core::completion::ModelRef>,
328 /// The tool definitions the driver advertised to the model for a turn,
329 /// recorded with [`AgentRun::advertise_tools`]. Protocol data, so a second
330 /// driver (or a resumed run) can re-pair tool calls with what was offered.
331 turn_tools: Option<TurnTools>,
332 /// Append-only host records (asides by rig, each of its hook's kind),
333 /// stored verbatim and excluded from provider requests. The driver
334 /// reconstructs hook state from them on resume.
335 entries: Vec<Aside>,
336 state: RunState,
337}
338
339/// The [`AgentRun`] envelope format this crate writes and reads.
340pub const RUN_FORMAT: u32 = 7;
341
342/// Deserialize the envelope's `format`, refusing any other than
343/// [`RUN_FORMAT`] by name so a run persisted by another rig is never loaded
344/// with defaults filled in.
345fn run_format<'de, D: serde::Deserializer<'de>>(deserializer: D) -> Result<u32, D::Error> {
346 let format = u32::deserialize(deserializer)?;
347 if format == RUN_FORMAT {
348 Ok(format)
349 } else {
350 Err(serde::de::Error::custom(format!(
351 "resume refused: the run is format {format}, this rig reads format {RUN_FORMAT}"
352 )))
353 }
354}
355
356/// Tool definitions advertised for one model call, recorded by the driver before
357/// execution. Recording definitions does not bind or execute tools.
358#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
359pub struct TurnTools {
360 /// One-based model-call index the definitions were advertised for
361 /// (the `turn` of the matching [`AgentRunStep::CallModel`]).
362 pub turn: usize,
363 /// The definitions sent with that request, in advertised order.
364 pub definitions: Vec<Arc<ToolDefinition>>,
365}
366
367impl AgentRun {
368 /// Create a run for one prompt with no input history, a one-model-call
369 /// budget, and no invalid tool-call retries.
370 pub fn new(prompt: impl Into<Message>) -> Self {
371 Self {
372 format: RUN_FORMAT,
373 max_turns: 1,
374 max_invalid_tool_call_retries: 0,
375 max_consecutive_malformed_tool_calls: None,
376 unhandled_invalid_tool_call: UnhandledInvalidToolCall::Fail,
377 output_tool_name: None,
378 output_schema: None,
379 max_output_retries: 0,
380 output_retries: 0,
381 chat_history: None,
382 history: committed::CommittedLog::new(prompt.into()),
383 current_turn: 0,
384 usage: Usage::default(),
385 completion_calls: Vec::new(),
386 completion_call_index: 0,
387 invalid_tool_call_retries: 0,
388 malformed_tool_call_retries: 0,
389 previous_model: None,
390 turn_tools: None,
391 entries: Vec::new(),
392 state: RunState::READY,
393 }
394 }
395
396 /// The prompt this run will send on its first model call, while the run
397 /// has not yet started. `None` once the first
398 /// [`AgentRunStep::CallModel`] has been emitted (the prompt is then run
399 /// history, no longer pending input).
400 pub fn initial_prompt(&self) -> Option<&Message> {
401 (self.current_turn == 0 && matches!(self.state, RunState::PreparingRequest { .. }))
402 .then(|| self.history.last().map(|prompt| &**prompt))
403 .flatten()
404 }
405
406 /// Replace the pending prompt before the run starts.
407 ///
408 /// This is the run-start steering point: a driver's pre-run hook may
409 /// rewrite the user prompt here, before any model call. Valid only while
410 /// [`initial_prompt`](Self::initial_prompt) is `Some`; once the first
411 /// [`AgentRunStep::CallModel`] has been emitted the prompt is committed
412 /// and rewriting returns [`PromptError::Cancelled`].
413 pub(crate) fn rewrite_initial_prompt(
414 &mut self,
415 prompt: impl Into<Message>,
416 ) -> Result<(), PromptError> {
417 let started =
418 self.current_turn != 0 || !matches!(self.state, RunState::PreparingRequest { .. });
419 if let (false, Some(slot)) = (started, self.history.unstarted_prompt()) {
420 *slot = Arc::new(prompt.into());
421 return Ok(());
422 }
423 Err(self.cancel_error("the initial prompt can only be rewritten before the run starts"))
424 }
425
426 /// Append one host record without interpreting or validating its contents.
427 pub fn append_entry(&mut self, entry: Aside) {
428 self.entries.push(entry);
429 }
430
431 /// Every appended record, in append order.
432 pub fn entries(&self) -> &[Aside] {
433 &self.entries
434 }
435
436 /// Record the tool definitions advertised to the model for `turn` (the
437 /// `turn` of the [`AgentRunStep::CallModel`] being served). Replaces any
438 /// earlier record; the run keeps only the latest turn's advertisement.
439 pub fn advertise_tools(&mut self, turn: usize, definitions: Vec<Arc<ToolDefinition>>) {
440 self.turn_tools = Some(TurnTools { turn, definitions });
441 }
442
443 /// The tools advertised for the most recent model call, if the driver
444 /// recorded them. A [`CallTools`](AgentRunStep::CallTools) step whose
445 /// calls name tools outside this set means the driver and the run have
446 /// desynchronized (a registry that changed under a resumed run, say); a
447 /// driver that wants that guard checks here before dispatching.
448 pub fn advertised_tools(&self) -> Option<&TurnTools> {
449 self.turn_tools.as_ref()
450 }
451
452 /// Set the input chat history preceding the prompt. It is not checked: a
453 /// history from outside the run (another store, a run resumed in another
454 /// process) goes through `rig_core::conversation::pairing::validate` first.
455 pub fn with_history(
456 mut self,
457 history: impl IntoIterator<Item = impl Into<Arc<Message>>>,
458 ) -> Self {
459 self.chat_history = Some(history.into_iter().map(Into::into).collect());
460 self
461 }
462
463 /// Set the total model-call budget, including the initial call and every
464 /// retry or continuation. A budget of zero emits no model calls. Exceeding
465 /// the budget makes [`AgentRun::next_step`] return
466 /// [`PromptError::MaxTurns`].
467 pub fn max_turns(mut self, max_turns: usize) -> Self {
468 self.max_turns = max_turns;
469 self
470 }
471
472 /// Set the output schema and retry budget for answers that miss it: text
473 /// that does not satisfy it, an output-tool call whose arguments are not
474 /// a JSON object or do not satisfy it. The answer must be JSON (the whole
475 /// text, else one value past leading prose or a fence) that fits the
476 /// schema as [`rig_core::tool::validate::validate`] checks it, which
477 /// covers types, required fields and the other keywords it lists.
478 /// Exhausting either the output or model-call budget on such an answer
479 /// fails the run with [`PromptError::OutputSchemaMismatch`].
480 pub fn with_output_validation(
481 mut self,
482 output_schema: Option<serde_json::Value>,
483 max_output_retries: usize,
484 ) -> Self {
485 self.output_schema = output_schema;
486 self.max_output_retries = max_output_retries;
487 self
488 }
489
490 /// The input chat history this run was created with, empty when none was
491 /// set. This is the history preceding the initial prompt, not the run's
492 /// accumulated messages.
493 pub fn input_chat_history(&self) -> &[Arc<Message>] {
494 self.chat_history.as_deref().unwrap_or_default()
495 }
496
497 /// Whether the run may re-prompt for output that satisfies the schema:
498 /// both the output-retry budget and the total model-call budget must
499 /// remain. Otherwise the run fails on the mismatch rather than surface a
500 /// max-turns error.
501 fn can_reprompt_for_output(&self) -> bool {
502 self.output_retries < self.max_output_retries && self.current_turn < self.max_turns
503 }
504
505 /// The run's error for a final answer that misses the output schema.
506 fn schema_mismatch(
507 &self,
508 output: String,
509 output_tool: Option<String>,
510 problems: Vec<Problem>,
511 ) -> PromptError {
512 PromptError::OutputSchemaMismatch {
513 output,
514 output_tool,
515 problems,
516 chat_history: self.full_history(),
517 }
518 }
519
520 /// Roll the run back to re-prompt for valid output. The caller must
521 /// have already appended the assistant turn and the corrective feedback
522 /// message to the history. Consumes one output-retry, then emits the retry
523 /// [`AgentRunStep::CallModel`].
524 fn reprompt_for_output(&mut self) -> Result<AgentRunStep, PromptError> {
525 self.output_retries += 1;
526 self.state = RunState::READY;
527 self.next_step()
528 }
529
530 /// Set the retry budget for [`InvalidToolCallAction::Retry`]
531 /// resolutions. Invalid tool-call retries also consume the total model-call
532 /// budget.
533 pub fn max_invalid_tool_call_retries(mut self, retries: usize) -> Self {
534 self.max_invalid_tool_call_retries = retries;
535 self
536 }
537
538 /// Set how many consecutive turns may answer a tool call whose arguments
539 /// are not a JSON object before the run fails. `None`, the default, sets
540 /// no limit. See [`RunSpec::max_consecutive_malformed_tool_calls`].
541 pub fn max_consecutive_malformed_tool_calls(mut self, limit: impl Into<Option<usize>>) -> Self {
542 self.max_consecutive_malformed_tool_calls = limit.into();
543 self
544 }
545
546 /// Set what the run does with an invalid tool call no hook resolves. See
547 /// [`UnhandledInvalidToolCall`].
548 pub fn with_unhandled_invalid_tool_call(mut self, policy: UnhandledInvalidToolCall) -> Self {
549 self.unhandled_invalid_tool_call = policy;
550 self
551 }
552
553 /// Pin the synthetic output-tool name for Tool output mode up front.
554 ///
555 /// This only seeds [`output_tool_name`](Self::output_tool_name), which the
556 /// driver passes to [`prepare_request`] as `committed_output_tool` for
557 /// later turns. It does not by itself make a call to the tool finalize the
558 /// run: a turn intercepts the call only when its [`TurnPolicy`] names the
559 /// tool, as `prepared.policy` does when `prepare_request` resolved Tool
560 /// output mode, or a hand-built `TurnPolicy::new(.., Some(name))`. Under a
561 /// policy that does not name it, a call to the tool is an invalid
562 /// (unknown) tool call.
563 pub fn with_output_tool_name(mut self, name: impl Into<String>) -> Self {
564 self.output_tool_name = Some(name.into());
565 self
566 }
567
568 /// The synthetic output-tool name pinned for this run, if any: set up
569 /// front, or by the first model turn whose policy names one. The driver
570 /// passes this back when preparing later turns so Tool output mode stays
571 /// pinned even if the per-turn tool set changes.
572 pub fn output_tool_name(&self) -> Option<&str> {
573 self.output_tool_name.as_deref()
574 }
575
576 /// Pin the output tool `policy` names unless one is already pinned. The
577 /// first name wins and is never unpinned, so a tool set that shifts
578 /// mid-run cannot flip the output mode.
579 fn pin_output_tool(&mut self, policy: &TurnPolicy) {
580 if self.output_tool_name.is_none() {
581 self.output_tool_name = policy.output_tool().map(str::to_owned);
582 }
583 }
584
585 /// The policy for an invalid tool call no hook resolves.
586 pub(crate) fn unhandled_invalid_tool_call(&self) -> UnhandledInvalidToolCall {
587 self.unhandled_invalid_tool_call
588 }
589
590 /// Aggregated token usage across all completed model calls so far.
591 pub fn usage(&self) -> Usage {
592 self.usage
593 }
594
595 /// Number of model calls emitted so far (including retries).
596 pub fn turn(&self) -> usize {
597 self.current_turn
598 }
599
600 /// Model of the preceding issued attempt, as recorded by the driver.
601 pub fn previous_model(&self) -> Option<&rig_core::completion::ModelRef> {
602 self.previous_model.as_ref()
603 }
604
605 /// Record the model an attempt is about to be issued to; the driver
606 /// calls this immediately before the model turn is driven.
607 pub fn set_previous_model(&mut self, model: rig_core::completion::ModelRef) {
608 self.previous_model = Some(model);
609 }
610
611 /// Every completion call the run made so far, in order.
612 pub fn completion_calls(&self) -> &[CompletionCall] {
613 &self.completion_calls
614 }
615
616 /// Messages accumulated by this run (the prompt plus all assistant turns
617 /// and tool results), excluding the input history. While tools run, the
618 /// last turn's calls are still unanswered here: this is the view to
619 /// display, and [`Self::full_history`] the one to resume from.
620 pub fn messages(&self) -> &[Arc<Message>] {
621 &self.history
622 }
623
624 /// Where a driver starts to [`project`] [`messages`](Self::messages): the
625 /// end, or the message holding a pending [`AgentRunStep::CallTools`]
626 /// batch, so a resumed run announces the calls whose results it streams.
627 pub fn projection_start(&self) -> usize {
628 let pending = matches!(self.state, RunState::ExecutingTools(..));
629 let holder = |message: &Arc<Message>| pending && matches!(**message, Message::Assistant(_));
630 (self.history.iter().rposition(holder)).unwrap_or(self.history.len())
631 }
632
633 /// Canonical content for the accepted model turn awaiting advancement.
634 pub fn accepted_turn_choice(&self) -> Option<Vec<AssistantContent>> {
635 let RunState::AwaitingAdvance(turn) = &self.state else {
636 return None;
637 };
638
639 if turn.items.is_empty() {
640 return None;
641 }
642 Some(turn.items.clone())
643 }
644
645 /// Replace accepted content before it enters history. Returns a cancellation
646 /// error without an accepted turn or if either turn contains tool calls.
647 pub fn replace_accepted_turn_choice(
648 &mut self,
649 choice: Vec<AssistantContent>,
650 ) -> Result<(), PromptError> {
651 let replacement_has_tool_calls = has_tool_calls(&choice);
652 let parked_has_tool_calls = match &self.state {
653 RunState::AwaitingAdvance(turn) => has_tool_calls(&turn.items),
654 _ => {
655 return Err(self.protocol_violation(
656 "replace_accepted_turn_choice called without an accepted turn awaiting advancement",
657 ));
658 }
659 };
660 if parked_has_tool_calls || replacement_has_tool_calls {
661 return Err(self.cancel_error(
662 "a completion outcome replacement does not support tool-bearing model turns; patch or deny the tool dispatches instead",
663 ));
664 }
665 if let RunState::AwaitingAdvance(turn) = &mut self.state {
666 turn.items = choice;
667 }
668 Ok(())
669 }
670
671 /// Reject the accepted, tool-free model turn and prepare another model call.
672 ///
673 /// [`RetryRequest::Repeat`] discards the rejected assistant response and
674 /// reuses the same prompt and preceding history with fresh request
675 /// preparation. [`RetryRequest::Feedback`] records the rejected response
676 /// followed by corrective user feedback. Canonical empty assistant turns
677 /// are omitted from history, matching normal turn advancement. Both modes
678 /// preserve completion-call and usage accounting, and the next call consumes
679 /// the existing total model-call budget.
680 ///
681 /// Tool-bearing turns cannot be retried through this operation because
682 /// preserving them without matching tool results would create invalid
683 /// provider-visible history. Use tool-call hooks to steer those turns.
684 pub fn retry_model_turn(&mut self, request: RetryRequest) -> Result<(), PromptError> {
685 let turn = match std::mem::replace(&mut self.state, RunState::Failed) {
686 RunState::AwaitingAdvance(turn) => turn,
687 other => {
688 self.state = other;
689 return Err(self.protocol_violation(
690 "retry_model_turn called without an accepted turn awaiting advancement",
691 ));
692 }
693 };
694
695 if has_tool_calls(&turn.items) {
696 return Err(self.fail(
697 "model-turn retry does not support tool-bearing model turns; use tool-call hooks instead",
698 ));
699 }
700
701 match request {
702 RetryRequest::Repeat => {}
703 RetryRequest::Feedback(feedback) => {
704 // Feedback may retry an empty answer, but empty assistant messages
705 // must not enter provider history.
706 self.history.commit(assistant_turn(turn.head, turn.items));
707 self.history.commit([Message::user(feedback)]);
708 }
709 }
710
711 self.state = RunState::READY;
712 Ok(())
713 }
714
715 /// The full conversation: input history followed by [`Self::messages`],
716 /// with a tool batch the host has not finished answering closed: its
717 /// results so far, then the other calls closed by
718 /// [`close_pending`](rig_core::conversation::pairing::close_pending) (a pre-resolved
719 /// result stands), so it resumes as a canonical transcript.
720 pub fn full_history(&self) -> Vec<Message> {
721 self.owned_history(self.closure())
722 }
723
724 /// The input history and the run's messages, then `extra`, as owned
725 /// messages: the history an error or a hook's context carries.
726 fn owned_history(&self, extra: impl IntoIterator<Item = Message>) -> Vec<Message> {
727 let shared = self.input_chat_history().iter().chain(self.history.iter());
728 shared
729 .map(|message| Message::clone(message))
730 .chain(extra)
731 .collect()
732 }
733
734 /// The user message closing the batch the host was told to run, while
735 /// it has not answered every call: the results so far, then the rest
736 /// closed.
737 fn closure(&self) -> Option<Message> {
738 let RunState::ExecutingTools(batch, _) = &self.state else {
739 return None;
740 };
741 Some(batch.interrupt())
742 }
743
744 /// Whether the run reached [`AgentRunStep::Done`].
745 pub fn is_done(&self) -> bool {
746 matches!(self.state, RunState::Done(_))
747 }
748
749 /// [`Self::full_history`] closed for cancellation by
750 /// [`repair`](rig_core::conversation::pairing::repair): mid tool batch,
751 /// the results so far follow it with the rest closed, and every call
752 /// still unanswered in the unchecked input history is closed as well.
753 pub fn canonical_history(&self) -> Vec<Message> {
754 rig_core::conversation::pairing::repair(self.full_history()).messages
755 }
756
757 /// Build the cancellation error a driver should return when one of its
758 /// hooks terminates the run, carrying [`Self::canonical_history`].
759 pub fn cancel_error(&self, reason: impl Into<String>) -> PromptError {
760 PromptError::cancelled(self.canonical_history(), reason)
761 }
762
763 /// [`Self::cancel_error`], then fail the run, its history ending as the
764 /// error's does.
765 fn fail(&mut self, reason: impl Into<String>) -> PromptError {
766 let error = self.cancel_error(reason);
767 let closure = self.closure();
768 self.history.commit(closure);
769 self.state = RunState::Failed;
770 error
771 }
772
773 /// The [`AgentRunStep::CallModel`] for the current turn.
774 fn call_model_step(&self) -> Result<AgentRunStep, PromptError> {
775 let Some((prompt, history)) = self.history.split_last() else {
776 return Err(self.cancel_error("prompt loop lost its pending prompt"));
777 };
778 let input = self.input_chat_history().iter();
779 Ok(AgentRunStep::CallModel {
780 prompt: Arc::clone(prompt),
781 history: input.chain(history).cloned().collect(),
782 turn: self.current_turn,
783 })
784 }
785
786 /// The invalid tool call currently awaiting
787 /// [`AgentRun::resolve_invalid_tool_call`], if any. Useful to re-derive
788 /// the resolution context after deserializing a suspended run.
789 pub fn pending_invalid_tool_call(&self) -> Option<InvalidToolCallContext> {
790 let RunState::ResolvingToolCalls(resolving) = &self.state else {
791 return None;
792 };
793 let tool_call = pending_invalid_call(resolving)?;
794
795 Some(resolving.turn.policy.invalid_call_context(
796 tool_call,
797 Some(tool_call.function.arguments_json()),
798 self.diagnostic_history(resolving),
799 false,
800 resolving.turn.policy.name_reason(tool_call),
801 ))
802 }
803
804 /// Advance the machine and return the next action for the driver.
805 ///
806 /// Idempotent while awaiting a model response or tool results: the step
807 /// is emitted again, a model call without consuming a turn and a tool
808 /// step with only its unanswered calls. A persisted run resumes from here
809 /// in any non-terminal state except a pending invalid tool-call
810 /// resolution.
811 ///
812 /// A re-issued [`AgentRunStep::CallModel`] is the same attempt: it carries
813 /// the same `turn`, and the run cannot tell its response from a late one of
814 /// the attempt it replaces. Before re-issuing, the driver drops (or
815 /// drains) the previous model call or stream, so nothing of it reaches
816 /// [`Self::model_response`], [`Self::record_streamed_completion_call`] or
817 /// [`Self::streamed_turn`]. Re-issues are not budgeted: they consume no
818 /// turn of [`Self::max_turns`], and an attempt that never reached
819 /// `model_response` or `record_streamed_completion_call` is not in
820 /// [`Self::usage`]. A driver that re-issues in a loop bounds it itself.
821 ///
822 /// # Errors
823 /// - [`PromptError::MaxTurns`] when the total model-call budget is exhausted.
824 /// - [`PromptError::OutputSchemaMismatch`] when the final answer misses
825 /// the output schema and no output retry is left
826 /// ([`Self::with_output_validation`]).
827 /// - [`PromptError::Cancelled`] when the machine is driven out of
828 /// protocol (for example, calling this while an invalid tool-call
829 /// resolution is pending).
830 pub fn next_step(&mut self) -> Result<AgentRunStep, PromptError> {
831 match std::mem::replace(&mut self.state, RunState::Failed) {
832 // Re-issuing a pending attempt consumes no turn; the interrupted
833 // attempt stays recorded and billed if it was.
834 state @ (RunState::PreparingRequest { .. } | RunState::AwaitingModel { .. }) => {
835 if let RunState::PreparingRequest { .. } = state {
836 if self.current_turn >= self.max_turns
837 && let Some(prompt) = self.history.last()
838 {
839 return Err(PromptError::MaxTurns {
840 max_turns: self.max_turns,
841 chat_history: self.full_history(),
842 prompt: Message::clone(prompt),
843 });
844 }
845 self.current_turn += 1;
846 }
847 let step = self.call_model_step()?;
848 self.state = RunState::AwaitingModel { recorded: false };
849 Ok(step)
850 }
851 RunState::AwaitingAdvance(turn_state) => {
852 let TurnState {
853 head,
854 items,
855 mut skipped,
856 policy,
857 cut_off,
858 } = turn_state;
859 let has_tool_calls = has_tool_calls(&items);
860 // A failed turn runs no tool and finalizes no output; reasoning
861 // alone is not an answer. A failed turn's calls never run, and
862 // the turn stays in the run's messages for display, as pi
863 // keeps it.
864 let finish = self
865 .completion_calls
866 .last()
867 .and_then(|call| call.finish_reason.as_ref());
868 if let Some(message) = turn_failure(&items, head.stop.as_ref(), finish) {
869 if has_tool_calls {
870 self.history.commit(assistant_turn(head, items));
871 }
872 return Err(ProviderError::Response(message).into());
873 }
874
875 // The first output-tool call is the answer, not executable work;
876 // sibling calls must not run after finalization.
877 if has_tool_calls
878 && let Some(output_tool_name) = policy.output_tool().map(str::to_owned)
879 && let Some((position, tool_call)) =
880 items
881 .iter()
882 .enumerate()
883 .find_map(|(position, item)| match item {
884 AssistantContent::ToolCall(tc)
885 if tc.function.name == output_tool_name =>
886 {
887 Some((position, tc))
888 }
889 _ => None,
890 })
891 {
892 let output_tool_calls = items
893 .iter()
894 .filter(|item| {
895 matches!(
896 item,
897 AssistantContent::ToolCall(tc)
898 if tc.function.name == output_tool_name
899 )
900 })
901 .count();
902 let args = tool_call.function.arguments_value();
903 let output = args.to_string();
904
905 // A call the reply was cut off in is no answer, whatever
906 // its arguments: the model is told to send less while
907 // the budget lasts. Arguments that are not a JSON object
908 // are no answer either, and missing fields keep their
909 // own, more pointed reprompt.
910 let refusal = if cut_off.contains(&position) {
911 let raw = tool_call.function.raw_arguments();
912 Some((
913 output_limit_feedback(&output_tool_name, &raw),
914 raw,
915 vec![Problem {
916 at: String::new(),
917 what: "cut off at the output limit".to_owned(),
918 }],
919 ))
920 } else if let Some(raw) = &tool_call.function.invalid_arguments {
921 Some((
922 invalid_arguments_feedback(&output_tool_name, raw),
923 raw.clone(),
924 vec![Problem {
925 at: String::new(),
926 what: "not a JSON object".to_owned(),
927 }],
928 ))
929 } else {
930 self.output_schema.as_ref().and_then(|schema| {
931 let problems =
932 rig_core::tool::validate::validate(schema, &args).err()?;
933 let missing = structured_output::missing_required_fields(schema, &args);
934 let feedback = if missing.is_empty() {
935 structured_output::reprompt_schema_problems(
936 &output_tool_name,
937 &response::join_problems(&problems),
938 )
939 } else {
940 structured_output::reprompt_missing_fields(
941 &output_tool_name,
942 &missing,
943 )
944 };
945 Some((feedback, output.clone(), problems))
946 })
947 };
948 if let Some((feedback, answer, problems)) = refusal {
949 if !self.can_reprompt_for_output() {
950 return Err(self.schema_mismatch(
951 answer,
952 Some(output_tool_name),
953 problems,
954 ));
955 }
956 self.history.commit(assistant_message(head, items.clone()));
957 let content = invalid_call_feedback(&items, position, &feedback);
958 self.history.commit([Message::User { content }]);
959 return self.reprompt_for_output();
960 }
961
962 // Store output as text without tool calls so resumed history
963 // cannot contain unanswered calls.
964 let mut final_items: Vec<AssistantContent> = items
965 .iter()
966 .filter(|item| !matches!(item, AssistantContent::ToolCall(_)))
967 .cloned()
968 .collect();
969 final_items.push(AssistantContent::text(output.clone()));
970 self.history
971 .commit(assistant_message(head, final_items.clone()));
972
973 let content = response::finalize_output_tool_choice(&items, &output)
974 .unwrap_or_else(|| vec![AssistantContent::text(output)]);
975 return Ok(self.finish(content, output_tool_calls));
976 }
977
978 let slots: Option<Vec<ToolSlot>> = has_tool_calls.then(|| {
979 items
980 .iter()
981 .enumerate()
982 .filter_map(|(index, item)| {
983 Some(ToolSlot::classify(
984 item.as_tool_call()?.clone(),
985 skipped.remove(&index),
986 cut_off.contains(&index),
987 ))
988 })
989 .collect()
990 });
991 // A turn past the malformed-call limit never enters history.
992 if let Some(slots) = &slots {
993 self.count_malformed_tool_calls(slots)?;
994 }
995 if let Some(slots) = slots {
996 self.history.commit(assistant_turn(head, items.clone()));
997 // Output retries are budgeted per finalization attempt, not per run.
998 self.output_retries = 0;
999 self.state = RunState::ExecutingTools(ToolBatch { slots }, policy);
1000 // A batch answered in full (a whole-turn skip) is
1001 // committed at once and the run moves on to the model.
1002 self.answer_all([])?;
1003 self.next_step()
1004 } else {
1005 // A run that asks for a schema ends only on text that
1006 // satisfies it, whatever enforced it (or did not): the
1007 // model is asked again while the budget lasts, then the
1008 // run fails. The reprompt names the output tool when the
1009 // turn offered one, else carries the schema, which a
1010 // provider that dropped it never showed the model.
1011 let reprompt = policy
1012 .output_tool()
1013 .map(structured_output::reprompt_text_answer)
1014 .or_else(|| {
1015 self.output_schema.as_ref().map(|schema| {
1016 structured_output::prompted_augmentation(
1017 &rig_core::json_utils::to_canonical_string(schema),
1018 )
1019 })
1020 });
1021 let text = AssistantContent::concat_text(&items);
1022 let refusal = reprompt.zip(
1023 structured_output::validate_text(self.output_schema.as_ref(), &text).err(),
1024 );
1025 if let Some((reprompt, problems)) = refusal {
1026 // A refused answer the run fails on stays out of history.
1027 if !self.can_reprompt_for_output() {
1028 return Err(self.schema_mismatch(text, None, problems));
1029 }
1030 self.history.commit(assistant_turn(head, items));
1031 self.history.commit([Message::user(reprompt)]);
1032 return self.reprompt_for_output();
1033 }
1034
1035 // Empty turns may succeed but cannot form provider history entries.
1036 self.history.commit(assistant_turn(head, items.clone()));
1037 Ok(self.finish(items, 0))
1038 }
1039 }
1040 RunState::ExecutingTools(batch, policy) => {
1041 let calls = batch.pending(self.current_turn);
1042 self.state = RunState::ExecutingTools(batch, policy);
1043 Ok(AgentRunStep::CallTools { calls })
1044 }
1045 RunState::Done(response) => {
1046 let step = AgentRunStep::Done(response.clone());
1047 self.state = RunState::Done(response);
1048 Ok(step)
1049 }
1050 state @ RunState::ResolvingToolCalls(_) => {
1051 self.state = state;
1052 Err(self.protocol_violation(
1053 "next_step called while an invalid tool-call resolution is pending; answer it via resolve_invalid_tool_call first",
1054 ))
1055 }
1056 RunState::Failed => Err(self.protocol_violation(
1057 "next_step called after the run already failed or was misdriven",
1058 )),
1059 }
1060 }
1061
1062 /// Feed the model's response for the pending [`AgentRunStep::CallModel`].
1063 ///
1064 /// Records the completion call and aggregates usage, then validates the
1065 /// turn's tool calls against the advertised tool names. See
1066 /// [`ModelTurnOutcome`] for what the driver must do next.
1067 pub fn model_response(&mut self, turn: ModelTurn) -> Result<ModelTurnOutcome, PromptError> {
1068 if self.pending_attempt("model_response")? {
1069 return Err(self.protocol_violation(
1070 "model_response called after record_streamed_completion_call for the same turn; feed streamed turns via streamed_turn",
1071 ));
1072 }
1073
1074 let call = self.completion_call(turn.usage, turn.identity, turn.finish_reason, turn.raw);
1075 self.push_completion_call(call);
1076 self.pin_output_tool(&turn.policy);
1077
1078 self.state = RunState::ResolvingToolCalls(ResolvingState {
1079 turn: TurnState {
1080 head: turn.head,
1081 items: turn.choice.clone(),
1082 skipped: BTreeMap::new(),
1083 policy: turn.policy,
1084 cut_off: Vec::new(),
1085 },
1086 original_choice: turn.choice,
1087 next_index: 0,
1088 recovered: false,
1089 any_skipped: false,
1090 });
1091
1092 self.advance_resolution()
1093 }
1094
1095 /// This run's next completion call, carrying `raw`.
1096 fn completion_call(
1097 &self,
1098 usage: Usage,
1099 identity: ResponseIdentity,
1100 finish_reason: Option<FinishReason>,
1101 raw: serde_json::Value,
1102 ) -> CompletionCall {
1103 CompletionCall {
1104 call_index: self.completion_call_index,
1105 usage,
1106 identity,
1107 finish_reason,
1108 raw,
1109 }
1110 }
1111
1112 /// Record `call` and aggregate its usage.
1113 fn push_completion_call(&mut self, call: CompletionCall) {
1114 self.completion_call_index += 1;
1115 self.usage += call.usage;
1116 self.completion_calls.push(call);
1117 }
1118
1119 /// Build the run's final [`PromptResponse`], park it in
1120 /// [`RunState::Done`], and return the `Done` step. Shared by the
1121 /// output-tool and plain-text finalization paths in `next_step`.
1122 fn finish(&mut self, content: Vec<AssistantContent>, output_tool_calls: usize) -> AgentRunStep {
1123 let response = PromptResponse {
1124 usage: self.usage,
1125 completion_calls: self.completion_calls.clone(),
1126 messages: self.history.iter().map(|m| Message::clone(m)).collect(),
1127 content,
1128 output_tool_calls,
1129 };
1130 self.state = RunState::Done(response.clone());
1131 AgentRunStep::Done(response)
1132 }
1133
1134 /// Count a tool step that answers a call whose arguments are not a JSON
1135 /// object, or reset the count when every executed call parsed. Past
1136 /// [`RunSpec::max_consecutive_malformed_tool_calls`] consecutive steps, when
1137 /// set, fails the run naming the tool and the parse error.
1138 fn count_malformed_tool_calls(&mut self, slots: &[ToolSlot]) -> Result<(), PromptError> {
1139 let malformed = slots.iter().find_map(|slot| match slot {
1140 ToolSlot::Malformed(tool_call) => tool_call
1141 .function
1142 .invalid_arguments
1143 .as_deref()
1144 .map(|raw| (tool_call, raw)),
1145 _ => None,
1146 });
1147 let Some((tool_call, raw)) = malformed else {
1148 self.malformed_tool_call_retries = 0;
1149 return Ok(());
1150 };
1151 self.malformed_tool_call_retries = self.malformed_tool_call_retries.saturating_add(1);
1152 let Some(limit) = self
1153 .max_consecutive_malformed_tool_calls
1154 .filter(|limit| self.malformed_tool_call_retries > *limit)
1155 else {
1156 return Ok(());
1157 };
1158 let error = policy::arguments_parse_error(raw);
1159 Err(ProviderError::Response(format!(
1160 "tool `{}` was called with arguments that are not a JSON object on {} consecutive \
1161 turns, more than the {} retries allowed: {error}",
1162 tool_call.function.name, self.malformed_tool_call_retries, limit,
1163 ))
1164 .into())
1165 }
1166
1167 /// The invalid-call context for a malformed pending call, for the driver
1168 /// to offer its invalid-call hook before answering the call. Outside a
1169 /// [`AgentRunStep::CallTools`] step the context lists no tools.
1170 pub fn malformed_context(
1171 &self,
1172 call: &MalformedCall,
1173 is_streaming: bool,
1174 ) -> InvalidToolCallContext {
1175 let policy = match &self.state {
1176 RunState::ExecutingTools(_, policy) => std::borrow::Cow::Borrowed(policy),
1177 _ => std::borrow::Cow::Owned(TurnPolicy::default()),
1178 };
1179 let raw = call.raw_arguments();
1180 policy.invalid_call_context(
1181 call.tool_call(),
1182 Some(raw.to_owned()),
1183 // Ends at the turn carrying the call: the hook decides how it is
1184 // answered, so the closure of pending calls is not part of it.
1185 self.owned_history(None),
1186 is_streaming,
1187 InvalidToolCallReason::malformed_arguments(raw),
1188 )
1189 }
1190
1191 /// Validate the recovery policy shared by buffered and streamed turns.
1192 /// Medium-specific rollback, repair, and skip effects remain at the call
1193 /// sites; rejection, retry budgeting, and tool-choice checks live here so
1194 /// the two surfaces cannot drift.
1195 fn validate_invalid_tool_call_action(
1196 &mut self,
1197 action: InvalidToolCallAction,
1198 tool_call: &ToolCall,
1199 policy: &TurnPolicy,
1200 history: &[Message],
1201 ) -> Result<ValidatedInvalidToolCallAction, PromptError> {
1202 let unknown = |name: String| policy.unknown_call(name, history.to_vec());
1203 let rejected = || unknown(tool_call.function.name.to_string());
1204 let result = match action {
1205 InvalidToolCallAction::Fail => Err(rejected()),
1206 InvalidToolCallAction::Retry { feedback } => {
1207 if self.invalid_tool_call_retries >= self.max_invalid_tool_call_retries {
1208 Err(rejected())
1209 } else {
1210 self.invalid_tool_call_retries += 1;
1211 Ok(ValidatedInvalidToolCallAction::Retry { feedback })
1212 }
1213 }
1214 InvalidToolCallAction::Repair { tool_name } => {
1215 if policy.allows(&tool_name) {
1216 Ok(ValidatedInvalidToolCallAction::Repair { tool_name })
1217 } else {
1218 Err(unknown(tool_name))
1219 }
1220 }
1221 InvalidToolCallAction::Stop { reason } => Err(self.cancel_error(reason)),
1222 InvalidToolCallAction::Skip { reason } => {
1223 if policy.forbids_calls() {
1224 Err(rejected())
1225 } else {
1226 Ok(ValidatedInvalidToolCallAction::Skip { reason })
1227 }
1228 }
1229 };
1230
1231 if result.is_err() {
1232 self.state = RunState::Failed;
1233 }
1234 result
1235 }
1236
1237 /// Answer a pending [`ModelTurnOutcome::NeedsResolution`].
1238 ///
1239 /// Applies the agent loop's recovery semantics:
1240 /// - [`InvalidToolCallAction::Fail`] fails the run with
1241 /// [`PromptError::UnknownToolCall`].
1242 /// - [`InvalidToolCallAction::Retry`] rolls the turn back with
1243 /// corrective feedback while budget remains, consuming the total
1244 /// model-call budget.
1245 /// - [`InvalidToolCallAction::Repair`] renames the tool call; the
1246 /// repaired name is revalidated against the allowed tools.
1247 /// - [`InvalidToolCallAction::Stop`] cancels the run with
1248 /// `PromptError::cancelled` and the supplied reason.
1249 /// - [`InvalidToolCallAction::Skip`] records a synthetic tool result
1250 /// and suppresses execution of every tool call in the turn. Rejected
1251 /// under a turn whose policy [`forbids_calls`](TurnPolicy::forbids_calls).
1252 pub fn resolve_invalid_tool_call(
1253 &mut self,
1254 action: InvalidToolCallAction,
1255 ) -> Result<ModelTurnOutcome, PromptError> {
1256 let mut resolving = self.take_resolving(
1257 "resolve_invalid_tool_call called without a pending invalid tool call",
1258 )?;
1259 let Some(tool_call) = pending_invalid_call(&resolving).cloned() else {
1260 self.state = RunState::ResolvingToolCalls(resolving);
1261 return Err(self.protocol_violation(
1262 "resolve_invalid_tool_call called without a pending invalid tool call",
1263 ));
1264 };
1265
1266 let diagnostic_history = self.diagnostic_history(&resolving);
1267 let action = self.validate_invalid_tool_call_action(
1268 action,
1269 &tool_call,
1270 &resolving.turn.policy,
1271 &diagnostic_history,
1272 )?;
1273
1274 match action {
1275 ValidatedInvalidToolCallAction::Retry { feedback } => {
1276 self.history.commit(assistant_message(
1277 resolving.turn.head.clone(),
1278 resolving.original_choice.clone(),
1279 ));
1280 let content = invalid_call_feedback(
1281 &resolving.original_choice,
1282 resolving.original_position(),
1283 &feedback,
1284 );
1285 self.history.commit([Message::User { content }]);
1286 self.state = RunState::READY;
1287 Ok(ModelTurnOutcome::TurnRetried)
1288 }
1289 ValidatedInvalidToolCallAction::Repair { tool_name } => {
1290 if let Some(AssistantContent::ToolCall(tool_call)) =
1291 resolving.turn.items.get_mut(resolving.next_index)
1292 && let Ok(tool_name) = ToolName::new(tool_name)
1293 {
1294 tool_call.function.name = tool_name;
1295 }
1296 resolving.recovered = true;
1297 self.state = RunState::ResolvingToolCalls(resolving);
1298 self.advance_resolution()
1299 }
1300 ValidatedInvalidToolCallAction::Skip { reason } => {
1301 let user_content = tool_result_message(
1302 tool_call.id.clone(),
1303 tool_call.function.name.clone(),
1304 reason,
1305 );
1306 // Keyed by the call's position: `next_index` is exactly the
1307 // invalid call's slot in `items`, and later mutations only
1308 // touch indices at or after it, so earlier keys stay stable.
1309 resolving
1310 .turn
1311 .skipped
1312 .insert(resolving.next_index, user_content);
1313 resolving.recovered = true;
1314 resolving.any_skipped = true;
1315 resolving.next_index += 1;
1316 self.state = RunState::ResolvingToolCalls(resolving);
1317 self.advance_resolution()
1318 }
1319 }
1320 }
1321
1322 /// Apply the configured unhandled-call policy after hooks decline resolution.
1323 /// `Fail` reports the invalid call; `Ignore` removes it without suppressing
1324 /// response hooks or sibling calls. Errors without a pending invalid call.
1325 pub fn resolve_unhandled_invalid_tool_call(&mut self) -> Result<ModelTurnOutcome, PromptError> {
1326 match self.unhandled_invalid_tool_call {
1327 UnhandledInvalidToolCall::Fail => {
1328 self.resolve_invalid_tool_call(InvalidToolCallAction::fail())
1329 }
1330 UnhandledInvalidToolCall::Ignore => self.ignore_invalid_tool_call(),
1331 }
1332 }
1333
1334 /// Resolve the pending invalid tool call by ignoring it: the turn
1335 /// proceeds as if the model had not made the call.
1336 pub fn ignore_invalid_tool_call(&mut self) -> Result<ModelTurnOutcome, PromptError> {
1337 let mut resolving = self.take_resolving(
1338 "ignore_invalid_tool_call called without a pending invalid tool call",
1339 )?;
1340
1341 if pending_invalid_call(&resolving).is_none() {
1342 self.state = RunState::ResolvingToolCalls(resolving);
1343 return Err(self.protocol_violation(
1344 "ignore_invalid_tool_call called without a pending invalid tool call",
1345 ));
1346 }
1347
1348 resolving.turn.items.remove(resolving.next_index);
1349 self.state = RunState::ResolvingToolCalls(resolving);
1350 self.advance_resolution()
1351 }
1352
1353 /// Apply one [`ToolAnswer`] for the pending [`AgentRunStep::CallTools`].
1354 /// See [`answer_all`](Self::answer_all).
1355 pub fn answer(&mut self, answer: ToolAnswer) -> Result<(), PromptError> {
1356 self.answer_all([answer])
1357 }
1358
1359 /// Apply answers for the pending [`AgentRunStep::CallTools`], all or none.
1360 /// The run builds each result; once every call is answered they are
1361 /// committed as one user message in call order.
1362 ///
1363 /// # Errors
1364 /// A protocol violation, storing nothing, for an answer whose call is not
1365 /// open. A malformed call's `Stop`, `Fail` or `Repair` ends the run once
1366 /// every answer is checked; the run keeps the other answers, and the
1367 /// first such answer in call order wins.
1368 pub fn answer_all(
1369 &mut self,
1370 answers: impl IntoIterator<Item = ToolAnswer>,
1371 ) -> Result<(), PromptError> {
1372 let RunState::ExecutingTools(batch, policy) = &self.state else {
1373 return Err(self.protocol_violation("answer called without a pending CallTools step"));
1374 };
1375 // The turn stays put until the batch is answered, so it names the batch.
1376 let (mut batch, policy, turn) = (batch.clone(), policy.clone(), self.current_turn);
1377 // A run-ending answer leaves its slot open for the closure, so it is
1378 // held by call index until every answer has been checked.
1379 let mut ends = BTreeMap::new();
1380 for ToolAnswer {
1381 turn: issued,
1382 index,
1383 call,
1384 kind,
1385 } in answers
1386 {
1387 let content = match (batch.slots.get(index), kind) {
1388 _ if issued != turn => {
1389 return Err(self.protocol_violation(&format!(
1390 "answer for tool call id `{call}` of model turn {issued}, but the pending calls are from turn {turn}"
1391 )));
1392 }
1393 _ if ends.contains_key(&index) => {
1394 return Err(self.protocol_violation(&format!(
1395 "answer for tool call id `{call}` that is already answered"
1396 )));
1397 }
1398 (Some(ToolSlot::Execute(tool_call)), AnswerKind::Executed(result))
1399 if tool_call.id == call =>
1400 {
1401 UserContent::ToolResult(tool_call.answer(&result))
1402 }
1403 (Some(ToolSlot::Malformed(tool_call)), AnswerKind::Malformed(action))
1404 if tool_call.id == call =>
1405 {
1406 match malformed_answer(tool_call, action) {
1407 Ok(content) => content,
1408 Err(end) => {
1409 ends.insert(index, end);
1410 continue;
1411 }
1412 }
1413 }
1414 (Some(ToolSlot::Answered(_)), _) => {
1415 return Err(self.protocol_violation(&format!(
1416 "answer for tool call id `{call}` that is already answered"
1417 )));
1418 }
1419 _ => {
1420 return Err(self.protocol_violation(&format!(
1421 "answer for tool call id `{call}` does not match the pending call at position {index}"
1422 )));
1423 }
1424 };
1425 if let Some(slot) = batch.slots.get_mut(index) {
1426 *slot = ToolSlot::Answered(content);
1427 }
1428 }
1429 if let Some((_, end)) = ends.pop_first() {
1430 // The run ends with the other answers kept and the rest of its
1431 // batch closed, as the error reports it.
1432 self.state = RunState::ExecutingTools(batch, policy);
1433 return Err(match end {
1434 Ok(reason) => self.fail(reason),
1435 Err(error) => {
1436 let closure = self.closure();
1437 self.history.commit(closure);
1438 self.state = RunState::Failed;
1439 error
1440 }
1441 });
1442 }
1443 self.state = match batch.complete() {
1444 Ok(results) => {
1445 self.history.commit([results]);
1446 RunState::READY
1447 }
1448 Err(batch) => RunState::ExecutingTools(batch, policy),
1449 };
1450 Ok(())
1451 }
1452
1453 /// Take the resolving state out of `self.state`, leaving `Failed` behind;
1454 /// callers restore it on their rejection paths so an out-of-protocol call
1455 /// does not corrupt a drivable run.
1456 fn take_resolving(&mut self, violation: &str) -> Result<ResolvingState, PromptError> {
1457 match std::mem::replace(&mut self.state, RunState::Failed) {
1458 RunState::ResolvingToolCalls(resolving) => Ok(resolving),
1459 other => {
1460 self.state = other;
1461 Err(self.protocol_violation(violation))
1462 }
1463 }
1464 }
1465
1466 /// Scan forward for the next invalid tool call; finish the turn when the
1467 /// scan completes.
1468 fn advance_resolution(&mut self) -> Result<ModelTurnOutcome, PromptError> {
1469 let mut resolving =
1470 self.take_resolving("internal: advance_resolution outside of tool-call resolution")?;
1471 while let Some(item) = resolving.turn.items.get(resolving.next_index) {
1472 match item {
1473 AssistantContent::ToolCall(tool_call)
1474 if !resolving
1475 .turn
1476 .policy
1477 .allows(tool_call.function.name.as_str()) =>
1478 {
1479 break;
1480 }
1481 _ => resolving.next_index += 1,
1482 }
1483 }
1484
1485 if resolving.next_index < resolving.turn.items.len() {
1486 self.state = RunState::ResolvingToolCalls(resolving);
1487 return match self.pending_invalid_tool_call() {
1488 Some(context) => Ok(ModelTurnOutcome::NeedsResolution(context)),
1489 None => Err(self.protocol_violation(
1490 "internal: pending invalid tool call could not be derived",
1491 )),
1492 };
1493 }
1494
1495 let ResolvingState {
1496 mut turn,
1497 recovered,
1498 any_skipped,
1499 ..
1500 } = resolving;
1501
1502 // When any tool call was skipped, none of the turn's tool calls
1503 // execute: peers get a synthetic "not executed" result.
1504 if any_skipped {
1505 for (index, item) in turn.items.iter().enumerate() {
1506 if let AssistantContent::ToolCall(tool_call) = item {
1507 turn.skipped
1508 .entry(index)
1509 .or_insert_with(|| not_executed(tool_call));
1510 }
1511 }
1512 }
1513
1514 self.state = RunState::AwaitingAdvance(turn);
1515 Ok(ModelTurnOutcome::Continue {
1516 response_hook_suppressed: recovered,
1517 })
1518 }
1519
1520 /// Record a streamed attempt's terminal metadata and aggregate its usage.
1521 /// All arguments must come from that attempt's final event; do not record a
1522 /// stream that ended without one. All-`None` counters mean unreported usage.
1523 ///
1524 /// Allowed once per model attempt: while awaiting its response, or after
1525 /// its streamed rollback before the next model step. Other states and
1526 /// duplicate records return a cancellation error. Abandoned streams must
1527 /// still be drained for usage.
1528 pub fn record_streamed_completion_call(
1529 &mut self,
1530 usage: Usage,
1531 identity: ResponseIdentity,
1532 finish_reason: Option<FinishReason>,
1533 raw: serde_json::Value,
1534 ) -> Result<CompletionCall, PromptError> {
1535 let recordable = match &mut self.state {
1536 RunState::AwaitingModel { recorded } => !std::mem::replace(recorded, true),
1537 RunState::PreparingRequest { rollback_owed } => std::mem::take(rollback_owed),
1538 _ => false,
1539 };
1540 if !recordable {
1541 return Err(self.protocol_violation(
1542 "record_streamed_completion_call called without a pending or rolled-back model attempt, or twice for one",
1543 ));
1544 }
1545
1546 let call = self.completion_call(usage, identity, finish_reason, raw);
1547 self.push_completion_call(call.clone());
1548 Ok(call)
1549 }
1550
1551 /// The recovery-hook context for an invalid tool call surfaced
1552 /// mid-stream by a [`streamed::StreamedTurnAssembler`].
1553 pub fn streamed_invalid_tool_call_context(
1554 &self,
1555 partial: &PartialStreamedTurn,
1556 invalid: &StreamedInvalidToolCall,
1557 ) -> InvalidToolCallContext {
1558 invalid.policy.invalid_call_context(
1559 &invalid.tool_call,
1560 invalid.args.clone(),
1561 self.streamed_diagnostic_history(partial, Some(invalid.tool_call.clone())),
1562 true,
1563 invalid.policy.name_reason(&invalid.tool_call),
1564 )
1565 }
1566
1567 /// Resolve an invalid tool call surfaced mid-stream.
1568 ///
1569 /// Uses buffered-turn recovery policy with rollback messages from the partial
1570 /// turn. Retry and skip abandon the stream; repair changes only the name and
1571 /// rejects malformed arguments. Errors without a pending model step.
1572 pub fn resolve_streamed_invalid_tool_call(
1573 &mut self,
1574 partial: &PartialStreamedTurn,
1575 invalid: &StreamedInvalidToolCall,
1576 action: InvalidToolCallAction,
1577 ) -> Result<StreamedResolution, PromptError> {
1578 let recorded = self.pending_attempt("resolve_streamed_invalid_tool_call")?;
1579
1580 // A streamed turn abandoned here never reaches `streamed_turn`, so
1581 // it pins like a buffered turn that is later retried.
1582 self.pin_output_tool(&invalid.policy);
1583 let diagnostic_history =
1584 self.streamed_diagnostic_history(partial, Some(invalid.tool_call.clone()));
1585 let action = self.validate_invalid_tool_call_action(
1586 action,
1587 &invalid.tool_call,
1588 &invalid.policy,
1589 &diagnostic_history,
1590 )?;
1591
1592 match action {
1593 ValidatedInvalidToolCallAction::Retry { feedback } => {
1594 self.abandon_streamed_turn(partial, invalid, feedback, !recorded)
1595 }
1596 ValidatedInvalidToolCallAction::Repair { tool_name } => {
1597 Ok(StreamedResolution::Repaired { tool_name })
1598 }
1599 ValidatedInvalidToolCallAction::Skip { reason } => {
1600 self.abandon_streamed_turn(partial, invalid, reason, !recorded)
1601 }
1602 }
1603 }
1604
1605 /// Resolve a streamed call as ignored. The driver must apply the returned
1606 /// resolution to the assembler so the call does not enter the turn.
1607 /// Errors without a pending model step.
1608 pub fn ignore_streamed_invalid_tool_call(&mut self) -> Result<StreamedResolution, PromptError> {
1609 self.pending_attempt("ignore_streamed_invalid_tool_call")?;
1610 Ok(StreamedResolution::Ignored)
1611 }
1612
1613 /// Shared rollback for the streamed Retry and Skip resolutions: push the
1614 /// partial turn's rollback messages and abandon the turn. `rollback_owed`
1615 /// says the abandoned attempt's completion call is still to be recorded.
1616 fn abandon_streamed_turn(
1617 &mut self,
1618 partial: &PartialStreamedTurn,
1619 invalid: &StreamedInvalidToolCall,
1620 feedback: String,
1621 rollback_owed: bool,
1622 ) -> Result<StreamedResolution, PromptError> {
1623 self.history
1624 .commit(partial.rollback_messages(invalid.tool_call.clone(), feedback));
1625 self.state = RunState::PreparingRequest { rollback_owed };
1626 Ok(StreamedResolution::TurnAbandoned)
1627 }
1628
1629 /// Feed the assembled streamed turn for the pending
1630 /// [`AgentRunStep::CallModel`].
1631 ///
1632 /// Rejects remaining disallowed tool names without further recovery. Requires
1633 /// a pending model step and exactly one prior call to
1634 /// [`AgentRun::record_streamed_completion_call`] for this attempt; otherwise
1635 /// returns a protocol error. Accepted turns await [`AgentRun::next_step`].
1636 pub fn streamed_turn(&mut self, turn: StreamedTurn) -> Result<(), PromptError> {
1637 if !self.pending_attempt("streamed_turn")? {
1638 return Err(self.protocol_violation(
1639 "streamed_turn called before record_streamed_completion_call recorded the turn's completion call",
1640 ));
1641 }
1642
1643 // A call the reply was cut off in is answered as such whatever its
1644 // name, as it never runs.
1645 for (position, item) in turn.choice.iter().enumerate() {
1646 let AssistantContent::ToolCall(tool_call) = item else {
1647 continue;
1648 };
1649 if !turn.policy.allows(tool_call.function.name.as_str())
1650 && !turn.cut_off.contains(&position)
1651 {
1652 let diagnostic_history =
1653 self.owned_history(assistant_turn(turn.head.clone(), turn.choice.clone()));
1654 self.state = RunState::Failed;
1655 return Err(turn
1656 .policy
1657 .unknown_call(tool_call.function.name.to_string(), diagnostic_history));
1658 }
1659 }
1660
1661 self.pin_output_tool(&turn.policy);
1662 self.state = RunState::AwaitingAdvance(TurnState {
1663 head: turn.head,
1664 items: turn.choice,
1665 skipped: BTreeMap::new(),
1666 policy: turn.policy,
1667 cut_off: turn.cut_off,
1668 });
1669 Ok(())
1670 }
1671
1672 /// Diagnostic history for a streamed turn: the run's messages plus the
1673 /// partial assistant turn under inspection.
1674 fn streamed_diagnostic_history(
1675 &self,
1676 partial: &PartialStreamedTurn,
1677 current_tool_call: Option<ToolCall>,
1678 ) -> Vec<Message> {
1679 self.owned_history(partial.assistant_message(current_tool_call))
1680 }
1681
1682 /// History used for invalid tool-call diagnostics: the run's messages plus
1683 /// the unmodified assistant turn under inspection.
1684 fn diagnostic_history(&self, resolving: &ResolvingState) -> Vec<Message> {
1685 self.owned_history(assistant_message(
1686 resolving.turn.head.clone(),
1687 resolving.original_choice.clone(),
1688 ))
1689 }
1690
1691 /// Whether the pending model attempt's streamed completion call is
1692 /// recorded; a protocol violation naming `op` when no attempt is pending.
1693 fn pending_attempt(&self, op: &str) -> Result<bool, PromptError> {
1694 match self.state {
1695 RunState::AwaitingModel { recorded } => Ok(recorded),
1696 _ => {
1697 Err(self
1698 .protocol_violation(&format!("{op} called without a pending CallModel step")))
1699 }
1700 }
1701 }
1702
1703 fn protocol_violation(&self, reason: &str) -> PromptError {
1704 self.cancel_error(format!("agent run driver protocol violation: {reason}"))
1705 }
1706}
1707
1708impl AgentRun {
1709 /// Build a run from a [`RunSpec`], a prompt and an optional prior history.
1710 ///
1711 /// Applies the spec's budget, invalid-call retries and output validation;
1712 /// everything else in the spec is request-shaping the driver reads when it
1713 /// prepares each model call. `spec.tool_choice` reaches invalid-call
1714 /// validation only through the turn's [`TurnPolicy`]: pass
1715 /// `prepared.policy` from [`prepare_request`] to
1716 /// [`ModelTurn::from_policy`] or [`ModelTurn::new`].
1717 pub fn from_spec(
1718 spec: &RunSpec,
1719 prompt: impl Into<Message>,
1720 history: Option<Vec<Arc<Message>>>,
1721 ) -> Self {
1722 let mut run = AgentRun::new(prompt)
1723 .max_turns(spec.effective_max_turns())
1724 .max_invalid_tool_call_retries(spec.max_invalid_tool_call_retries)
1725 .with_unhandled_invalid_tool_call(spec.unhandled_invalid_tool_call)
1726 .with_output_validation(
1727 spec.output_schema
1728 .as_ref()
1729 .map(|schema| schema.as_value().clone()),
1730 RunSpec::DEFAULT_OUTPUT_RETRIES,
1731 );
1732 run.max_consecutive_malformed_tool_calls = spec.max_consecutive_malformed_tool_calls;
1733 if let Some(history) = history {
1734 run = run.with_history(history);
1735 }
1736 if let Some(name) = spec.output_tool_name.clone() {
1737 run = run.with_output_tool_name(name);
1738 }
1739 run
1740 }
1741}
1742
1743// Compile-time contract: run state is plain, owned data a host can keep in
1744// shared state (worker pools, ECS components) on native targets.
1745#[cfg(not(target_family = "wasm"))]
1746const _: fn() = || {
1747 fn assert_send_sync_static<T: Send + Sync + 'static>() {}
1748 assert_send_sync_static::<AgentRun>();
1749 assert_send_sync_static::<AgentRunStep>();
1750 assert_send_sync_static::<PendingToolCall>();
1751 assert_send_sync_static::<ModelTurn>();
1752 assert_send_sync_static::<StreamedTurn>();
1753 assert_send_sync_static::<StreamedTurnAssembler>();
1754 assert_send_sync_static::<PromptResponse>();
1755 assert_send_sync_static::<CompletionCall>();
1756 assert_send_sync_static::<PromptError>();
1757 assert_send_sync_static::<TurnTools>();
1758};
1759
1760/// The result content for a malformed call answered with `action`, or how
1761/// the answer ends the run: `Ok` with a stop reason, or `Err` with the failure.
1762fn malformed_answer(
1763 tool_call: &ToolCall,
1764 action: Option<InvalidToolCallAction>,
1765) -> Result<UserContent, Result<String, PromptError>> {
1766 let (id, name) = (tool_call.id.clone(), tool_call.function.name.clone());
1767 let raw = tool_call
1768 .function
1769 .invalid_arguments
1770 .as_deref()
1771 .unwrap_or_default();
1772 let feedback = match action {
1773 None => invalid_arguments_feedback(name.as_str(), raw),
1774 Some(InvalidToolCallAction::Retry { feedback }) => feedback,
1775 Some(InvalidToolCallAction::Skip { reason }) => {
1776 let skipped = rig_core::tool::ToolResult::skipped(reason);
1777 return Ok(UserContent::ToolResult(tool_call.answer(&skipped)));
1778 }
1779 Some(InvalidToolCallAction::Stop { reason }) => return Err(Ok(reason)),
1780 Some(InvalidToolCallAction::Fail | InvalidToolCallAction::Repair { .. }) => {
1781 return Err(Err(ProviderError::Response(format!(
1782 "tool `{name}` was called with arguments that are not a JSON object: {}",
1783 policy::arguments_parse_error(raw)
1784 ))
1785 .into()));
1786 }
1787 };
1788 Ok(tool_result_message(id, name, feedback))
1789}
1790
1791#[cfg(test)]
1792mod tests;