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}