Skip to main content

glass_dev/development/
events.rs

1use super::{DEVELOPMENT_SCHEMA_VERSION, DevelopmentResult, MAX_TIMELINE_EVENTS};
2use serde::{Deserialize, Serialize};
3use serde_json::Value;
4use std::{
5    collections::VecDeque,
6    fs::{self, OpenOptions},
7    io::{BufRead, BufReader, Write},
8    path::{Path, PathBuf},
9    time::{SystemTime, UNIX_EPOCH},
10};
11
12#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
13#[serde(rename_all = "camelCase")]
14pub enum ActorKind {
15    Human,
16    EmbeddedAgent,
17    ExternalAgent,
18    System,
19    Observer,
20}
21
22#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
23#[serde(rename_all = "camelCase")]
24pub struct Actor {
25    pub id: String,
26    pub kind: ActorKind,
27    pub name: String,
28    #[serde(default = "default_session")]
29    pub session: String,
30    #[serde(default)]
31    pub capabilities: Vec<String>,
32    #[serde(default)]
33    pub authority: ActorAuthority,
34    #[serde(default)]
35    pub connection: ActorConnection,
36}
37
38#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq, Eq)]
39#[serde(rename_all = "camelCase")]
40pub enum ActorAuthority {
41    Owner,
42    Mutate,
43    #[default]
44    ReadOnly,
45    System,
46}
47
48#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq, Eq)]
49#[serde(rename_all = "camelCase")]
50pub enum ActorConnection {
51    Local,
52    Embedded,
53    Cli,
54    Mcp,
55    Daemon,
56    #[default]
57    Disconnected,
58}
59
60fn default_session() -> String {
61    "legacy".into()
62}
63
64impl Actor {
65    pub fn local() -> Self {
66        Self {
67            id: "human:local".into(),
68            kind: ActorKind::Human,
69            name: "Human".into(),
70            session: "local".into(),
71            capabilities: vec!["read".into(), "mutate".into(), "approve".into()],
72            authority: ActorAuthority::Owner,
73            connection: ActorConnection::Local,
74        }
75    }
76
77    pub fn embedded() -> Self {
78        Self {
79            id: "embedded:glass-agent".into(),
80            kind: ActorKind::EmbeddedAgent,
81            name: "Glass Agent".into(),
82            session: "embedded".into(),
83            capabilities: vec!["read".into(), "tool.call".into()],
84            authority: ActorAuthority::Mutate,
85            connection: ActorConnection::Embedded,
86        }
87    }
88
89    pub fn external(name: &str) -> Self {
90        let normalized = name
91            .chars()
92            .filter(|character| character.is_ascii_alphanumeric() || "-_.".contains(*character))
93            .take(64)
94            .collect::<String>();
95        let name = if normalized.is_empty() {
96            "external".to_string()
97        } else {
98            normalized
99        };
100        Self {
101            id: format!("external:{name}"),
102            kind: ActorKind::ExternalAgent,
103            name,
104            session: "external".into(),
105            capabilities: vec!["read".into(), "structured".into()],
106            authority: ActorAuthority::ReadOnly,
107            connection: ActorConnection::Cli,
108        }
109    }
110}
111
112#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
113#[serde(rename_all = "camelCase")]
114pub enum DevelopmentEventKind {
115    WorkspaceOpened,
116    FileOpened,
117    FileSaved,
118    ProcessStarted,
119    ProcessOutput,
120    ProcessExited,
121    AgentPrompt,
122    AgentSteered,
123    AgentToolCalled,
124    AgentToolResult,
125    SourceRuntimeLinked,
126    VerificationCompleted,
127    DiagnosticsPublished,
128    SemanticBreakpointHit,
129    TestStarted,
130    TestCompleted,
131    HmrObserved,
132    ActorJoined,
133    ActorLeft,
134}
135
136#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
137#[serde(rename_all = "camelCase")]
138pub struct DevelopmentEvent {
139    pub schema_version: String,
140    pub id: String,
141    pub occurred_at_ms: u64,
142    pub actor: Actor,
143    pub kind: DevelopmentEventKind,
144    pub workspace: String,
145    #[serde(default)]
146    pub payload: Value,
147}
148
149#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
150#[serde(rename_all = "camelCase")]
151pub struct DevelopmentEventPage {
152    pub schema_version: String,
153    pub events: Vec<DevelopmentEvent>,
154    pub cursor: Option<String>,
155    pub oldest_id: Option<String>,
156    pub newest_id: Option<String>,
157    pub has_more: bool,
158    pub cursor_expired: bool,
159}
160
161impl DevelopmentEvent {
162    pub fn new(
163        actor: Actor,
164        kind: DevelopmentEventKind,
165        workspace: impl Into<String>,
166        payload: Value,
167        ordinal: u64,
168    ) -> Self {
169        let occurred_at_ms = SystemTime::now()
170            .duration_since(UNIX_EPOCH)
171            .map_or(0, |duration| duration.as_millis() as u64);
172        Self {
173            schema_version: DEVELOPMENT_SCHEMA_VERSION.into(),
174            id: format!("dev-{occurred_at_ms}-{ordinal}"),
175            occurred_at_ms,
176            actor,
177            kind,
178            workspace: workspace.into(),
179            payload,
180        }
181    }
182}
183
184#[derive(Debug)]
185pub struct Timeline {
186    path: PathBuf,
187    events: VecDeque<DevelopmentEvent>,
188    next_ordinal: u64,
189}
190
191impl Timeline {
192    pub fn for_project(root: &Path) -> DevelopmentResult<Self> {
193        use sha2::{Digest, Sha256};
194        let state_root = dirs::data_local_dir()
195            .or_else(dirs::cache_dir)
196            .unwrap_or_else(std::env::temp_dir)
197            .join("glass")
198            .join("development");
199        let digest = Sha256::digest(root.to_string_lossy().as_bytes());
200        let project_id = digest
201            .iter()
202            .map(|byte| format!("{byte:02x}"))
203            .collect::<String>();
204        Self::open(state_root.join(project_id).join("timeline.jsonl"))
205    }
206
207    pub fn open(path: impl Into<PathBuf>) -> DevelopmentResult<Self> {
208        let path = path.into();
209        let mut events = VecDeque::new();
210        if path.is_file() {
211            let file = fs::File::open(&path)?;
212            for line in BufReader::new(file).lines() {
213                let line = line?;
214                if line.len() > 64 * 1024 {
215                    continue;
216                }
217                if let Ok(event) = serde_json::from_str::<DevelopmentEvent>(&line) {
218                    if events.len() == MAX_TIMELINE_EVENTS {
219                        events.pop_front();
220                    }
221                    events.push_back(event);
222                }
223            }
224        }
225        Ok(Self {
226            path,
227            next_ordinal: events.len() as u64 + 1,
228            events,
229        })
230    }
231
232    pub fn path(&self) -> &Path {
233        &self.path
234    }
235
236    pub fn events(&self) -> impl DoubleEndedIterator<Item = &DevelopmentEvent> + ExactSizeIterator {
237        self.events.iter()
238    }
239
240    /// Return one bounded page after an opaque event ID. If compaction removed
241    /// the requested cursor, return the oldest retained page and mark the
242    /// cursor expired so a subscriber can report the gap instead of silently
243    /// claiming continuity.
244    pub fn events_after(&self, after_id: Option<&str>, limit: usize) -> DevelopmentEventPage {
245        let limit = limit.clamp(1, 256);
246        let start = match after_id {
247            Some(after_id) => self
248                .events
249                .iter()
250                .position(|event| event.id == after_id)
251                .map(|index| index.saturating_add(1)),
252            None => Some(0),
253        };
254        let cursor_expired = after_id.is_some() && start.is_none();
255        let start = start.unwrap_or(0);
256        let events = self
257            .events
258            .iter()
259            .skip(start)
260            .take(limit)
261            .cloned()
262            .collect::<Vec<_>>();
263        let has_more = self.events.len().saturating_sub(start) > events.len();
264        let cursor = events.last().map(|event| event.id.clone()).or_else(|| {
265            (!cursor_expired)
266                .then(|| after_id.map(str::to_string))
267                .flatten()
268        });
269        DevelopmentEventPage {
270            schema_version: DEVELOPMENT_SCHEMA_VERSION.into(),
271            events,
272            cursor,
273            oldest_id: self.events.front().map(|event| event.id.clone()),
274            newest_id: self.events.back().map(|event| event.id.clone()),
275            has_more,
276            cursor_expired,
277        }
278    }
279
280    pub fn record(
281        &mut self,
282        actor: Actor,
283        kind: DevelopmentEventKind,
284        workspace: impl Into<String>,
285        payload: Value,
286    ) -> DevelopmentResult<DevelopmentEvent> {
287        let event = DevelopmentEvent::new(actor, kind, workspace, payload, self.next_ordinal);
288        self.next_ordinal = self.next_ordinal.saturating_add(1);
289        if let Some(parent) = self.path.parent() {
290            fs::create_dir_all(parent)?;
291        }
292        if self.events.len() == MAX_TIMELINE_EVENTS {
293            self.events.pop_front();
294        }
295        self.events.push_back(event.clone());
296        self.persist_bounded()?;
297        Ok(event)
298    }
299
300    fn persist_bounded(&self) -> DevelopmentResult<()> {
301        let temporary = self.path.with_extension(format!(
302            "jsonl.tmp-{}-{}",
303            std::process::id(),
304            self.next_ordinal
305        ));
306        let mut file = OpenOptions::new()
307            .create_new(true)
308            .write(true)
309            .open(&temporary)?;
310        for event in &self.events {
311            serde_json::to_writer(&mut file, event)?;
312            file.write_all(b"\n")?;
313        }
314        file.sync_all()?;
315        if let Err(error) = fs::rename(&temporary, &self.path) {
316            let _ = fs::remove_file(&temporary);
317            return Err(error.into());
318        }
319        Ok(())
320    }
321}
322
323#[cfg(test)]
324mod tests {
325    use super::*;
326
327    #[test]
328    fn timeline_round_trips_bounded_events() {
329        let root = std::env::temp_dir().join(format!("glass-timeline-{}", std::process::id()));
330        let path = root.join("timeline.jsonl");
331        let _ = fs::remove_dir_all(&root);
332        let mut timeline = Timeline::open(&path).unwrap();
333        timeline
334            .record(
335                Actor::local(),
336                DevelopmentEventKind::WorkspaceOpened,
337                "/tmp/project",
338                serde_json::json!({"status":"ready"}),
339            )
340            .unwrap();
341        let reopened = Timeline::open(&path).unwrap();
342        assert_eq!(reopened.events().count(), 1);
343        assert_eq!(
344            reopened.events().next().unwrap().kind,
345            DevelopmentEventKind::WorkspaceOpened
346        );
347        let _ = fs::remove_dir_all(root);
348    }
349
350    #[test]
351    fn timeline_persists_only_the_newest_bounded_events() {
352        let root = std::env::temp_dir().join(format!("glass-timeline-cap-{}", std::process::id()));
353        let path = root.join("timeline.jsonl");
354        let _ = fs::remove_dir_all(&root);
355        let mut timeline = Timeline::open(&path).unwrap();
356        for ordinal in 0..MAX_TIMELINE_EVENTS + 3 {
357            timeline
358                .record(
359                    Actor::local(),
360                    DevelopmentEventKind::WorkspaceOpened,
361                    "/tmp/project",
362                    serde_json::json!({"ordinal": ordinal}),
363                )
364                .unwrap();
365        }
366        let reopened = Timeline::open(&path).unwrap();
367        assert_eq!(reopened.events().count(), MAX_TIMELINE_EVENTS);
368        assert_eq!(reopened.events().next().unwrap().payload["ordinal"], 3);
369        assert_eq!(
370            fs::read_to_string(path).unwrap().lines().count(),
371            MAX_TIMELINE_EVENTS
372        );
373        let _ = fs::remove_dir_all(root);
374    }
375
376    #[test]
377    fn event_pages_are_cursor_bounded_and_report_compaction_gaps() {
378        let root = std::env::temp_dir().join(format!("glass-event-page-{}", std::process::id()));
379        let path = root.join("timeline.jsonl");
380        let _ = fs::remove_dir_all(&root);
381        let mut timeline = Timeline::open(&path).unwrap();
382        for ordinal in 0..3 {
383            timeline
384                .record(
385                    Actor::local(),
386                    DevelopmentEventKind::WorkspaceOpened,
387                    "/tmp/project",
388                    serde_json::json!({"ordinal": ordinal}),
389                )
390                .unwrap();
391        }
392        let first = timeline.events_after(None, 2);
393        assert_eq!(first.events.len(), 2);
394        assert!(first.has_more);
395        assert!(!first.cursor_expired);
396        let second = timeline.events_after(first.cursor.as_deref(), 2);
397        assert_eq!(second.events.len(), 1);
398        assert_eq!(second.events[0].payload["ordinal"], 2);
399        assert!(!second.has_more);
400        let expired = timeline.events_after(Some("dev-expired"), 1);
401        assert!(expired.cursor_expired);
402        assert_eq!(expired.events[0].payload["ordinal"], 0);
403        let empty = Timeline::open(root.join("empty.jsonl")).unwrap();
404        let empty_expired = empty.events_after(Some("dev-expired"), 1);
405        assert!(empty_expired.cursor_expired);
406        assert_eq!(empty_expired.cursor, None);
407        let _ = fs::remove_dir_all(root);
408    }
409}