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}