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 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}