Enum Error 

pub enum Error {
    Io(Error),
    State(Error),
    Provider {
        kind: ProviderErrorKind,
        status: Option<u16>,
        retry_after: Option<Duration>,
        message: String,
    },
    Config(String),
    Sandbox {
        reason: String,
    },
    Refused {
        act: String,
        target: String,
        rule: Option<String>,
        layer: Option<String>,
    },
    Mcp {
        server: String,
        reason: String,
    },
    Resume {
        reason: String,
    },
}

Errors io-harness can return from a run.

The variants are separate because the response to each is separate — a refusal is not a malfunction, a bad checkpoint is not a bad key, and only one arm here is ever worth retrying. This is the match a caller writes around an entry point:

use io_harness::Error;

match failure {
    // The policy said no. Nothing happened and nothing is broken: either
    // widen the rule that refused it, or accept the refusal. The rule and
    // layer are carried so the operator knows which line of config to edit.
    Error::Refused { act, target, rule, layer } => format!(
        "{act} {target} refused by {} in layer {}",
        rule.unwrap_or_else(|| "the tier default".into()),
        layer.unwrap_or_else(|| "-".into()),
    ),
    // The checkpoint could not be honoured — newer format, missing run, or a
    // run started under a policy this resume would have silently dropped.
    // Never retried in a loop: re-resume the way the message names.
    Error::Resume { reason } => format!("resume refused: {reason}"),
    // Operator error, raised before the provider is called once. Fail the
    // job; a second attempt reaches the same missing key or duplicate tool.
    Error::Config(message) => format!("fix the configuration: {message}"),
    // The tool server never came up. The run fails rather than quietly
    // proceeding without a capability it was told it had.
    Error::Mcp { server, reason } => format!("server {server} did not start: {reason}"),
    // The gate never ran the code, as opposed to running it and failing it.
    Error::Sandbox { reason } => format!("verification never executed: {reason}"),
    // The one arm where another attempt is a real option — and only for some
    // kinds; see `ProviderErrorKind::is_retryable`.
    Error::Provider { kind, message, .. } if kind.is_retryable() => format!("retry: {message}"),
    other => other.to_string(),
}

Variants

Io(Error)

A filesystem tool operation failed.

State(Error)

The state store (rusqlite) failed.

Provider

The provider request or its streamed response failed.

ProviderErrorKind is what a caller branches on; status and retry_after are kept rather than folded into the message so a retry can honour what the server actually said.

Fields

kind: ProviderErrorKind

Why the call failed, and whether retrying is worth it.

status: Option<u16>

The HTTP status, when the failure had one.

retry_after: Option<Duration>

The server’s Retry-After, when it sent one.

message: String

What the provider or the transport reported.

Config(String)

Configuration was missing or invalid (e.g. no API key).

Sandbox

The sandbox failed to start (e.g. the backend or the program could not be spawned). Typed separately from Error::Io so a calling agent can tell “the sandbox never ran the code” apart from “the code ran and failed”, and adapt — one failed child does not take down its siblings or the tree.

Fields

reason: String

Why the sandbox could not start the command.

Refused

The permission policy refused the action. Typed separately from Error::Config so a refusal is distinguishable from a malfunction — a verification that was refused is not a verification that ran and failed, and the model is told the difference.

Fields

act: String

The action attempted.

target: String

The path or binary it targeted.

rule: Option<String>

The glob that refused it, when a rule rather than a default did.

layer: Option<String>

The layer that rule came from.

Mcp

An MCP server could not be reached or set up. Typed separately from Error::Provider so a caller can tell “the model call failed” from “the tool server the operator configured never came up” — the second is a configuration problem, and the run fails on it rather than quietly proceeding without a capability it was told it had.

Failures during a call — a timeout, a dead transport, a tool reporting its own error — are not this. They come back to the model as observations it can adapt to, like a refused path or a bad regex.

Fields

server: String

The configured server’s id.

reason: String

What went wrong.

Resume

A durable run could not be resumed from its checkpoint — the checkpoint format is newer than this binary supports, the run row is missing or corrupt, or the run has already finished. Typed separately so a caller handles a bad-checkpoint resume as a recoverable error instead of a panic or a silent half-resume. A partially written (crashed mid-commit) step is never surfaced here: the transaction rolls it back, so resume always sees the prior consistent checkpoint, not a torn one.

Fields

reason: String

Why the run could not be resumed.

Implementations

impl Error

pub fn provider(kind: ProviderErrorKind, message: impl Into<String>) -> Self

A provider failure of kind carrying no HTTP status — the request never completed, or the response could not be read.

pub fn provider_transport(message: impl Into<String>) -> Self

The request never completed: connection refused, DNS, TLS, a mid-stream byte error.

pub fn provider_malformed(message: impl Into<String>) -> Self

The response arrived and nothing in it could be read.

pub fn provider_status( status: u16, retry_after: Option<Duration>, message: impl Into<String>, ) -> Self

A non-success HTTP status, with the kind derived once by ProviderErrorKind::from_status so no provider can classify it differently.

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.

impl From<Error> for Error

fn from(source: Error) -> Self

Converts to this type from the input type.

impl From<Error> for Error

fn from(source: Error) -> Self

Converts to this type from the input type.

impl From<Error> for Error

Every reqwest failure the crate sees is a provider call that did not complete, so the timeout/transport split is decided here once instead of at each of the four call sites (three providers plus the shared SSE reader).

fn from(e: Error) -> Self

Converts to this type from the input type.