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