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,
    },
    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,
    },
    Store {
        path: String,
        source: Error,
    },
    Parse {
        agent: Agent,
        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.

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.

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.

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; 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.

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.

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.