zeph_subagent/
error.rs

1// SPDX-FileCopyrightText: 2026 Andrei G <bug-ops>
2// SPDX-License-Identifier: MIT OR Apache-2.0
3
4/// All errors that can arise during sub-agent lifecycle operations.
5///
6/// [`SubAgentError`] is the single error type for the entire `zeph-subagent` crate.
7/// Every fallible public function returns `Result<_, SubAgentError>`.
8///
9/// # Examples
10///
11/// ```rust
12/// use zeph_subagent::{SubAgentDef, SubAgentError};
13///
14/// let err = SubAgentDef::parse("missing frontmatter").unwrap_err();
15/// assert!(matches!(err, SubAgentError::Parse { .. }));
16/// ```
17#[derive(Debug, thiserror::Error)]
18pub enum SubAgentError {
19    /// Frontmatter parsing failed (malformed YAML/TOML or missing delimiters).
20    #[error("parse error in {path}: {reason}")]
21    Parse { path: String, reason: String },
22
23    /// Definition semantics are invalid (e.g. empty name, conflicting tool policies).
24    #[error("invalid definition: {0}")]
25    Invalid(String),
26
27    /// No definition or running agent with the requested name or ID was found.
28    #[error("agent not found: {0}")]
29    NotFound(String),
30
31    /// The background task could not be spawned (OS or tokio error).
32    #[error("spawn failed: {0}")]
33    Spawn(String),
34
35    /// The manager's concurrency limit is exhausted; no new agents can be spawned.
36    #[error("concurrency limit reached (active: {active}, max: {max})")]
37    ConcurrencyLimit { active: usize, max: usize },
38
39    /// The agent loop was cancelled via its [`tokio_util::sync::CancellationToken`].
40    #[error("cancelled")]
41    Cancelled,
42
43    /// A slash-command string (`/agent`, `/agents`) could not be parsed.
44    #[error("invalid command: {0}")]
45    InvalidCommand(String),
46
47    /// An I/O operation on a transcript file failed.
48    #[error("transcript error: {0}")]
49    Transcript(String),
50
51    /// An ID prefix matched more than one transcript; provide a longer prefix.
52    #[error("ambiguous id prefix '{0}': matches {1} agents")]
53    AmbiguousId(String, usize),
54
55    /// Resume was requested for an agent that is still running.
56    #[error("agent '{0}' is still running; cancel it first or wait for completion")]
57    StillRunning(String),
58
59    /// A memory directory could not be created or resolved.
60    #[error("memory error for agent '{name}': {reason}")]
61    Memory { name: String, reason: String },
62
63    /// A filesystem I/O error unrelated to transcripts.
64    #[error("I/O error at {path}: {reason}")]
65    Io { path: String, reason: String },
66
67    /// The underlying LLM provider returned an error during the agent loop.
68    #[error("LLM call failed: {0}")]
69    Llm(String),
70
71    /// A channel send (status watch, secret approval) failed.
72    #[error("channel send failed: {0}")]
73    Channel(String),
74
75    /// The tokio task panicked and the join handle propagated the panic.
76    #[error("task panicked: {0}")]
77    TaskPanic(String),
78
79    /// The recursion depth for nested sub-agent spawning exceeded the configured limit.
80    #[error("max spawn depth exceeded (depth: {depth}, max: {max})")]
81    MaxDepthExceeded { depth: u32, max: u32 },
82}
zeph_subagent/error.rs

zeph_subagent/
error.rs
