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