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