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