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