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 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}