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