zagens-cli 0.8.3

Zagens headless CLI + HTTP/SSE runtime sidecar (`zagens`, `zagens-runtime` binaries)
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

//! Turn-end replay coherence + optional SQLite persist verify.

use std::time::Duration;

use tracing::warn;
use zagens_core::engine::kernel_event::KernelEvent;
use zagens_core::engine::turn_machine::{LiveTurnSnapshot, verify_turn_replay_coherence};
use zagens_runtime_adapters::persist::KernelEventWriter;

pub struct KernelTurnReplayVerify {
    enabled: bool,
}

impl KernelTurnReplayVerify {
    pub fn new(enabled: bool) -> Self {
        Self { enabled }
    }

    /// In-memory replay gate (sync — called at turn end from `run.rs`).
    pub fn verify_turn_in_memory(&self, events: &[KernelEvent], live: &LiveTurnSnapshot) {
        if !self.enabled {
            return;
        }
        if let Some(summary) = verify_turn_replay_coherence(events, Some(live)) {
            warn!(
                target: "kernel_turn_replay",
                turn_id = %live.turn_id,
                summary,
                "turn replay coherence diff"
            );
        }
    }

    /// SQLite round-trip check (async — drain task may lag slightly behind turn end).
    pub async fn verify_turn_persisted(
        &self,
        writer: &KernelEventWriter,
        turn_id: &str,
        in_memory: &[KernelEvent],
    ) {
        if !self.enabled {
            return;
        }
        tokio::time::sleep(Duration::from_millis(50)).await;
        if let Some(summary) = writer.verify_persisted_turn_matches(turn_id, in_memory) {
            warn!(
                target: "kernel_turn_replay",
                turn_id,
                summary,
                "persisted replay diff"
            );
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use zagens_core::engine::kernel_event::TurnOutcome;
    use zagens_core::turn::TurnLoopMode;

    #[test]
    fn verify_turn_in_memory_passes_minimal_turn() {
        let events = vec![
            KernelEvent::TurnStarted {
                turn_id: "t1".into(),
                mode: TurnLoopMode::Agent,
                input_text: "hi".into(),
                max_steps: 5,
            },
            KernelEvent::TurnEnded {
                turn_id: "t1".into(),
                outcome: TurnOutcome::Completed,
                total_steps: 1,
            },
        ];
        let live = LiveTurnSnapshot {
            turn_id: "t1".into(),
            max_steps: 5,
            ..Default::default()
        };
        let verify = KernelTurnReplayVerify::new(true);
        verify.verify_turn_in_memory(&events, &live);
    }
}