agent_abstraction/error.rs
1//! The one error type every fallible call in this crate returns.
2//!
3//! Each variant is a case a caller has to branch on differently. A GUI shows
4//! [`Error::NotInstalled`] as an install prompt, [`Error::RateLimited`] as
5//! "wait", and [`Error::Unsupported`] as a programming mistake. Failures that
6//! need no branch collapse into [`Error::Spawn`] / [`Error::Store`].
7
8use std::time::Duration;
9
10use crate::agent::Agent;
11
12/// Result alias for this crate.
13pub type Result<T> = std::result::Result<T, Error>;
14
15/// Everything that can go wrong driving an agent CLI.
16#[derive(Debug, thiserror::Error)]
17#[non_exhaustive]
18pub enum Error {
19 /// The agent's binary is not on `PATH`. Carries the install command so a UI
20 /// can offer it directly instead of making the user go find it.
21 #[error("`{bin}` not found on PATH; install it: {hint}")]
22 NotInstalled {
23 /// The agent whose binary is missing.
24 agent: Agent,
25 /// The binary name that was looked up.
26 bin: String,
27 /// The documented install command.
28 hint: &'static str,
29 },
30
31 /// The child process could not be started, or its stdio could not be read.
32 #[error("failed to spawn `{bin}`: {source}")]
33 Spawn {
34 /// The binary that failed to start.
35 bin: String,
36 /// The underlying OS error.
37 #[source]
38 source: std::io::Error,
39 },
40
41 /// The run exceeded its deadline and the child was killed. Any output
42 /// captured before the kill is preserved so a caller can still show it.
43 #[error("`{bin}` exceeded its {} s timeout and was killed", timeout.as_secs())]
44 Timeout {
45 /// The binary that overran.
46 bin: String,
47 /// The deadline that was hit.
48 timeout: Duration,
49 /// Whatever the agent had printed before it was killed.
50 partial: String,
51 },
52
53 /// The agent ran to completion but exited non-zero.
54 #[error("`{bin}` exited with status {code}: {stderr}")]
55 Failed {
56 /// The binary that failed.
57 bin: String,
58 /// Its exit code, or `-1` when it died to a signal.
59 code: i32,
60 /// Its stderr, trimmed, for the message.
61 stderr: String,
62 },
63
64 /// The provider refused the request for quota reasons: a usage limit, a
65 /// rate limit, or an exhausted budget.
66 ///
67 /// This is deliberately its own variant and this crate never retries it
68 /// automatically. Backing off is the caller's decision and burying a
69 /// retry loop in here would turn a limit the provider set into something
70 /// the library quietly works around. See `docs/operating-limits.md`.
71 #[error("`{bin}` was rate limited or hit a usage limit: {message}")]
72 RateLimited {
73 /// The binary that was limited.
74 bin: String,
75 /// The provider's own wording, passed through unedited.
76 message: String,
77 },
78
79 /// The request asked an agent for something it cannot do headlessly:
80 /// forking on Codex, a named session on Copilot, an event stream on an
81 /// agent that only prints text.
82 ///
83 /// Always an error, never a silent downgrade: a caller that asked to fork
84 /// and got a linear resume would corrupt the conversation it meant to
85 /// branch.
86 #[error("{agent} does not support {what}")]
87 Unsupported {
88 /// The agent that was asked.
89 agent: Agent,
90 /// The capability it lacks.
91 what: &'static str,
92 },
93
94 /// A named session already belongs to a different agent. Sessions cannot
95 /// migrate: the stored handle is only meaningful to the CLI that minted it.
96 #[error("session `{name}` belongs to {bound}, cannot resume it on {requested}")]
97 SessionConflict {
98 /// The caller's session name.
99 name: String,
100 /// The agent that created the session.
101 bound: Agent,
102 /// The agent the caller tried to use.
103 requested: Agent,
104 },
105
106 /// The session store could not be read or written.
107 #[error("session store I/O failed at {path}: {source}")]
108 Store {
109 /// The file or directory involved.
110 path: String,
111 /// The underlying OS error.
112 #[source]
113 source: std::io::Error,
114 },
115
116 /// The agent produced output this crate could not interpret: a missing
117 /// session id under a format that promises one, or unparseable JSON where
118 /// the contract requires it.
119 #[error("could not parse {agent} output: {detail}")]
120 Parse {
121 /// The agent whose output was unreadable.
122 agent: Agent,
123 /// What specifically was wrong.
124 detail: String,
125 },
126
127 /// The agent has no usable credentials.
128 ///
129 /// Its own category because the remedy is a specific human action rather
130 /// than anything about the request, and because it is easy to reach by
131 /// accident: [`crate::EnvPolicy::Minimal`] withholds the environment by
132 /// default, so a credential this crate does not know to pass through
133 /// presents as a login failure rather than a configuration one.
134 #[error("`{bin}` is not authenticated: {message}. To fix: {hint}")]
135 NotAuthenticated {
136 /// The agent that refused.
137 agent: Agent,
138 /// The binary that refused.
139 bin: String,
140 /// The provider's own wording, unedited.
141 message: String,
142 /// The command that resolves it.
143 hint: &'static str,
144 },
145
146 /// The agent ran, exited cleanly, and reported that the turn itself failed.
147 ///
148 /// Its own variant because the process succeeding says nothing about the
149 /// turn succeeding. An unknown model, a schema the provider rejects or an
150 /// upstream outage all arrive this way: exit code 0, with the failure
151 /// described in the output. Reporting that as `Ok` hands back an
152 /// [`crate::Outcome`] whose `text` is an error message, which a caller
153 /// checking only `Result::is_ok` will render as the answer.
154 ///
155 /// The same reasoning already applied to [`Error::NotAuthenticated`] and
156 /// [`Error::RateLimited`], which are also reported with a zero exit; this
157 /// covers everything else in that family.
158 #[error("{agent} reported a failed turn{}: {message}", status.map(|s| format!(" (status {s})")).unwrap_or_default())]
159 AgentError {
160 /// The agent that failed.
161 agent: Agent,
162 /// The binary that ran.
163 bin: String,
164 /// The provider's status code, where the agent reported one. A 404 is
165 /// typically an unknown model, a 400 a rejected request.
166 status: Option<u16>,
167 /// The agent's own description, unedited.
168 message: String,
169 },
170
171 /// The CLI rejected an argument this crate passed it.
172 ///
173 /// Almost always a version mismatch: the flag was verified against the
174 /// release named in [`crate::Agent::verified_version`] and the installed
175 /// one differs. Separated from [`Error::Failed`] because the remedy is
176 /// different: nothing about the request is wrong, the wrapper and the CLI
177 /// disagree. Run [`crate::Probe`] to confirm.
178 #[error(
179 "`{bin}` rejected an argument, which usually means its version differs from the one these flags were verified against: {detail}"
180 )]
181 FlagRejected {
182 /// The binary that refused.
183 bin: String,
184 /// Its own complaint, unedited.
185 detail: String,
186 },
187
188 /// The run was stopped by [`crate::Run::cancel`] or by dropping its handle.
189 ///
190 /// Not a fault: the caller asked for this. Distinguished from
191 /// [`Error::Interrupted`], which means the driver died unexpectedly, and
192 /// from [`Error::Timeout`], which is a deadline rather than a request.
193 #[error("the run of `{bin}` was cancelled")]
194 Cancelled {
195 /// The binary that was stopped.
196 bin: String,
197 },
198
199 /// A prompt, system prompt or raw argument too large for the command line,
200 /// on an agent with no way to deliver it off the argv.
201 ///
202 /// Returned rather than letting the OS reject the spawn with a bare
203 /// `E2BIG`, which says nothing about which input was the problem.
204 #[error(
205 "{what} is {size} bytes, over the {limit} byte command-line budget for {agent}, \
206 and it has no way to take it off the command line"
207 )]
208 CommandLineTooLarge {
209 /// The agent the request targeted.
210 agent: Agent,
211 /// Which input overflowed.
212 what: &'static str,
213 /// Its size in bytes.
214 size: usize,
215 /// The budget it exceeded.
216 limit: usize,
217 },
218
219 /// [`crate::stream`] was called outside a Tokio runtime.
220 ///
221 /// Spawning the driver task needs a runtime context. Reporting this rather
222 /// than letting `tokio::spawn` panic keeps the fallible signature honest.
223 #[error("no Tokio runtime is running; call this from within one")]
224 NoRuntime,
225
226 /// The task driving the run panicked or was cancelled, so there is no
227 /// outcome to report.
228 ///
229 /// Distinct from [`Error::Spawn`] on purpose: the process started fine, and
230 /// reporting this as a spawn failure would name the wrong cause. It is also
231 /// why this is not squeezed into an [`std::io::Error`], which a dropped
232 /// runtime task is not.
233 #[error("the run of `{bin}` was interrupted: {detail}")]
234 Interrupted {
235 /// The binary that was running.
236 bin: String,
237 /// Whether the task panicked or was cancelled.
238 detail: String,
239 },
240}
241
242impl Error {
243 /// Whether retrying this exact request later could plausibly succeed.
244 ///
245 /// True for quota and timeout failures; false for a missing binary, an
246 /// unsupported capability, or a session conflict, which need the caller to
247 /// change something first. This classifies; it does not retry.
248 #[must_use]
249 pub fn is_transient(&self) -> bool {
250 matches!(self, Error::RateLimited { .. } | Error::Timeout { .. })
251 }
252
253 /// Whether this run was stopped because the caller asked, rather than
254 /// because anything went wrong. A UI should not show it as a failure.
255 #[must_use]
256 pub fn is_cancelled(&self) -> bool {
257 matches!(self, Error::Cancelled { .. })
258 }
259
260 /// Whether this failed because the agent has no usable credentials.
261 ///
262 /// Worth branching on in a UI: unlike most failures, the user can fix it,
263 /// and [`Error::NotAuthenticated`] carries the command that does.
264 #[must_use]
265 pub fn is_auth_failure(&self) -> bool {
266 matches!(self, Error::NotAuthenticated { .. })
267 }
268}