Skip to main content

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>;