aegis-agent-core 1.0.1

Core engine for the Aegis cognitive agent runtime
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

use anyhow::{anyhow, Result};
use serde::{Deserialize, Serialize};
use serde_json::Value;
use std::time::SystemTime;

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub enum DispatchStatus {
    Pending,
    Notified,
    Delivered,
    Failed,
}

impl std::fmt::Display for DispatchStatus {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            DispatchStatus::Pending => write!(f, "Pending"),
            DispatchStatus::Notified => write!(f, "Notified"),
            DispatchStatus::Delivered => write!(f, "Delivered"),
            DispatchStatus::Failed => write!(f, "Failed"),
        }
    }
}

/// A single dispatch item with strict state-machine transitions.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct DispatchRecord {
    pub id: String,
    pub payload: Value,
    pub status: DispatchStatus,
    pub created_at: u64,
    pub updated_at: u64,
    pub failure_reason: Option<String>,
}

impl DispatchRecord {
    /// Create a new dispatch record in Pending status.
    pub fn new(id: impl Into<String>, payload: Value) -> Self {
        let now = SystemTime::now()
            .duration_since(SystemTime::UNIX_EPOCH)
            .unwrap_or_default()
            .as_secs();
        Self {
            id: id.into(),
            payload,
            status: DispatchStatus::Pending,
            created_at: now,
            updated_at: now,
            failure_reason: None,
        }
    }

    /// Strict state transitions:
    ///   Pending -> Notified | Failed
    ///   Notified -> Delivered | Failed
    pub fn transition(&mut self, to: DispatchStatus, reason: Option<String>) -> Result<()> {
        let valid = matches!(
            (&self.status, &to),
            (DispatchStatus::Pending, DispatchStatus::Notified)
                | (DispatchStatus::Pending, DispatchStatus::Failed)
                | (DispatchStatus::Notified, DispatchStatus::Delivered)
                | (DispatchStatus::Notified, DispatchStatus::Failed)
        );
        if !valid {
            return Err(anyhow!(
                "invalid dispatch transition: {} -> {}",
                self.status,
                to
            ));
        }
        if matches!(to, DispatchStatus::Failed) {
            self.failure_reason = reason;
        }
        self.updated_at = SystemTime::now()
            .duration_since(SystemTime::UNIX_EPOCH)
            .unwrap_or_default()
            .as_secs();
        self.status = to;
        Ok(())
    }

    /// Returns true if the dispatch is in a terminal state (Delivered or Failed).
    pub fn is_terminal(&self) -> bool {
        matches!(
            self.status,
            DispatchStatus::Delivered | DispatchStatus::Failed
        )
    }
}

/// Mailbox message between workers
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct MailboxRecord {
    pub id: String,
    pub from: String,
    pub to: String,
    pub content: Value,
    pub delivered: bool,
    pub created_at: u64,
}

impl MailboxRecord {
    /// Create a new undelivered mailbox message between workers.
    pub fn new(id: impl Into<String>, from: impl Into<String>, to: impl Into<String>, content: Value) -> Self {
        let now = SystemTime::now()
            .duration_since(SystemTime::UNIX_EPOCH)
            .unwrap_or_default()
            .as_secs();
        Self {
            id: id.into(),
            from: from.into(),
            to: to.into(),
            content,
            delivered: false,
            created_at: now,
        }
    }
}