clark_agent/
error.rs

1//! Typed error enums.
2//!
3//! `LoopError` is fatal-only: stream transport unrecoverable failure or
4//! caller cancellation. Recoverable tool errors are not loop errors —
5//! they're context events: the tool returns `ToolResult` with the error encoded as text,
6//! the loop appends it to history, and the model decides what to do.
7//! Only explicit tool aborts and fatal tool errors bubble out.
8
9use thiserror::Error;
10
11/// Why the loop terminated abnormally.
12///
13/// A successful run returns `Ok(messages)` with no error. The loop's
14/// natural stop condition (no more tool calls + no follow-up) does not
15/// produce an error.
16#[derive(Debug, Error)]
17pub enum LoopError {
18    /// Stream transport raised an unrecoverable error. The provider
19    /// implementation decides what's recoverable; everything that bubbles
20    /// up through `StreamFn::stream` ends the run.
21    #[error("stream transport error: {0}")]
22    Stream(#[from] StreamError),
23
24    /// Caller cancelled via the abort signal.
25    #[error("aborted")]
26    Aborted,
27
28    /// A tool encountered an unrecoverable failure and requested that
29    /// the loop stop immediately rather than append a recoverable
30    /// context event.
31    #[error("fatal tool `{tool}` error: {reason}")]
32    ToolFatal { tool: String, reason: String },
33
34    /// Cannot continue without a starting message: `run_continue` was
35    /// called on an empty context, or the trailing message is `assistant`
36    /// (which the model would not respond to).
37    #[error("cannot continue: {0}")]
38    InvalidContinuation(String),
39
40    /// The model repeatedly stopped without any tool call after the
41    /// configured no-tool recovery budget had already been spent.
42    #[error(
43        "empty assistant outcome retry budget exhausted: observed {observed} no-tool assistant stop(s), budget {budget}"
44    )]
45    EmptyOutcomeBudgetExhausted { budget: usize, observed: usize },
46}
47
48#[derive(Debug, Error)]
49pub enum StreamError {
50    /// Transient failure: rate limit, network blip, retryable provider
51    /// error. The transport implementation decides whether to retry
52    /// internally or surface this.
53    #[error("transient stream error: {0}")]
54    Transient(String),
55
56    /// The selected model/provider is temporarily rate-limited. The
57    /// transport exhausted its own retry budget before surfacing this.
58    #[error("provider rate-limited request: {0}")]
59    ProviderRateLimited(String),
60
61    /// Transport failed before the provider produced an actionable
62    /// assistant turn. The request can be replayed as a clean provider
63    /// attempt because there is no runnable assistant turn to preserve.
64    #[error("zero-output transport error: {0}")]
65    ZeroOutputTransport(String),
66
67    /// Permanent failure: invalid request, auth, unsupported model.
68    #[error("fatal stream error: {0}")]
69    Fatal(String),
70
71    /// Provider returned an empty response after streaming completed.
72    /// The model produced nothing.
73    #[error("empty stream response")]
74    Empty,
75
76    /// Provider rejected the request because the input context exceeds
77    /// the model's window. Distinct from `Fatal` so the loop can apply
78    /// recovery (compact + retry) instead of terminating. Today the
79    /// run still ends — the recovery path lands with the Phase 2
80    /// `OverflowRecovery` plugin chain.
81    #[error("context overflow: {0}")]
82    ContextOverflow(String),
83}
84
85#[derive(Debug, Error)]
86pub enum ToolError {
87    /// Tool execution failed but the agent should keep running. Maps to
88    /// a tool result with the error text and `is_error = true`.
89    #[error("tool execution failed: {0}")]
90    Execution(String),
91
92    /// Tool was cancelled mid-run via the abort signal.
93    #[error("tool aborted")]
94    Aborted,
95
96    /// Tool encountered a fatal error that should end the run. Use
97    /// sparingly — most failures should be `Execution`.
98    #[error("fatal tool error: {0}")]
99    Fatal(String),
100}
101
102#[derive(Debug, Error)]
103pub enum ToolValidationError {
104    /// JSON Schema validation failed for the named field.
105    #[error("invalid arguments for `{tool}`: {reason}")]
106    InvalidArguments { tool: String, reason: String },
107
108    /// Required field is missing for the requested action variant.
109    #[error("missing required field `{field}` for `{tool}.{action}`")]
110    MissingField {
111        tool: String,
112        action: String,
113        field: String,
114    },
115
116    /// Some other validation failure not covered above.
117    #[error("{0}")]
118    Other(String),
119}
clark_agent/error.rs

clark_agent/
error.rs
