haest_core/fs.rs
1//! The file system the agent sees. Every file operation haest performs -- tools,
2//! spilled output, the session log, instruction files, skills -- goes through
3//! an [`Fs`]. Nothing in haest touches `std::fs` for the agent directly.
4//!
5//! PLUG POINT: a host with its own storage implements [`Fs`] (the `haest`
6//! crate's `notebook` example stages every write for review); `haest-workspace`
7//! has the real disk (`RealFs`) and can put a sandboxed bash over ANY `Fs`, so
8//! the file the agent writes with Write is the file `cat` shows. A
9//! [`Workspace`](crate::Workspace) hands its `Fs` to the tools.
10//!
11//! Here: the trait, [`MemFs`] (in memory: tests, scratch, a sandbox with no
12//! disk), [`ShutFs`] (refuses everything), and the path helpers every
13//! implementation and tool shares.
14//!
15//! Paths are absolute. A relative path is the caller's bug: resolve it against
16//! the cwd first ([`resolve_path`]).
17//!
18//! # Examples
19//!
20//! ```
21//! use std::path::Path;
22//!
23//! use haest_core::{
24//! Fs, MemFs,
25//! fs::{ensure_dir, read_text_if_present},
26//! };
27//!
28//! # #[tokio::main(flavor = "current_thread")]
29//! # async fn main() -> std::io::Result<()> {
30//! let fs = MemFs::from_files([("/project/README.md", "# Hello")]);
31//! assert_eq!(fs.read_to_string(Path::new("/project/README.md")).await?, "# Hello");
32//!
33//! ensure_dir(&fs, Path::new("/project/notes")).await?;
34//! fs.write(Path::new("/project/notes/a.md"), b"first").await?;
35//! fs.append(Path::new("/project/notes/a.md"), b", second").await?;
36//! assert_eq!(fs.read(Path::new("/project/notes/a.md")).await?, b"first, second");
37//!
38//! let names: Vec<String> = fs.read_dir(Path::new("/project")).await?
39//! .into_iter().map(|e| e.name).collect();
40//! assert_eq!(names, ["README.md", "notes"]);
41//!
42//! // A file a host may or may not have: None, not an error.
43//! assert_eq!(read_text_if_present(&fs, Path::new("/project/.mcp.json")).await?, None);
44//! # Ok(())
45//! # }
46//! ```
47
48use std::{
49 any::Any,
50 fmt, io,
51 path::{Path, PathBuf},
52 time::SystemTime,
53};
54
55use async_trait::async_trait;
56
57/// What a path is.
58#[derive(Debug, Clone, Copy, PartialEq, Eq)]
59pub enum FileKind {
60 /// A file (anything that is neither a directory nor a link).
61 File,
62 /// A directory.
63 Dir,
64 /// A symbolic link, as [`Fs::read_dir`] reports one; [`Fs::stat`] follows
65 /// links, so it reports what the link names instead.
66 Symlink,
67}
68
69/// What [`Fs::stat`] knows about a path.
70///
71/// Built with [`FsStat::new`] and [`with_modified`](FsStat::with_modified),
72/// so a field added later (a mode) breaks no [`Fs`] outside haest.
73///
74/// ```
75/// use std::time::SystemTime;
76///
77/// use haest_core::fs::{FileKind, FsStat};
78///
79/// let stat = FsStat::new(FileKind::File, 42).with_modified(SystemTime::UNIX_EPOCH);
80/// assert!(stat.is_file());
81/// assert_eq!((stat.size, stat.modified), (42, Some(SystemTime::UNIX_EPOCH)));
82/// ```
83#[derive(Debug, Clone, PartialEq, Eq)]
84#[non_exhaustive]
85pub struct FsStat {
86 /// File, directory or link.
87 pub kind: FileKind,
88 /// Size in bytes (0 for a directory in [`MemFs`]; whatever the platform says on disk).
89 pub size: u64,
90 /// When it last changed; None where the file system keeps no time.
91 pub modified: Option<SystemTime>,
92}
93
94impl FsStat {
95 /// A path of `kind` holding `size` bytes, with no time it last changed.
96 pub fn new(kind: FileKind, size: u64) -> Self {
97 Self {
98 kind,
99 size,
100 modified: None,
101 }
102 }
103
104 /// The same, last changed `at`.
105 #[must_use]
106 pub fn with_modified(mut self, at: SystemTime) -> Self {
107 self.modified = Some(at);
108 self
109 }
110
111 /// Is it a directory?
112 pub fn is_dir(&self) -> bool {
113 self.kind == FileKind::Dir
114 }
115 /// Is it a file?
116 pub fn is_file(&self) -> bool {
117 self.kind == FileKind::File
118 }
119}
120
121/// One entry of a directory listing ([`Fs::read_dir`]), built with
122/// [`DirEntry::new`].
123#[derive(Debug, Clone, PartialEq, Eq)]
124#[non_exhaustive]
125pub struct DirEntry {
126 /// The entry's own name, no directory part.
127 pub name: String,
128 /// What it is; a link is [`FileKind::Symlink`], not followed.
129 pub kind: FileKind,
130}
131
132impl DirEntry {
133 /// The entry `name` (no directory part), of `kind`.
134 pub fn new(name: impl Into<String>, kind: FileKind) -> Self {
135 Self {
136 name: name.into(),
137 kind,
138 }
139 }
140}
141
142/// A lock on a file, held until this value is dropped: what [`Fs::try_lock`]
143/// hands back.
144///
145/// It holds whatever releases the lock as it drops: the open file the
146/// system's lock is on, or a guard of the host's own store.
147///
148/// ```
149/// use std::sync::{
150/// Arc,
151/// atomic::{AtomicBool, Ordering},
152/// };
153///
154/// use haest_core::fs::FsLock;
155///
156/// /// A host's store marks a file held; this unmarks it as it drops.
157/// struct Unmark(Arc<AtomicBool>);
158///
159/// impl Drop for Unmark {
160/// fn drop(&mut self) {
161/// self.0.store(false, Ordering::SeqCst);
162/// }
163/// }
164///
165/// let held = Arc::new(AtomicBool::new(true));
166/// let lock = FsLock::new(Unmark(held.clone()));
167/// assert!(held.load(Ordering::SeqCst));
168/// drop(lock);
169/// assert!(!held.load(Ordering::SeqCst));
170/// ```
171pub struct FsLock {
172 _held: Box<dyn Any + Send + Sync>,
173}
174
175impl FsLock {
176 /// A lock held until this value is dropped, which drops `held`: what
177 /// releases the lock as it drops.
178 pub fn new(held: impl Send + Sync + 'static) -> Self {
179 Self {
180 _held: Box::new(held),
181 }
182 }
183}
184
185/// Nothing of what it holds.
186impl fmt::Debug for FsLock {
187 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
188 f.debug_struct("FsLock").finish_non_exhaustive()
189 }
190}
191
192/// A file system: the one way haest reads and writes files.
193///
194/// Every path is absolute (see [`resolve_path`]). Errors are `io::Error`s with
195/// the [`io::ErrorKind`] `std::fs` would give for the same failure: callers
196/// match on them ([`read_text_if_present`] treats `NotFound` and
197/// `NotADirectory` as "no file"; the sandboxed shell turns each kind into its
198/// own error).
199///
200/// Nine methods are required: `read`, `write`, `append`, `stat`, `read_dir`,
201/// `create_dir`, `remove`, `remove_all` (a store with no one-step removal
202/// walks the tree with [`remove_tree`]) and `rename`. The rest have defaults
203/// built on them; override one when the store can do it better
204/// ([`Fs::read_head`] that stops early, [`Fs::create_dir_all`] in one step,
205/// [`Fs::write_whole`] on a disk whose write empties a file first,
206/// [`Fs::read_link`] and [`Fs::chmod`] on a store that has links and modes,
207/// [`Fs::try_lock`] on a store more than one writer shares).
208/// A host's wrapper over another `Fs` forwards each method it does not
209/// change, [`Fs::write_whole`] and [`Fs::try_lock`] above all (left to its
210/// default, the one writes with the inner store's plain `write`, which on
211/// the real disk empties the file first, and the other holds nothing), and
212/// puts `#[warn(clippy::missing_trait_methods)]` on its impl, which names
213/// each one it left out.
214/// [`FsStat`] and [`DirEntry`] are built with their `new`.
215///
216/// Implementations here: [`MemFs`] and [`ShutFs`]; `haest-workspace` has the
217/// real disk (`RealFs`) and a copy-on-write sandbox over any `Fs`.
218///
219/// # Examples
220///
221/// A host's own store, here a read-only view over a [`MemFs`]:
222///
223/// ```
224/// use std::{io, path::Path};
225///
226/// use async_trait::async_trait;
227/// use haest_core::{DirEntry, Fs, FsStat, MemFs};
228///
229/// struct ReadOnly(MemFs);
230///
231/// fn refused() -> io::Error {
232/// io::Error::new(io::ErrorKind::PermissionDenied, "read-only")
233/// }
234///
235/// #[async_trait]
236/// impl Fs for ReadOnly {
237/// async fn read(&self, path: &Path) -> io::Result<Vec<u8>> {
238/// self.0.read(path).await
239/// }
240/// async fn stat(&self, path: &Path) -> io::Result<FsStat> {
241/// self.0.stat(path).await
242/// }
243/// async fn read_dir(&self, path: &Path) -> io::Result<Vec<DirEntry>> {
244/// self.0.read_dir(path).await
245/// }
246/// async fn write(&self, _: &Path, _: &[u8]) -> io::Result<()> {
247/// Err(refused())
248/// }
249/// async fn append(&self, _: &Path, _: &[u8]) -> io::Result<()> {
250/// Err(refused())
251/// }
252/// async fn create_dir(&self, _: &Path) -> io::Result<()> {
253/// Err(refused())
254/// }
255/// async fn remove(&self, _: &Path) -> io::Result<()> {
256/// Err(refused())
257/// }
258/// async fn remove_all(&self, _: &Path) -> io::Result<()> {
259/// Err(refused())
260/// }
261/// async fn rename(&self, _: &Path, _: &Path) -> io::Result<()> {
262/// Err(refused())
263/// }
264/// }
265///
266/// # #[tokio::main(flavor = "current_thread")]
267/// # async fn main() -> io::Result<()> {
268/// let fs = ReadOnly(MemFs::from_files([("/docs/a.md", "A")]));
269/// assert_eq!(fs.read_to_string(Path::new("/docs/a.md")).await?, "A");
270/// assert!(fs.exists(Path::new("/docs")).await);
271/// let refused = fs.write(Path::new("/docs/b.md"), b"B").await;
272/// assert!(refused.is_err_and(|e| e.kind() == io::ErrorKind::PermissionDenied));
273/// # Ok(())
274/// # }
275/// ```
276#[async_trait]
277pub trait Fs: Send + Sync {
278 /// The whole file's bytes.
279 ///
280 /// # Errors
281 ///
282 /// `NotFound` when nothing is there, and an error for a directory. An
283 /// implementation may refuse what is not a regular file: the real disk
284 /// refuses a FIFO or a device (`InvalidInput`) rather than block on it.
285 async fn read(&self, path: &Path) -> io::Result<Vec<u8>>;
286 /// The whole file as text.
287 ///
288 /// # Errors
289 ///
290 /// [`Fs::read`]'s, and `InvalidData` when the bytes are not strict UTF-8.
291 async fn read_to_string(&self, path: &Path) -> io::Result<String> {
292 let bytes = self.read(path).await?;
293 String::from_utf8(bytes).map_err(|e| io::Error::new(io::ErrorKind::InvalidData, e))
294 }
295 /// The first `max` bytes (all of a shorter file), for a caller that needs
296 /// only the start of many files (a list of saved sessions). The default
297 /// reads the whole file, then cuts it; a file system that can stop early
298 /// should.
299 async fn read_head(&self, path: &Path, max: usize) -> io::Result<Vec<u8>> {
300 let mut bytes = self.read(path).await?;
301 bytes.truncate(max);
302 Ok(bytes)
303 }
304 /// Create the file or replace its contents with `data`.
305 ///
306 /// # Errors
307 ///
308 /// `NotFound` when the parent directory does not exist (it is never
309 /// created: see [`ensure_dir`]), and an error when `path` is a directory.
310 async fn write(&self, path: &Path, data: &[u8]) -> io::Result<()>;
311 /// Replace what the file at `path` holds with `data`, whole or not at
312 /// all where the store can: a write it stops partway (a full disk, a
313 /// kill) leaves the file as it was, never emptied or cut short. The
314 /// tools that rewrite a file that is there call it (Edit, Write over
315 /// one, `GenerateImage` over an image), since the model cannot put back
316 /// a file it only edited, and so does the overlay's apply; a new file
317 /// is made with [`Fs::write`].
318 ///
319 /// The default is [`Fs::write`]: a store whose write cannot stop
320 /// partway (memory), or that keeps writes its own way (a host's,
321 /// staging them for review), has nothing to add. A disk that empties a
322 /// file before it writes it overrides it (the real disk writes a new
323 /// file beside it and renames it over); a wrapper over another `Fs`
324 /// forwards it.
325 ///
326 /// # Errors
327 ///
328 /// [`Fs::write`]'s, and the store's own where it cannot replace the
329 /// file whole (no room for the new copy), with the file as it was. A
330 /// store that writes some files in place all the same (the real disk:
331 /// one with another hard link, a symlink) can fail with such a file
332 /// cut short.
333 async fn write_whole(&self, path: &Path, data: &[u8]) -> io::Result<()> {
334 self.write(path, data).await
335 }
336 /// Add `data` to the end of the file, creating it when it is missing.
337 /// The session log writes every record this way.
338 ///
339 /// # Errors
340 ///
341 /// As [`Fs::write`]: the parent directory must exist, and `path` must not
342 /// be a directory.
343 async fn append(&self, path: &Path, data: &[u8]) -> io::Result<()>;
344 /// Is anything at `path`? Any error from [`Fs::stat`] counts as no.
345 async fn exists(&self, path: &Path) -> bool {
346 self.stat(path).await.is_ok()
347 }
348 /// What is at `path`, following symbolic links: what a read or a write
349 /// cares about is the file a link names.
350 ///
351 /// # Errors
352 ///
353 /// `NotFound` when nothing is there (a dangling link included).
354 async fn stat(&self, path: &Path) -> io::Result<FsStat>;
355 /// The target of the symbolic link at `path`, the link itself not
356 /// followed; `InvalidInput` when `path` is not a link. The default is a
357 /// file system with no links (memory, a host's own store): every path
358 /// that exists is not one.
359 ///
360 /// # Errors
361 ///
362 /// `NotFound` when nothing is there, `InvalidInput` when it is not a link.
363 async fn read_link(&self, path: &Path) -> io::Result<PathBuf> {
364 self.stat(path).await?;
365 Err(io::Error::new(
366 io::ErrorKind::InvalidInput,
367 format!("{}: not a symbolic link", path.display()),
368 ))
369 }
370 /// The directory's direct children, sorted by name. A link is listed as
371 /// [`FileKind::Symlink`] and not followed, so a walk never descends a
372 /// link loop.
373 ///
374 /// # Errors
375 ///
376 /// `NotFound` when nothing is there, `NotADirectory` for a file.
377 async fn read_dir(&self, path: &Path) -> io::Result<Vec<DirEntry>>;
378 /// Create the directory `path`; its parent must exist.
379 ///
380 /// # Errors
381 ///
382 /// `AlreadyExists` when something is at `path`, `NotFound` when the
383 /// parent is missing, and an error when a file sits where the parent
384 /// should be.
385 async fn create_dir(&self, path: &Path) -> io::Result<()>;
386 /// Create the directory `path` and every missing parent, like `mkdir -p`;
387 /// a directory already there is fine. The default walks down from the
388 /// root with [`Fs::stat`] and [`Fs::create_dir`]; a store that can do it
389 /// in one step should.
390 ///
391 /// # Errors
392 ///
393 /// `NotADirectory` when a file sits where a directory should be, and
394 /// [`Fs::create_dir`]'s.
395 async fn create_dir_all(&self, path: &Path) -> io::Result<()> {
396 let dirs: Vec<&Path> = path.ancestors().collect();
397 for dir in dirs.into_iter().rev() {
398 match self.stat(dir).await {
399 Ok(stat) if stat.is_dir() => {}
400 Ok(_) => {
401 return Err(io::Error::new(
402 io::ErrorKind::NotADirectory,
403 format!("{}: not a directory", dir.display()),
404 ));
405 }
406 Err(_) => match self.create_dir(dir).await {
407 Ok(()) => {}
408 // Another writer made it first: fine, if it is a directory.
409 Err(e)
410 if e.kind() == io::ErrorKind::AlreadyExists
411 && self.stat(dir).await.is_ok_and(|s| s.is_dir()) => {}
412 Err(e) => return Err(e),
413 },
414 }
415 }
416 Ok(())
417 }
418 /// Delete a file, a link (not what it names) or an empty directory.
419 ///
420 /// # Errors
421 ///
422 /// `NotFound` when nothing is there, and an error for a directory with
423 /// anything in it ([`Fs::remove_all`] deletes those).
424 async fn remove(&self, path: &Path) -> io::Result<()>;
425 /// Delete `path` and, for a directory, everything in it. A link is
426 /// deleted, never followed.
427 ///
428 /// Required: deleting a whole tree is where a store's own rules belong
429 /// (a cap on how much one call removes, one step instead of many). A
430 /// store with nothing of its own to say calls [`remove_tree`], which
431 /// walks the tree with [`Fs::read_link`], [`Fs::read_dir`] and
432 /// [`Fs::remove`].
433 ///
434 /// # Errors
435 ///
436 /// `NotFound` when nothing is there, and an error when any part of the
437 /// tree could not be removed.
438 async fn remove_all(&self, path: &Path) -> io::Result<()>;
439 /// Move a file or a whole directory tree from `from` to `to`, as
440 /// rename(2): a file replaces a file at `to`, a directory an empty
441 /// directory, and onto itself nothing changes. The parent of `to` must
442 /// exist.
443 ///
444 /// # Errors
445 ///
446 /// `NotFound` when `from` (or `to`'s parent) is missing; `InvalidInput`
447 /// when `to` is inside the directory `from`; `IsADirectory` for a file
448 /// onto a directory, `NotADirectory` for a directory onto a file, and
449 /// `DirectoryNotEmpty` for a directory onto one with anything in it.
450 async fn rename(&self, from: &Path, to: &Path) -> io::Result<()>;
451 /// Set Unix permission bits (the session log is 0600 in a 0700 dir). The
452 /// default does nothing: a file system with no permissions (memory, a
453 /// host's own store) has nothing to set.
454 async fn chmod(&self, _path: &Path, _mode: u32) -> io::Result<()> {
455 Ok(())
456 }
457 /// Hold the file at `path` for one writer until the returned lock is
458 /// dropped; it never waits for one. Meanwhile every other `try_lock` of
459 /// the file, in this process or another, fails. A lock must not outlive
460 /// the process that holds it, so a crash never leaves a file locked. A
461 /// store makes the file, empty, when it is not there (its dir must be).
462 /// A session is held this way while a conversation writes it, through a
463 /// lock file of its own beside the session file
464 /// ([`JsonlSessionFile::try_lock`](crate::session::JsonlSessionFile::try_lock)).
465 ///
466 /// `Ok(None)` when the file system has no locks: nothing is held, nothing
467 /// is refused, and no file is made. That is the default (memory, a
468 /// host's own store that one writer uses); a store more than one writer
469 /// shares overrides it.
470 ///
471 /// # Errors
472 ///
473 /// `WouldBlock` when another holder has the file, and the file system's
474 /// other errors: the file cannot be made or opened, or the lock cannot be
475 /// taken.
476 async fn try_lock(&self, _path: &Path) -> io::Result<Option<FsLock>> {
477 Ok(None)
478 }
479}
480
481crate::plug_ref! {
482 /// An [`Fs`], shared: what [`Workspace::fs`](crate::Workspace::fs) hands
483 /// out, and what a session file or a skill set reads through. Built from
484 /// the file system itself (`MemFs::new()`, a host's own), or from an
485 /// `Arc` of one.
486 pub struct FsRef(dyn Fs);
487}
488
489mod mem;
490mod ops;
491mod paths;
492mod shut;
493pub use mem::MemFs;
494pub use ops::{ensure_dir, looks_binary, read_text_if_present, remove_tree};
495pub(crate) use ops::{not_found, read_lossy};
496pub use paths::{normalize, resolve_path};
497pub use shut::ShutFs;
498
499#[cfg(test)]
500mod tests;