Enum Error 

pub enum Error {
    Provider {
        kind: ProviderErrorKind,
        suggestion: Option<String>,
    },
    Tool {
        name: String,
        call_id: ToolCallId,
        message: String,
        source: Option<Box<dyn Error + Send + Sync>>,
    },
    ContextOverflow {
        used: usize,
        limit: usize,
    },
    Config {
        message: String,
    },
    Cancelled,
    Internal(Box<dyn Error + Send + Sync>),
}

顶层错误枚举。

Agent loop 对此做 match 决定行为：

• Provider { kind: RateLimit { .. }, .. } → 退避重试
• Provider { kind: Authentication { .. }, .. } → 终止并提示用户
• Tool { .. } → 将错误作为 ToolResult 回传给 LLM
• ContextOverflow { .. } → 触发上下文压缩

Examples

use katu_core::error::{Error, ProviderErrorKind};
use katu_core::types::ToolCallId;

// 构造一个工具错误
let err = Error::tool("read_file", ToolCallId::new("call_1"), "file not found");
assert!(err.to_string().contains("read_file"));
assert!(!err.retryable());

// 构造一个可重试的 Provider 错误
let err = Error::provider(
    ProviderErrorKind::RateLimit {
        message: "too many requests".into(),
        retry_after: None,
    },
    "please wait 30 seconds",
);
assert!(err.retryable());
assert!(err.retry_after().is_some());

Variants

Provider

LLM Provider 返回的错误。

Fields

kind: ProviderErrorKind

suggestion: Option<String>

可选的恢复建议，面向终端用户。

Tool

工具执行失败。 非致命：Agent loop 将此作为 tool_result 回传 LLM，让模型自行修正。

Fields

name: String

call_id: ToolCallId

message: String

source: Option<Box<dyn Error + Send + Sync>>

ContextOverflow

上下文窗口溢出。 Agent loop 收到此错误后应触发上下文压缩策略。

Fields

used: usize

limit: usize

Config

配置错误（缺失字段、无效值）。

Fields

message: String

Cancelled

用户或系统取消操作。

Internal(Box<dyn Error + Send + Sync>)

不可归类的内部错误。

Implementations

impl Error

pub fn tool( name: impl Into<String>, call_id: ToolCallId, message: impl Into<String>, ) -> Self

构造一个 Tool 错误。

Examples

use katu_core::error::Error;
use katu_core::types::ToolCallId;

let err = Error::tool("bash", ToolCallId::new("call_42"), "command not found");
assert!(matches!(err, Error::Tool { .. }));

pub fn tool_with_source( name: impl Into<String>, call_id: ToolCallId, message: impl Into<String>, source: impl Error + Send + Sync + 'static, ) -> Self

构造一个带 source 的 Tool 错误。

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

构造一个带恢复建议的 Provider 错误。

Examples

use katu_core::error::{Error, ProviderErrorKind, AuthErrorKind};

let err = Error::provider(
    ProviderErrorKind::Authentication {
        message: "invalid key".into(),
        kind: AuthErrorKind::Invalid,
    },
    "check your API key in ~/.config/katu/config.toml",
);
assert!(!err.retryable());

pub fn retryable(&self) -> bool

该错误是否可重试。

仅 RateLimit 和 ServerError 返回 true。

pub fn retry_after(&self) -> Option<Duration>

建议的退避时间。

如果 Provider 在 header 中指定了 retry-after，返回该值； 否则按分类返回默认退避时间。

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<Box<dyn Error + Sync + Send>> for Error

fn from(source: Box<dyn Error + Send + Sync>) -> Self

Converts to this type from the input type.