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}