runifold_agent/
error.rs

1use runifold_core::{BudgetExceeded, CheckpointError, JournalError};
2use runifold_effect::EffectExecutorError;
3use runifold_model::ModelError;
4use runifold_retrieval::RetrievalError;
5use runifold_tool::ToolError;
6use thiserror::Error;
7
8use crate::GatewayError;
9
10/// Failure of an agent run.
11#[derive(Debug, Error)]
12#[non_exhaustive]
13pub enum AgentError {
14    /// Model invocation failed.
15    #[error("model invocation failed: {0}")]
16    Model(#[from] ModelError),
17    /// Tool execution failed.
18    #[error("tool execution failed: {0}")]
19    Tool(#[from] ToolError),
20    /// Static or dynamic context retrieval failed.
21    #[error("agent retrieval failed: {0}")]
22    Retrieval(#[from] RetrievalError),
23    /// A shared run-tree budget was exceeded.
24    #[error("agent budget exceeded: {0}")]
25    Budget(#[from] BudgetExceeded),
26    /// Agent delegation failed.
27    #[error("agent delegation failed: {0}")]
28    Gateway(#[from] GatewayError),
29    /// Structured event recording failed.
30    #[error("agent observability failed: {0}")]
31    Journal(#[from] JournalError),
32    /// Checkpoint persistence or validation failed.
33    #[error("agent checkpoint failed: {0}")]
34    Checkpoint(#[from] CheckpointError),
35    /// Write-ahead effect coordination failed.
36    #[error("agent effect failed: {0}")]
37    Effect(#[from] EffectExecutorError),
38    /// Recovery would silently retry a possibly partial external turn.
39    #[error("checkpoint contains an ambiguous in-flight turn {turn}")]
40    AmbiguousCheckpoint {
41        /// One-based interrupted turn number.
42        turn: u32,
43    },
44    /// Agent configuration is invalid.
45    #[error("invalid agent configuration: {0}")]
46    InvalidConfig(String),
47    /// Model output violated the agent-loop protocol.
48    #[error("agent protocol error: {0}")]
49    Protocol(String),
50    /// The configured local turn bound was reached.
51    #[error("agent exceeded its local maximum of {max_turns} turns")]
52    MaxTurns {
53        /// Configured local turn bound.
54        max_turns: u32,
55    },
56    /// The model terminated before the successful local Tool-call minimum.
57    #[error(
58        "agent completed only {successful} successful local Tool calls; at least {required} required"
59    )]
60    ToolRequirementUnsatisfied {
61        /// Required successful local Tool calls.
62        required: u32,
63        /// Successful local Tool calls observed in this execution.
64        successful: u32,
65    },
66    /// The remaining shared Tool-call budget cannot satisfy the local minimum.
67    #[error(
68        "agent requires {required} successful local Tool calls but only {remaining} Tool calls remain in the shared budget"
69    )]
70    ToolRequirementExceedsBudget {
71        /// Additional successful local Tool calls still required.
72        required: u32,
73        /// Remaining shared Tool-call budget.
74        remaining: u64,
75    },
76    /// A tool produced output that policy forbids exposing to the model.
77    #[error("tool `{tool}` returned host-only output")]
78    ToolOutputNotVisible {
79        /// Tool name.
80        tool: String,
81    },
82}
runifold_agent/error.rs

runifold_agent/
error.rs
