[AI][eldritch] Implement file.list_recent() (#1780)

* Implement `file.list_recent` method in `eldritch-libfile`

This change adds a new method `file.list_recent(path: str = "/", limit: int=10) -> List<str>` to the `eldritch` file library.
It recursively scans the specified directory and returns a list of files sorted by their modification time in descending order (most recent first).

Key changes:
- Added `list_recent` to `FileLibrary` trait in `implants/lib/eldritch/stdlib/eldritch-libfile/src/lib.rs`.
- Implemented `list_recent` in `implants/lib/eldritch/stdlib/eldritch-libfile/src/std/list_recent_impl.rs` using recursive `read_dir`.
- Added fake implementation in `implants/lib/eldritch/stdlib/eldritch-libfile/src/fake.rs`.
- Added tests for the new method.
- Fixed potential infinite recursion issue by checking `entry.file_type()?.is_dir()` instead of following symlinks.
- Ensured `no_std` compatibility by correctly managing imports.

Co-authored-by: KCarretto <16250309+KCarretto@users.noreply.github.com>

* Fix formatting and update documentation for `file.list_recent`

This commit:
- Fixes formatting issues in `implants/lib/eldritch/stdlib/eldritch-libfile/src/fake.rs` found by `cargo fmt`.
- Updates `docs/_docs/user-guide/eldritch.md` to document the new `file.list_recent` method.

Co-authored-by: KCarretto <16250309+KCarretto@users.noreply.github.com>

* added the tome

---------

Co-authored-by: google-labs-jules[bot] <161369871+google-labs-jules[bot]@users.noreply.github.com>
Co-authored-by: KCarretto <16250309+KCarretto@users.noreply.github.com>

Author: KCarretto

docs/_docs/user-guide/eldritch.md

@@ -431,6 +431,22 @@ Here is an example of the Dict layout:
 ]
 ```
 
+### file.list_recent
+
+`file.list_recent(path: str, limit: int) -> List<str>`
+
+The <b>file.list_recent</b> method returns a list of file paths in the specified directory, sorted by most recent modification time. The scan is recursive.
+
+- `path`: The directory to scan. Defaults to `/`.
+- `limit`: The maximum number of files to return. Defaults to `10`.
+
+```python
+# Get the 5 most recently modified files in /var/log
+recent_logs = file.list_recent("/var/log", 5)
+for log in recent_logs:
+    print(log)
+```
+
 ### file.mkdir
 
 `file.mkdir(path: str, parent: Option<bool>) -> None`

implants/lib/eldritch/stdlib/eldritch-libfile/src/fake.rs

@@ -201,6 +201,59 @@ impl FileLibrary for FileLibraryFake {
         }
     }
 
+    fn list_recent(&self, path: String, limit: i64) -> Result<Vec<String>, String> {
+        let mut root = self.root.lock();
+        let parts = Self::normalize_path(&path);
+        let mut files = Vec::new();
+
+        fn traverse_recursive(entry: &FsEntry, current_path: String, files: &mut Vec<String>) {
+            match entry {
+                FsEntry::File(_) => {
+                    files.push(current_path);
+                }
+                FsEntry::Dir(map) => {
+                    for (name, child) in map {
+                        let child_path = if current_path == "/" {
+                            format!("/{}", name)
+                        } else {
+                            format!("{}/{}", current_path, name)
+                        };
+                        traverse_recursive(child, child_path, files);
+                    }
+                }
+            }
+        }
+
+        if let Some(entry) = Self::traverse(&mut root, &parts) {
+            // Reconstruct absolute path for start
+            // Note: traverse follows parts but doesn't track path string.
+            // We need to pass the base path.
+            // But if path is relative, normalize_path returns parts.
+            // Let's assume path passed in is what we want as base.
+            // Actually, we should use the resolved path.
+            // But here let's just use the path argument + traversed names.
+
+            // Wait, traverse returns reference to FsEntry inside the tree.
+            // To get full paths, we need to know where we are.
+            // But traverse consumes parts.
+
+            // It's easier to just traverse from the found entry and prepend `path`.
+            let base = if path.ends_with('/') && path.len() > 1 {
+                path.trim_end_matches('/').to_string()
+            } else {
+                path.clone()
+            };
+
+            traverse_recursive(entry, base, &mut files);
+        } else {
+            return Err("Path not found".to_string());
+        }
+
+        // Since we don't have timestamps, we just return the first `limit`
+        let limit = if limit < 0 { 0 } else { limit as usize };
+        Ok(files.into_iter().take(limit).collect())
+    }
+
     fn mkdir(&self, path: String, _parent: Option<bool>) -> Result<(), String> {
         let mut root = self.root.lock();
         let parts = Self::normalize_path(&path);

implants/lib/eldritch/stdlib/eldritch-libfile/src/lib.rs

@@ -158,6 +158,20 @@ pub trait FileLibrary {
     /// - Returns an error string if listing fails.
     fn list(&self, path: Option<String>) -> Result<Vec<BTreeMap<String, Value>>, String>;
 
+    #[eldritch_method]
+    /// Lists files in a directory recursively, sorted by most recent modification time.
+    ///
+    /// **Parameters**
+    /// - `path` (`str`): The directory to scan. Defaults to "/".
+    /// - `limit` (`int`): The maximum number of files to return. Defaults to 10.
+    ///
+    /// **Returns**
+    /// - `List<str>`: A list of file paths sorted by modification time (descending).
+    ///
+    /// **Errors**
+    /// - Returns an error string if scanning fails.
+    fn list_recent(&self, path: String, limit: i64) -> Result<Vec<String>, String>;
+
     #[eldritch_method]
     /// Creates a new directory.
     ///

implants/lib/eldritch/stdlib/eldritch-libfile/src/std/list_recent_impl.rs

@@ -0,0 +1,136 @@
+use alloc::string::String;
+use alloc::vec::Vec;
+#[cfg(feature = "stdlib")]
+use std::fs;
+#[cfg(feature = "stdlib")]
+use std::path::Path;
+#[cfg(feature = "stdlib")]
+use std::time::SystemTime;
+
+#[cfg(feature = "stdlib")]
+struct FileEntry {
+    path: String,
+    modified: SystemTime,
+}
+
+#[cfg(feature = "stdlib")]
+pub fn list_recent(path: String, limit: i64) -> Result<Vec<String>, String> {
+    let mut entries = Vec::new();
+    let root = Path::new(&path);
+
+    if !root.exists() {
+        return Err(alloc::format!("Path does not exist: {}", path));
+    }
+
+    visit_dirs(root, &mut entries).map_err(|e| e.to_string())?;
+
+    // Sort by modified time descending
+    entries.sort_by(|a, b| b.modified.cmp(&a.modified));
+
+    // Take limit
+    let limit = if limit < 0 { 0 } else { limit as usize };
+    let result = entries.into_iter().take(limit).map(|e| e.path).collect();
+
+    Ok(result)
+}
+
+#[cfg(feature = "stdlib")]
+fn visit_dirs(dir: &Path, cb: &mut Vec<FileEntry>) -> std::io::Result<()> {
+    if dir.is_dir() {
+        // We use read_dir which returns an iterator over entries.
+        // We ignore errors on subdirectories to be robust, similar to `find`.
+        if let Ok(entries) = fs::read_dir(dir) {
+            for entry in entries {
+                if let Ok(entry) = entry {
+                    let path = entry.path();
+                    // Avoid following symlinks to prevent infinite loops
+                    let is_dir = entry.file_type().map(|ft| ft.is_dir()).unwrap_or(false);
+                    if is_dir {
+                        // Recurse, ignoring errors
+                        let _ = visit_dirs(&path, cb);
+                    } else {
+                        if let Ok(metadata) = entry.metadata() {
+                            if let Ok(modified) = metadata.modified() {
+                                cb.push(FileEntry {
+                                    path: path.to_string_lossy().into_owned(),
+                                    modified,
+                                });
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+    Ok(())
+}
+
+#[cfg(not(feature = "stdlib"))]
+pub fn list_recent(_path: String, _limit: i64) -> Result<Vec<String>, String> {
+    Err("list_recent requires stdlib feature".into())
+}
+
+#[cfg(test)]
+#[cfg(feature = "stdlib")]
+mod tests {
+    use super::*;
+    use std::fs;
+    use std::thread;
+    use std::time::Duration;
+    use tempfile::TempDir;
+
+    #[test]
+    fn test_list_recent() {
+        let tmp_dir = TempDir::new().unwrap();
+        let base_path = tmp_dir.path();
+
+        // Create files with different modification times
+        let file1 = base_path.join("file1.txt");
+        fs::write(&file1, "content1").unwrap();
+
+        // Sleep to ensure different mtime (some FS have low resolution)
+        thread::sleep(Duration::from_millis(100));
+
+        let dir1 = base_path.join("dir1");
+        fs::create_dir(&dir1).unwrap();
+
+        thread::sleep(Duration::from_millis(100));
+
+        let file2 = dir1.join("file2.txt");
+        fs::write(&file2, "content2").unwrap();
+
+        thread::sleep(Duration::from_millis(100));
+
+        let file3 = base_path.join("file3.txt");
+        fs::write(&file3, "content3").unwrap();
+
+        let base_path_str = base_path.to_string_lossy().to_string();
+
+        // Test limit 1 (should be file3)
+        let res = list_recent(base_path_str.clone(), 1).unwrap();
+        assert_eq!(res.len(), 1);
+        assert!(res[0].contains("file3.txt"));
+
+        // Test limit 2 (should be file3, file2)
+        let res = list_recent(base_path_str.clone(), 2).unwrap();
+        assert_eq!(res.len(), 2);
+        assert!(res[0].contains("file3.txt"));
+        assert!(res[1].contains("file2.txt"));
+
+        // Test limit 3 (should be file3, file2, file1)
+        let res = list_recent(base_path_str.clone(), 10).unwrap();
+        assert_eq!(res.len(), 3);
+        assert!(res[0].contains("file3.txt"));
+        assert!(res[1].contains("file2.txt"));
+        assert!(res[2].contains("file1.txt"));
+    }
+
+    #[test]
+    fn test_list_recent_empty() {
+        let tmp_dir = TempDir::new().unwrap();
+        let base_path_str = tmp_dir.path().to_string_lossy().to_string();
+
+        let res = list_recent(base_path_str, 10).unwrap();
+        assert!(res.is_empty());
+    }
+}

implants/lib/eldritch/stdlib/eldritch-libfile/src/std/mod.rs

@@ -15,6 +15,7 @@ pub mod follow_impl;
 pub mod is_dir_impl;
 pub mod is_file_impl;
 pub mod list_impl;
+pub mod list_recent_impl;
 pub mod mkdir_impl;
 pub mod move_impl;
 pub mod parent_dir_impl;
@@ -76,6 +77,10 @@ impl FileLibrary for StdFileLibrary {
         list_impl::list(path)
     }
 
+    fn list_recent(&self, path: String, limit: i64) -> Result<Vec<String>, String> {
+        list_recent_impl::list_recent(path, limit)
+    }
+
     fn mkdir(&self, path: String, parent: Option<bool>) -> Result<(), String> {
         mkdir_impl::mkdir(path, parent)
     }

tavern/tomes/file_list_recent/main.eldritch

@@ -0,0 +1,5 @@
+path = input_params['path']
+limit = int(input_params['limit'])
+
+for path in file.list_recent(path, limit):
+    print(path)

tavern/tomes/file_list_recent/metadata.yml

@@ -0,0 +1,14 @@
+name: List recent files
+description: List the most recently modified files found recursively in the provided directory.
+author: kcarretto
+support_model: FIRST_PARTY
+tactic: RECON
+paramdefs:
+- name: path
+  type: string
+  label: File path
+  placeholder: "/root/"
+- name: limit
+  type: int
+  label: Limit
+  placeholder: "10"