rusty_agent_runtime/error.rs
1//! Error types for Rusty Core.
2//!
3//! All fallible operations in the crate return [`Result<T>`] with
4//! [`RustyError`] as the error type.
5
6use serde_json::Value;
7use thiserror::Error;
8
9/// The single error type for the whole crate.
10///
11/// Design note: `Interrupt` is modeled as an *error* because a node calls
12/// `interrupt()` mid-execution to unwind out of the current super-step; the
13/// executor catches this variant, persists a checkpoint, and surfaces the
14/// payload to the caller. This mirrors LangGraph's `GraphInterrupt` and keeps
15/// the control flow explicit in the type system.
16#[derive(Debug, Error)]
17pub enum RustyError {
18 /// Structural graph problems: invalid builder usage, validation failures
19 /// from `GraphBuilder::compile()` (unknown entry point, dangling edges), routing
20 /// to unknown nodes at runtime, exceeded `max_steps`, etc.
21 #[error("graph error: {0}")]
22 Graph(String),
23
24 /// A node failed during execution. The string should include the node
25 /// name and the underlying failure description.
26 #[error("node error: {0}")]
27 Node(String),
28
29 /// A node invoked `interrupt(payload)`. Carries the payload to surface
30 /// to the caller; resumable via `RunConfig::resume` / `Command::resume`.
31 ///
32 /// This variant is **not** a failure — it is the suspend signal of the
33 /// interrupt/resume protocol.
34 #[error("graph interrupted")]
35 Interrupt {
36 /// The payload passed to `interrupt()`, surfaced to the caller
37 /// (e.g. a human-in-the-loop approval request).
38 value: Value,
39 },
40
41 /// Checkpoint persistence failures (IO, serialization, not found).
42 #[error("checkpoint error: {0}")]
43 Checkpoint(String),
44
45 /// LLM provider failures (HTTP errors, malformed responses, auth).
46 #[error("llm error: {0}")]
47 Llm(String),
48
49 /// Tool execution failures (unknown tool, bad arguments, runtime error).
50 #[error("tool error: {0}")]
51 Tool(String),
52
53 /// Exact-replay failures (Flight Recorder, R0.5): the run diverged from
54 /// the journaled evidence (request-hash mismatch, effect-order violation,
55 /// unserved recorded effects), a journal snapshot or fixture failed
56 /// integrity verification, or a replay was requested against an
57 /// incompatible graph, fixture, or resumed-run journal.
58 #[error("replay error: {0}")]
59 Replay(String),
60
61 /// JSON (de)serialization failures.
62 #[error("serialization error: {0}")]
63 Serialization(#[from] serde_json::Error),
64
65 /// A channel received an update it cannot accept — most commonly a
66 /// `LastValue`-style channel written more than once in a single
67 /// super-step (the LangGraph `InvalidUpdateError` class of bug), or a
68 /// write to an undeclared channel.
69 #[error("invalid state update: {0}")]
70 InvalidUpdate(String),
71
72 /// The run was cancelled cooperatively through
73 /// [`crate::executor::RunConfig::cancellation`] (R0.6 wave 2c, drain):
74 /// the executor stopped *at a super-step boundary*, so the boundary
75 /// checkpoint is intact and the run resumes from exactly there.
76 ///
77 /// Like [`RustyError::Interrupt`], this variant is **not** a failure —
78 /// it is control flow (the `cancelled` class of the Durable Work
79 /// taxonomy: never retried, never dead-lettered). Unlike an interrupt,
80 /// nothing is being asked of a human; whoever cancelled decides whether
81 /// and when to re-drive the run from its last checkpoint.
82 #[error("run cancelled: {0}")]
83 Cancelled(String),
84}
85
86impl RustyError {
87 /// Returns `true` if this error is an interrupt (suspend) signal rather
88 /// than an actual failure.
89 pub fn is_interrupt(&self) -> bool {
90 matches!(self, RustyError::Interrupt { .. })
91 }
92
93 /// If this is an [`RustyError::Interrupt`], returns a reference to
94 /// the interrupt payload.
95 pub fn interrupt_value(&self) -> Option<&Value> {
96 match self {
97 RustyError::Interrupt { value } => Some(value),
98 _ => None,
99 }
100 }
101}
102
103/// Crate-wide result alias.
104pub type Result<T> = std::result::Result<T, RustyError>;