Raw error messages (like Connection refused (os error 111)) are often confusing for end-users. Agent Air encourages a pattern of “User-Facing Error Transformation”.

The Display Implementation

While Debug implementations should show full internal details, Display implementations for high-level errors should aim for readability.

// Good Display impl
impl fmt::Display for LlmError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            LlmError::Api { status: 401, .. } => 
                write!(f, "Authentication failed. Please check your API key."),
            LlmError::Network(_) => 
                write!(f, "Could not connect to the AI provider. Check your internet connection."),
            // ...
        }
    }
}

UI Presentation

The TUI differentiates between levels of severity:

  1. Info/Success: Green text or subtle indicators.
  2. Warning: Yellow text. Used for things like “Context limit approaching” or “Tool execution took too long”.
  3. Error: Red text. Used for “Request failed” or “Permission denied”.

Privacy

Be careful not to leak sensitive information (like full file paths or raw API keys) in error messages that might be displayed in the UI or logs, especially if the agent output is shared.