rightkit-agent-engine-protocol 0.1.0

Agent engine protocol: events, envelopes, tool calls, trust wrapping and settlement types shared by agent hosts
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

use super::ProtocolEvent;

/// Whether an event is canonical replay truth or an ephemeral live projection.
/// Durable facts belong in SQLite and must survive reconnect/replay. Live
/// projections may be dropped/reordered without changing settled session truth.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum EventDurability {
    DurableFact,
    LiveProjection,
}

impl ProtocolEvent {
    /// Conservative classification: only events that are unambiguously
    /// presentation/control projections are non-durable. New variants default
    /// to durable by virtue of the explicit catch-all arm.
    pub fn durability(&self) -> EventDurability {
        match self {
            Self::AssistantDelta { .. }
            | Self::ToolOutputDelta { .. }
            | Self::StreamResyncRequired { .. }
            | Self::PersistenceFailed { .. } => EventDurability::LiveProjection,
            _ => EventDurability::DurableFact,
        }
    }

    pub fn is_durable_fact(&self) -> bool {
        self.durability() == EventDurability::DurableFact
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::TranscriptMessage;

    #[test]
    fn token_delta_and_resync_are_live_projections() {
        assert_eq!(
            ProtocolEvent::AssistantDelta {
                session_id: "s".into(),
                seq: 1,
                created_at: "t".into(),
                text: "x".into(),
                is_reasoning: false,
            }
            .durability(),
            EventDurability::LiveProjection
        );
        assert_eq!(
            ProtocolEvent::StreamResyncRequired {
                session_id: "s".into(),
                seq: 2,
                created_at: "t".into(),
                after_seq: 0,
                oldest_available_seq: 1,
                high_water_mark: 1,
            }
            .durability(),
            EventDurability::LiveProjection
        );
    }

    #[test]
    fn persistence_failed_is_live_only() {
        let event = ProtocolEvent::PersistenceFailed {
            session_id: "s".into(),
            seq: 0,
            created_at: "t".into(),
            reason: "disk full".into(),
        };
        assert_eq!(event.durability(), EventDurability::LiveProjection);
        assert!(!event.is_durable_fact());
    }

    #[test]
    fn settled_assistant_message_is_durable_truth() {
        let message = TranscriptMessage::Assistant {
            id: "m".into(),
            created_at: "t".into(),
            content: "done".into(),
            reasoning_content: None,
            tool_calls: Vec::new(),
            pinned: false,
        };
        assert!(ProtocolEvent::AssistantMessageCompleted {
            session_id: "s".into(),
            seq: 3,
            created_at: "t".into(),
            message,
        }
        .is_durable_fact());
    }
}