Decide what to do with an Awaken Agents execution error

First identify where the error was returned. A failed Runtime call, a terminal Run, a failed Tool invocation, and a model-visible Tool result have different owners. Branch on the enum variant or stable failure code. Error messages are diagnostic text, not a compatibility contract.

Choose by surface

flowchart TD
  Start[What did the caller receive?] --> Call{Runtime call returned Err?}
  Call -->|Yes| API[execution::Error<br/>Resolution · Execution · Commit]
  Call -->|No| State{RunState is Ended Error?}
  State -->|Yes| Failure[Failure<br/>stable code and message]
  State -->|No| Tool{Inside a Tool implementation?}
  Tool -->|Invocation failed| ToolError[ToolError]
  Tool -->|Model should see a failed result| Output[ToolOutput::error]
  Tool -->|No| Continue[Continue from returned RunState]

Runtime call errors

The direct embedding surface is:

pub enum awaken_runtime_contract::execution::Error {
    Resolution(String),
    Execution(String),
    Commit(String),
    StateConflict, // internal; converted to a terminal Failure
}

The strings explain the concrete failure but are not stable error subtypes. A host that needs finer public errors maps these neutral variants at its adapter boundary.

Model failures and retry ownership

awaken_runtime_contract::llm::Error classifies one model request. Runtime owns the retry decision for that request.

sequenceDiagram
  participant Runtime
  participant Provider
  participant Commit
  participant Caller

  Runtime->>Provider: one logical model request
  alt Provider, RateLimited, Overloaded, or Timeout
    Provider-->>Runtime: retryable llm::Error
    Runtime->>Runtime: backoff and retry within policy
  else permanent classification
    Provider-->>Runtime: non-retryable llm::Error
  end
  alt a request eventually succeeds
    Runtime->>Commit: continue the Step
  else recovery is exhausted or impossible
    Runtime->>Commit: Ended(Error(Failure::Inference code))
    Commit-->>Caller: terminal RunState or RunFailed fact
  end

If a model failure cannot recover, Runtime commits Failure::Inference { code, message }. The stable code comes from llm::Error::code().

Tool invocation versus Tool result

pub enum ToolError {
    Unknown(String),
    InvalidArguments(String),
    UnavailableBeforeDispatch(String),
    Execution(String),
}

UnavailableBeforeDispatch is the only variant that proves the request did not cross the executor dispatch boundary. A recovery policy may replay it. An Execution error does not prove whether an external effect occurred; inspect the committed ToolBatch and use its recovery policy or downstream reconciliation contract.

When failure is an ordinary domain result the model can respond to, return ToolOutput::error(call_id, content). Do not turn that result into ToolError.

Terminal and composition failures

Failure is the committed Run-level classification:

pub enum Failure {
    Inference { code: String, message: String },
    CapabilityBound,
    StateConflict,
}

CapabilityBound means a Plugin attempted to contribute or schedule outside its published bound. StateConflict means one commit batch wrote an Exclusive (Scope, Key) more than once. Both fail closed; correct the Plugin contribution or state-command construction before creating a new Run.

Plugin authors may receive PluginConfigError, BoundViolation, or MergeError while resolving one ResolvedExecutionEnv. Fix malformed config, missing dependencies, cycles, MergeError::DuplicatePlugin, other duplicate ids, or out-of-bound contributions at that boundary. Runtime does not silently drop a contribution to make the Run start.

pub enum MergeError {
    Bound(BoundViolation),
    DuplicateTool { id: String, first: String, second: String },
    DuplicateActionKind { id: String, first: String, second: String },
    MissingDependency { plugin: String, missing: String },
    DependencyCycle,
    DuplicatePlugin { id: String },
    Config(PluginConfigError),
}

Related

• Tool Trait
• State Keys
• Run, Step, and ToolBatch state