Skip to main content

rig_agent/run/
response.rs

1//! Per-call accounting, final run responses, and prompting errors.
2//!
3//! ```
4//! use rig_agent::run::response::PromptResponse;
5//! let response = PromptResponse::new("done", Default::default());
6//! assert_eq!(response.output(), "done");
7//! ```
8
9use rig_core::completion::{FinishReason, ResponseIdentity, Usage};
10use rig_core::error::ProviderError;
11use rig_core::message::{AssistantContent, Message};
12use rig_core::tool::validate::Problem;
13use serde::{Deserialize, Serialize};
14
15/// One completion call of a run: what was asked and what came back.
16#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
17pub struct CompletionCall {
18    /// Zero-based index of the completion request within this agent run.
19    pub call_index: usize,
20    /// Token usage reported for this completion request.
21    ///
22    /// A counter the provider did not report is `None`; a reported zero is
23    /// `Some(0)`. Every counter is `None` when no usage was reported at all.
24    pub usage: Usage,
25    /// The response and transport request ids this call reported.
26    #[serde(flatten)]
27    pub identity: ResponseIdentity,
28    /// Why this call stopped generating, or `None` if unreported.
29    /// Retained per call so callers can identify which attempt was truncated.
30    #[serde(default, skip_serializing_if = "Option::is_none")]
31    pub finish_reason: Option<FinishReason>,
32    /// This attempt's provider response payload, as defined by
33    /// [`rig_core::completion::CompletionResponse::raw`]. A stream without a
34    /// terminal response produces no completion-call entry.
35    pub raw: serde_json::Value,
36}
37
38impl CompletionCall {
39    /// Create details for one completion request in an agent run, carrying
40    /// the provider's own response `raw` (see [`Self::raw`]); identity and
41    /// finish reason start unset.
42    pub fn new(call_index: usize, usage: Usage, raw: serde_json::Value) -> Self {
43        Self {
44            call_index,
45            usage,
46            identity: ResponseIdentity::default(),
47            finish_reason: None,
48            raw,
49        }
50    }
51}
52
53/// Final run output and accounting, returned by awaited runs and terminal
54/// `MultiTurnStreamItem::FinalResponse` stream items.
55#[derive(Debug, Clone, Serialize, Deserialize)]
56pub struct PromptResponse {
57    /// Aggregated token usage across the whole run.
58    pub usage: Usage,
59    /// Successfully completed completion requests made by this agent run.
60    ///
61    /// `usage` remains the aggregate across the whole run. Use the last
62    /// entry's usage to inspect the final completion request's prompt/context
63    /// length. An entry whose counters are all `None` means the provider
64    /// reported no usage metrics for that request.
65    #[serde(default, skip_serializing_if = "Vec::is_empty")]
66    pub completion_calls: Vec<CompletionCall>,
67    /// The run's transcript: the prompt, every accepted assistant turn, every
68    /// committed tool result and the corrective feedback of any retried turn,
69    /// excluding the input history the run started from: what a caller keeping
70    /// the conversation appends to it. Empty only for a response built without
71    /// a run behind it.
72    #[serde(default)]
73    pub messages: Vec<Message>,
74    /// Structured assistant content for the final turn: its text,
75    /// reasoning, images, and other parts. In output-tool mode the model's
76    /// prose and tool calls are replaced by one text part holding the
77    /// serialized structured output. [`output`](Self::output) is derived
78    /// from it.
79    pub content: Vec<AssistantContent>,
80    /// Number of synthetic output-tool calls in the turn that finalized this
81    /// response. Kept crate-private because it is runner bookkeeping rather
82    /// than provider-facing response content.
83    #[serde(skip)]
84    pub(crate) output_tool_calls: usize,
85}
86
87impl std::fmt::Display for PromptResponse {
88    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
89        self.output().fmt(f)
90    }
91}
92
93impl PromptResponse {
94    /// A response whose final turn is the single text part `output`, with the
95    /// run's `usage`.
96    pub fn new(output: impl Into<String>, usage: Usage) -> Self {
97        Self::from_content(vec![AssistantContent::text(output)], usage)
98    }
99
100    /// A response whose final turn is `content`.
101    pub(crate) fn from_content(content: Vec<AssistantContent>, usage: Usage) -> Self {
102        Self {
103            content,
104            usage,
105            completion_calls: Vec::new(),
106            messages: Vec::new(),
107            output_tool_calls: 0,
108        }
109    }
110
111    /// Record how many times the output tool was called.
112    pub(crate) fn with_output_tool_calls(mut self, count: usize) -> Self {
113        self.output_tool_calls = count;
114        self
115    }
116
117    /// How many times the output tool was called.
118    pub fn output_tool_calls(&self) -> usize {
119        self.output_tool_calls
120    }
121
122    /// The concatenated text parts of [`content`](Self::content). In
123    /// output-tool mode this is the serialized structured output.
124    pub fn output(&self) -> String {
125        AssistantContent::concat_text(&self.content)
126    }
127
128    /// Aggregated token usage across the whole run.
129    pub fn usage(&self) -> Usage {
130        self.usage
131    }
132
133    /// The run's transcript (see the [field](Self::messages)).
134    pub fn messages(&self) -> &[Message] {
135        &self.messages
136    }
137
138    /// The structured assistant content for the final turn (see the
139    /// [field](Self::content)).
140    pub fn content(&self) -> &[AssistantContent] {
141        &self.content
142    }
143
144    /// Returns successfully completed completion requests made by this agent run.
145    ///
146    /// An entry whose counters are all `None` means the provider reported no
147    /// usage metrics for that request.
148    pub fn completion_calls(&self) -> &[CompletionCall] {
149        &self.completion_calls
150    }
151
152    /// Number of completion requests this agent run made.
153    pub fn requests(&self) -> usize {
154        self.completion_calls.len()
155    }
156}
157
158/// Replace calls and prose in a finished output-tool turn with final output text,
159/// retaining reasoning and images. Call only after finalization, when remaining
160/// calls are output-tool calls. Persisted history retains prose independently;
161/// returns `None` if no call is present.
162pub(crate) fn finalize_output_tool_choice(
163    choice: &[AssistantContent],
164    output: &str,
165) -> Option<Vec<AssistantContent>> {
166    let finalized_via_output_tool = choice
167        .iter()
168        .any(|item| matches!(item, AssistantContent::ToolCall(_)));
169    if !finalized_via_output_tool {
170        return None;
171    }
172    let mut items: Vec<AssistantContent> = choice
173        .iter()
174        .filter(|item| {
175            !matches!(
176                item,
177                AssistantContent::ToolCall(_) | AssistantContent::Text(_)
178            )
179        })
180        .cloned()
181        .collect();
182    items.push(AssistantContent::text(output.to_string()));
183    Some(items)
184}
185
186use thiserror::Error;
187
188/// Why an agent run failed, whether it was awaited or streamed.
189///
190/// Variants that wrap another error display it unchanged and forward its
191/// source.
192#[derive(Debug, Error)]
193#[non_exhaustive]
194pub enum PromptError {
195    /// A provider completion failed.
196    #[error(transparent)]
197    Provider(ProviderError),
198
199    /// Structured effect failure from a handler, a hook, or a stream item. A
200    /// relayed provider failure arrives as its report.
201    #[error(transparent)]
202    Report(#[from] rig_core::error::ErrorReport),
203
204    /// The run's conversation could not be loaded from its memory store,
205    /// before any model call, or the finished run could not be saved there
206    /// ([`AgentBuilder::memory`](crate::AgentBuilder::memory)). The run did
207    /// not succeed. A failed save may already have set aside a torn last
208    /// line the log ended in (to `recovered/` in the store) and stored the
209    /// blobs of the run's images; its own append stored nothing or, cut
210    /// short, a cut last line, which the next save sets aside. A remote
211    /// store that applied the append before failing to answer may hold all
212    /// of it.
213    #[error("the conversation memory failed: {error}")]
214    Memory {
215        /// Why the store refused or failed, such as
216        /// [`SessionError::Changed`](rig_memory::SessionError::Changed) when
217        /// another run saved to the log after this one loaded it.
218        #[source]
219        error: rig_memory::SessionError,
220        /// The finished run whose save failed; `None` when the load did.
221        response: Option<Box<PromptResponse>>,
222    },
223
224    /// The run exhausted its total model-call budget.
225    #[error("reached the max turns limit of {max_turns}")]
226    MaxTurns {
227        /// Configured total model-call budget.
228        max_turns: usize,
229        /// Canonical history available when the budget was exhausted.
230        chat_history: Vec<Message>,
231        /// Prompt for the call that could not be dispatched.
232        prompt: Message,
233    },
234
235    /// The run was cancelled.
236    #[error("the run was cancelled: {reason}")]
237    Cancelled {
238        /// The run's history at cancellation, every tool call answered
239        /// (closed by [`repair`](rig_core::conversation::pairing::repair)).
240        chat_history: Vec<Message>,
241        /// Human-readable cancellation reason.
242        reason: String,
243    },
244
245    /// The final answer missed the run's output schema, as
246    /// [`rig_core::tool::validate::validate`] checks it, once the
247    /// output-retry budget was spent. The message names the problems and the
248    /// answer's first 200 characters; the fields keep all of them.
249    #[error("{}", schema_mismatch_message(.output, .output_tool.as_deref(), .problems))]
250    OutputSchemaMismatch {
251        /// The whole answer: the text, or the output tool call's arguments,
252        /// re-serialized from their parsed JSON (key order and spacing may
253        /// differ from the model's), or their raw text when they are not a
254        /// JSON object.
255        output: String,
256        /// The output tool the model called, or `None` for a text answer.
257        output_tool: Option<String>,
258        /// Every problem found. Within an object, the problems of its fields
259        /// come first, in the parsed answer's key order (sorted by key unless
260        /// the build enables serde_json's `preserve_order`), then its missing
261        /// required fields, in the schema's `required` order.
262        problems: Vec<Problem>,
263        /// Canonical history at failure, without the refused answer.
264        chat_history: Vec<Message>,
265    },
266
267    /// The model attempted to call a tool unavailable for the current turn.
268    #[error(
269        "model attempted to call unknown or disallowed tool `{tool_name}`. Available tools: {available_tools:?}. Allowed tools for this turn: {allowed_tools:?}"
270    )]
271    UnknownToolCall {
272        /// Tool name emitted by the model.
273        tool_name: String,
274        /// Tools registered on the runtime.
275        available_tools: Vec<String>,
276        /// Exact immutable set allowed for this turn.
277        allowed_tools: Vec<String>,
278        /// Canonical history available at failure.
279        chat_history: Vec<Message>,
280    },
281}
282
283/// The problems as one line, `; `-separated.
284pub(crate) fn join_problems(problems: &[Problem]) -> String {
285    problems
286        .iter()
287        .map(ToString::to_string)
288        .collect::<Vec<_>>()
289        .join("; ")
290}
291
292fn schema_mismatch_message(
293    output: &str,
294    output_tool: Option<&str>,
295    problems: &[Problem],
296) -> String {
297    let problems = join_problems(problems);
298    let excerpt = match output.char_indices().nth(200) {
299        Some((end, _)) => format!("{}…", output.get(..end).unwrap_or_default()),
300        None => output.to_owned(),
301    };
302    let answer = match output_tool {
303        Some(name) => format!("the output tool `{name}` call"),
304        None => "the answer".to_owned(),
305    };
306    format!("{answer} does not satisfy the output schema ({problems}): {excerpt}")
307}
308
309/// A relayed failure is the report the origin sent.
310impl From<ProviderError> for PromptError {
311    fn from(error: ProviderError) -> Self {
312        match error {
313            ProviderError::Relayed(report) => Self::Report(*report),
314            error => Self::Provider(error),
315        }
316    }
317}
318
319/// Forward provider response accessors through wrapped errors and optional reports.
320macro_rules! forward_provider_response_helpers {
321    ($err:ident, $variant:ident, $inner:literal $(, report = $report:ident)?) => {
322        impl $err {
323            #[doc = concat!("Returns the provider response body exposed by a wrapped ", $inner, ".")]
324            pub fn provider_response_body(&self) -> Option<&str> {
325                match self {
326                    Self::$variant(error) => error.provider_response_body(),
327                    $(Self::$report(report) => report.provider_response_body(),)?
328                    _ => None,
329                }
330            }
331
332            #[doc = concat!("Parses the provider response body of a wrapped ", $inner, " as JSON when present.")]
333            pub fn provider_response_json(
334                &self,
335            ) -> Result<Option<serde_json::Value>, serde_json::Error> {
336                match self {
337                    Self::$variant(error) => error.provider_response_json(),
338                    $(Self::$report(report) => report.provider_response_json(),)?
339                    _ => Ok(None),
340                }
341            }
342
343            #[doc = concat!("Returns the provider transport request id exposed by a wrapped ", $inner, ", or carried by a wire report.")]
344            pub fn provider_request_id(&self) -> Option<&str> {
345                match self {
346                    Self::$variant(error) => error.provider_request_id(),
347                    $(Self::$report(report) => report.provider_request_id(),)?
348                    _ => None,
349                }
350            }
351
352            #[doc = concat!("Returns the HTTP status exposed by a wrapped ", $inner, ", or carried by a wire report.")]
353            pub fn provider_response_status(&self) -> Option<http::StatusCode> {
354                match self {
355                    Self::$variant(error) => error.provider_response_status(),
356                    $(Self::$report(report) => report.provider_response_status(),)?
357                    _ => None,
358                }
359            }
360
361            #[doc = concat!("Returns the response headers exposed by a wrapped ", $inner, " or report.")]
362            pub fn provider_response_headers(&self) -> Option<&http::HeaderMap> {
363                match self {
364                    Self::$variant(error) => error.provider_response_headers(),
365                    $(Self::$report(report) => report.provider_response_headers(),)?
366                    _ => None,
367                }
368            }
369        }
370    };
371}
372
373pub(crate) use forward_provider_response_helpers;
374
375forward_provider_response_helpers!(PromptError, Provider, "completion error", report = Report);
376
377impl PromptError {
378    /// Build a [`PromptError::Cancelled`]. A driver gets the history from
379    /// [`AgentRun::cancel_error`](super::AgentRun::cancel_error), or closes
380    /// its own with [`repair`](rig_core::conversation::pairing::repair).
381    pub fn cancelled(chat_history: Vec<Message>, reason: impl Into<String>) -> Self {
382        Self::Cancelled {
383            chat_history,
384            reason: reason.into(),
385        }
386    }
387}