Skip to main content

session_activity/
store.rs

1use std::fs::{self, OpenOptions};
2use std::io::{Read, Write};
3use std::path::{Path, PathBuf};
4use std::sync::atomic::{AtomicU64, Ordering};
5use std::time::{SystemTime, UNIX_EPOCH};
6
7use anyhow::{Context, Result, ensure};
8
9use crate::{Agent, FileEvent, SessionKey};
10
11pub(crate) const MAX_BATCH_BYTES: u64 = 16 * 1024 * 1024;
12
13#[derive(Debug, Default)]
14pub struct ReadReport {
15    pub events: Vec<FileEvent>,
16    pub warnings: Vec<BatchWarning>,
17}
18
19#[derive(Debug, Default)]
20pub struct SessionReport {
21    pub sessions: Vec<SessionKey>,
22    pub warnings: Vec<BatchWarning>,
23}
24
25#[derive(Debug)]
26pub struct BatchWarning {
27    pub path: PathBuf,
28    pub message: String,
29}
30
31static NEXT_BATCH: AtomicU64 = AtomicU64::new(0);
32
33/// An append-only store of metadata-only batches, namespaced by agent/session.
34/// Each hook writes its own batch then renames it atomically. Concurrent hooks
35/// cannot overwrite each other, and readers never see a partially written batch.
36#[derive(Clone, Debug)]
37pub struct Store {
38    root: PathBuf,
39}
40
41impl Store {
42    pub fn new(root: impl Into<PathBuf>) -> Self {
43        Self { root: root.into() }
44    }
45
46    pub(crate) fn directory(&self, session: &SessionKey) -> Result<PathBuf> {
47        session.validate()?;
48        Ok(self.root.join(session.agent.slug()).join(&session.session_id))
49    }
50
51    /// Enumerate retained session directories, including ended/compacted sessions.
52    /// Does not create state or follow namespace/session directory symlinks.
53    pub fn sessions(&self) -> SessionReport {
54        let mut report = SessionReport::default();
55        for agent in [Agent::Claude, Agent::Codex] {
56            let path = self.root.join(agent.slug());
57            let entries = (|| -> Result<Option<fs::ReadDir>> {
58                let metadata = match fs::symlink_metadata(&path) {
59                    Ok(metadata) => metadata,
60                    Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(None),
61                    Err(e) => return Err(e.into()),
62                };
63                ensure!(metadata.is_dir(), "agent namespace must be a directory, not a symlink");
64                Ok(Some(fs::read_dir(&path)?))
65            })();
66            let entries = match entries {
67                Ok(Some(entries)) => entries,
68                Ok(None) => continue,
69                Err(error) => {
70                    report.warnings.push(BatchWarning { path, message: format!("{error:#}") });
71                    continue;
72                }
73            };
74            for entry in entries {
75                let entry = match entry {
76                    Ok(entry) => entry,
77                    Err(error) => {
78                        report.warnings.push(BatchWarning { path: path.clone(), message: error.to_string() });
79                        continue;
80                    }
81                };
82                let result = (|| -> Result<Option<SessionKey>> {
83                    let kind = entry.file_type()?;
84                    ensure!(!kind.is_symlink(), "session directory symlinks are not followed");
85                    if !kind.is_dir() {
86                        return Ok(None);
87                    }
88                    let session_id = entry
89                        .file_name()
90                        .into_string()
91                        .map_err(|_| anyhow::anyhow!("invalid session directory name"))?;
92                    let key = SessionKey { agent, session_id };
93                    key.validate()?;
94                    Ok(Some(key))
95                })();
96                match result {
97                    Ok(Some(key)) => report.sessions.push(key),
98                    Ok(None) => {}
99                    Err(error) => {
100                        report.warnings.push(BatchWarning { path: entry.path(), message: format!("{error:#}") })
101                    }
102                }
103            }
104        }
105        report
106            .sessions
107            .sort_by(|a, b| a.agent.slug().cmp(b.agent.slug()).then_with(|| a.session_id.cmp(&b.session_id)));
108        report
109    }
110
111    /// Read retained history across agents/sessions. Per-session failures become
112    /// warnings so one damaged checkpoint cannot hide other sessions. This is
113    /// not a globally atomic snapshot; each session is read under its own lock.
114    pub fn read_all(&self) -> ReadReport {
115        let sessions = self.sessions();
116        let mut report = ReadReport { events: Vec::new(), warnings: sessions.warnings };
117        for key in sessions.sessions {
118            match self.read(&key) {
119                Ok(mut read) => {
120                    report.events.append(&mut read.events);
121                    report.warnings.append(&mut read.warnings);
122                }
123                Err(error) => report.warnings.push(BatchWarning {
124                    path: self.root.join(key.agent.slug()).join(&key.session_id),
125                    message: format!("{error:#}"),
126                }),
127            }
128        }
129        report.events.sort_by_key(|e| e.timestamp);
130        report
131    }
132
133    pub fn append(&self, session: &SessionKey, events: &[FileEvent]) -> Result<()> {
134        let Some(dir) = self.prepare(session, events)? else { return Ok(()) };
135        let _lock = crate::lock::Lock::acquire(&dir, false)?;
136        self.append_unlocked(&dir, events)
137    }
138
139    /// Append the events not already retained, and return how many. Captures
140    /// repeat evidence, such as a transcript parsed at every turn; this keeps
141    /// one copy. `concurrent` is not part of an event's identity, and the read
142    /// and append happen under one exclusive lock.
143    pub fn append_new(&self, session: &SessionKey, events: &[FileEvent]) -> Result<usize> {
144        let Some(dir) = self.prepare(session, events)? else { return Ok(0) };
145        let _lock = crate::lock::Lock::acquire(&dir, true)?;
146        let report = self.read_unlocked(session)?;
147        let mut seen: std::collections::HashSet<_> = report.events.iter().map(identity).collect();
148        let fresh: Vec<_> = events.iter().filter(|e| seen.insert(identity(e))).cloned().collect();
149        self.append_unlocked(&dir, &fresh)?;
150        Ok(fresh.len())
151    }
152
153    fn prepare(&self, session: &SessionKey, events: &[FileEvent]) -> Result<Option<PathBuf>> {
154        let dir = self.directory(session)?;
155        if events.is_empty() {
156            return Ok(None);
157        }
158        validate_batch(session, events)?;
159        let missing: Vec<_> =
160            dir.ancestors().take_while(|p| !p.as_os_str().is_empty() && !p.exists()).map(Path::to_path_buf).collect();
161        let mut builder = fs::DirBuilder::new();
162        builder.recursive(true);
163        #[cfg(unix)]
164        {
165            use std::os::unix::fs::DirBuilderExt;
166            builder.mode(0o700);
167        }
168        builder.create(&dir)?;
169        // Persist newly created directory links as well as the final batch.
170        for path in missing {
171            sync_directory(&path)?;
172            if let Some(parent) = path.parent() {
173                sync_directory(if parent.as_os_str().is_empty() { Path::new(".") } else { parent })?;
174            }
175        }
176        Ok(Some(dir))
177    }
178
179    fn append_unlocked(&self, dir: &Path, events: &[FileEvent]) -> Result<()> {
180        let cutoff = crate::maintenance::retained_from(dir)?;
181        let retained: Vec<_> = events.iter().filter(|e| cutoff.is_none_or(|at| e.timestamp >= at)).collect();
182        if retained.is_empty() {
183            return Ok(());
184        }
185        let bytes = serde_json::to_vec(&retained)?;
186        ensure!(bytes.len() as u64 <= MAX_BATCH_BYTES, "activity batch exceeds 16 MiB limit");
187        let nonce = SystemTime::now().duration_since(UNIX_EPOCH)?.as_nanos();
188        let name = format!("{nonce:039}-{}-{}", std::process::id(), NEXT_BATCH.fetch_add(1, Ordering::Relaxed));
189        let temporary = dir.join(format!("{name}.tmp"));
190        let destination = dir.join(format!("{name}.json"));
191        let result = write_batch(&temporary, &bytes).and_then(|()| {
192            fs::rename(&temporary, destination).context("publishing activity batch")?;
193            sync_directory(dir)
194        });
195        if result.is_err() {
196            let _ = fs::remove_file(&temporary);
197        }
198        result
199    }
200
201    /// Strict reads remain available for callers that require complete history.
202    pub fn events(&self, session: &SessionKey) -> Result<Vec<FileEvent>> {
203        let report = self.read(session)?;
204        ensure!(
205            report.warnings.is_empty(),
206            "incomplete activity history: {}",
207            report
208                .warnings
209                .iter()
210                .map(|w| format!("{}: {}", w.path.display(), w.message))
211                .collect::<Vec<_>>()
212                .join("; ")
213        );
214        Ok(report.events)
215    }
216
217    /// Read every valid batch and report damaged/unreadable batches separately.
218    /// Bad batches are left untouched for inspection and recovery.
219    pub fn read(&self, session: &SessionKey) -> Result<ReadReport> {
220        let dir = self.directory(session)?;
221        if !dir.try_exists()? {
222            return Ok(ReadReport::default());
223        }
224        let _lock = crate::lock::Lock::acquire(&dir, false)?;
225        self.read_unlocked(session)
226    }
227
228    pub(crate) fn read_unlocked(&self, session: &SessionKey) -> Result<ReadReport> {
229        let dir = self.directory(session)?;
230        let paths = crate::maintenance::active_paths(&dir)?;
231        let mut report = ReadReport::default();
232        for path in paths {
233            match read_batch(&path, session) {
234                Ok(batch) => report.events.extend(batch),
235                Err(error) => report.warnings.push(BatchWarning { path, message: format!("{error:#}") }),
236            }
237        }
238        report.events.sort_by_key(|e| e.timestamp);
239        if let Some(cutoff) = crate::maintenance::retained_from(&dir)? {
240            report.events.retain(|event| event.timestamp >= cutoff);
241        }
242        Ok(report)
243    }
244}
245
246type Identity<'a> =
247    (i64, &'a Path, Option<&'a Path>, &'a Path, crate::Operation, crate::Source, crate::Outcome, Option<&'a str>);
248
249fn identity(event: &FileEvent) -> Identity<'_> {
250    (
251        event.timestamp,
252        &event.path,
253        event.previous_path.as_deref(),
254        &event.cwd,
255        event.operation,
256        event.source,
257        event.outcome,
258        event.tool_call_id.as_deref(),
259    )
260}
261
262pub(crate) fn write_batch(path: &Path, bytes: &[u8]) -> Result<()> {
263    let mut options = OpenOptions::new();
264    options.write(true).create_new(true);
265    #[cfg(unix)]
266    {
267        use std::os::unix::fs::OpenOptionsExt;
268        options.mode(0o600);
269    }
270    let mut file = options.open(path)?;
271    file.write_all(bytes)?;
272    file.sync_all()?;
273    Ok(())
274}
275
276fn validate_batch(session: &SessionKey, events: &[FileEvent]) -> Result<()> {
277    for event in events {
278        ensure!(&event.session == session, "event belongs to a different session");
279        ensure!((1..=crate::SCHEMA_VERSION).contains(&event.schema_version), "unsupported activity schema");
280        ensure!(event.path.is_absolute() && event.cwd.is_absolute(), "event paths must be absolute");
281        ensure!(event.previous_path.as_ref().is_none_or(|p| p.is_absolute()), "rename origin must be absolute");
282        ensure!(
283            (event.operation == crate::Operation::Rename) == event.previous_path.is_some(),
284            "rename operation and origin must agree"
285        );
286    }
287    Ok(())
288}
289
290fn read_batch(path: &Path, session: &SessionKey) -> Result<Vec<FileEvent>> {
291    ensure!(fs::symlink_metadata(path)?.file_type().is_file(), "batch must be a regular file");
292    let mut bytes = Vec::new();
293    fs::File::open(path)?.take(MAX_BATCH_BYTES + 1).read_to_end(&mut bytes)?;
294    ensure!(bytes.len() as u64 <= MAX_BATCH_BYTES, "activity batch exceeds 16 MiB limit");
295    let events = serde_json::from_slice::<Vec<FileEvent>>(&bytes)?;
296    validate_batch(session, &events)?;
297    Ok(events)
298}
299
300pub(crate) fn sync_directory(path: &Path) -> Result<()> {
301    #[cfg(unix)]
302    fs::File::open(path)?.sync_all().with_context(|| format!("syncing {}", path.display()))?;
303    #[cfg(not(unix))]
304    let _ = path;
305    Ok(())
306}