Skip to main content

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;