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}