Enum Error 

#[non_exhaustive]
pub enum Error {
    NotInstalled {
        agent: Agent,
        bin: String,
        hint: &'static str,
    },
    Spawn {
        bin: String,
        source: Error,
    },
    Timeout {
        bin: String,
        timeout: Duration,
        partial: String,
    },
    ControlTimeout {
        bin: String,
        timeout: Duration,
    },
    Failed {
        bin: String,
        code: i32,
        stderr: String,
    },
    RateLimited {
        bin: String,
        message: String,
    },
    Unsupported {
        agent: Agent,
        what: &'static str,
    },
    SessionConflict {
        name: String,
        bound: Agent,
        requested: Agent,
    },
    SessionBusy {
        name: String,
        project: String,
    },
    Store {
        path: String,
        source: Error,
    },
    Parse {
        agent: Agent,
        detail: String,
    },
    NotAuthenticated {
        agent: Agent,
        bin: String,
        message: String,
        hint: &'static str,
    },
    AgentError {
        agent: Agent,
        bin: String,
        status: Option<u16>,
        message: String,
    },
    FlagRejected {
        bin: String,
        detail: String,
    },
    Cancelled {
        bin: String,
    },
    CommandLineTooLarge {
        agent: Agent,
        what: &'static str,
        size: usize,
        limit: usize,
    },
    NoRuntime,
    Interrupted {
        bin: String,
        detail: String,
    },
}

Everything that can go wrong driving an agent CLI.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

NotInstalled

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.

Fields

agent: Agent

The agent whose binary is missing.

bin: String

The binary name that was looked up.

hint: &'static str

The documented install command.

Spawn

The child process could not be started, or its stdio could not be read.

Fields

bin: String

The binary that failed to start.

source: Error

The underlying OS error.

Timeout

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.

Fields

bin: String

The binary that overran.

timeout: Duration

The deadline that was hit.

partial: String

Whatever the agent had printed before it was killed.

ControlTimeout

An interactive transport accepted a control request locally but never acknowledged it. The agent process may still be alive, but the caller must stop that run before retrying the input on a resumed session.

Fields

bin: String

The agent binary whose transport stopped responding.

timeout: Duration

How long the delivery receipt was allowed to take.

Failed

The agent ran to completion but exited non-zero.

Fields

bin: String

The binary that failed.

code: i32

Its exit code, or -1 when it died to a signal.

stderr: String

Its stderr, trimmed, for the message.

RateLimited

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.

Fields

bin: String

The binary that was limited.

message: String

The provider’s own wording, passed through unedited.

Unsupported

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.

Fields

agent: Agent

The agent that was asked.

what: &'static str

The capability it lacks.

SessionConflict

A named session already belongs to a different agent. Sessions cannot migrate: the stored handle is only meaningful to the CLI that minted it.

Fields

name: String

The caller’s session name.

bound: Agent

The agent that created the session.

requested: Agent

The agent the caller tried to use.

SessionBusy

Another run currently owns the same named session.

The lease is cross-process and ends when that run settles or its process dies. Retrying later is safe; running both would fork the provider’s conversation and leave the store pointing at whichever finished last.

Fields

name: String

The caller-owned session name.

project: String

The project namespace containing it.

Store

The session store could not be read or written.

Fields

path: String

The file or directory involved.

source: Error

The underlying OS error.

Parse

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.

Fields

agent: Agent

The agent whose output was unreadable.

detail: String

What specifically was wrong.

NotAuthenticated

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.

Fields

agent: Agent

The agent that refused.

bin: String

The binary that refused.

message: String

The provider’s own wording, unedited.

hint: &'static str

The command that resolves it.

AgentError

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.

Fields

agent: Agent

The agent that failed.

bin: String

The binary that ran.

status: Option<u16>

The provider’s status code, where the agent reported one. A 404 is typically an unknown model, a 400 a rejected request.

message: String

The agent’s own description, unedited.

FlagRejected

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.

Fields

bin: String

The binary that refused.

detail: String

Its own complaint, unedited.

Cancelled

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.

Fields

bin: String

The binary that was stopped.

CommandLineTooLarge

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.

Fields

agent: Agent

The agent the request targeted.

what: &'static str

Which input overflowed.

size: usize

Its size in bytes.

limit: usize

The budget it exceeded.

NoRuntime

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.

Interrupted

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.

Fields

bin: String

The binary that was running.

detail: String

Whether the task panicked or was cancelled.

Implementations

impl Error

pub fn is_transient(&self) -> bool

Whether retrying this exact request later could plausibly succeed.

True for quota and timeout failures, and for a named session whose prior run has not settled yet. False for a missing binary, an unsupported capability, or an agent mismatch, which need the caller to change something first. This classifies; it does not retry. A caller must stop the old run before retrying Error::ControlTimeout.

pub fn is_cancelled(&self) -> bool

Whether this run was stopped because the caller asked, rather than because anything went wrong. A UI should not show it as a failure.

pub fn is_auth_failure(&self) -> bool

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.

Trait Implementations

impl Debug for Error

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for Error

fn fmt(&self, __formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Error for Error

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.