ControllerError encapsulates failures that occur during the “thinking” and “acting” loops of the agent. This includes context management, tool execution coordination, and message processing.

Definition

#[derive(Debug, Error)]
pub enum ControllerError {
    #[error("Context window exceeded: {used}/{limit} tokens")]
    ContextLimitExceeded { used: usize, limit: usize },

    #[error("Tool execution failed: {0}")]
    ToolExecution(String),

    #[error("Unknown tool: {0}")]
    UnknownTool(String),

    #[error("Invalid state transition")]
    InvalidState,

    #[error("Session not found: {0}")]
    SessionNotFound(String),
    
    #[error("Channel closed")]
    ChannelClosed,
}

Handling Controller Errors

Unlike configuration errors which are usually fatal at startup, controller errors often happen during runtime.

• ContextLimitExceeded: Can trigger a compaction strategy or prompt the user to summarize.
• ToolExecution: Usually reported to the LLM so it can retry or apologize to the user.
• ChannelClosed: Often indicates a panic in a worker task or an intentional shutdown.