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