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    EditorCommentAdded,
119    EditorCommentResolved,
120    EditorProposalCreated,
121    EditorProposalAccepted,
122    EditorProposalRejected,
123    EditorCheckpointCreated,
124    EditorCheckpointRestored,
125    ProcessStarted,
126    ProcessOutput,
127    ProcessExited,
128    AgentPrompt,
129    AgentSteered,
130    AgentToolCalled,
131    AgentToolResult,
132    SourceRuntimeLinked,
133    VerificationCompleted,
134    DiagnosticsPublished,
135    SemanticBreakpointHit,
136    TestStarted,
137    TestCompleted,
138    HmrObserved,
139    ActorJoined,
140    ActorLeft,
141}
142
143#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
144#[serde(rename_all = "camelCase")]
145pub struct DevelopmentEvent {
146    pub schema_version: String,
147    pub id: String,
148    pub occurred_at_ms: u64,
149    pub actor: Actor,
150    pub kind: DevelopmentEventKind,
151    pub workspace: String,
152    #[serde(default)]
153    pub payload: Value,
154}
155
156#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
157#[serde(rename_all = "camelCase")]
158pub struct DevelopmentEventPage {
159    pub schema_version: String,
160    pub events: Vec<DevelopmentEvent>,
161    pub cursor: Option<String>,
162    pub oldest_id: Option<String>,
163    pub newest_id: Option<String>,
164    pub has_more: bool,
165    pub cursor_expired: bool,
166}
167
168impl DevelopmentEvent {
169    pub fn new(
170        actor: Actor,
171        kind: DevelopmentEventKind,
172        workspace: impl Into<String>,
173        payload: Value,
174        ordinal: u64,
175    ) -> Self {
176        let occurred_at_ms = SystemTime::now()
177            .duration_since(UNIX_EPOCH)
178            .map_or(0, |duration| duration.as_millis() as u64);
179        Self {
180            schema_version: DEVELOPMENT_SCHEMA_VERSION.into(),
181            id: format!("dev-{occurred_at_ms}-{ordinal}"),
182            occurred_at_ms,
183            actor,
184            kind,
185            workspace: workspace.into(),
186            payload,
187        }
188    }
189}
190
191#[derive(Debug)]
192pub struct Timeline {
193    path: PathBuf,
194    events: VecDeque<DevelopmentEvent>,
195    next_ordinal: u64,
196}
197
198impl Timeline {
199    pub fn for_project(root: &Path) -> DevelopmentResult<Self> {
200        use sha2::{Digest, Sha256};
201        let state_root = dirs::data_local_dir()
202            .or_else(dirs::cache_dir)
203            .unwrap_or_else(std::env::temp_dir)
204            .join("glass")
205            .join("development");
206        let digest = Sha256::digest(root.to_string_lossy().as_bytes());
207        let project_id = digest
208            .iter()
209            .map(|byte| format!("{byte:02x}"))
210            .collect::<String>();
211        Self::open(state_root.join(project_id).join("timeline.jsonl"))
212    }
213
214    pub fn open(path: impl Into<PathBuf>) -> DevelopmentResult<Self> {
215        let path = path.into();
216        let mut events = VecDeque::new();
217        if path.is_file() {
218            let file = fs::File::open(&path)?;
219            for line in BufReader::new(file).lines() {
220                let line = line?;
221                if line.len() > 64 * 1024 {
222                    continue;
223                }
224                if let Ok(event) = serde_json::from_str::<DevelopmentEvent>(&line) {
225                    if events.len() == MAX_TIMELINE_EVENTS {
226                        events.pop_front();
227                    }
228                    events.push_back(event);
229                }
230            }
231        }
232        Ok(Self {
233            path,
234            next_ordinal: events.len() as u64 + 1,
235            events,
236        })
237    }
238
239    pub fn path(&self) -> &Path {
240        &self.path
241    }
242
243    pub fn events(&self) -> impl DoubleEndedIterator<Item = &DevelopmentEvent> + ExactSizeIterator {
244        self.events.iter()
245    }
246
247    /// Return one bounded page after an opaque event ID. If compaction removed
248    /// the requested cursor, return the oldest retained page and mark the
249    /// cursor expired so a subscriber can report the gap instead of silently
250    /// claiming continuity.
251    pub fn events_after(&self, after_id: Option<&str>, limit: usize) -> DevelopmentEventPage {
252        let limit = limit.clamp(1, 256);
253        let start = match after_id {
254            Some(after_id) => self
255                .events
256                .iter()
257                .position(|event| event.id == after_id)
258                .map(|index| index.saturating_add(1)),
259            None => Some(0),
260        };
261        let cursor_expired = after_id.is_some() && start.is_none();
262        let start = start.unwrap_or(0);
263        let events = self
264            .events
265            .iter()
266            .skip(start)
267            .take(limit)
268            .cloned()
269            .collect::<Vec<_>>();
270        let has_more = self.events.len().saturating_sub(start) > events.len();
271        let cursor = events.last().map(|event| event.id.clone()).or_else(|| {
272            (!cursor_expired)
273                .then(|| after_id.map(str::to_string))
274                .flatten()
275        });
276        DevelopmentEventPage {
277            schema_version: DEVELOPMENT_SCHEMA_VERSION.into(),
278            events,
279            cursor,
280            oldest_id: self.events.front().map(|event| event.id.clone()),
281            newest_id: self.events.back().map(|event| event.id.clone()),
282            has_more,
283            cursor_expired,
284        }
285    }
286
287    pub fn record(
288        &mut self,
289        actor: Actor,
290        kind: DevelopmentEventKind,
291        workspace: impl Into<String>,
292        payload: Value,
293    ) -> DevelopmentResult<DevelopmentEvent> {
294        let event = DevelopmentEvent::new(actor, kind, workspace, payload, self.next_ordinal);
295        self.next_ordinal = self.next_ordinal.saturating_add(1);
296        if let Some(parent) = self.path.parent() {
297            fs::create_dir_all(parent)?;
298        }
299        if self.events.len() == MAX_TIMELINE_EVENTS {
300            self.events.pop_front();
301        }
302        self.events.push_back(event.clone());
303        self.persist_bounded()?;
304        Ok(event)
305    }
306
307    fn persist_bounded(&self) -> DevelopmentResult<()> {
308        let temporary = self.path.with_extension(format!(
309            "jsonl.tmp-{}-{}",
310            std::process::id(),
311            self.next_ordinal
312        ));
313        let mut file = OpenOptions::new()
314            .create_new(true)
315            .write(true)
316            .open(&temporary)?;
317        for event in &self.events {
318            serde_json::to_writer(&mut file, event)?;
319            file.write_all(b"\n")?;
320        }
321        file.sync_all()?;
322        if let Err(error) = fs::rename(&temporary, &self.path) {
323            let _ = fs::remove_file(&temporary);
324            return Err(error.into());
325        }
326        Ok(())
327    }
328}
329
330#[cfg(test)]
331mod tests {
332    use super::*;
333
334    #[test]
335    fn timeline_round_trips_bounded_events() {
336        let root = std::env::temp_dir().join(format!("glass-timeline-{}", std::process::id()));
337        let path = root.join("timeline.jsonl");
338        let _ = fs::remove_dir_all(&root);
339        let mut timeline = Timeline::open(&path).unwrap();
340        timeline
341            .record(
342                Actor::local(),
343                DevelopmentEventKind::WorkspaceOpened,
344                "/tmp/project",
345                serde_json::json!({"status":"ready"}),
346            )
347            .unwrap();
348        let reopened = Timeline::open(&path).unwrap();
349        assert_eq!(reopened.events().count(), 1);
350        assert_eq!(
351            reopened.events().next().unwrap().kind,
352            DevelopmentEventKind::WorkspaceOpened
353        );
354        let _ = fs::remove_dir_all(root);
355    }
356
357    #[test]
358    fn timeline_persists_only_the_newest_bounded_events() {
359        let root = std::env::temp_dir().join(format!("glass-timeline-cap-{}", std::process::id()));
360        let path = root.join("timeline.jsonl");
361        let _ = fs::remove_dir_all(&root);
362        let mut timeline = Timeline::open(&path).unwrap();
363        for ordinal in 0..MAX_TIMELINE_EVENTS + 3 {
364            timeline
365                .record(
366                    Actor::local(),
367                    DevelopmentEventKind::WorkspaceOpened,
368                    "/tmp/project",
369                    serde_json::json!({"ordinal": ordinal}),
370                )
371                .unwrap();
372        }
373        let reopened = Timeline::open(&path).unwrap();
374        assert_eq!(reopened.events().count(), MAX_TIMELINE_EVENTS);
375        assert_eq!(reopened.events().next().unwrap().payload["ordinal"], 3);
376        assert_eq!(
377            fs::read_to_string(path).unwrap().lines().count(),
378            MAX_TIMELINE_EVENTS
379        );
380        let _ = fs::remove_dir_all(root);
381    }
382
383    #[test]
384    fn event_pages_are_cursor_bounded_and_report_compaction_gaps() {
385        let root = std::env::temp_dir().join(format!("glass-event-page-{}", std::process::id()));
386        let path = root.join("timeline.jsonl");
387        let _ = fs::remove_dir_all(&root);
388        let mut timeline = Timeline::open(&path).unwrap();
389        for ordinal in 0..3 {
390            timeline
391                .record(
392                    Actor::local(),
393                    DevelopmentEventKind::WorkspaceOpened,
394                    "/tmp/project",
395                    serde_json::json!({"ordinal": ordinal}),
396                )
397                .unwrap();
398        }
399        let first = timeline.events_after(None, 2);
400        assert_eq!(first.events.len(), 2);
401        assert!(first.has_more);
402        assert!(!first.cursor_expired);
403        let second = timeline.events_after(first.cursor.as_deref(), 2);
404        assert_eq!(second.events.len(), 1);
405        assert_eq!(second.events[0].payload["ordinal"], 2);
406        assert!(!second.has_more);
407        let expired = timeline.events_after(Some("dev-expired"), 1);
408        assert!(expired.cursor_expired);
409        assert_eq!(expired.events[0].payload["ordinal"], 0);
410        let empty = Timeline::open(root.join("empty.jsonl")).unwrap();
411        let empty_expired = empty.events_after(Some("dev-expired"), 1);
412        assert!(empty_expired.cursor_expired);
413        assert_eq!(empty_expired.cursor, None);
414        let _ = fs::remove_dir_all(root);
415    }
416}