zeph-orchestration 0.19.0

Task orchestration: DAG execution, failure propagation, and persistence for Zeph
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101

// SPDX-FileCopyrightText: 2026 Andrei G <bug-ops>
// SPDX-License-Identifier: MIT OR Apache-2.0

use zeph_subagent::SubAgentError;

/// All error variants produced by the orchestration subsystem.
///
/// Variants are exhaustive — callers that match on this type should use a
/// `_ => …` arm to stay robust against future additions.
///
/// # Fail-open policy
///
/// LLM-backed steps (verification, replan) are always fail-open: on failure
/// they log a warning and continue rather than returning an error. Only
/// structural invariant violations and hard configuration errors propagate as
/// `Err`.
///
/// # Examples
///
/// ```rust
/// use zeph_orchestration::OrchestrationError;
///
/// fn describe(err: &OrchestrationError) -> &'static str {
///     match err {
///         OrchestrationError::CycleDetected => "graph has a cycle",
///         OrchestrationError::Disabled => "orchestration is off",
///         _ => "other orchestration error",
///     }
/// }
///
/// let err = OrchestrationError::CycleDetected;
/// assert_eq!(describe(&err), "graph has a cycle");
/// ```
#[derive(Debug, thiserror::Error)]
pub enum OrchestrationError {
    /// Orchestration is disabled in configuration.
    #[error("orchestration is disabled")]
    Disabled,

    /// The LLM planner failed to produce a valid task graph.
    #[error("planning failed: {0}")]
    PlanningFailed(String),

    /// The task graph structure is invalid (e.g. wrong task-id invariant, bad reference).
    #[error("invalid graph: {0}")]
    InvalidGraph(String),

    /// A cycle was detected during topological sort of the task graph.
    #[error("cycle detected in task graph")]
    CycleDetected,

    /// A `TaskId` or task title lookup yielded no result.
    #[error("task not found: {0}")]
    TaskNotFound(String),

    /// No agent in the available pool can be routed to a task.
    #[error("no agent available for task: {0}")]
    NoAgentAvailable(String),

    /// A `GraphId` could not be found in persistence.
    #[error("graph not found: {0}")]
    GraphNotFound(String),

    /// An internal scheduler invariant was violated.
    #[error("scheduler error: {0}")]
    Scheduler(String),

    /// Result aggregation failed and the fallback path also failed.
    #[error("aggregation failed: {0}")]
    AggregationFailed(String),

    /// A database read/write or serialization error in graph persistence.
    #[error("persistence error: {0}")]
    Persistence(String),

    /// A task exceeded its per-task wall-clock timeout.
    #[error("task timed out: {0}")]
    TaskTimeout(String),

    /// The scheduler or a task was canceled by the caller.
    #[error("canceled")]
    Canceled,

    /// A `/plan` CLI command could not be parsed.
    #[error("invalid command: {0}")]
    InvalidCommand(String),

    /// Hard invariant violation during verification (e.g. cycle detected after `inject_tasks`).
    ///
    /// Never used for LLM call failures — those are fail-open and only log a warning.
    #[error("verification failed: {0}")]
    VerificationFailed(String),

    /// A required configuration value is missing or out of range.
    #[error("invalid configuration: {0}")]
    InvalidConfig(String),

    /// Propagated error from a sub-agent execution.
    #[error(transparent)]
    SubAgent(#[from] SubAgentError),
}