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