Skip to main content

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;