agentstategraph-core 1.3.0

Core types and algorithms for AgentStateGraph — zero I/O dependencies
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
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146

//! Intent lifecycle state machine — enforces valid transitions.
//!
//! Proposed → Authorized → InProgress → Completed
//!                │                │ → Failed
//!                │                └─→ Blocked → InProgress
//!                └─→ (rejected)                     → Failed

use crate::intent::{IntentLifecycle, IntentStatus, Resolution};

/// Errors from lifecycle transitions.
#[derive(Debug, Clone, PartialEq, thiserror::Error)]
pub enum LifecycleError {
    #[error("invalid transition from {from:?} to {to:?}")]
    InvalidTransition {
        from: IntentStatus,
        to: IntentStatus,
    },
    #[error("resolution required to transition to {0:?}")]
    ResolutionRequired(IntentStatus),
}

/// Check if a lifecycle transition is valid.
pub fn is_valid_transition(from: &IntentStatus, to: &IntentStatus) -> bool {
    matches!(
        (from, to),
        (IntentStatus::Proposed, IntentStatus::Authorized)
            | (IntentStatus::Proposed, IntentStatus::InProgress) // skip auth for simple cases
            | (IntentStatus::Authorized, IntentStatus::InProgress)
            | (IntentStatus::InProgress, IntentStatus::Completed)
            | (IntentStatus::InProgress, IntentStatus::Failed)
            | (IntentStatus::InProgress, IntentStatus::Blocked)
            | (IntentStatus::Blocked, IntentStatus::InProgress)
            | (IntentStatus::Blocked, IntentStatus::Failed)
    )
}

/// Transition an intent lifecycle to a new status.
/// Validates the transition and enforces requirements (e.g., resolution for terminal states).
pub fn transition(
    lifecycle: &mut IntentLifecycle,
    to: IntentStatus,
    resolution: Option<Resolution>,
) -> Result<(), LifecycleError> {
    if !is_valid_transition(&lifecycle.status, &to) {
        return Err(LifecycleError::InvalidTransition {
            from: lifecycle.status.clone(),
            to,
        });
    }

    // Terminal states require a resolution
    match &to {
        IntentStatus::Completed | IntentStatus::Failed => {
            if resolution.is_none() && lifecycle.resolution.is_none() {
                return Err(LifecycleError::ResolutionRequired(to));
            }
            if let Some(res) = resolution {
                lifecycle.resolution = Some(res);
            }
        }
        _ => {}
    }

    lifecycle.status = to;
    Ok(())
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::intent::{Outcome, Resolution};

    fn test_lifecycle() -> IntentLifecycle {
        IntentLifecycle {
            status: IntentStatus::Proposed,
            assigned_to: vec![],
            resolution: None,
            notification: None,
        }
    }

    fn test_resolution() -> Resolution {
        Resolution {
            summary: "Done".to_string(),
            deviations: vec![],
            commits: vec![],
            branches_explored: vec![],
            outcome: Outcome::Fulfilled,
            confidence: 0.9,
        }
    }

    #[test]
    fn test_valid_happy_path() {
        let mut lc = test_lifecycle();
        assert!(transition(&mut lc, IntentStatus::Authorized, None).is_ok());
        assert!(transition(&mut lc, IntentStatus::InProgress, None).is_ok());
        assert!(transition(&mut lc, IntentStatus::Completed, Some(test_resolution())).is_ok());
        assert_eq!(lc.status, IntentStatus::Completed);
        assert!(lc.resolution.is_some());
    }

    #[test]
    fn test_skip_auth() {
        let mut lc = test_lifecycle();
        assert!(transition(&mut lc, IntentStatus::InProgress, None).is_ok());
    }

    #[test]
    fn test_blocked_and_resume() {
        let mut lc = test_lifecycle();
        transition(&mut lc, IntentStatus::InProgress, None).unwrap();
        transition(&mut lc, IntentStatus::Blocked, None).unwrap();
        transition(&mut lc, IntentStatus::InProgress, None).unwrap();
        assert_eq!(lc.status, IntentStatus::InProgress);
    }

    #[test]
    fn test_invalid_transition() {
        let mut lc = test_lifecycle();
        assert!(transition(&mut lc, IntentStatus::Completed, Some(test_resolution())).is_err());
    }

    #[test]
    fn test_completed_requires_resolution() {
        let mut lc = test_lifecycle();
        transition(&mut lc, IntentStatus::InProgress, None).unwrap();
        assert!(transition(&mut lc, IntentStatus::Completed, None).is_err());
    }

    #[test]
    fn test_failed_requires_resolution() {
        let mut lc = test_lifecycle();
        transition(&mut lc, IntentStatus::InProgress, None).unwrap();
        assert!(transition(&mut lc, IntentStatus::Failed, None).is_err());
    }

    #[test]
    fn test_cannot_go_backwards() {
        let mut lc = test_lifecycle();
        transition(&mut lc, IntentStatus::Authorized, None).unwrap();
        transition(&mut lc, IntentStatus::InProgress, None).unwrap();
        assert!(transition(&mut lc, IntentStatus::Proposed, None).is_err());
        assert!(transition(&mut lc, IntentStatus::Authorized, None).is_err());
    }
}