Skip to main content

tea_kernel/
error.rs

1use serde::{Deserialize, Serialize};
2use thiserror::Error;
3
4/// Stable machine-readable kernel failure classification.
5#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
6#[serde(rename_all = "snake_case")]
7pub enum KernelErrorCode {
8    /// The requested model is absent or incompatible with the run snapshot.
9    InvalidModel,
10    /// Run configuration or immutable request construction failed.
11    InvalidRequest,
12    /// A runtime state transition is not legal.
13    InvalidState,
14    /// A model adapter stream violated its normalized contract.
15    ModelFailure,
16    /// Tool lookup, validation, or execution failed.
17    ToolFailure,
18    /// Policy or approval context could not be constructed safely.
19    PolicyFailure,
20    /// Durable session state could not be loaded or appended.
21    SessionFailure,
22    /// The awaited observation sink rejected an event.
23    EventSinkFailure,
24    /// The run was cooperatively cancelled.
25    Cancelled,
26    /// A deterministic run limit was reached.
27    LimitExceeded,
28    /// A required deterministic ID could not be produced.
29    IdExhausted,
30    /// The configured clock could not provide a canonical timestamp.
31    ClockFailure,
32    /// The compiled prompt, tools, and messages exceed the model context window.
33    ContextOverflow,
34    /// A retryable model request exhausted the configured retry policy.
35    RetryExhausted,
36    /// The tool scheduler could not place an invocation safely.
37    SchedulerConflict,
38}
39
40/// Bounded safe failure returned by the agent kernel.
41#[derive(Debug, Clone, PartialEq, Eq, Error)]
42#[error("{code:?}: {message}")]
43pub struct KernelError {
44    code: KernelErrorCode,
45    message: String,
46    safe_diagnostic: bool,
47}
48
49impl KernelError {
50    /// Creates a bounded English technical failure.
51    #[must_use]
52    pub fn new(code: KernelErrorCode, message: impl Into<String>) -> Self {
53        let mut message = message.into();
54        if message.is_empty() {
55            "kernel operation failed".clone_into(&mut message);
56        }
57        if message.len() > 4096 {
58            let boundary = message
59                .char_indices()
60                .map(|(index, _)| index)
61                .take_while(|index| *index <= 4096)
62                .last()
63                .unwrap_or(0);
64            message.truncate(boundary);
65        }
66        message.retain(|character| character != '\0');
67        Self {
68            code,
69            message,
70            safe_diagnostic: false,
71        }
72    }
73
74    /// Creates a provider failure whose message was normalized by an adapter.
75    #[must_use]
76    pub fn provider_failure(code: KernelErrorCode, message: impl Into<String>) -> Self {
77        let mut error = Self::new(code, message);
78        error.safe_diagnostic = true;
79        error
80    }
81
82    /// Returns the stable machine-readable code.
83    #[must_use]
84    pub const fn code(&self) -> KernelErrorCode {
85        self.code
86    }
87
88    /// Returns the bounded safe diagnostic.
89    #[must_use]
90    pub fn message(&self) -> &str {
91        &self.message
92    }
93
94    /// Returns whether the message is safe to expose as provider diagnostics.
95    #[must_use]
96    pub const fn is_safe_diagnostic(&self) -> bool {
97        self.safe_diagnostic
98    }
99}