Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
feat(storage): add pagination capability for ls/tree. support http-api/cli/python-sdk/go-sdk/typescript-sdk/mcp && CLI/MCP support ls sort capability (#4698)
baojun-zhang94ff079f514f
diff --git a/crates/ov_cli/README_CN.md b/crates/ov_cli/README_CN.mdindex fd7ceb050..7eeb21930 100644--- a/crates/ov_cli/README_CN.md+++ b/crates/ov_cli/README_CN.md@@ -272,6 +272,11 @@ ov find "authentication" --uri viking://resources/project --level 0,1# 递归列目录ov ls viking://resources --recursive+# 按修改时间排序并分页+ov ls viking://resources --offset 100 --limit 50 \+ --sort-by mtime --sort-order desc+ov tree viking://resources --offset 100 --limit 50+# 写入调用方提供的 tags,再按 tags 过滤或回显ov write viking://resources/docs/api.md --content "# API" \--tags team=search,env=proddiff --git a/crates/ov_cli/src/client.rs b/crates/ov_cli/src/client.rsindex 4ae57e6de..8c3106511 100644--- a/crates/ov_cli/src/client.rs+++ b/crates/ov_cli/src/client.rs@@ -587,6 +587,10 @@ impl HttpClient {abs_limit: i32,show_all_hidden: bool,node_limit: i32,+ offset: i32,+ limit: Option<i32>,+ sort_by: Option<&str>,+ sort_order: Option<&str>,extra_fields: &[String],tags: &[String],include_tags: bool,@@ -600,6 +604,18 @@ impl HttpClient {("show_all_hidden".to_string(), show_all_hidden.to_string()),("node_limit".to_string(), node_limit.to_string()),];+ if offset != 0 {+ params.push(("offset".to_string(), offset.to_string()));+ }+ if let Some(limit) = limit {+ params.push(("limit".to_string(), limit.to_string()));+ }+ if let Some(sort_by) = sort_by {+ params.push(("sort_by".to_string(), sort_by.to_string()));+ if let Some(sort_order) = sort_order {+ params.push(("sort_order".to_string(), sort_order.to_string()));+ }+ }for field in extra_fields {params.push(("extra_fields".to_string(), field.clone()));}@@ -620,6 +636,8 @@ impl HttpClient {show_all_hidden: bool,node_limit: i32,level_limit: i32,+ offset: i32,+ limit: Option<i32>,extra_fields: &[String],tags: &[String],include_tags: bool,@@ -632,6 +650,12 @@ impl HttpClient {("node_limit".to_string(), node_limit.to_string()),("level_limit".to_string(), level_limit.to_string()),];+ if offset != 0 {+ params.push(("offset".to_string(), offset.to_string()));+ }+ if let Some(limit) = limit {+ params.push(("limit".to_string(), limit.to_string()));+ }for field in extra_fields {params.push(("extra_fields".to_string(), field.clone()));}@@ -2301,14 +2325,64 @@ mod tests {let client = HttpClient::new(base_url, None, None, None, None, 5.0, false, None);client- .ls("viking://resources", false, false, "agent", 256, false, 1, &[], &[], false)+ .ls(+ "viking://resources",+ false,+ false,+ "agent",+ 256,+ false,+ 20,+ 4,+ Some(5),+ Some("mtime"),+ Some("desc"),+ &[],+ &[],+ false,+ ).await.expect("ls request should succeed");let request = request_rx.await.expect("request should be captured");assert!(request.starts_with("GET /api/v1/fs/ls?"));+ assert!(request.contains("node_limit=20"));+ assert!(request.contains("offset=4"));+ assert!(request.contains("limit=5"));+ assert!(request.contains("sort_by=mtime"));+ assert!(request.contains("sort_order=desc"));assert!(!request.contains("tz="));assert!(!request.contains("include_mod_time_iso="));++ let (default_url, default_request_rx) = spawn_request_capture_server().await;+ let default_client =+ HttpClient::new(default_url, None, None, None, None, 5.0, false, None);+ default_client+ .ls(+ "viking://resources",+ false,+ false,+ "agent",+ 256,+ false,+ 20,+ 0,+ None,+ None,+ None,+ &[],+ &[],+ false,+ )+ .await+ .expect("default ls request should succeed");+ let default_request = default_request_rx+ .await+ .expect("default request should be captured");+ assert!(!default_request.contains("offset="));+ assert!(!default_request.contains("&limit="));+ assert!(!default_request.contains("sort_by="));+ assert!(!default_request.contains("sort_order="));}#[tokio::test]@@ -2448,14 +2522,54 @@ mod tests {let client = HttpClient::new(base_url, None, None, None, None, 5.0, false, None);client- .tree("viking://resources", "agent", 256, false, 1, 3, &[], &[], false)+ .tree(+ "viking://resources",+ "agent",+ 256,+ false,+ 20,+ 3,+ 4,+ Some(5),+ &[],+ &[],+ false,+ ).await.expect("tree request should succeed");let request = request_rx.await.expect("request should be captured");assert!(request.starts_with("GET /api/v1/fs/tree?"));+ assert!(request.contains("node_limit=20"));+ assert!(request.contains("offset=4"));+ assert!(request.contains("limit=5"));assert!(!request.contains("tz="));assert!(!request.contains("include_mod_time_iso="));++ let (default_url, default_request_rx) = spawn_request_capture_server().await;+ let default_client =+ HttpClient::new(default_url, None, None, None, None, 5.0, false, None);+ default_client+ .tree(+ "viking://resources",+ "agent",+ 256,+ false,+ 20,+ 3,+ 0,+ None,+ &[],+ &[],+ false,+ )+ .await+ .expect("default tree request should succeed");+ let default_request = default_request_rx+ .await+ .expect("default request should be captured");+ assert!(!default_request.contains("offset="));+ assert!(!default_request.contains("&limit="));}#[tokio::test]diff --git a/crates/ov_cli/src/commands/filesystem.rs b/crates/ov_cli/src/commands/filesystem.rsindex bca35f6c2..456284ca7 100644--- a/crates/ov_cli/src/commands/filesystem.rs+++ b/crates/ov_cli/src/commands/filesystem.rs@@ -171,6 +171,10 @@ pub async fn ls(abs_limit: i32,show_all_hidden: bool,node_limit: i32,+ offset: i32,+ limit: Option<i32>,+ sort_by: Option<&str>,+ sort_order: Option<&str>,output_format: OutputFormat,compact: bool,fields: Option<Vec<String>>,@@ -188,6 +192,10 @@ pub async fn ls(abs_limit,show_all_hidden,node_limit,+ offset,+ limit,+ sort_by,+ sort_order,&extra,tags,fields.as_ref().is_some_and(|items| items.iter().any(|item| item == "tags")) || !tags.is_empty(),@@ -205,6 +213,8 @@ pub async fn tree(show_all_hidden: bool,node_limit: i32,level_limit: i32,+ offset: i32,+ limit: Option<i32>,output_format: OutputFormat,compact: bool,simple: bool,@@ -220,6 +230,8 @@ pub async fn tree(show_all_hidden,node_limit,level_limit,+ offset,+ limit,&extra,tags,fields.as_ref().is_some_and(|items| items.iter().any(|item| item == "tags")) || !tags.is_empty(),diff --git a/crates/ov_cli/src/handlers.rs b/crates/ov_cli/src/handlers.rsindex 246cc0b15..6d77b6fba 100644--- a/crates/ov_cli/src/handlers.rs+++ b/crates/ov_cli/src/handlers.rs@@ -1644,6 +1644,10 @@ pub async fn handle_ls(abs_limit: i32,show_all_hidden: bool,node_limit: i32,+ offset: i32,+ limit: Option<i32>,+ sort_by: Option<String>,+ sort_order: Option<String>,fields: Option<Vec<String>>,tags: Vec<String>,ctx: CliContext,@@ -1662,6 +1666,18 @@ pub async fn handle_ls(if show_all_hidden {params.push("-a".to_string());}+ if offset != 0 {+ params.push(format!("--offset {}", offset));+ }+ if let Some(limit) = limit {+ params.push(format!("--limit {}", limit));+ }+ if let Some(sort_by) = &sort_by {+ params.push(format!("--sort-by {}", sort_by));+ }+ if let Some(sort_order) = &sort_order {+ params.push(format!("--sort-order {}", sort_order));+ }if !tags.is_empty() {params.push(format!("--tags {}", tags.join(",")));}@@ -1685,6 +1701,10 @@ pub async fn handle_ls(abs_limit,show_all_hidden,node_limit,+ offset,+ limit,+ sort_by.as_deref(),+ sort_order.as_deref(),ctx.output_format,ctx.compact,fields,@@ -1698,6 +1718,8 @@ pub async fn handle_tree(abs_limit: i32,show_all_hidden: bool,node_limit: i32,+ offset: i32,+ limit: Option<i32>,level_limit: i32,simple: bool,fields: Option<Vec<String>>,@@ -1716,6 +1738,12 @@ pub async fn handle_tree(if simple {params.push("-s".to_string());}+ if offset != 0 {+ params.push(format!("--offset {}", offset));+ }+ if let Some(limit) = limit {+ params.push(format!("--limit {}", limit));+ }if !tags.is_empty() {params.push(format!("--tags {}", tags.join(",")));}@@ -1738,6 +1766,8 @@ pub async fn handle_tree(show_all_hidden,node_limit,level_limit,+ offset,+ limit,ctx.output_format,ctx.compact,simple,diff --git a/crates/ov_cli/src/main.rs b/crates/ov_cli/src/main.rsindex 7f1425fa4..2f2aec367 100644--- a/crates/ov_cli/src/main.rs+++ b/crates/ov_cli/src/main.rs@@ -523,13 +523,41 @@ enum Commands {#[arg(long = "node-limit",short = 'n',- alias = "limit",default_value = "256",value_parser = clap::value_parser!(i32).range(0..),value_name = "n",help_heading = "Common options")]node_limit: i32,+ /// Number of visible entries to skip+ #[arg(+ long,+ default_value = "0",+ value_parser = clap::value_parser!(i32).range(0..),+ value_name = "n",+ help_heading = "Common options"+ )]+ offset: i32,+ /// Maximum number of visible entries to return+ #[arg(+ long,+ value_parser = clap::value_parser!(i32).range(1..),+ value_name = "n",+ help_heading = "Common options"+ )]+ limit: Option<i32>,+ /// Sort entries by name or modification time+ #[arg(long, value_parser = ["name", "mtime"], value_name = "field", help_heading = "Common options")]+ sort_by: Option<String>,+ /// Sort direction+ #[arg(+ long,+ requires = "sort_by",+ value_parser = ["asc", "desc"],+ value_name = "order",+ help_heading = "Common options"+ )]+ sort_order: Option<String>,/// Comma-separated fields to display (name,uri,path,type,size,mode,mtime,locked,id,count,tags,abstract)#[arg(short = 'f', long = "fields", value_delimiter = ',', value_name = "FIELDS", help_heading = "Output options")]fields: Option<Vec<String>>,@@ -558,13 +586,29 @@ enum Commands {#[arg(long = "node-limit",short = 'n',- alias = "limit",default_value = "256",value_parser = clap::value_parser!(i32).range(0..),value_name = "n",help_heading = "Common options")]node_limit: i32,+ /// Number of visible entries to skip+ #[arg(+ long,+ default_value = "0",+ value_parser = clap::value_parser!(i32).range(0..),+ value_name = "n",+ help_heading = "Common options"+ )]+ offset: i32,+ /// Maximum number of visible entries to return+ #[arg(+ long,+ value_parser = clap::value_parser!(i32).range(1..),+ value_name = "n",+ help_heading = "Common options"+ )]+ limit: Option<i32>,/// Maximum depth level to traverse (default: 3)#[arg(short = 'L',@@ -3518,19 +3562,57 @@ async fn main() {abs_limit,all,node_limit,+ offset,+ limit,+ sort_by,+ sort_order,fields,tags,- } => handlers::handle_ls(uri, simple, recursive, abs_limit, all, node_limit, fields, tags, ctx).await,+ } => {+ handlers::handle_ls(+ uri,+ simple,+ recursive,+ abs_limit,+ all,+ node_limit,+ offset,+ limit,+ sort_by,+ sort_order,+ fields,+ tags,+ ctx,+ )+ .await+ }Commands::Tree {uri,abs_limit,all,node_limit,+ offset,+ limit,level_limit,simple,fields,tags,- } => handlers::handle_tree(uri, abs_limit, all, node_limit, level_limit, simple, fields, tags, ctx).await,+ } => {+ handlers::handle_tree(+ uri,+ abs_limit,+ all,+ node_limit,+ offset,+ limit,+ level_limit,+ simple,+ fields,+ tags,+ ctx,+ )+ .await+ }Commands::Mkdir { uri, description } => handlers::handle_mkdir(uri, description, ctx).await,Commands::Rm {uri,@@ -4124,8 +4206,61 @@ mod tests {#[test]fn server_commands_require_existing_cli_config() {let cli = Cli::try_parse_from(["ov", "ls"]).expect("ls should parse");+ let paged_ls = Cli::try_parse_from([+ "ov",+ "ls",+ "--offset",+ "4",+ "--limit",+ "5",+ "--sort-by",+ "mtime",+ "--sort-order",+ "desc",+ ])+ .expect("paged ls should parse");+ let paged_tree = Cli::try_parse_from([+ "ov",+ "tree",+ "viking://resources",+ "--offset",+ "6",+ "--limit",+ "7",+ ])+ .expect("paged tree should parse");let health = Cli::try_parse_from(["ov", "health"]).expect("health should parse");+ match paged_ls.command {+ Commands::Ls {+ offset,+ limit,+ sort_by,+ sort_order,+ node_limit,+ ..+ } => {+ assert_eq!(offset, 4);+ assert_eq!(limit, Some(5));+ assert_eq!(sort_by.as_deref(), Some("mtime"));+ assert_eq!(sort_order.as_deref(), Some("desc"));+ assert_eq!(node_limit, 256);+ }+ _ => panic!("expected ls command"),+ }+ match paged_tree.command {+ Commands::Tree {+ offset,+ limit,+ node_limit,+ ..+ } => {+ assert_eq!(offset, 6);+ assert_eq!(limit, Some(7));+ assert_eq!(node_limit, 256);+ }+ _ => panic!("expected tree command"),+ }assert!(cli.command.requires_cli_config_file());assert!(health.command.requires_cli_config_file());}@@ -4996,6 +5131,32 @@ mod tests {"{args:?} should accept a positive node limit");}++ for prefix in [+ vec!["ov", "ls", "--limit"],+ vec!["ov", "tree", "viking://resources", "--limit"],+ ] {+ let mut zero_args = prefix.clone();+ zero_args.push("0");+ assert!(Cli::try_parse_from(&zero_args).is_err());++ let mut positive_args = prefix;+ positive_args.push("1");+ assert!(Cli::try_parse_from(&positive_args).is_ok());+ }++ for prefix in [+ vec!["ov", "ls", "--offset"],+ vec!["ov", "tree", "viking://resources", "--offset"],+ ] {+ let mut negative_args = prefix.clone();+ negative_args.push("-1");+ assert!(Cli::try_parse_from(&negative_args).is_err());++ let mut zero_args = prefix;+ zero_args.push("0");+ assert!(Cli::try_parse_from(&zero_args).is_ok());+ }}#[test]diff --git a/crates/ov_cli/src/tui/tree.rs b/crates/ov_cli/src/tui/tree.rsindex 3f88e50a7..995118183 100644--- a/crates/ov_cli/src/tui/tree.rs+++ b/crates/ov_cli/src/tui/tree.rs@@ -139,7 +139,22 @@ impl TreeState {async fn fetch_children(client: &HttpClient, uri: &str) -> Result<Vec<TreeNode>, String> {let result = client- .ls(uri, false, false, "original", 256, false, 1000, &[], &[], false)+ .ls(+ uri,+ false,+ false,+ "original",+ 256,+ false,+ 1000,+ 0,+ None,+ None,+ None,+ &[],+ &[],+ false,+ ).await.map_err(|e| e.to_string())?;diff --git a/crates/ragfs-python/src/lib.rs b/crates/ragfs-python/src/lib.rsindex f1bc7e842..a3b8fe467 100644--- a/crates/ragfs-python/src/lib.rs+++ b/crates/ragfs-python/src/lib.rs@@ -217,8 +217,8 @@ use ragfs::core::builder::{};use ragfs::core::{build_configured_stack, ConfigValue, FileInfo, FileSystem, FilesystemStats, FsContext,- FsContextInner, FsOperation, GlobPage, GrepResult, MountableFS, OperationStats,- PathLockContext, PluginConfig, RagfsConfig, TreeEntry, WriteFlag, FS_CTX,+ FsContextInner, FsOperation, GlobPage, GrepResult, ListSortBy, MountableFS, OperationStats,+ PathLockContext, PluginConfig, RagfsConfig, SortOrder, TreeEntry, WriteFlag, FS_CTX,};use ragfs::lock::types::PathLockError;use ragfs::lock::{@@ -226,6 +226,43 @@ use ragfs::lock::{PathLockManager, PathLockRequest,};+/// Parse an optional listing sort field and return the matching RagFS value.+fn parse_list_sort_by(value: Option<&str>) -> PyResult<Option<ListSortBy>> {+ match value {+ None => Ok(None),+ Some("name") => Ok(Some(ListSortBy::Name)),+ Some("mtime") => Ok(Some(ListSortBy::Mtime)),+ Some(value) => Err(PyValueError::new_err(format!(+ "sort_by must be 'name' or 'mtime', got {value:?}"+ ))),+ }+}++/// Parse an optional listing sort direction and return the matching RagFS value.+fn parse_sort_order(value: Option<&str>) -> PyResult<Option<SortOrder>> {+ match value {+ None | Some("asc") => Ok(Some(SortOrder::Asc)),+ Some("desc") => Ok(Some(SortOrder::Desc)),+ Some(value) => Err(PyValueError::new_err(format!(+ "sort_order must be 'asc' or 'desc', got {value:?}"+ ))),+ }+}++/// Validate `offset` and return it as an unsigned RagFS offset.+fn parse_listing_offset(offset: i64) -> PyResult<usize> {+ usize::try_from(offset).map_err(|_| PyValueError::new_err("offset must be non-negative"))+}++/// Validate `limit` and return it as an optional unsigned RagFS limit.+fn parse_listing_limit(limit: Option<i64>) -> PyResult<Option<usize>> {+ match limit {+ None => Ok(None),+ Some(value) if value > 0 => Ok(Some(value as usize)),+ Some(_) => Err(PyValueError::new_err("limit must be positive")),+ }+}+/// Parse one Python pathlock request without silently defaulting invalid fields.fn parse_pathlock_request(raw: &HashMap<String, String>) -> PyResult<PathLockRequest> {let path = raw@@ -1599,17 +1636,28 @@ impl RAGFSBindingClient {////// Returns a list of file info dicts with keys:/// name, size, mode, modTime, isDir- #[pyo3(signature = (path, ctx=None))]+ #[pyo3(signature = (path, ctx=None, *, offset=0, limit=None, sort_by=None, sort_order=None))]fn ls(&self,py: Python<'_>,path: String,ctx: Option<HashMap<String, String>>,+ offset: i64,+ limit: Option<i64>,+ sort_by: Option<&str>,+ sort_order: Option<&str>,) -> PyResult<Py<PyAny>> {let fs_ctx = build_fs_context(ctx);let top = self.top.clone();+ let offset = parse_listing_offset(offset)?;+ let limit = parse_listing_limit(limit)?;+ let sort_by = parse_list_sort_by(sort_by)?;+ let sort_order = parse_sort_order(sort_order)?;let entries = self- .run_scoped(py, fs_ctx, move || async move { top.read_dir(&path).await })+ .run_scoped(py, fs_ctx, move || async move {+ top.read_dir(&path, Some(offset), limit, sort_by, sort_order)+ .await+ }).map_err(to_py_err)?;Python::attach(|py| {@@ -2095,7 +2143,7 @@ impl RAGFSBindingClient {////// Returns:/// A list of dicts, each with keys: path, rel_path, info, extra- #[pyo3(signature = (path, show_hidden=false, node_limit=None, level_limit=None, ctx=None))]+ #[pyo3(signature = (path, show_hidden=false, node_limit=None, level_limit=None, ctx=None, *, offset=0, sort_by=None, sort_order=None))]fn tree_directory(&self,py: Python<'_>,@@ -2104,16 +2152,30 @@ impl RAGFSBindingClient {node_limit: Option<i32>,level_limit: Option<i32>,ctx: Option<HashMap<String, String>>,+ offset: i64,+ sort_by: Option<&str>,+ sort_order: Option<&str>,) -> PyResult<Py<PyAny>> {let fs_ctx = build_fs_context(ctx);let top = self.top.clone();let limit = node_limit.map(|n| if n < 0 { 0 } else { n as usize });let level_limit_usize = level_limit.map(|n| if n < 0 { 0 } else { n as usize });+ let offset = parse_listing_offset(offset)?;+ let sort_by = parse_list_sort_by(sort_by)?;+ let sort_order = parse_sort_order(sort_order)?;let entries = self.run_scoped(py, fs_ctx, move || async move {- top.tree_directory(&path, show_hidden, limit, level_limit_usize)- .await+ top.tree_directory(+ &path,+ show_hidden,+ limit,+ level_limit_usize,+ Some(offset),+ sort_by,+ sort_order,+ )+ .await}).map_err(to_py_err)?;diff --git a/crates/ragfs/src/cache/wrapper.rs b/crates/ragfs/src/cache/wrapper.rsindex 1e91a61cc..e2e62e248 100644--- a/crates/ragfs/src/cache/wrapper.rs+++ b/crates/ragfs/src/cache/wrapper.rs@@ -4,12 +4,12 @@ use super::envelope::{CacheEnvelope, CacheObjectKind, GenerationSnapshot};use super::{CacheMetrics, CachePolicy, CacheTraversalMode};use crate::cache_runtime::{CacheError, CacheResult, CacheRuntime, SetOptions, SetResult};use crate::core::filesystem::{- compile_grep_regex, is_excluded_path, normalize_prefix_path, relative_depth,- relative_match_file, sort_directory_entries,+ apply_read_dir_options, compile_grep_regex, is_excluded_path, normalize_prefix_path,+ paginate_entries, relative_depth, relative_match_file,};use crate::core::{- FileInfo, FileSystem, GlobPage, GrepMatch, GrepResult, MultiWriteWrappedFS, Result, TreeEntry,- WriteFlag,+ FileInfo, FileSystem, GlobPage, GrepMatch, GrepResult, ListSortBy, MultiWriteWrappedFS, Result,+ SortOrder, TreeEntry, WriteFlag,};use async_trait::async_trait;use bytes::Bytes;@@ -124,6 +124,9 @@ impl CachedFileSystem {show_hidden: bool,node_limit: Option<usize>,level_limit: Option<usize>,+ offset: Option<usize>,+ sort_by: Option<ListSortBy>,+ sort_order: Option<SortOrder>,) -> Result<Vec<TreeEntry>> {enum TreeTask {VisitDir(String),@@ -133,9 +136,10 @@ impl CachedFileSystem {let base_path = normalize_prefix_path(path);let mut result = Vec::new();let mut stack = vec![TreeTask::VisitDir(base_path.clone())];+ let traversal_limit = node_limit.map(|limit| offset.unwrap_or(0).saturating_add(limit));while let Some(task) = stack.pop() {- if node_limit.is_some_and(|limit| result.len() >= limit) {+ if traversal_limit.is_some_and(|limit| result.len() >= limit) {break;}@@ -149,8 +153,9 @@ impl CachedFileSystem {}}- let mut entries = self.read_dir(¤t_path).await?;- sort_directory_entries(&mut entries);+ let entries = self+ .read_dir(¤t_path, None, None, sort_by, sort_order)+ .await?;for entry in entries.into_iter().rev() {let is_hidden_file = !entry.is_dir && entry.name.starts_with('.');if is_hidden_file && !show_hidden {@@ -180,7 +185,7 @@ impl CachedFileSystem {}}- Ok(result)+ Ok(paginate_entries(result, offset, node_limit))}async fn grep_via_cache(@@ -846,13 +851,13 @@ impl CachedFileSystem {) -> Result<Vec<FileInfo>> {if !self.policy.cache_directory(path) || self.is_runtime_bypassed(path).await {self.metrics.policy_bypass();- return self.backend.read_dir(path).await;+ return self.backend.read_dir(path, None, None, None, None).await;}let _operation_guard = self.operation_lock.read().await;if self.is_runtime_bypassed(path).await {self.metrics.policy_bypass();- return self.backend.read_dir(path).await;+ return self.backend.read_dir(path, None, None, None, None).await;}let normalized = normalize_path(path);@@ -890,7 +895,7 @@ impl CachedFileSystem {}}- let entries = self.backend.read_dir(path).await;+ let entries = self.backend.read_dir(path, None, None, None, None).await;if let Ok(value) = &entries {self.metrics.backend_fallback(0);self.fill_directory(&key, &normalized, value).await;@@ -1082,22 +1087,37 @@ impl FileSystem for CachedFileSystem {Ok(written)}- async fn read_dir(&self, path: &str) -> Result<Vec<FileInfo>> {+ async fn read_dir(+ &self,+ path: &str,+ offset: Option<usize>,+ limit: Option<usize>,+ sort_by: Option<ListSortBy>,+ sort_order: Option<SortOrder>,+ ) -> Result<Vec<FileInfo>> {if !self.policy.cache_directory(path) || self.is_runtime_bypassed(path).await {self.metrics.policy_bypass();- return self.backend.read_dir(path).await;+ return self+ .backend+ .read_dir(path, offset, limit, sort_by, sort_order)+ .await;}let _operation_guard = self.operation_lock.read().await;if self.is_runtime_bypassed(path).await {self.metrics.policy_bypass();- return self.backend.read_dir(path).await;+ return self+ .backend+ .read_dir(path, offset, limit, sort_by, sort_order)+ .await;}let normalized = normalize_path(path);let key = self.directory_key(&normalized);if let Some(entries) = self.probe_directory(&key, &normalized, true).await {- return Ok(entries);+ return Ok(apply_read_dir_options(+ entries, offset, limit, sort_by, sort_order,+ ));}self.metrics.read_dir_miss();@@ -1114,18 +1134,20 @@ impl FileSystem for CachedFileSystem {self.metrics.inflight_backend_saved();drop(inflight_guard);self.release_inflight(&key, &inflight).await;- return Ok(entries);+ return Ok(apply_read_dir_options(+ entries, offset, limit, sort_by, sort_order,+ ));}}- let entries = self.backend.read_dir(path).await;+ let entries = self.backend.read_dir(path, None, None, None, None).await;if let Ok(value) = &entries {self.metrics.backend_fallback(0);self.fill_directory(&key, &normalized, value).await;}drop(inflight_guard);self.release_inflight(&key, &inflight).await;- entries+ entries.map(|entries| apply_read_dir_options(entries, offset, limit, sort_by, sort_order))}async fn stat(&self, path: &str) -> Result<FileInfo> {@@ -1230,17 +1252,36 @@ impl FileSystem for CachedFileSystem {show_hidden: bool,node_limit: Option<usize>,level_limit: Option<usize>,+ offset: Option<usize>,+ sort_by: Option<ListSortBy>,+ sort_order: Option<SortOrder>,) -> Result<Vec<TreeEntry>> {if self.policy.traversal_mode() == CacheTraversalMode::CachedTraversal&& !self.wraps_multiwrite(){return self- .tree_directory_via_cache(path, show_hidden, node_limit, level_limit)+ .tree_directory_via_cache(+ path,+ show_hidden,+ node_limit,+ level_limit,+ offset,+ sort_by,+ sort_order,+ ).await;}self.backend- .tree_directory(path, show_hidden, node_limit, level_limit)+ .tree_directory(+ path,+ show_hidden,+ node_limit,+ level_limit,+ offset,+ sort_by,+ sort_order,+ ).await}diff --git a/crates/ragfs/src/core/encryption_wrapper.rs b/crates/ragfs/src/core/encryption_wrapper.rsindex 6d014749d..9237b1596 100644--- a/crates/ragfs/src/core/encryption_wrapper.rs+++ b/crates/ragfs/src/core/encryption_wrapper.rs@@ -16,17 +16,17 @@ use async_trait::async_trait;use sha2::{Digest, Sha256};use tracing::{debug, warn};-use crate::crypto;use crate::core::internal_names::is_hidden_runtime_lock_name;-use crate::lock::{- AutoPathLockAction, PathLockKind, PathLockManager, PathLockRequest,-};+use crate::crypto;+use crate::lock::{AutoPathLockAction, PathLockKind, PathLockManager, PathLockRequest};use crate::shape::SHAPE_MANIFEST_PATH;use super::context::FsContextView;use super::errors::{Error, Result};-use super::filesystem::{compile_grep_regex, normalize_prefix_path, FileSystem};-use super::types::{FileInfo, GlobPage, GrepResult, TreeEntry, WriteFlag};+use super::filesystem::{+ apply_read_dir_options, compile_grep_regex, normalize_prefix_path, paginate_entries, FileSystem,+};+use super::types::{FileInfo, GlobPage, GrepResult, ListSortBy, SortOrder, TreeEntry, WriteFlag};const SYSTEM_ACCOUNT_ID: &str = "_system";const TEMP_ROOT_CACHE_TTL: Duration = Duration::from_secs(15 * 60);@@ -182,7 +182,10 @@ impl EncryptionWrappedFS {} else {format!("/{}", path)};- let parts: Vec<&str> = normalized.split('/').filter(|part| !part.is_empty()).collect();+ let parts: Vec<&str> = normalized+ .split('/')+ .filter(|part| !part.is_empty())+ .collect();match parts.as_slice() {["local", account_id, ..] => format!("/local/{}/temp/.encrypt_stage", account_id),[mount_root, _, ..] => format!("/{}/temp/.encrypt_stage", mount_root),@@ -275,7 +278,6 @@ impl EncryptionWrappedFS {}Ok(written)}-}/// Slice `data` by `(offset, size)` with `size == 0` meaning "to end", matching plugin read semantics.@@ -379,7 +381,10 @@ impl FileSystem for EncryptionWrappedFS {kind: PathLockKind::Exact,};let requests = vec![- PathLockRequest { path: temp_lock_path, kind: PathLockKind::Exact },+ PathLockRequest {+ path: temp_lock_path,+ kind: PathLockKind::Exact,+ },final_request.clone(),];let action = self@@ -389,22 +394,20 @@ impl FileSystem for EncryptionWrappedFS {.map_err(|error| {Error::internal(format!("encrypted write lock context error: {error}"))})?;- let action_name = match &action { AutoPathLockAction::Disabled => "disabled", AutoPathLockAction::Covered(_) => "covered", AutoPathLockAction::Acquire => "acquire" };+ let action_name = match &action {+ AutoPathLockAction::Disabled => "disabled",+ AutoPathLockAction::Covered(_) => "covered",+ AutoPathLockAction::Acquire => "acquire",+ };debug!(path = %path, temp_path = %temp_path, final_lock_path = %requests[1].path, temp_lock_path = %requests[0].path, action = %action_name, "encrypted write resolved dual-path pathlock action");let lock_guard = match action {AutoPathLockAction::Disabled => None,AutoPathLockAction::Covered(outer) => {- let owner_capability = (- outer.lease.lease_ref.as_str(),- outer.ownership_ref.as_str(),- );+ let owner_capability =+ (outer.lease.lease_ref.as_str(), outer.ownership_ref.as_str());Some(self.pathlock_manager- .acquire_batch(- &requests,- Duration::from_secs(1),- Some(owner_capability),- )+ .acquire_batch(&requests, Duration::from_secs(1), Some(owner_capability)).await.map_err(|error| {Error::internal(format!("encrypted write lock error: {error}"))@@ -422,7 +425,9 @@ impl FileSystem for EncryptionWrappedFS {};// Release lock on error. On success, release after replace.- let result = self.encrypted_write_inner(path, &temp_path, &envelope).await;+ let result = self+ .encrypted_write_inner(path, &temp_path, &envelope)+ .await;let replace_result = match result {Ok(written) => self.inner.replace(&temp_path, path).await.map(|_| written),Err(e) => Err(e),@@ -512,12 +517,22 @@ impl FileSystem for EncryptionWrappedFS {self.inner.remove_all(path).await}- async fn read_dir(&self, path: &str) -> Result<Vec<FileInfo>> {- let entries = self.inner.read_dir(path).await?;- Ok(entries+ async fn read_dir(+ &self,+ path: &str,+ offset: Option<usize>,+ limit: Option<usize>,+ sort_by: Option<ListSortBy>,+ sort_order: Option<SortOrder>,+ ) -> Result<Vec<FileInfo>> {+ let entries = self.inner.read_dir(path, None, None, None, None).await?;+ let entries = entries.into_iter().filter(|entry| entry.name != SHAPE_MANIFEST_PATH.trim_start_matches('/'))- .collect())+ .collect();+ Ok(apply_read_dir_options(+ entries, offset, limit, sort_by, sort_order,+ ))}async fn stat(&self, path: &str) -> Result<FileInfo> {@@ -541,16 +556,28 @@ impl FileSystem for EncryptionWrappedFS {show_hidden: bool,node_limit: Option<usize>,level_limit: Option<usize>,+ offset: Option<usize>,+ sort_by: Option<ListSortBy>,+ sort_order: Option<SortOrder>,) -> Result<Vec<TreeEntry>> {// Metadata only — no content read, so delegate to preserve plugin-native tree optimizations.let entries = self.inner- .tree_directory(path, show_hidden, node_limit, level_limit)+ .tree_directory(+ path,+ show_hidden,+ None,+ level_limit,+ None,+ sort_by,+ sort_order,+ ).await?;- Ok(entries+ let entries = entries.into_iter().filter(|entry| !Self::is_shape_manifest_path(&entry.path))- .collect())+ .collect();+ Ok(paginate_entries(entries, offset, node_limit))}async fn glob_directory(@@ -594,9 +621,7 @@ mod tests {use crate::core::context::{FsContextInner, FS_CTX};use crate::core::MountableFS;use crate::core::PluginConfig;- use crate::lock::{- MemoryPathLockProvider, PathLockConfig, PathLockManager, PathLockProvider,- };+ use crate::lock::{MemoryPathLockProvider, PathLockConfig, PathLockManager, PathLockProvider};use crate::plugins::MemFSPlugin;/// Build a memfs plugin config for encryption wrapper tests.@@ -928,12 +953,7 @@ mod tests {}).await;- assert!(- inner- .stat(temp_path)- .await- .is_err()- );+ assert!(inner.stat(temp_path).await.is_err());let raw = inner.read("/mem/a.txt", 0, 0).await.unwrap();assert!(crypto::is_encrypted(&raw));}@@ -960,7 +980,10 @@ mod tests {];for (final_path, temp_path) in cases {- assert_eq!(EncryptionWrappedFS::encrypted_temp_path(final_path), temp_path);+ assert_eq!(+ EncryptionWrappedFS::encrypted_temp_path(final_path),+ temp_path+ );}}}diff --git a/crates/ragfs/src/core/filesystem.rs b/crates/ragfs/src/core/filesystem.rsindex 7a9c7965e..429341f0b 100644--- a/crates/ragfs/src/core/filesystem.rs+++ b/crates/ragfs/src/core/filesystem.rs@@ -12,7 +12,9 @@ use std::path::{Component, Path};use super::errors::{Error, Result};use super::glob::{compare_rel_paths, decode_offset_token, encode_offset_token, PreparedGlob};-use super::types::{FileInfo, GlobEntry, GlobPage, GrepResult, TreeEntry, WriteFlag};+use super::types::{+ FileInfo, GlobEntry, GlobPage, GrepResult, ListSortBy, SortOrder, TreeEntry, WriteFlag,+};/// Reject virtual paths that can escape a mounted backend lexically.pub(crate) fn validate_virtual_path(path: &str) -> Result<()> {@@ -53,6 +55,70 @@ pub(crate) fn sort_directory_entries(entries: &mut [FileInfo]) {});}+/// Sort entries by `sort_by` and `sort_order`, keeping directories before files.+///+/// Returns through the mutable `entries` slice.+pub(crate) fn sort_directory_entries_by(+ entries: &mut [FileInfo],+ sort_by: Option<ListSortBy>,+ sort_order: Option<SortOrder>,+) {+ let Some(sort_by) = sort_by else {+ return;+ };+ let descending = matches!(sort_order, Some(SortOrder::Desc));+ entries.sort_by(|a, b| {+ let group_order = b.is_dir.cmp(&a.is_dir);+ if group_order != Ordering::Equal {+ return group_order;+ }+ match sort_by {+ ListSortBy::Name => {+ let order = compare_listing_names(&a.name, &b.name);+ if descending {+ order.reverse()+ } else {+ order+ }+ }+ ListSortBy::Mtime => {+ let order = a.mod_time.cmp(&b.mod_time);+ let order = if descending { order.reverse() } else { order };+ order.then_with(|| compare_listing_names(&a.name, &b.name))+ }+ }+ });+}++/// Consume `entries` and return the range selected by `offset` and `limit`.+pub(crate) fn paginate_entries<T>(+ entries: Vec<T>,+ offset: Option<usize>,+ limit: Option<usize>,+) -> Vec<T> {+ entries+ .into_iter()+ .skip(offset.unwrap_or(0))+ .take(limit.unwrap_or(usize::MAX))+ .collect()+}++/// Apply the requested sorting and pagination options and return the selected entries.+pub(crate) fn apply_read_dir_options(+ mut entries: Vec<FileInfo>,+ offset: Option<usize>,+ limit: Option<usize>,+ sort_by: Option<ListSortBy>,+ sort_order: Option<SortOrder>,+) -> Vec<FileInfo> {+ if sort_by.is_some() {+ sort_directory_entries_by(&mut entries, sort_by, sort_order);+ } else {+ sort_directory_entries(&mut entries);+ }+ paginate_entries(entries, offset, limit)+}+/// Check whether `path` is under `exclude_path` (including itself).pub(crate) fn is_excluded_path(path: &str, exclude_path: &str) -> bool {if exclude_path == "/" {@@ -247,6 +313,10 @@ pub trait FileSystem: Send + Sync + Any {////// # Arguments/// * `path` - The path of the directory to list+ /// * `offset` - Number of sorted entries to skip+ /// * `limit` - Maximum number of entries to return+ /// * `sort_by` - Optional field used to sort entries+ /// * `sort_order` - Optional sort direction////// # Returns/// A vector of FileInfo for each entry in the directory@@ -254,7 +324,14 @@ pub trait FileSystem: Send + Sync + Any {/// # Errors/// * `Error::NotFound` - If the directory doesn't exist/// * `Error::NotADirectory` - If the path is not a directory- async fn read_dir(&self, path: &str) -> Result<Vec<FileInfo>>;+ async fn read_dir(+ &self,+ path: &str,+ offset: Option<usize>,+ limit: Option<usize>,+ sort_by: Option<ListSortBy>,+ sort_order: Option<SortOrder>,+ ) -> Result<Vec<FileInfo>>;/// List directory contents without public internal-name filtering.///@@ -264,7 +341,7 @@ pub trait FileSystem: Send + Sync + Any {/// # Returns/// Raw directory entries visible to filesystem internals.async fn read_internal_dir(&self, path: &str) -> Result<Vec<FileInfo>> {- self.read_dir(path).await+ self.read_dir(path, None, None, None, None).await}/// Get file or directory metadata@@ -431,7 +508,7 @@ pub trait FileSystem: Send + Sync + Any {}}- let entries = self.read_dir(current_path).await?;+ let entries = self.read_dir(current_path, None, None, None, None).await?;for entry in entries {if node_limit.is_some_and(|limit| result.count >= limit) {@@ -514,6 +591,9 @@ pub trait FileSystem: Send + Sync + Any {/// * `show_hidden` - Whether to include hidden files (names starting with `.`)/// * `node_limit` - Maximum number of nodes to return (None means no limit)/// * `level_limit` - Maximum depth relative to query root (None means no limit)+ /// * `offset` - Number of flattened DFS entries to skip+ /// * `sort_by` - Optional sibling sort field+ /// * `sort_order` - Optional sibling sort direction////// # Returns/// A flat `Vec<TreeEntry>` in DFS order (directories before their children).@@ -523,21 +603,27 @@ pub trait FileSystem: Send + Sync + Any {show_hidden: bool,node_limit: Option<usize>,level_limit: Option<usize>,+ offset: Option<usize>,+ sort_by: Option<ListSortBy>,+ sort_order: Option<SortOrder>,) -> Result<Vec<TreeEntry>> {let normalized_path = normalize_prefix_path(path);let mut result = Vec::new();+ let traversal_limit = node_limit.map(|limit| offset.unwrap_or(0).saturating_add(limit));self.tree_directory_internal(normalized_path.as_str(),normalized_path.as_str(),show_hidden,- node_limit,+ traversal_limit,level_limit,+ sort_by,+ sort_order,&mut result,).await?;- Ok(result)+ Ok(paginate_entries(result, offset, node_limit))}/// Return one page of flat glob results under `path`.@@ -560,7 +646,7 @@ pub trait FileSystem: Send + Sync + Any {}let entries = self- .tree_directory(path, show_hidden, None, level_limit)+ .tree_directory(path, show_hidden, None, level_limit, None, None, None).await?;let mut matched = Vec::new();@@ -607,6 +693,8 @@ pub trait FileSystem: Send + Sync + Any {/// * `show_hidden` - Whether to include hidden files/// * `node_limit` - Maximum number of nodes to return/// * `level_limit` - Maximum depth relative to base_path+ /// * `sort_by` - Optional sibling sort field+ /// * `sort_order` - Optional sibling sort direction/// * `result` - Accumulator for the flat result listasync fn tree_directory_internal(&self,@@ -615,6 +703,8 @@ pub trait FileSystem: Send + Sync + Any {show_hidden: bool,node_limit: Option<usize>,level_limit: Option<usize>,+ sort_by: Option<ListSortBy>,+ sort_order: Option<SortOrder>,result: &mut Vec<TreeEntry>,) -> Result<()> {if node_limit.is_some_and(|limit| result.len() >= limit) {@@ -633,8 +723,9 @@ pub trait FileSystem: Send + Sync + Any {}}- let mut entries = self.read_dir(current_path).await?;+ let mut entries = self.read_dir(current_path, None, None, None, None).await?;sort_directory_entries(&mut entries);+ sort_directory_entries_by(&mut entries, sort_by, sort_order);for entry in entries {if node_limit.is_some_and(|limit| result.len() >= limit) {@@ -668,6 +759,8 @@ pub trait FileSystem: Send + Sync + Any {show_hidden,node_limit,level_limit,+ sort_by,+ sort_order,result,).await?;@@ -756,7 +849,14 @@ mod tests {Ok(_data.len() as u64)}- async fn read_dir(&self, _path: &str) -> Result<Vec<FileInfo>> {+ async fn read_dir(+ &self,+ _path: &str,+ _offset: Option<usize>,+ _limit: Option<usize>,+ _sort_by: Option<ListSortBy>,+ _sort_order: Option<SortOrder>,+ ) -> Result<Vec<FileInfo>> {Ok(vec![])}@@ -846,12 +946,22 @@ mod tests {Ok(data.len() as u64)}- async fn read_dir(&self, path: &str) -> Result<Vec<FileInfo>> {+ async fn read_dir(+ &self,+ path: &str,+ offset: Option<usize>,+ limit: Option<usize>,+ sort_by: Option<ListSortBy>,+ sort_order: Option<SortOrder>,+ ) -> Result<Vec<FileInfo>> {let entries = self.dirs.get(path).cloned().unwrap_or_default();- Ok(entries+ let entries = entries.into_iter().map(|(name, is_dir)| TreeFS::file_info(name, is_dir))- .collect())+ .collect::<Vec<_>>();+ Ok(apply_read_dir_options(+ entries, offset, limit, sort_by, sort_order,+ ))}async fn stat(&self, path: &str) -> Result<FileInfo> {@@ -954,9 +1064,17 @@ mod tests {node_limit: Option<usize>,level_limit: Option<usize>,) -> Vec<TreeEntry> {- fs.tree_directory("/root", show_hidden, node_limit, level_limit)- .await- .unwrap()+ fs.tree_directory(+ "/root",+ show_hidden,+ node_limit,+ level_limit,+ None,+ None,+ None,+ )+ .await+ .unwrap()}/// Assert tree entry names in order.@@ -987,14 +1105,52 @@ mod tests {async fn test_tree_single_layer_files() {let fs = TreeFS::default().with_dir_entries("/root",- vec![("a.txt", false), ("b.txt", false), ("c.txt", false)],+ vec![("c.txt", false), ("a.txt", false), ("b.txt", false)],);let entries = root_tree(&fs, false, None, None).await;+ let default_page = fs+ .read_dir("/root", Some(1), Some(1), None, None)+ .await+ .unwrap();+ let page = fs+ .read_dir(+ "/root",+ Some(1),+ Some(1),+ Some(ListSortBy::Name),+ Some(SortOrder::Desc),+ )+ .await+ .unwrap();assert_eq!(entries.len(), 3);assert_tree_names(&entries, &["a.txt", "b.txt", "c.txt"]);assert_tree_rel_paths(&entries, &["a.txt", "b.txt", "c.txt"]);+ assert_eq!(default_page[0].name, "b.txt");+ assert_eq!(page[0].name, "b.txt");++ let mut by_mtime = vec![+ TreeFS::file_info("a.txt".to_string(), false),+ TreeFS::file_info("b.txt".to_string(), false),+ TreeFS::file_info("c.txt".to_string(), false),+ ];+ by_mtime[0].mod_time = std::time::UNIX_EPOCH + std::time::Duration::from_secs(1);+ by_mtime[1].mod_time = std::time::UNIX_EPOCH + std::time::Duration::from_secs(2);+ by_mtime[2].mod_time = std::time::UNIX_EPOCH + std::time::Duration::from_secs(2);+ let page = apply_read_dir_options(+ by_mtime,+ None,+ Some(2),+ Some(ListSortBy::Mtime),+ Some(SortOrder::Desc),+ );+ assert_eq!(+ page.iter()+ .map(|entry| entry.name.as_str())+ .collect::<Vec<_>>(),+ vec!["b.txt", "c.txt"]+ );}#[tokio::test]@@ -1035,10 +1191,21 @@ mod tests {],);- let entries = root_tree(&fs, false, Some(3), None).await;+ let entries = fs+ .tree_directory(+ "/root",+ false,+ Some(3),+ None,+ Some(1),+ Some(ListSortBy::Name),+ Some(SortOrder::Asc),+ )+ .await+ .unwrap();assert_eq!(entries.len(), 3);- assert_tree_names(&entries, &["a.txt", "b.txt", "c.txt"]);+ assert_tree_names(&entries, &["b.txt", "c.txt", "d.txt"]);}#[tokio::test]@@ -1135,7 +1302,10 @@ mod tests {async fn test_tree_root_path() {let fs = TreeFS::default().with_dir_entries("/", vec![("a.txt", false), ("sub", true)]);- let entries = fs.tree_directory("/", false, None, None).await.unwrap();+ let entries = fs+ .tree_directory("/", false, None, None, None, None, None)+ .await+ .unwrap();assert_eq!(entries.len(), 2);assert_eq!(entries[0].path, "/sub");@@ -1151,7 +1321,10 @@ mod tests {.with_dir_entries("/a/b/c/d", vec![("e", true)]).with_dir_entries("/a/b/c/d/e", vec![("f.txt", false)]);- let entries = fs.tree_directory("/a", false, None, None).await.unwrap();+ let entries = fs+ .tree_directory("/a", false, None, None, None, None, None)+ .await+ .unwrap();assert_eq!(entries.len(), 5);assert_eq!(diff --git a/crates/ragfs/src/core/mod.rs b/crates/ragfs/src/core/mod.rsindex 0d8bdcdcc..632af6545 100644--- a/crates/ragfs/src/core/mod.rs+++ b/crates/ragfs/src/core/mod.rs@@ -23,14 +23,14 @@ pub mod types;// Re-export commonly used typespub use crate::multibackend::{FsContextResolver, MetaStateStore};-pub use builder::{- build_default_stack, build_stack_with_mountable, register_builtin_plugins,- EncryptionConfig as BuilderEncryptionConfig, RagfsConfig, RagfsStack,-};#[cfg(feature = "cache")]pub use builder::{build_configured_stack, CacheFsConfig, CacheRuntimeProviderConfig, CacheStackConfig,};+pub use builder::{+ build_default_stack, build_stack_with_mountable, register_builtin_plugins,+ EncryptionConfig as BuilderEncryptionConfig, RagfsConfig, RagfsStack,+};pub use context::{FsContext, FsContextInner, FsContextView, PathLockContext, FS_CTX};pub use encryption_wrapper::EncryptionWrappedFS;pub use errors::{Error, Result};@@ -42,7 +42,7 @@ pub use stats::{FilesystemStats, FsOperation, OperationStats, OperationTimer, Stpub use stats_wrapper::StatsWrappedFS;pub use types::{BackendItemConfig, BackendRole, BackendSyncState, BackendsConfig, ConfigParameter, ConfigValue,- EncryptionConfig, FileInfo, GlobEntry, GlobPage, GrepMatch, GrepResult,- OperationItemConfig, PluginConfig, RedirectEntry, RedirectMeta, RedirectPolicy,+ EncryptionConfig, FileInfo, GlobEntry, GlobPage, GrepMatch, GrepResult, ListSortBy,+ OperationItemConfig, PluginConfig, RedirectEntry, RedirectMeta, RedirectPolicy, SortOrder,SyncLogEntry, SyncLogMeta, SyncOp, SyncType, TreeEntry, WriteFlag,};diff --git a/crates/ragfs/src/core/mountable.rs b/crates/ragfs/src/core/mountable.rsindex f6ecbe3b5..a6c1bda4a 100644--- a/crates/ragfs/src/core/mountable.rs+++ b/crates/ragfs/src/core/mountable.rs@@ -23,7 +23,10 @@ use super::internal_names::is_hidden_internal_name;use super::encryption_wrapper::EncryptionWrappedFS;use super::errors::{Error, Result};-use super::filesystem::{sort_directory_entries, validate_virtual_path, FileSystem};+use super::filesystem::{+ apply_read_dir_options, paginate_entries, sort_directory_entries, validate_virtual_path,+ FileSystem,+};use super::multibackend_wrapper::MultiWriteWrappedFS;use super::plugin::ServicePlugin;use super::stats::{FilesystemStats, StatsCollector};@@ -809,8 +812,17 @@ impl FileSystem for ArcFileSystem {self.0.write(path, data, offset, flags).await}- async fn read_dir(&self, path: &str) -> Result<Vec<FileInfo>> {- self.0.read_dir(path).await+ async fn read_dir(+ &self,+ path: &str,+ offset: Option<usize>,+ limit: Option<usize>,+ sort_by: Option<crate::core::ListSortBy>,+ sort_order: Option<crate::core::SortOrder>,+ ) -> Result<Vec<FileInfo>> {+ self.0+ .read_dir(path, offset, limit, sort_by, sort_order)+ .await}async fn stat(&self, path: &str) -> Result<FileInfo> {@@ -958,11 +970,20 @@ impl FileSystem for MountableFS {Ok(changed)}- async fn read_dir(&self, path: &str) -> Result<Vec<FileInfo>> {+ async fn read_dir(+ &self,+ path: &str,+ offset: Option<usize>,+ limit: Option<usize>,+ sort_by: Option<crate::core::ListSortBy>,+ sort_order: Option<crate::core::SortOrder>,+ ) -> Result<Vec<FileInfo>> {let mut entries = self.read_internal_dir(path).await?;entries.retain(|entry| !is_hidden_internal_name(&entry.name));sort_directory_entries(&mut entries);- Ok(entries)+ Ok(apply_read_dir_options(+ entries, offset, limit, sort_by, sort_order,+ ))}async fn read_internal_dir(&self, path: &str) -> Result<Vec<FileInfo>> {@@ -1080,6 +1101,9 @@ impl FileSystem for MountableFS {show_hidden: bool,node_limit: Option<usize>,level_limit: Option<usize>,+ offset: Option<usize>,+ sort_by: Option<crate::core::ListSortBy>,+ sort_order: Option<crate::core::SortOrder>,) -> Result<Vec<TreeEntry>> {let (mount_info, rel_path) = self.find_mount(path).await?;@@ -1091,7 +1115,15 @@ impl FileSystem for MountableFS {let mut entries = mount_info.fs- .tree_directory(&rel_path, show_hidden, node_limit, level_limit)+ .tree_directory(+ &rel_path,+ show_hidden,+ None,+ level_limit,+ None,+ sort_by,+ sort_order,+ ).await?;for entry in &mut entries {@@ -1112,7 +1144,7 @@ impl FileSystem for MountableFS {.map_or(true, |name| !is_hidden_internal_name(name))});- Ok(entries)+ Ok(paginate_entries(entries, offset, node_limit))}async fn glob_directory(@@ -1277,7 +1309,14 @@ mod tests {Ok(data.len() as u64)}- async fn read_dir(&self, _path: &str) -> Result<Vec<FileInfo>> {+ async fn read_dir(+ &self,+ _path: &str,+ _offset: Option<usize>,+ _limit: Option<usize>,+ _sort_by: Option<crate::core::ListSortBy>,+ _sort_order: Option<crate::core::SortOrder>,+ ) -> Result<Vec<FileInfo>> {Ok(self.tree_entries.iter()@@ -1319,6 +1358,9 @@ mod tests {_show_hidden: bool,_node_limit: Option<usize>,_level_limit: Option<usize>,+ _offset: Option<usize>,+ _sort_by: Option<crate::core::ListSortBy>,+ _sort_order: Option<crate::core::SortOrder>,) -> Result<Vec<TreeEntry>> {Ok(self.tree_entries.clone())}@@ -1412,7 +1454,14 @@ mod tests {Ok(data.len() as u64)}- async fn read_dir(&self, _path: &str) -> Result<Vec<FileInfo>> {+ async fn read_dir(+ &self,+ _path: &str,+ _offset: Option<usize>,+ _limit: Option<usize>,+ _sort_by: Option<crate::core::ListSortBy>,+ _sort_order: Option<crate::core::SortOrder>,+ ) -> Result<Vec<FileInfo>> {Ok(vec![])}@@ -1739,7 +1788,7 @@ mod tests {assert_eq!(mfs.read("/local/dir/b.md", 0, 0).await.unwrap(), b"old");assert_eq!(- mfs.read_dir("/local/dir")+ mfs.read_dir("/local/dir", None, None, None, None).await.unwrap().into_iter()@@ -1756,7 +1805,7 @@ mod tests {let copied = mfs.read("/local/dir/b.md", 0, 0).await.unwrap();let copied_size = mfs- .read_dir("/local/dir")+ .read_dir("/local/dir", None, None, None, None).await.unwrap().into_iter()@@ -2148,13 +2197,14 @@ mod tests {make_tree_entry("/A.txt", "A.txt", "A.txt", false),make_tree_entry("/c", "c", "c", true),make_tree_entry("/B", "B", "B", true),+ make_tree_entry("/.path.ovlock", ".path.ovlock", ".path.ovlock", false),],);mfs.register_plugin(plugin).await;mfs.mount(test_config("sorted", "/sorted")).await.unwrap();let names: Vec<String> = mfs- .read_dir("/sorted")+ .read_dir("/sorted", None, None, None, None).await.unwrap().into_iter()@@ -2162,13 +2212,28 @@ mod tests {.collect();assert_eq!(names, vec!["B", "c", "A.txt", "b.txt"]);++ let page: Vec<String> = mfs+ .read_dir(+ "/sorted",+ Some(1),+ Some(2),+ Some(crate::core::ListSortBy::Name),+ Some(crate::core::SortOrder::Desc),+ )+ .await+ .unwrap()+ .into_iter()+ .map(|entry| entry.name)+ .collect();+ assert_eq!(page, vec!["B", "b.txt"]);}#[tokio::test]async fn test_tree_directory_no_mount_returns_error() {let mfs = MountableFS::new();let result = mfs- .tree_directory("/nonexistent/subdir", false, None, None)+ .tree_directory("/nonexistent/subdir", false, None, None, None, None, None).await;assert!(result.is_err());}@@ -2189,7 +2254,7 @@ mod tests {mfs.mount(test_config("rewrite", "/rewrite")).await.unwrap();let result = mfs- .tree_directory("/rewrite/sub", false, None, None)+ .tree_directory("/rewrite/sub", false, None, None, None, None, None).await.unwrap();assert_eq!(result.len(), 1);@@ -2210,7 +2275,7 @@ mod tests {.unwrap();let result = mfs- .tree_directory("/local/test_account/a", false, None, None)+ .tree_directory("/local/test_account/a", false, None, None, None, None, None).await.unwrap();assert_eq!(result.len(), 1);diff --git a/crates/ragfs/src/core/multibackend_wrapper.rs b/crates/ragfs/src/core/multibackend_wrapper.rsindex 4c2804859..b0b89777d 100644--- a/crates/ragfs/src/core/multibackend_wrapper.rs+++ b/crates/ragfs/src/core/multibackend_wrapper.rs@@ -22,10 +22,14 @@ use tokio::sync::{Mutex, Notify};use super::context::{FsContext, FS_CTX};use super::encryption_wrapper::EncryptionWrappedFS;use super::errors::{Error, Result};-use super::filesystem::{normalize_prefix_path, relative_depth, relative_match_file, FileSystem};+use super::filesystem::{+ apply_read_dir_options, normalize_prefix_path, paginate_entries, relative_depth,+ relative_match_file, FileSystem,+};use super::types::{- BackendRole, BackendSyncState, FileInfo, GlobEntry, GlobPage, GrepResult, OperationItemConfig,- RedirectEntry, RedirectPolicy, SyncLogEntry, SyncOp, SyncType, TreeEntry, WriteFlag,+ BackendRole, BackendSyncState, FileInfo, GlobEntry, GlobPage, GrepResult, ListSortBy,+ OperationItemConfig, RedirectEntry, RedirectPolicy, SortOrder, SyncLogEntry, SyncOp, SyncType,+ TreeEntry, WriteFlag,};use crate::core::glob::{compare_rel_paths, decode_offset_token, encode_offset_token, PreparedGlob,@@ -1390,15 +1394,28 @@ impl FileSystem for MultiWriteWrappedFS {.await}- async fn read_dir(&self, path: &str) -> Result<Vec<FileInfo>> {+ async fn read_dir(+ &self,+ path: &str,+ offset: Option<usize>,+ limit: Option<usize>,+ sort_by: Option<ListSortBy>,+ sort_order: Option<SortOrder>,+ ) -> Result<Vec<FileInfo>> {let inner = &self.inner;- let mut entries = inner.primary().backend.read_dir(path).await?;+ let mut entries = inner+ .primary()+ .backend+ .read_dir(path, None, None, None, None)+ .await?;// Filter multi-write internal names.entries.retain(|e| !MULTIWRITE_INTERNAL_NAMES.contains(&e.name.as_str()));if inner.redirects.is_empty() {- return Ok(entries);+ return Ok(apply_read_dir_options(+ entries, offset, limit, sort_by, sort_order,+ ));}// Merge redirect entries so users can see redirected files in listings.@@ -1422,7 +1439,9 @@ impl FileSystem for MultiWriteWrappedFS {}}- Ok(entries)+ Ok(apply_read_dir_options(+ entries, offset, limit, sort_by, sort_order,+ ))}async fn stat(&self, path: &str) -> Result<FileInfo> {@@ -1439,7 +1458,12 @@ impl FileSystem for MultiWriteWrappedFS {if is_hidden_internal_name(file_name(old_path))|| is_hidden_internal_name(file_name(new_path)){- return self.inner.primary().backend.rename(old_path, new_path).await;+ return self+ .inner+ .primary()+ .backend+ .rename(old_path, new_path)+ .await;}let ctx = current_required_ctx()?;let inner = &self.inner;@@ -1580,7 +1604,7 @@ impl FileSystem for MultiWriteWrappedFS {if recursive && search_dir == path_owned {let redirect_entries = self- .tree_directory(&path_owned, true, None, level_limit)+ .tree_directory(&path_owned, true, None, level_limit, None, None, None).await?;for entry in redirect_entries {if node_limit.is_some_and(|limit| result.count >= limit) {@@ -1692,7 +1716,7 @@ impl FileSystem for MultiWriteWrappedFS {}let entries = self- .tree_directory(path, show_hidden, None, level_limit)+ .tree_directory(path, show_hidden, None, level_limit, None, None, None).await?;let mut matched = Vec::new();@@ -1737,13 +1761,33 @@ impl FileSystem for MultiWriteWrappedFS {show_hidden: bool,node_limit: Option<usize>,level_limit: Option<usize>,+ offset: Option<usize>,+ sort_by: Option<ListSortBy>,+ sort_order: Option<SortOrder>,) -> Result<Vec<TreeEntry>> {let base = normalize_prefix_path(path);+ if sort_by.is_some() {+ let mut entries = Vec::new();+ let traversal_limit = node_limit.map(|limit| offset.unwrap_or(0).saturating_add(limit));+ self.tree_directory_internal(+ &base,+ &base,+ show_hidden,+ traversal_limit,+ level_limit,+ sort_by,+ sort_order,+ &mut entries,+ )+ .await?;+ return Ok(paginate_entries(entries, offset, node_limit));+ }+let mut entries = self.inner.primary().backend- .tree_directory(path, show_hidden, node_limit, level_limit)+ .tree_directory(path, show_hidden, None, level_limit, None, None, None).await?;entries.retain(|e| {@@ -1752,11 +1796,7 @@ impl FileSystem for MultiWriteWrappedFS {});if self.inner.redirects.is_empty() {- return Ok(entries);- }-- if node_limit.is_some_and(|limit| entries.len() >= limit) {- return Ok(entries);+ return Ok(paginate_entries(entries, offset, node_limit));}let ctx = current_required_ctx()@@ -1796,15 +1836,11 @@ impl FileSystem for MultiWriteWrappedFS {}).buffered(DEFAULT_TREE_REDIRECT_META_CONCURRENCY);- 'redirect_dirs: while let Some((dir, redirect_meta)) = redirect_results.next().await {+ while let Some((dir, redirect_meta)) = redirect_results.next().await {let Some(redirect_meta) = redirect_meta else {continue;};for (name, redirect_entry) in redirect_meta.entries {- if node_limit.is_some_and(|limit| entries.len() >= limit) {- break 'redirect_dirs;- }-let virtual_path = if dir == "/" {format!("/{}", name)} else {@@ -1840,6 +1876,6 @@ impl FileSystem for MultiWriteWrappedFS {}}- Ok(entries)+ Ok(paginate_entries(entries, offset, node_limit))}}diff --git a/crates/ragfs/src/core/multibackend_wrapper/tests.rs b/crates/ragfs/src/core/multibackend_wrapper/tests.rsindex d0ec7bced..bc3763a26 100644--- a/crates/ragfs/src/core/multibackend_wrapper/tests.rs+++ b/crates/ragfs/src/core/multibackend_wrapper/tests.rs@@ -80,7 +80,9 @@ async fn test_read_dir_redirect_entries_use_target_stat() {).await?;- let entries = fs.read_dir("/local/acct/docs").await?;+ let entries = fs+ .read_dir("/local/acct/docs", None, None, None, None)+ .await?;let report = entries.iter().find(|entry| entry.name == "report.pdf")@@ -143,12 +145,14 @@ async fn test_read_dir_redirect_entries_use_target_stat() {).await?;- let entries = no_redirect_fs.read_dir("/local/acct/docs").await?;+ let entries = no_redirect_fs+ .read_dir("/local/acct/docs", None, None, None, None)+ .await?;let names: Vec<&str> = entries.iter().map(|entry| entry.name.as_str()).collect();assert_eq!(names, vec!["real.txt"]);let tree = no_redirect_fs- .tree_directory("/local/acct", false, None, Some(3))+ .tree_directory("/local/acct", false, None, Some(3), None, None, None).await?;let paths: Vec<&str> = tree.iter().map(|entry| entry.path.as_str()).collect();assert!(!paths.contains(&"/local/acct/docs/ghost.pdf"));@@ -201,19 +205,43 @@ async fn test_recursive_grep_finds_nested_redirected_files() {.await?;let shallow = fs- .tree_directory("/local/acct/resources", false, None, Some(1))+ .tree_directory(+ "/local/acct/resources",+ false,+ None,+ Some(1),+ None,+ None,+ None,+ ).await?;let shallow_paths: Vec<&str> =shallow.iter().map(|entry| entry.path.as_str()).collect();assert_eq!(shallow_paths, vec!["/local/acct/resources/doc-1"]);let root_only = fs- .tree_directory("/local/acct/resources", false, None, Some(0))+ .tree_directory(+ "/local/acct/resources",+ false,+ None,+ Some(0),+ None,+ None,+ None,+ ).await?;assert!(root_only.is_empty());let deep = fs- .tree_directory("/local/acct/resources", false, None, Some(2))+ .tree_directory(+ "/local/acct/resources",+ false,+ None,+ Some(2),+ None,+ None,+ None,+ ).await?;let deep_paths: Vec<&str> = deep.iter().map(|entry| entry.path.as_str()).collect();assert_eq!(@@ -225,7 +253,15 @@ async fn test_recursive_grep_finds_nested_redirected_files() {);let capped = fs- .tree_directory("/local/acct/resources", false, Some(1), Some(2))+ .tree_directory(+ "/local/acct/resources",+ false,+ Some(1),+ Some(2),+ None,+ None,+ None,+ ).await?;let capped_paths: Vec<&str> = capped.iter().map(|entry| entry.path.as_str()).collect();assert_eq!(capped_paths, vec!["/local/acct/resources/doc-1"]);diff --git a/crates/ragfs/src/core/plugin.rs b/crates/ragfs/src/core/plugin.rsindex 07326e902..21a656efe 100644--- a/crates/ragfs/src/core/plugin.rs+++ b/crates/ragfs/src/core/plugin.rs@@ -220,7 +220,14 @@ mod tests {) -> Result<u64> {Ok(_data.len() as u64)}- async fn read_dir(&self, _path: &str) -> Result<Vec<FileInfo>> {+ async fn read_dir(+ &self,+ _path: &str,+ _offset: Option<usize>,+ _limit: Option<usize>,+ _sort_by: Option<crate::core::ListSortBy>,+ _sort_order: Option<crate::core::SortOrder>,+ ) -> Result<Vec<FileInfo>> {Ok(vec![])}async fn stat(&self, _path: &str) -> Result<FileInfo> {diff --git a/crates/ragfs/src/core/stats_wrapper.rs b/crates/ragfs/src/core/stats_wrapper.rsindex 3ee069ca1..d731698f3 100644--- a/crates/ragfs/src/core/stats_wrapper.rs+++ b/crates/ragfs/src/core/stats_wrapper.rs@@ -106,9 +106,19 @@ impl FileSystem for StatsWrappedFS {result}- async fn read_dir(&self, path: &str) -> Result<Vec<FileInfo>> {+ async fn read_dir(+ &self,+ path: &str,+ offset: Option<usize>,+ limit: Option<usize>,+ sort_by: Option<crate::core::ListSortBy>,+ sort_order: Option<crate::core::SortOrder>,+ ) -> Result<Vec<FileInfo>> {let timer = OperationTimer::start(FsOperation::ReadDir, Arc::clone(&self.stats));- let result = self.inner.read_dir(path).await;+ let result = self+ .inner+ .read_dir(path, offset, limit, sort_by, sort_order)+ .await;timer.finish().await;result}@@ -195,11 +205,22 @@ impl FileSystem for StatsWrappedFS {show_hidden: bool,node_limit: Option<usize>,level_limit: Option<usize>,+ offset: Option<usize>,+ sort_by: Option<crate::core::ListSortBy>,+ sort_order: Option<crate::core::SortOrder>,) -> Result<Vec<TreeEntry>> {let timer = OperationTimer::start(FsOperation::TreeDir, Arc::clone(&self.stats));let result = self.inner- .tree_directory(path, show_hidden, node_limit, level_limit)+ .tree_directory(+ path,+ show_hidden,+ node_limit,+ level_limit,+ offset,+ sort_by,+ sort_order,+ ).await;timer.finish().await;resultdiff --git a/crates/ragfs/src/core/types.rs b/crates/ragfs/src/core/types.rsindex 35d9f64f5..eb0af3c76 100644--- a/crates/ragfs/src/core/types.rs+++ b/crates/ragfs/src/core/types.rs@@ -8,6 +8,26 @@ use serde::{Deserialize, Serialize};use std::collections::HashMap;use std::time::SystemTime;+/// Supported directory listing sort fields.+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]+#[serde(rename_all = "snake_case")]+pub enum ListSortBy {+ /// Sort entries by name.+ Name,+ /// Sort entries by modification time.+ Mtime,+}++/// Supported directory listing sort directions.+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]+#[serde(rename_all = "snake_case")]+pub enum SortOrder {+ /// Sort values in ascending order.+ Asc,+ /// Sort values in descending order.+ Desc,+}+/// Grep match result////// Represents a single match found during a grep operation.diff --git a/crates/ragfs/src/git/enumerate.rs b/crates/ragfs/src/git/enumerate.rsindex ff31968fe..a06c0d14d 100644--- a/crates/ragfs/src/git/enumerate.rs+++ b/crates/ragfs/src/git/enumerate.rs@@ -106,7 +106,9 @@ pub async fn collect_under(};let account_prefix = format!("/local/{}/", account);- let entries = vfs.tree_directory(&root, true, None, None).await?;+ let entries = vfs+ .tree_directory(&root, true, None, None, None, None, None)+ .await?;let mut survivors = Vec::new();for entry in entries {@@ -193,7 +195,14 @@ mod tests {) -> Result<u64> {unimplemented!()}- async fn read_dir(&self, _path: &str) -> Result<Vec<FileInfo>> {+ async fn read_dir(+ &self,+ _path: &str,+ _offset: Option<usize>,+ _limit: Option<usize>,+ _sort_by: Option<crate::core::ListSortBy>,+ _sort_order: Option<crate::core::SortOrder>,+ ) -> Result<Vec<FileInfo>> {unimplemented!()}async fn stat(&self, _path: &str) -> Result<FileInfo> {@@ -214,6 +223,9 @@ mod tests {_show_hidden: bool,_node_limit: Option<usize>,_level_limit: Option<usize>,+ _offset: Option<usize>,+ _sort_by: Option<crate::core::ListSortBy>,+ _sort_order: Option<crate::core::SortOrder>,) -> Result<Vec<TreeEntry>> {let raw = self.entries_by_root.get(path).cloned().unwrap_or_default();diff --git a/crates/ragfs/src/git/service.rs b/crates/ragfs/src/git/service.rsindex 6d4d6a9e1..52781e54d 100644--- a/crates/ragfs/src/git/service.rs+++ b/crates/ragfs/src/git/service.rs@@ -1267,6 +1267,10 @@ impl GitService {let is_empty = match crate::core::filesystem::FileSystem::read_dir(self.vfs.as_ref(),&abs,+ None,+ None,+ None,+ None,).await{@@ -1948,7 +1952,14 @@ mod tests {.insert(path.to_string(), data.to_vec());Ok(data.len() as u64)}- async fn read_dir(&self, _path: &str) -> Result<Vec<FileInfo>> {+ async fn read_dir(+ &self,+ _path: &str,+ _offset: Option<usize>,+ _limit: Option<usize>,+ _sort_by: Option<crate::core::ListSortBy>,+ _sort_order: Option<crate::core::SortOrder>,+ ) -> Result<Vec<FileInfo>> {unimplemented!()}@@ -1974,6 +1985,9 @@ mod tests {_show_hidden: bool,_node_limit: Option<usize>,_level_limit: Option<usize>,+ _offset: Option<usize>,+ _sort_by: Option<crate::core::ListSortBy>,+ _sort_order: Option<crate::core::SortOrder>,) -> Result<Vec<TreeEntry>> {let prefix = if path == "/" {"/".to_string()@@ -6070,7 +6084,14 @@ mod fast_path1_tests {.insert(path.to_string(), (data.to_vec(), 0));Ok(data.len() as u64)}- async fn read_dir(&self, _path: &str) -> Result<Vec<FileInfo>> {+ async fn read_dir(+ &self,+ _path: &str,+ _offset: Option<usize>,+ _limit: Option<usize>,+ _sort_by: Option<crate::core::ListSortBy>,+ _sort_order: Option<crate::core::SortOrder>,+ ) -> Result<Vec<FileInfo>> {unimplemented!()}@@ -6102,6 +6123,9 @@ mod fast_path1_tests {_show_hidden: bool,_node_limit: Option<usize>,_level_limit: Option<usize>,+ _offset: Option<usize>,+ _sort_by: Option<crate::core::ListSortBy>,+ _sort_order: Option<crate::core::SortOrder>,) -> Result<Vec<TreeEntry>> {let prefix = if path == "/" {"/".to_string()diff --git a/crates/ragfs/src/lock/manager.rs b/crates/ragfs/src/lock/manager.rsindex 5ed5b4cdb..2bcc45d62 100644--- a/crates/ragfs/src/lock/manager.rs+++ b/crates/ragfs/src/lock/manager.rs@@ -2113,8 +2113,17 @@ mod tests {self.inner.write(path, data, offset, flags).await}- async fn read_dir(&self, path: &str) -> FsResult<Vec<FileInfo>> {- self.inner.read_dir(path).await+ async fn read_dir(+ &self,+ path: &str,+ offset: Option<usize>,+ limit: Option<usize>,+ sort_by: Option<crate::core::ListSortBy>,+ sort_order: Option<crate::core::SortOrder>,+ ) -> FsResult<Vec<FileInfo>> {+ self.inner+ .read_dir(path, offset, limit, sort_by, sort_order)+ .await}async fn stat(&self, path: &str) -> FsResult<FileInfo> {diff --git a/crates/ragfs/src/lock/wrapper.rs b/crates/ragfs/src/lock/wrapper.rsindex 89da83064..4bd9653ae 100644--- a/crates/ragfs/src/lock/wrapper.rs+++ b/crates/ragfs/src/lock/wrapper.rs@@ -7,13 +7,15 @@//! It is NOT a lock protocol implementation — all lock logic is delegated to//! `PathLockManager`.-use std::sync::Arc;use async_trait::async_trait;+use std::sync::Arc;use tracing::debug;use crate::core::filesystem::FileSystem;use crate::core::internal_names::is_hidden_runtime_lock_name;-use crate::core::types::{FileInfo, GlobPage, GrepResult, TreeEntry, WriteFlag};+use crate::core::types::{+ FileInfo, GlobPage, GrepResult, ListSortBy, SortOrder, TreeEntry, WriteFlag,+};use crate::core::MountableFS;use super::manager::{AutoPathLockAction, PathLockManager};@@ -58,9 +60,18 @@ impl PathLockWrappedFS {requests: &[PathLockRequest],) -> crate::core::Result<bool> {match self.manager.resolve_auto_pathlock_action(requests).await {- Ok(AutoPathLockAction::Disabled) => { debug!(requests = ?requests, "pathlock wrapper skipped auto-lock because context disabled it"); Ok(true) }- Ok(AutoPathLockAction::Covered(lease)) => { debug!(lease_ref = %lease.lease.lease_ref, requests = ?requests, "pathlock wrapper skipped auto-lock because active lease already covers request"); Ok(true) }- Ok(AutoPathLockAction::Acquire) => { debug!(requests = ?requests, "pathlock wrapper will auto-acquire lease for request"); Ok(false) }+ Ok(AutoPathLockAction::Disabled) => {+ debug!(requests = ?requests, "pathlock wrapper skipped auto-lock because context disabled it");+ Ok(true)+ }+ Ok(AutoPathLockAction::Covered(lease)) => {+ debug!(lease_ref = %lease.lease.lease_ref, requests = ?requests, "pathlock wrapper skipped auto-lock because active lease already covers request");+ Ok(true)+ }+ Ok(AutoPathLockAction::Acquire) => {+ debug!(requests = ?requests, "pathlock wrapper will auto-acquire lease for request");+ Ok(false)+ }Err(error) => Err(crate::core::Error::internal(format!("lock lease error: {error}"))),@@ -191,8 +202,17 @@ impl FileSystem for PathLockWrappedFS {Self::merge_operation_and_release(result, release)}- async fn read_dir(&self, path: &str) -> crate::core::Result<Vec<FileInfo>> {- self.inner.read_dir(path).await+ async fn read_dir(+ &self,+ path: &str,+ offset: Option<usize>,+ limit: Option<usize>,+ sort_by: Option<ListSortBy>,+ sort_order: Option<SortOrder>,+ ) -> crate::core::Result<Vec<FileInfo>> {+ self.inner+ .read_dir(path, offset, limit, sort_by, sort_order)+ .await}async fn stat(&self, path: &str) -> crate::core::Result<FileInfo> {@@ -332,9 +352,20 @@ impl FileSystem for PathLockWrappedFS {show_hidden: bool,node_limit: Option<usize>,level_limit: Option<usize>,+ offset: Option<usize>,+ sort_by: Option<ListSortBy>,+ sort_order: Option<SortOrder>,) -> crate::core::Result<Vec<TreeEntry>> {self.inner- .tree_directory(path, show_hidden, node_limit, level_limit)+ .tree_directory(+ path,+ show_hidden,+ node_limit,+ level_limit,+ offset,+ sort_by,+ sort_order,+ ).await}diff --git a/crates/ragfs/src/multibackend/admin.rs b/crates/ragfs/src/multibackend/admin.rsindex f9d12331b..9a5e684a2 100644--- a/crates/ragfs/src/multibackend/admin.rs+++ b/crates/ragfs/src/multibackend/admin.rs@@ -39,7 +39,7 @@ impl MultiWriteWrappedFS {for entry in inner.primary().backend- .tree_directory(&normalized, true, None, None)+ .tree_directory(&normalized, true, None, None, None, None, None).await?{if entry.info.is_dir {diff --git a/crates/ragfs/src/plugins/kvfs/mod.rs b/crates/ragfs/src/plugins/kvfs/mod.rsindex 85be8ed6e..32803b79d 100644--- a/crates/ragfs/src/plugins/kvfs/mod.rs+++ b/crates/ragfs/src/plugins/kvfs/mod.rs@@ -256,7 +256,14 @@ impl FileSystem for KVFileSystem {}}- async fn read_dir(&self, path: &str) -> Result<Vec<FileInfo>> {+ async fn read_dir(+ &self,+ path: &str,+ offset: Option<usize>,+ limit: Option<usize>,+ sort_by: Option<crate::core::ListSortBy>,+ sort_order: Option<crate::core::SortOrder>,+ ) -> Result<Vec<FileInfo>> {let key = Self::path_to_key(path);let store = self.store.read().await;@@ -281,7 +288,9 @@ impl FileSystem for KVFileSystem {}}- Ok(result)+ Ok(crate::core::filesystem::apply_read_dir_options(+ result, offset, limit, sort_by, sort_order,+ ))}async fn stat(&self, path: &str) -> Result<FileInfo> {@@ -517,7 +526,7 @@ mod tests {write_key(&fs, "/key2", b"val2").await;write_key(&fs, "/key3", b"val3").await;- let entries = fs.read_dir("/").await.unwrap();+ let entries = fs.read_dir("/", None, None, None, None).await.unwrap();assert_eq!(entries.len(), 3);}@@ -531,7 +540,7 @@ mod tests {write_key(&fs, "/user/123", b"alice").await;write_key(&fs, "/user/456", b"bob").await;- let entries = fs.read_dir("/user").await.unwrap();+ let entries = fs.read_dir("/user", None, None, None, None).await.unwrap();assert_eq!(entries.len(), 2);}diff --git a/crates/ragfs/src/plugins/localfs/mod.rs b/crates/ragfs/src/plugins/localfs/mod.rsindex 928f537ba..a5c1f35f3 100644--- a/crates/ragfs/src/plugins/localfs/mod.rs+++ b/crates/ragfs/src/plugins/localfs/mod.rs@@ -20,7 +20,9 @@ use crate::core::errors::{Error, Result};use crate::core::filesystem::{validate_virtual_path, FileSystem};use crate::core::glob::{decode_offset_token, encode_offset_token, PreparedGlob};use crate::core::plugin::ServicePlugin;-use crate::core::types::{ConfigParameter, FileInfo, GlobEntry, GlobPage, GrepResult, PluginConfig, WriteFlag};+use crate::core::types::{+ ConfigParameter, FileInfo, GlobEntry, GlobPage, GrepResult, PluginConfig, WriteFlag,+};/// LocalFS - Local file system implementationpub struct LocalFileSystem {@@ -208,8 +210,9 @@ impl LocalFileSystem {return Ok(false);}- file.set_len(0)- .map_err(|e| Error::plugin(format!("failed to truncate for compare_and_write: {}", e)))?;+ file.set_len(0).map_err(|e| {+ Error::plugin(format!("failed to truncate for compare_and_write: {}", e))+ })?;file.seek(SeekFrom::Start(0)).map_err(|e| Error::plugin(format!("failed to rewind for compare_and_write: {}", e)))?;file.write_all(&new_data)@@ -261,8 +264,9 @@ impl LocalFileSystem {return Ok(false);}- fs::remove_file(&local_path)- .map_err(|e| Error::plugin(format!("failed to remove for compare_and_remove: {}", e)))?;+ fs::remove_file(&local_path).map_err(|e| {+ Error::plugin(format!("failed to remove for compare_and_remove: {}", e))+ })?;Ok(true)}@@ -815,7 +819,8 @@ impl LocalFileSystem {break;}- let dent = dent.map_err(|e| Error::plugin(format!("failed to walk directory: {}", e)))?;+ let dent =+ dent.map_err(|e| Error::plugin(format!("failed to walk directory: {}", e)))?;raw_seen += 1;if raw_seen <= start {@@ -849,11 +854,14 @@ impl LocalFileSystem {});}- let next_token = next_offset- .filter(|_| page_size.is_some())- .map(|offset| encode_offset_token(offset, virtual_path, pattern, show_hidden, level_limit));+ let next_token = next_offset.filter(|_| page_size.is_some()).map(|offset| {+ encode_offset_token(offset, virtual_path, pattern, show_hidden, level_limit)+ });- Ok(GlobPage { entries, next_token })+ Ok(GlobPage {+ entries,+ next_token,+ })}fn resolve_virtual_path(base_path: &Path, path: &str) -> PathBuf {@@ -1058,11 +1066,18 @@ impl FileSystem for LocalFileSystem {Self::run_blocking_fs(move || Self::compare_and_remove_locked(local_path, expected)).await}- async fn read_dir(&self, path: &str) -> Result<Vec<FileInfo>> {+ async fn read_dir(+ &self,+ path: &str,+ offset: Option<usize>,+ limit: Option<usize>,+ sort_by: Option<crate::core::ListSortBy>,+ sort_order: Option<crate::core::SortOrder>,+ ) -> Result<Vec<FileInfo>> {let local_path = self.resolve_path(path)?;let path = path.to_string();- Self::run_blocking_fs(move || {+ let entries = Self::run_blocking_fs(move || {// Check if directory existsif !local_path.exists() {return Err(Error::NotFound(path.clone()));@@ -1101,7 +1116,10 @@ impl FileSystem for LocalFileSystem {Ok(files)})- .await+ .await?;+ Ok(crate::core::filesystem::apply_read_dir_options(+ entries, offset, limit, sort_by, sort_order,+ ))}async fn stat(&self, path: &str) -> Result<FileInfo> {@@ -1180,58 +1198,58 @@ impl FileSystem for LocalFileSystem {}}- // Keep replace semantics explicit instead of inheriting rename behavior:- // encrypted publish needs an overwrite-on-destination move.- #[cfg(windows)]- {- use std::ffi::OsStr;- use std::io;- use std::os::windows::ffi::OsStrExt;-- type BOOL = i32;- type DWORD = u32;- type LPCWSTR = *const u16;-- const MOVEFILE_REPLACE_EXISTING: DWORD = 0x1;- const MOVEFILE_WRITE_THROUGH: DWORD = 0x8;-- unsafe extern "system" {- fn MoveFileExW(- lpExistingFileName: LPCWSTR,- lpNewFileName: LPCWSTR,- dwFlags: DWORD,- ) -> BOOL;- }-- let src_wide: Vec<u16> = OsStr::new(src_local.as_os_str())- .encode_wide()- .chain(std::iter::once(0))- .collect();- let dst_wide: Vec<u16> = OsStr::new(dst_local.as_os_str())- .encode_wide()- .chain(std::iter::once(0))- .collect();-- let replaced = unsafe {- MoveFileExW(- src_wide.as_ptr(),- dst_wide.as_ptr(),- MOVEFILE_REPLACE_EXISTING | MOVEFILE_WRITE_THROUGH,- )- };- if replaced == 0 {- return Err(Error::plugin(format!(- "failed to replace: {}",- io::Error::last_os_error()- )));- }- }-- #[cfg(not(windows))]- {- fs::rename(&src_local, &dst_local)- .map_err(|e| Error::plugin(format!("failed to replace: {}", e)))?;- }+ // Keep replace semantics explicit instead of inheriting rename behavior:+ // encrypted publish needs an overwrite-on-destination move.+ #[cfg(windows)]+ {+ use std::ffi::OsStr;+ use std::io;+ use std::os::windows::ffi::OsStrExt;++ type BOOL = i32;+ type DWORD = u32;+ type LPCWSTR = *const u16;++ const MOVEFILE_REPLACE_EXISTING: DWORD = 0x1;+ const MOVEFILE_WRITE_THROUGH: DWORD = 0x8;++ unsafe extern "system" {+ fn MoveFileExW(+ lpExistingFileName: LPCWSTR,+ lpNewFileName: LPCWSTR,+ dwFlags: DWORD,+ ) -> BOOL;+ }++ let src_wide: Vec<u16> = OsStr::new(src_local.as_os_str())+ .encode_wide()+ .chain(std::iter::once(0))+ .collect();+ let dst_wide: Vec<u16> = OsStr::new(dst_local.as_os_str())+ .encode_wide()+ .chain(std::iter::once(0))+ .collect();++ let replaced = unsafe {+ MoveFileExW(+ src_wide.as_ptr(),+ dst_wide.as_ptr(),+ MOVEFILE_REPLACE_EXISTING | MOVEFILE_WRITE_THROUGH,+ )+ };+ if replaced == 0 {+ return Err(Error::plugin(format!(+ "failed to replace: {}",+ io::Error::last_os_error()+ )));+ }+ }++ #[cfg(not(windows))]+ {+ fs::rename(&src_local, &dst_local)+ .map_err(|e| Error::plugin(format!("failed to replace: {}", e)))?;+ }Ok(())}@@ -1781,7 +1799,10 @@ mod tests {let (dir, fs) = fallback_localfs();std::fs::create_dir_all(dir.path().join("folder")).unwrap();- let out = fs.glob_directory("/", "**/*", false, None, None, None).await.unwrap();+ let out = fs+ .glob_directory("/", "**/*", false, None, None, None)+ .await+ .unwrap();assert_eq!(out.entries.iter()@@ -1847,7 +1868,10 @@ mod tests {write_file(dir.path(), ".hidden.md", "");write_file(dir.path(), ".hidden_dir/nested.md", "");- let out = fs.glob_directory("/", "**/*.md", false, None, None, None).await.unwrap();+ let out = fs+ .glob_directory("/", "**/*.md", false, None, None, None)+ .await+ .unwrap();assert_eq!(out.entries.iter()@@ -1870,12 +1894,17 @@ mod tests {write_file(dir.path(), "z_blocked/late.md", "");let blocked_dir = dir.path().join("z_blocked");- let old_mode = std::fs::metadata(&blocked_dir).unwrap().permissions().mode();+ let old_mode = std::fs::metadata(&blocked_dir)+ .unwrap()+ .permissions()+ .mode();let mut perms = std::fs::metadata(&blocked_dir).unwrap().permissions();perms.set_mode(0);std::fs::set_permissions(&blocked_dir, perms).unwrap();- let first = fs.glob_directory("/", "**/*.md", false, Some(2), None, None).await;+ let first = fs+ .glob_directory("/", "**/*.md", false, Some(2), None, None)+ .await;assert!(first.is_ok());let first = first.unwrap();assert_eq!(diff --git a/crates/ragfs/src/plugins/memfs/mod.rs b/crates/ragfs/src/plugins/memfs/mod.rsindex bdec5a9e8..c3645ab22 100644--- a/crates/ragfs/src/plugins/memfs/mod.rs+++ b/crates/ragfs/src/plugins/memfs/mod.rs@@ -357,7 +357,14 @@ impl FileSystem for MemFileSystem {Ok(matches)}- async fn read_dir(&self, path: &str) -> Result<Vec<FileInfo>> {+ async fn read_dir(+ &self,+ path: &str,+ offset: Option<usize>,+ limit: Option<usize>,+ sort_by: Option<crate::core::ListSortBy>,+ sort_order: Option<crate::core::SortOrder>,+ ) -> Result<Vec<FileInfo>> {let normalized = Self::normalize_path(path);let entries = self.entries.read().await;@@ -385,7 +392,9 @@ impl FileSystem for MemFileSystem {}}- Ok(result)+ Ok(crate::core::filesystem::apply_read_dir_options(+ result, offset, limit, sort_by, sort_order,+ ))}async fn stat(&self, path: &str) -> Result<FileInfo> {@@ -495,7 +504,10 @@ impl FileSystem for MemFileSystem {}}- if entries.get(&dst_normalized).is_some_and(|entry| entry.is_dir) {+ if entries+ .get(&dst_normalized)+ .is_some_and(|entry| entry.is_dir)+ {return Err(Error::IsADirectory(dst_normalized));}@@ -641,7 +653,10 @@ mod tests {fs.create("/testdir/file2.txt").await.unwrap();// List directory- let entries = fs.read_dir("/testdir").await.unwrap();+ let entries = fs+ .read_dir("/testdir", None, None, None, None)+ .await+ .unwrap();assert_eq!(entries.len(), 2);}diff --git a/crates/ragfs/src/plugins/queuefs/mod.rs b/crates/ragfs/src/plugins/queuefs/mod.rsindex 43bbc8511..b0659bd75 100644--- a/crates/ragfs/src/plugins/queuefs/mod.rs+++ b/crates/ragfs/src/plugins/queuefs/mod.rs@@ -436,7 +436,14 @@ impl FileSystem for QueueFileSystem {}}- async fn read_dir(&self, path: &str) -> Result<Vec<FileInfo>> {+ async fn read_dir(+ &self,+ path: &str,+ offset: Option<usize>,+ limit: Option<usize>,+ sort_by: Option<crate::core::ListSortBy>,+ sort_order: Option<crate::core::SortOrder>,+ ) -> Result<Vec<FileInfo>> {let parsed = Self::parse_queue_path(path)?;if !parsed.is_dir {@@ -456,7 +463,7 @@ impl FileSystem for QueueFileSystem {}}- return Ok(top_level+ let entries = top_level.into_iter().map(|name| FileInfo {name,@@ -465,7 +472,10 @@ impl FileSystem for QueueFileSystem {mod_time: now,is_dir: true,})- .collect());+ .collect();+ return Ok(crate::core::filesystem::apply_read_dir_options(+ entries, offset, limit, sort_by, sort_order,+ ));}// Queue directory: check if it has nested queues@@ -489,7 +499,7 @@ impl FileSystem for QueueFileSystem {}}- return Ok(subdirs+ let entries = subdirs.into_iter().map(|name| FileInfo {name,@@ -498,7 +508,10 @@ impl FileSystem for QueueFileSystem {mod_time: now,is_dir: true,})- .collect());+ .collect();+ return Ok(crate::core::filesystem::apply_read_dir_options(+ entries, offset, limit, sort_by, sort_order,+ ));}// Leaf queue: return control files@@ -506,7 +519,13 @@ impl FileSystem for QueueFileSystem {return Err(Error::NotFound(format!("queue not found: {}", queue_name)));}- Ok(Self::leaf_control_files(now))+ Ok(crate::core::filesystem::apply_read_dir_options(+ Self::leaf_control_files(now),+ offset,+ limit,+ sort_by,+ sort_order,+ ))}async fn stat(&self, path: &str) -> Result<FileInfo> {@@ -979,13 +998,16 @@ mod tests {let fs = queuefs_with("test").await;// Root should list the queue- let entries = fs.read_dir("/").await.unwrap();+ let entries = fs.read_dir("/", None, None, None, None).await.unwrap();assert_eq!(entries.len(), 1);assert_eq!(entries[0].name, "test");assert!(entries[0].is_dir);// Queue directory should list control files- let entries = fs.read_dir("/test").await.unwrap();+ let entries = fs+ .read_dir("/test", None, None, None, None)+ .await+ .unwrap();assert_eq!(entries.len(), 7);let names: Vec<String> = entries.iter().map(|e| e.name.clone()).collect();@@ -1144,7 +1166,10 @@ mod tests {fs.mkdir("/logs/warnings", 0o755).await.unwrap();// List /logs should show subdirectories- let entries = fs.read_dir("/logs").await.unwrap();+ let entries = fs+ .read_dir("/logs", None, None, None, None)+ .await+ .unwrap();assert_eq!(entries.len(), 2);let names: Vec<_> = entries.iter().map(|e| e.name.as_str()).collect();assert!(names.contains(&"errors"));@@ -1252,7 +1277,10 @@ mod tests {provider.set_unavailable(true);assert!(matches!(fs.stat("/Semantic").await, Err(Error::Network(_))));- assert!(matches!(fs.read_dir("/").await, Err(Error::Network(_))));+ assert!(matches!(+ fs.read_dir("/", None, None, None, None).await,+ Err(Error::Network(_))+ ));}#[tokio::test]diff --git a/crates/ragfs/src/plugins/s3fs/mod.rs b/crates/ragfs/src/plugins/s3fs/mod.rsindex eeec24015..4cc2297a5 100644--- a/crates/ragfs/src/plugins/s3fs/mod.rs+++ b/crates/ragfs/src/plugins/s3fs/mod.rs@@ -283,12 +283,16 @@ impl S3FileSystem {page_offset: 0,last_rel_parts: Vec::new(),}),- Some(raw) if raw.is_empty() => Err(Error::invalid_operation("empty continuation token")),+ Some(raw) if raw.is_empty() => {+ Err(Error::invalid_operation("empty continuation token"))+ }Some(raw) => {let state: S3GlobToken = serde_json::from_str(raw).map_err(|_| Error::invalid_operation("invalid continuation token"))?;if state.scope != scope {- return Err(Error::invalid_operation("continuation token scope mismatch"));+ return Err(Error::invalid_operation(+ "continuation token scope mismatch",+ ));}Ok(state)}@@ -355,7 +359,6 @@ impl S3FileSystem {Ok((matched, next_last_rel_parts))}-/// Get file name from pathfn file_name(path: &str) -> String {if path == "/" {@@ -599,7 +602,9 @@ impl FileSystem for S3FileSystem {match flags {WriteFlag::CreateNew => {- self.client.put_object_create_new(&key, data.to_vec()).await?;+ self.client+ .put_object_create_new(&key, data.to_vec())+ .await?;}_ => {// S3 always replaces the full object for non-exclusive writes.@@ -656,12 +661,21 @@ impl FileSystem for S3FileSystem {Ok(changed)}- async fn read_dir(&self, path: &str) -> Result<Vec<FileInfo>> {+ async fn read_dir(+ &self,+ path: &str,+ offset: Option<usize>,+ limit: Option<usize>,+ sort_by: Option<crate::core::ListSortBy>,+ sort_order: Option<crate::core::SortOrder>,+ ) -> Result<Vec<FileInfo>> {let normalized = Self::normalize_path(path);// Check cacheif let Some(files) = self.dir_cache.get(&normalized).await {- return Ok(files);+ return Ok(crate::core::filesystem::apply_read_dir_options(+ files, offset, limit, sort_by, sort_order,+ ));}// Build prefix for listing@@ -720,7 +734,9 @@ impl FileSystem for S3FileSystem {// Cacheself.dir_cache.put(normalized.clone(), files.clone()).await;- Ok(files)+ Ok(crate::core::filesystem::apply_read_dir_options(+ files, offset, limit, sort_by, sort_order,+ ))}async fn stat(&self, path: &str) -> Result<FileInfo> {@@ -857,7 +873,6 @@ impl FileSystem for S3FileSystem {Err(Error::not_found(&old_normalized))}-async fn replace(&self, src_path: &str, dst_path: &str) -> Result<()> {let src_normalized = Self::normalize_path(src_path);let dst_normalized = Self::normalize_path(dst_path);@@ -1011,8 +1026,29 @@ impl FileSystem for S3FileSystem {show_hidden: bool,node_limit: Option<usize>,level_limit: Option<usize>,+ offset: Option<usize>,+ sort_by: Option<crate::core::ListSortBy>,+ sort_order: Option<crate::core::SortOrder>,) -> Result<Vec<TreeEntry>> {let normalized = Self::normalize_path(path);+ if sort_by.is_some() {+ let mut result = Vec::new();+ let traversal_limit = node_limit.map(|limit| offset.unwrap_or(0).saturating_add(limit));+ self.tree_directory_internal(+ &normalized,+ &normalized,+ show_hidden,+ traversal_limit,+ level_limit,+ sort_by,+ sort_order,+ &mut result,+ )+ .await?;+ return Ok(crate::core::filesystem::paginate_entries(+ result, offset, node_limit,+ ));+ }let prefix = if normalized == "/" {self.client.build_key("")@@ -1030,15 +1066,9 @@ impl FileSystem for S3FileSystem {|key| self.client.strip_prefix(key),)?;- let mut result = Vec::new();- for entry in ordered {- if node_limit.is_some_and(|limit| result.len() >= limit) {- break;- }- result.push(entry);- }-- Ok(result)+ Ok(crate::core::filesystem::paginate_entries(+ ordered, offset, node_limit,+ ))}async fn glob_directory(diff --git a/crates/ragfs/src/plugins/serverinfofs/mod.rs b/crates/ragfs/src/plugins/serverinfofs/mod.rsindex 72df71aea..9c490ce77 100644--- a/crates/ragfs/src/plugins/serverinfofs/mod.rs+++ b/crates/ragfs/src/plugins/serverinfofs/mod.rs@@ -211,7 +211,14 @@ impl FileSystem for ServerInfoFileSystem {))}- async fn read_dir(&self, path: &str) -> Result<Vec<FileInfo>> {+ async fn read_dir(+ &self,+ path: &str,+ offset: Option<usize>,+ limit: Option<usize>,+ sort_by: Option<crate::core::ListSortBy>,+ sort_order: Option<crate::core::SortOrder>,+ ) -> Result<Vec<FileInfo>> {if path != "/" {return Err(Error::plugin(format!("not a directory: {}", path)));}@@ -225,7 +232,7 @@ impl FileSystem for ServerInfoFileSystem {let stats = self.get_stats();let readme = self.get_readme();- Ok(vec![+ let entries = vec![FileInfo::new("README".to_string(), readme.len() as u64, 0o444, now, false),FileInfo::new("server_info".to_string(),@@ -243,7 +250,10 @@ impl FileSystem for ServerInfoFileSystem {false,),FileInfo::new("stats".to_string(), stats.len() as u64, 0o444, now, false),- ])+ ];+ Ok(crate::core::filesystem::apply_read_dir_options(+ entries, offset, limit, sort_by, sort_order,+ ))}async fn stat(&self, path: &str) -> Result<FileInfo> {diff --git a/crates/ragfs/src/plugins/sqlfs/mod.rs b/crates/ragfs/src/plugins/sqlfs/mod.rsindex 0ab7bb367..31fe11f99 100644--- a/crates/ragfs/src/plugins/sqlfs/mod.rs+++ b/crates/ragfs/src/plugins/sqlfs/mod.rs@@ -412,12 +412,21 @@ impl FileSystem for SQLFileSystem {Ok(changed)}- async fn read_dir(&self, path: &str) -> Result<Vec<FileInfo>> {+ async fn read_dir(+ &self,+ path: &str,+ offset: Option<usize>,+ limit: Option<usize>,+ sort_by: Option<crate::core::ListSortBy>,+ sort_order: Option<crate::core::SortOrder>,+ ) -> Result<Vec<FileInfo>> {let normalized = Self::normalize_path(path);// Try cache firstif let Some(files) = self.cache.get(&normalized).await {- return Ok(files);+ return Ok(crate::core::filesystem::apply_read_dir_options(+ files, offset, limit, sort_by, sort_order,+ ));}let normalized_for_db = normalized.clone();@@ -453,7 +462,9 @@ impl FileSystem for SQLFileSystem {// Cache the resultself.cache.put(normalized.clone(), files.clone()).await;- Ok(files)+ Ok(crate::core::filesystem::apply_read_dir_options(+ files, offset, limit, sort_by, sort_order,+ ))}async fn stat(&self, path: &str) -> Result<FileInfo> {@@ -799,7 +810,10 @@ mod tests {write_file(&fs, "/testdir/file.txt", b"data").await;// List directory- let entries = fs.read_dir("/testdir").await.unwrap();+ let entries = fs+ .read_dir("/testdir", None, None, None, None)+ .await+ .unwrap();assert_eq!(entries.len(), 1);assert_eq!(entries[0].name, "file.txt");@@ -862,7 +876,7 @@ mod tests {write_file(&fs, "/a/b/file.txt", b"nested").await;// List /a should only show /a/b- let entries = fs.read_dir("/a").await.unwrap();+ let entries = fs.read_dir("/a", None, None, None, None).await.unwrap();assert_eq!(entries.len(), 1);assert_eq!(entries[0].name, "b");assert!(entries[0].is_dir);diff --git a/crates/ragfs/src/shape/probe.rs b/crates/ragfs/src/shape/probe.rsindex 254c78e40..2dace2ed3 100644--- a/crates/ragfs/src/shape/probe.rs+++ b/crates/ragfs/src/shape/probe.rs@@ -115,7 +115,7 @@ pub async fn write_shape_guard(/// Probe existing backend files to infer the legacy storage shape.pub async fn detect_legacy_shape(raw_fs: &Arc<dyn FileSystem>) -> Result<Option<StorageShape>> {- let entries = raw_fs.tree_directory("/", true, None, None).await?;+ let entries = raw_fs.tree_directory("/", true, None, None, None, None, None).await?;let mut candidates = Vec::new();for entry in entries {diff --git a/docs/en/api/03-filesystem.md b/docs/en/api/03-filesystem.mdindex 1694ea715..6923b3cc5 100644--- a/docs/en/api/03-filesystem.md+++ b/docs/en/api/03-filesystem.md@@ -23,12 +23,14 @@ List directory contents.| abs_limit | int | No | 256 | Abstract length limit for `agent` output || show_all_hidden | bool | No | False | Include hidden files like `-a` || node_limit | int | No | 1000 | Maximum number of results |-| sort_by | str | No | None | Sort directories and files within their groups by `name` or `mtime` before applying `node_limit`; directories remain first |+| offset | int | No | 0 | Number of visible results to skip |+| limit | int | No | None | Alias for `node_limit` |+| sort_by | str | No | None | Sort directories and files within their groups by `name` or `mtime` before pagination; directories remain first || sort_order | str | No | `asc` | Sort direction: `asc` or `desc` || extra_fields | list[str] | No | None | Extra fields to include: `locked`, `id`, `count` || tags | string[] | No | Unset | Return only entries matching every supplied `k=v` retrieval tag |-`tags` uses AND semantics and is applied before `node_limit`. Tags are included for filtered responses; for an unfiltered response, request `include_tags=true` (CLI: `-f tags`).+`tags` uses AND semantics and is applied before `offset` and `limit`. Tags are included for filtered responses; for an unfiltered response, request `include_tags=true` (CLI: `-f tags`).**Entry Structure**@@ -70,7 +72,8 @@ existing hiding rules.```pythonentries = client.ls(uri="viking://resources/",- node_limit=200,+ offset=100,+ limit=100,sort_by="mtime",sort_order="desc",)@@ -101,7 +104,7 @@ for _, entry := range entries {**HTTP API**```-GET /api/v1/fs/ls?uri={uri}&simple={bool}&recursive={bool}&tags={k=v}&include_tags={bool}+GET /api/v1/fs/ls?uri={uri}&offset={int}&limit={int}``````bash@@ -163,17 +166,19 @@ Get directory tree structure.| abs_limit | int | No | HTTP: 256; SDKs: 128 | Abstract length limit for `agent` output || show_all_hidden | bool | No | False | Include hidden files like `-a` || node_limit | int | No | 1000 | Maximum number of results |+| offset | int | No | 0 | Number of visible results to skip |+| limit | int | No | None | Alias for `node_limit` || level_limit | int | No | 3 | Maximum directory depth to traverse || extra_fields | list[str] | No | None | Extra fields to include: `locked`, `id`, `count` || tags | string[] | No | Unset | Retain only nodes matching every supplied `k=v` retrieval tag |-`tags` uses AND semantics and is applied before `node_limit`. Tags are included for filtered responses; for an unfiltered response, request `include_tags=true` (CLI: `-f tags`).+`tags` uses AND semantics and is applied before `offset` and `limit`. Tags are included for filtered responses; for an unfiltered response, request `include_tags=true` (CLI: `-f tags`).**Python HTTP SDK**```python-entries = client.tree(uri="viking://resources/")+entries = client.tree(uri="viking://resources/", offset=100, limit=100)for entry in entries:type_str = "dir" if entry['isDir'] else "file"print(f"{entry['rel_path']} - {type_str}")@@ -201,7 +206,7 @@ for _, entry := range entries {**HTTP API**```-GET /api/v1/fs/tree?uri={uri}&tags={k=v}&include_tags={bool}+GET /api/v1/fs/tree?uri={uri}&offset={int}&limit={int}``````bashdiff --git a/docs/en/guides/06-mcp-integration.md b/docs/en/guides/06-mcp-integration.mdindex 577f8d9ad..fc366d53e 100644--- a/docs/en/guides/06-mcp-integration.md+++ b/docs/en/guides/06-mcp-integration.md@@ -136,8 +136,8 @@ Once connected, OpenViking exposes 15 tools:| `find` | Fast semantic retrieval without session context | `query`, `target_uri` (optional), `limit`, `min_score`, `level` (optional), `context_type` (optional) || `search` | Deep semantic retrieval; `mode="context"` assembles injection-ready context and replaces the former `recall` tool | `query`, `mode` (`list` or `context`), `target_uri` (list mode only), `session_id` (optional), `limit`, `min_score`, `level` (list mode), `context_type` (optional), plus context-mode `quotas`, `purpose`, `max_tokens`, `detail` or `detail_by_category`, `dedup_turns`, `exclude_uris`, `peer_scope`, scalar `other_peer_penalty` or `other_peer_penalties` by category, and `rewrite` (`off` or `auto`) || `read` | Read one or more `viking://` URIs. PNG, JPEG, GIF, and WebP return native MCP image content; WAV, MP3, FLAC, OGG, and M4A return native audio content. Video is not supported because MCP has no standard video content block | `uris` (single string or array) |-| `list` | List entries under a `viking://` directory | `uri`, `recursive` (optional) |-| `tree` | Show the recursive directory tree under a `viking://` URI, indented by depth — use when you need a full picture of the file tree (prefer `list` for a single level, `glob` for filename patterns) | `uri` (optional), `level_limit` (default 3), `node_limit` (default 1000), `include_abstract` (optional — also show each file's summary) |+| `list` | List entries under a `viking://` directory | `uri`, `recursive`, `offset`, `limit`, `sort_by`, `sort_order` (optional) |+| `tree` | Show the recursive directory tree under a `viking://` URI, indented by depth — use when you need a full picture of the file tree (prefer `list` for a single level, `glob` for filename patterns) | `uri` (optional), `level_limit` (default 3), `node_limit` (default 1000), `offset`, `limit`, `include_abstract` (optional — also show each file's summary) || `remember` | Store messages into long-term memory (triggers extraction) | `messages` (list of `{role, content}`) || `write` | Write text to a `viking://` file (create/overwrite/append). Parent directories are created automatically; use `read` first to see current content before overwriting, and prefer `edit` for changing part of an existing file | `uri`, `content`, `mode` (optional: `replace` default — overwrites or creates if missing; `append` — appends or creates if missing; `create` — fails if it exists), `wait` (optional, block until re-indexed), `timeout` (optional) || `edit` | Replace an exact string with new text in an existing `viking://` file — for targeted changes instead of a full rewrite. The file is left unchanged if `old_string` is not found, or matches multiple times while `replace_all` is false | `uri`, `old_string`, `new_string`, `replace_all` (optional), `wait` (optional, block until re-indexed), `timeout` (optional) |diff --git a/docs/zh/api/03-filesystem.md b/docs/zh/api/03-filesystem.mdindex fb43a9181..4ebf06ffb 100644--- a/docs/zh/api/03-filesystem.md+++ b/docs/zh/api/03-filesystem.md@@ -23,12 +23,13 @@ OpenViking 提供类 Unix 的文件系统操作来管理上下文。| abs_limit | int | 否 | 256 | `agent` 输出中的摘要长度限制 || show_all_hidden | bool | 否 | False | 像 `-a` 一样包含隐藏文件 || node_limit | int | 否 | 1000 | 最大返回节点数 |+| offset | int | 否 | 0 | 跳过的可见节点数 || limit | int | 否 | None | `node_limit` 的别名 |-| sort_by | str | 否 | None | 在应用 `node_limit` 前,分别按 `name` 或 `mtime` 排序目录组和文件组;目录仍优先 |+| sort_by | str | 否 | None | 在分页前,分别按 `name` 或 `mtime` 排序目录组和文件组;目录仍优先 || sort_order | str | 否 | `asc` | 排序方向:`asc` 或 `desc` || tags | string[] | 否 | 未设置 | 仅返回同时匹配全部 `k=v` 检索标签的条目 |-`tags` 使用 AND 语义,并在 `node_limit` 前应用。带 tags 过滤的响应会返回 `tags`;未过滤时需传 `include_tags=true`(CLI:`-f tags`)才返回它们。`simple=true` 保持仅返回路径。+`tags` 使用 AND 语义,并在 `offset` 和 `limit` 前应用。带 tags 过滤的响应会返回 `tags`;未过滤时需传 `include_tags=true`(CLI:`-f tags`)才返回它们。`simple=true` 保持仅返回路径。**条目结构**@@ -68,7 +69,8 @@ OpenViking 提供类 Unix 的文件系统操作来管理上下文。```pythonentries = client.ls(uri="viking://resources/",- node_limit=200,+ offset=100,+ limit=100,sort_by="mtime",sort_order="desc",tags=["team=search", "env=prod"],@@ -104,7 +106,7 @@ for _, entry := range entries {**HTTP API**```-GET /api/v1/fs/ls?uri={uri}&simple={bool}&recursive={bool}&tags={k=v}&include_tags={bool}+GET /api/v1/fs/ls?uri={uri}&offset={int}&limit={int}``````bash@@ -180,16 +182,23 @@ openviking ls viking://resources/ --fields tags| abs_limit | int | 否 | HTTP:256;SDK:128 | `agent` 输出中的摘要长度限制 || show_all_hidden | bool | 否 | False | 像 `-a` 一样包含隐藏文件 || node_limit | int | 否 | 1000 | 最大返回节点数 |+| offset | int | 否 | 0 | 跳过的可见节点数 |+| limit | int | 否 | None | `node_limit` 的别名 || level_limit | int | 否 | 3 | 最大目录遍历深度 || tags | string[] | 否 | 未设置 | 仅保留同时匹配全部 `k=v` 检索标签的节点 |-`tags` 使用 AND 语义,并在 `node_limit` 前应用。带 tags 过滤的响应会返回 `tags`;未过滤时需传 `include_tags=true` 才返回它们,否则会省略 tags 以避免额外的向量库读取。+`tags` 使用 AND 语义,并在 `offset` 和 `limit` 前应用。带 tags 过滤的响应会返回 `tags`;未过滤时需传 `include_tags=true` 才返回它们,否则会省略 tags 以避免额外的向量库读取。**Python HTTP SDK**```python-entries = client.tree(uri="viking://resources/", tags=["team=search", "env=prod"])+entries = client.tree(+ uri="viking://resources/",+ offset=100,+ limit=100,+ tags=["team=search", "env=prod"],+)for entry in entries:type_str = "dir" if entry['isDir'] else "file"print(f"{entry['rel_path']} - {type_str}")@@ -222,7 +231,7 @@ for _, entry := range entries {**HTTP API**```-GET /api/v1/fs/tree?uri={uri}&tags={k=v}&include_tags={bool}+GET /api/v1/fs/tree?uri={uri}&offset={int}&limit={int}``````bashdiff --git a/openviking/pyagfs/async_client.py b/openviking/pyagfs/async_client.pyindex 3732a8e82..eeb310c72 100644--- a/openviking/pyagfs/async_client.py+++ b/openviking/pyagfs/async_client.py@@ -105,9 +105,25 @@ class AsyncAGFSClient:)async def ls(- self, path: str = "/", *, fs_ctx: Dict[str, str] | None = None+ self,+ path: str = "/",+ *,+ offset: int = 0,+ limit: int | None = None,+ sort_by: str | None = None,+ sort_order: str = "asc",+ fs_ctx: Dict[str, str] | None = None,) -> List[Dict[str, Any]]:- return await self.run("ls", path, ctx=_fs_ctx_or_default(path, fs_ctx))+ """Return a sorted directory range."""+ kwargs: Dict[str, Any] = {}+ if offset:+ kwargs["offset"] = offset+ if limit is not None:+ kwargs["limit"] = limit+ if sort_by is not None:+ kwargs["sort_by"] = sort_by+ kwargs["sort_order"] = sort_order+ return await self.run("ls", path, **kwargs, ctx=_fs_ctx_or_default(path, fs_ctx))async def read(self,@@ -279,14 +295,26 @@ class AsyncAGFSClient:node_limit: int | None = None,level_limit: int | None = None,*,+ offset: int = 0,+ sort_by: str | None = None,+ sort_order: str = "asc",fs_ctx: Dict[str, str] | None = None,) -> list[Dict[str, Any]]:+ """Return a sorted range from a recursive directory traversal."""+ kwargs: Dict[str, Any] = {+ "show_hidden": show_hidden,+ "node_limit": node_limit,+ "level_limit": level_limit,+ }+ if offset:+ kwargs["offset"] = offset+ if sort_by is not None:+ kwargs["sort_by"] = sort_by+ kwargs["sort_order"] = sort_orderreturn await self.run("tree_directory",path,- show_hidden=show_hidden,- node_limit=node_limit,- level_limit=level_limit,+ **kwargs,ctx=_fs_ctx_or_default(path, fs_ctx),)diff --git a/openviking/pyagfs/protocols.py b/openviking/pyagfs/protocols.pyindex d04fe6680..3920c3945 100644--- a/openviking/pyagfs/protocols.py+++ b/openviking/pyagfs/protocols.py@@ -12,8 +12,17 @@ AGFSByteStream = Iterator[bytes]class AGFSSyncClientProtocol(Protocol):"""Minimal synchronous AGFS client contract used by OpenViking."""- def ls(self, path: str = "/") -> list[Dict[str, Any]]:- """List directory entries under the given AGFS path."""+ def ls(+ self,+ path: str = "/",+ ctx: Dict[str, str] | None = None,+ *,+ offset: int = 0,+ limit: int | None = None,+ sort_by: str | None = None,+ sort_order: str = "asc",+ ) -> list[Dict[str, Any]]:+ """List a sorted directory range."""@overloaddef read(@@ -90,8 +99,13 @@ class AGFSSyncClientProtocol(Protocol):show_hidden: bool = False,node_limit: int | None = None,level_limit: int | None = None,+ ctx: Dict[str, str] | None = None,+ *,+ offset: int = 0,+ sort_by: str | None = None,+ sort_order: str = "asc",) -> list[Dict[str, Any]]:- """Return a tree view for the given AGFS directory."""+ """Return a sorted range from a directory tree."""def glob_directory(self,diff --git a/openviking/server/mcp_endpoint.py b/openviking/server/mcp_endpoint.pyindex 145425957..a6edcaa45 100644--- a/openviking/server/mcp_endpoint.py+++ b/openviking/server/mcp_endpoint.py@@ -630,13 +630,49 @@ async def read(uris: str | list[str]) -> str | list[ContentBlock]:@mcp.tool(name="list")-async def ls(uri: str, recursive: bool = False) -> str:- """List files and subdirectories under a viking:// directory URI. Use recursive=true for deep listing."""+async def ls(+ uri: str,+ recursive: bool = False,+ offset: int = 0,+ limit: int | None = None,+ sort_by: Literal["name", "mtime"] | None = None,+ sort_order: Literal["asc", "desc"] = "asc",+) -> str:+ """List one sorted page under a viking:// directory URI.++ Args:+ uri: Directory URI to list.+ recursive: Whether to recursively list descendants.+ offset: Number of visible entries to skip.+ limit: Optional maximum number of entries.+ sort_by: Optional name or modification-time ordering.+ sort_order: Ascending or descending order.++ Returns:+ A line-oriented directory listing.+ """+ if offset < 0:+ raise InvalidArgumentError("offset must be greater than or equal to 0")+ if limit is not None and limit <= 0:+ raise InvalidArgumentError("limit must be greater than 0")+service = get_service()ctx = _get_ctx()resolved_uri = _resolve_mcp_workspace_uri(uri, ctx)- entries = await service.fs.ls(resolved_uri, ctx=ctx, recursive=recursive, output="original")+ options: dict[str, Any] = {+ "ctx": ctx,+ "recursive": recursive,+ "output": "original",+ }+ if offset:+ options["offset"] = offset+ if limit is not None:+ options["node_limit"] = limit+ if sort_by is not None:+ options["sort_by"] = sort_by+ options["sort_order"] = sort_order+ entries = await service.fs.ls(resolved_uri, **options)if not entries:return f"(no entries under {uri})"@@ -661,19 +697,40 @@ async def tree(level_limit: int = 3,node_limit: int = 1000,include_abstract: bool = False,+ offset: int = 0,+ limit: int | None = None,) -> str:- """Show the recursive directory tree under a viking:// URI, indented by depth, so you can understand the whole layout at a glance. Use this when you need a full picture of the file tree; use list for a single directory level, glob for filename patterns, and grep for content. level_limit caps the depth (default 3); node_limit caps the total entries. Set include_abstract=true to also see each file's summary (slower, but useful for orientation in unfamiliar directories)."""+ """Show one visible page from a recursive directory tree.++ Args:+ uri: Directory URI to traverse.+ level_limit: Maximum traversal depth.+ node_limit: Existing default result limit.+ include_abstract: Whether to include file summaries.+ offset: Number of visible nodes to skip.+ limit: Optional result limit that overrides node_limit.++ Returns:+ An indented directory tree.+ """+ if offset < 0:+ raise InvalidArgumentError("offset must be greater than or equal to 0")+ if limit is not None and limit <= 0:+ raise InvalidArgumentError("limit must be greater than 0")+service = get_service()ctx = _get_ctx()resolved_uri = _resolve_mcp_workspace_uri(uri, ctx)output = "agent" if include_abstract else "original"+ effective_limit = limit if limit is not None else node_limittry:entries = await service.fs.tree(resolved_uri,ctx=ctx,output=output,- node_limit=node_limit,+ node_limit=effective_limit,level_limit=level_limit,+ offset=offset,)except NotFoundError:entries = []@@ -695,9 +752,9 @@ async def tree(abstract = (e.get("abstract") or "").strip().replace("\n", " ")if include_abstract and abstract:lines.append(f"{indent} - {abstract}")- if len(entries) >= node_limit:+ if len(entries) >= effective_limit:lines.append(- f"(truncated at node_limit={node_limit}; narrow the uri or raise node_limit to see more)"+ f"(truncated at node_limit={effective_limit}; narrow the uri or raise node_limit to see more)")return "\n".join(lines)diff --git a/openviking/server/routers/filesystem.py b/openviking/server/routers/filesystem.pyindex 3db41d2c4..8c9320dbc 100644--- a/openviking/server/routers/filesystem.py+++ b/openviking/server/routers/filesystem.py@@ -74,7 +74,8 @@ async def ls(abs_limit: int = Query(256, description="Abstract limit (only for agent output)"),show_all_hidden: bool = Query(False, description="List all hidden files, like -a"),node_limit: int = Query(1000, description="Maximum number of nodes to list"),- limit: Optional[int] = Query(None, description="Alias for node_limit"),+ offset: int = Query(0, ge=0, description="Number of visible nodes to skip"),+ limit: Optional[int] = Query(None, ge=1, description="Alias for node_limit"),sort_by: Optional[Literal["name", "mtime"]] = Query(None,description="Sort directory and file groups before applying node_limit",@@ -102,6 +103,7 @@ async def ls(abs_limit=abs_limit,show_all_hidden=show_all_hidden,node_limit=actual_node_limit,+ offset=offset,sort_by=sort_by,sort_order=sort_order,extra_fields=extra_fields,@@ -125,7 +127,8 @@ async def tree(abs_limit: int = Query(256, description="Abstract limit (only for agent output)"),show_all_hidden: bool = Query(False, description="List all hidden files, like -a"),node_limit: int = Query(1000, description="Maximum number of nodes to list"),- limit: Optional[int] = Query(None, description="Alias for node_limit"),+ offset: int = Query(0, ge=0, description="Number of visible nodes to skip"),+ limit: Optional[int] = Query(None, ge=1, description="Alias for node_limit"),level_limit: int = Query(3, description="Maximum depth level to traverse"),extra_fields: Optional[list[str]] = Query(None, description="Extra fields to include: locked, id, count"@@ -148,6 +151,7 @@ async def tree(show_all_hidden=show_all_hidden,node_limit=actual_node_limit,level_limit=level_limit,+ offset=offset,extra_fields=extra_fields,tags=tags,include_tags=include_tags,diff --git a/openviking/service/fs_service.py b/openviking/service/fs_service.pyindex b1cba9b7a..6310a933f 100644--- a/openviking/service/fs_service.py+++ b/openviking/service/fs_service.py@@ -8,7 +8,7 @@ Provides file system operations: ls, mkdir, rm, mv, tree, stat, read, abstract,import asynciofrom collections.abc import Coroutine-from typing import TYPE_CHECKING, Any, Dict, List, Literal, Optional+from typing import TYPE_CHECKING, Any, Awaitable, Callable, Dict, List, Literal, Optionalfrom openviking.core.context import ContextLevelfrom openviking.core.namespace import classify_uri, context_type_for_uri, uri_leaf_name@@ -178,6 +178,52 @@ class FSService:result_entries.append(entry)return result_entries+ async def _collect_tagged_page(+ self,+ fetch_page: Callable[[int, Optional[int]], Awaitable[List[Dict[str, Any]]]],+ ctx: RequestContext,+ tags: List[str],+ include_tags: bool,+ offset: int,+ node_limit: int,+ ) -> List[Dict[str, Any]]:+ """Collect a visible page after tag filtering.++ Args:+ fetch_page: Loads one pre-tag page by offset and limit.+ ctx: Request identity used for tag lookup.+ tags: Required retrieval tags.+ include_tags: Whether to retain tags in returned entries.+ offset: Number of matched entries to skip.+ node_limit: Maximum matched entries to return.++ Returns:+ The requested page of tag-filtered entries.+ """+ if node_limit <= 0:+ entries = await fetch_page(0, None)+ entries = await self._attach_and_filter_tags(entries, ctx, tags, include_tags)+ return entries[offset:]++ batch_size = max(node_limit, 256)+ source_offset = 0+ remaining_offset = offset+ result: List[Dict[str, Any]] = []+ while len(result) < node_limit:+ entries = await fetch_page(source_offset, batch_size)+ filtered = await self._attach_and_filter_tags(entries, ctx, tags, include_tags)+ if remaining_offset >= len(filtered):+ remaining_offset -= len(filtered)+ else:+ result.extend(+ filtered[remaining_offset : remaining_offset + node_limit - len(result)]+ )+ remaining_offset = 0+ if len(entries) < batch_size:+ break+ source_offset += len(entries)+ return result+async def ls(self,uri: str,@@ -194,6 +240,7 @@ class FSService:extra_fields: Optional[List[str]] = None,tags: Optional[List[str]] = None,include_tags: bool = False,+ offset: int = 0,) -> List[Any]:"""List directory contents.@@ -211,63 +258,62 @@ class FSService:"""viking_fs = self._ensure_initialized()extra_fields = extra_fields or []-use_simple_paths = simple and not extra_fields- if use_simple_paths:- # Only return URIs — skip expensive abstract fetching to save tokens+ async def fetch_page(page_offset: int, page_limit: Optional[int]) -> List[Dict[str, Any]]:+ """Fetch and return one pre-tag page."""if recursive:- entries = await viking_fs.tree(+ return await viking_fs.tree(uri,ctx=ctx,- output="original",+ output="original" if tags or use_simple_paths else output,+ abs_limit=abs_limit,show_all_hidden=show_all_hidden,- node_limit=None if tags else node_limit,+ node_limit=page_limit,level_limit=level_limit,- )- else:- entries = await viking_fs.ls(- uri,- ctx=ctx,- output="original",- show_all_hidden=show_all_hidden,- node_limit=None if tags else node_limit,+ offset=page_offset,sort_by=sort_by,sort_order=sort_order,+ extra_fields=None if tags or use_simple_paths else extra_fields,)- entries = await self._attach_and_filter_tags(entries, ctx, tags, include_tags=False)- if tags and node_limit > 0:- entries = entries[:node_limit]- return [e.get("uri", "") for e in entries]-- if recursive:- entries = await viking_fs.tree(+ return await viking_fs.ls(uri,ctx=ctx,- output=output,+ output="original" if tags or use_simple_paths else output,abs_limit=abs_limit,show_all_hidden=show_all_hidden,- node_limit=None if tags else node_limit,- level_limit=level_limit,- extra_fields=extra_fields,+ node_limit=page_limit,+ offset=page_offset,+ sort_by=sort_by,+ sort_order=sort_order,+ extra_fields=None if tags or use_simple_paths else extra_fields,+ )++ if tags:+ entries = await self._collect_tagged_page(+ fetch_page,+ ctx,+ tags,+ False if use_simple_paths else include_tags or bool(tags) or "tags" in extra_fields,+ offset,+ node_limit,)else:- entries = await viking_fs.ls(- uri,+ entries = await fetch_page(offset, node_limit)+ entries = await self._attach_and_filter_tags(+ entries, ctx, None, include_tags or "tags" in extra_fields+ )+ if use_simple_paths:+ return [entry.get("uri", "") for entry in entries]+ if tags and (output != "original" or extra_fields):+ return await viking_fs._finalize_listing_entries(+ entries,+ output,+ abs_limit,+ extra_fields,+ recursive,ctx=ctx,- output=output,- abs_limit=abs_limit,- show_all_hidden=show_all_hidden,- node_limit=None if tags else node_limit,- sort_by=sort_by,- sort_order=sort_order,- extra_fields=extra_fields,)- entries = await self._attach_and_filter_tags(- entries, ctx, tags, include_tags or bool(tags) or "tags" in extra_fields- )- if tags and node_limit > 0:- entries = entries[:node_limit]return entriesasync def mkdir(@@ -838,25 +884,49 @@ class FSService:extra_fields: Optional[List[str]] = None,tags: Optional[List[str]] = None,include_tags: bool = False,+ offset: int = 0,) -> List[Dict[str, Any]]:"""Get directory tree."""viking_fs = self._ensure_initialized()- result = await viking_fs.tree(- uri,- ctx=ctx,- output=output,- abs_limit=abs_limit,- show_all_hidden=show_all_hidden,- node_limit=None if tags else node_limit,- level_limit=level_limit,- extra_fields=extra_fields,- )- result = await self._attach_and_filter_tags(- result, ctx, tags, include_tags or bool(tags) or "tags" in (extra_fields or [])++ async def fetch_page(page_offset: int, page_limit: Optional[int]) -> List[Dict[str, Any]]:+ """Fetch and return one pre-tag tree page."""+ return await viking_fs.tree(+ uri,+ ctx=ctx,+ output="original" if tags else output,+ abs_limit=abs_limit,+ show_all_hidden=show_all_hidden,+ node_limit=page_limit,+ level_limit=level_limit,+ extra_fields=None if tags else extra_fields,+ offset=page_offset,+ )++ if tags:+ result = await self._collect_tagged_page(+ fetch_page,+ ctx,+ tags,+ include_tags or bool(tags) or "tags" in (extra_fields or []),+ offset,+ node_limit,+ )+ if output != "original" or extra_fields:+ return await viking_fs._finalize_listing_entries(+ result,+ output,+ abs_limit,+ extra_fields,+ True,+ ctx=ctx,+ )+ return result++ result = await fetch_page(offset, node_limit)+ return await self._attach_and_filter_tags(+ result, ctx, None, include_tags or "tags" in (extra_fields or []))- if tags and node_limit > 0:- result = result[:node_limit]- return resultasync def stat(self, uri: str, ctx: RequestContext, skip_count: bool = False) -> Dict[str, Any]:"""Get resource status."""diff --git a/openviking/storage/viking_fs/_access.py b/openviking/storage/viking_fs/_access.pyindex c7b85a2c3..502e68c85 100644--- a/openviking/storage/viking_fs/_access.py+++ b/openviking/storage/viking_fs/_access.py@@ -43,10 +43,6 @@ from openviking_cli.utils.uri import VikingURIclass _AccessMixin:"""URI normalization, access control, path conversion, and visibility helpers."""- # Over-fetch multiplier for bounded tree traversal. When a node_limit is- # set, we push down node_limit * this factor as the raw-node limit to Rust,- # leaving headroom for ACL/internal-name filtering before re-fetching.- _TREE_OVERFETCH_FACTOR = 4_GLOB_PAGE_SIZE_DEFAULT = 1024# Maximum bytes for a single filename component (filesystem limit is typically 255)@@ -59,14 +55,16 @@ class _AccessMixin:# crates/ragfs/src/git/enumerate.rs and VikingFS._INTERNAL_NAMES so that# callers fail fast in Python with a clear error rather than passing a# path that the Rust side will silently drop.- _GIT_INTERNAL_FIRST_SEGMENTS = frozenset({- "_system",- "tasks",- "temp",- "queue",- "upload",- ".path.ovlock",- })+ _GIT_INTERNAL_FIRST_SEGMENTS = frozenset(+ {+ "_system",+ "tasks",+ "temp",+ "queue",+ "upload",+ ".path.ovlock",+ }+ )_DEFAULT_GIT_AUTHOR_NAME = "viking-bot"_DEFAULT_GIT_AUTHOR_EMAIL = "[email protected]"@@ -259,9 +257,7 @@ class _AccessMixin:resource=uri,)- async def _ensure_retrieval_scope(- self, uri: str, ctx: Optional[RequestContext]- ) -> None:+ async def _ensure_retrieval_scope(self, uri: str, ctx: Optional[RequestContext]) -> None:self._safe_uri_parts(uri)if self._acl_enabled(ctx) and is_acl_uri(uri):return@@ -269,13 +265,9 @@ class _AccessMixin:def _acl_enabled(self, ctx: Optional[RequestContext]) -> bool:real_ctx = self._ctx_or_default(ctx)- return self.acl_manager is not None and self.acl_manager.is_enabled(- real_ctx.account_id- )+ return self.acl_manager is not None and self.acl_manager.is_enabled(real_ctx.account_id)- async def _ensure_acl_manage(- self, uri: str, ctx: Optional[RequestContext]- ) -> RequestContext:+ async def _ensure_acl_manage(self, uri: str, ctx: Optional[RequestContext]) -> RequestContext:if self.acl_manager is None:raise RuntimeError("ACL is not initialized")real_ctx = self._ctx_or_default(ctx)@@ -367,11 +359,7 @@ class _AccessMixin:def _ensure_user_not_deleting(self, ctx: RequestContext) -> None:guard = getattr(self, "_user_deletion_guard", None)- if (- ctx.role != Role.ROOT- and guard is not None- and guard(ctx.account_id, ctx.user.user_id)- ):+ if ctx.role != Role.ROOT and guard is not None and guard(ctx.account_id, ctx.user.user_id):raise FailedPreconditionError("User deletion is in progress")def _ensure_supported_delete_namespace(self, normalized_uri: str) -> None:@@ -513,25 +501,12 @@ class _AccessMixin:show_all_hidden: bool = False,node_limit: Optional[int] = None,level_limit: Optional[int] = None,+ offset: int = 0,+ sort_by: Optional[str] = None,+ sort_order: str = "asc",ctx: Optional[RequestContext] = None,):- """Shared generator: fetch raw TreeEntry list from Rust, yield (entry, uri) tuples.-- node_limit counts ACL-visible entries, so the user's node_limit cannot- be pushed directly to Rust — doing so would truncate before filtering- and drop entries that should be visible.-- To keep memory bounded without changing that semantic, we push down an- *amplified* raw-node limit (node_limit * _TREE_OVERFETCH_FACTOR). If ACL- filtering leaves fewer than node_limit visible entries while Rust still- returned a full page (i.e. more raw nodes may exist), we double the raw- limit and re-fetch. Because Rust truncates a deterministic sorted prefix,- this yields exactly the same result as an unbounded fetch, while avoiding- materializing the entire prefix in the common case.-- When node_limit is None (full-tree callers), no limit is pushed down.- level_limit IS always passed to Rust.- """+ """Yield one visible tree page after namespace and ACL filtering."""real_ctx = self._ctx_or_default(ctx)primary_path = self._uri_to_path(uri, ctx=ctx)path: Optional[str] = None@@ -546,11 +521,15 @@ class _AccessMixin:returnraise NotFoundError(uri, "directory")- if node_limit is None:- raw_limit: Optional[int] = None- else:- raw_limit = max(node_limit * self._TREE_OVERFETCH_FACTOR, node_limit)+ if node_limit == 0:+ return+ raw_offset = 0+ raw_limit = None if node_limit is None else max(node_limit, 256)+ remaining_offset = offset+ yielded = 0acl_enabled = self._acl_enabled(real_ctx)+ expose_resource_names = acl_enabled and is_acl_uri(uri)+ denied_directories: set[str] = set()while True:raw_entries = await self._async_agfs.tree_directory(@@ -558,7 +537,12 @@ class _AccessMixin:show_hidden=show_all_hidden,node_limit=raw_limit,level_limit=level_limit,+ offset=raw_offset,+ sort_by=sort_by,+ sort_order=sort_order,)+ if not raw_entries:+ returncandidates: List[tuple] = []for entry in raw_entries:@@ -573,14 +557,14 @@ class _AccessMixin:ctx=ctx,)candidates.append((entry, entry_uri))+ remaining_limit = None if node_limit is None else node_limit - yieldedif (not acl_enabled- and node_limit is not None- and len(candidates) >= node_limit+ and remaining_limit is not None+ and len(candidates) >= (remaining_offset + remaining_limit)):break- expose_resource_names = acl_enabled and is_acl_uri(uri)if not acl_enabled:visible = candidateselse:@@ -588,12 +572,14 @@ class _AccessMixin:[entry_uri for _, entry_uri in candidates], real_ctx)if expose_resource_names:- denied_directories = {- entry["path"].rstrip("/")- for entry, entry_uri in candidates- if entry.get("info", {}).get("isDir", False)- and not access.get(entry_uri, False)- }+ denied_directories.update(+ {+ entry["path"].rstrip("/")+ for entry, entry_uri in candidates+ if entry.get("info", {}).get("isDir", False)+ and not access.get(entry_uri, False)+ }+ )visible = []base = path.rstrip("/")for entry, entry_uri in candidates:@@ -614,25 +600,19 @@ class _AccessMixin:visible.append((denied_entry, entry_uri))else:visible = [item for item in candidates if access.get(item[1], False)]- if node_limit is not None:- visible = visible[:node_limit]-- # If we still lack enough visible entries but Rust returned a full- # page (raw_limit reached), more raw nodes may exist — re-fetch with- # a doubled limit. Otherwise Rust is exhausted and we yield as-is.- need_more = (- node_limit is not None- and len(visible) < node_limit- and raw_limit is not None- and len(raw_entries) >= raw_limit- )- if need_more:- raw_limit *= 2- continuefor item in visible:+ if remaining_offset:+ remaining_offset -= 1+ continueyield item- return+ yielded += 1+ if node_limit is not None and yielded >= node_limit:+ return++ if raw_limit is None or len(raw_entries) < raw_limit:+ return+ raw_offset += len(raw_entries)# ========== URI Conversion ==========@@ -662,9 +642,7 @@ class _AccessMixin:raise ValueError(f"Legacy session URI is not accepted internally: {uri}")if parts and parts[0] == "agent" and self._is_legacy_agent_id_uri(uri):# Old format: viking://agent/{agent_id}/... — direct mapping for read-only compat- safe_parts = [- self._shorten_component(p, self._MAX_FILENAME_BYTES) for p in parts- ]+ safe_parts = [self._shorten_component(p, self._MAX_FILENAME_BYTES) for p in parts]return f"/local/{account_id}/{'/'.join(safe_parts)}"if not parts:return f"/local/{account_id}"@@ -736,9 +714,7 @@ class _AccessMixin:return Trueif self._legacy_session_alias(request_uri):owner_user_id = self._safe_uri_parts(request_uri)[1]- return await self._legacy_session_path_visible(- path, owner_user_id=owner_user_id- )+ return await self._legacy_session_path_visible(path, owner_user_id=owner_user_id)return Truedef _alias_uri_for_path(@@ -751,9 +727,7 @@ class _AccessMixin:) -> str:base = base_path.rstrip("/")request_parts = self._safe_uri_parts(request_uri)- request_root = (- request_uri if request_uri == "viking://" else request_uri.rstrip("/")- )+ request_root = request_uri if request_uri == "viking://" else request_uri.rstrip("/")preserve_request_alias = request_uri in {"viking://", "viking://user"} or bool(request_partsand request_parts[0] == "agent"@@ -932,23 +906,38 @@ class _AccessMixin:async def _list_read_path_items(self,uri: str,+ raw_offset: int = 0,+ raw_limit: Optional[int] = None,+ sort_by: Optional[str] = None,+ sort_order: str = "asc",ctx: Optional[RequestContext] = None,- ) -> List[tuple[Dict[str, Any], str]]:+ ) -> tuple[List[tuple[Dict[str, Any], str]], int, bool]:+ """Return one mapped RagFS page, consumed count, and exhaustion state."""real_ctx = self._ctx_or_default(ctx)if self._is_session_root_uri(uri):- return await self._session_root_items(uri, real_ctx)+ items = await self._session_root_items(uri, real_ctx)+ return items, len(items), Trueprimary_path = self._uri_to_path(uri, ctx=ctx)merge_paths = self._legacy_session_alias(uri) is not Nonefound_path = Falselast_not_found: Optional[Exception] = Noneby_uri: Dict[str, tuple[Dict[str, Any], str]] = {}+ raw_count = 0for path in self._read_paths(uri, ctx=ctx):if not await self._read_path_visible(uri, path, primary_path, real_ctx):continuetry:- entries = await self._ls_entries(path, ctx=ctx)+ entries = await self._ls_entries(+ path,+ offset=0 if merge_paths else raw_offset,+ limit=None if merge_paths else raw_limit,+ sort_by=sort_by,+ sort_order=sort_order,+ filter_internal=False,+ ctx=ctx,+ )except Exception as exc:if is_not_found_error(exc):last_not_found = exc@@ -956,6 +945,8 @@ class _AccessMixin:raisefound_path = True+ raw_count += len(entries)+ entries = self._filter_ls_entries(path, entries)for entry in entries:entry_uri = self._alias_uri_for_path(request_uri=uri,@@ -968,7 +959,8 @@ class _AccessMixin:breakif found_path:- return list(by_uri.values())+ exhausted = raw_limit is None or merge_paths or raw_count < raw_limit+ return list(by_uri.values()), raw_count, exhaustedraise NotFoundError(uri, "directory") from last_not_founddef _path_to_uri(self, path: str, ctx: Optional[RequestContext] = None) -> str:diff --git a/openviking/storage/viking_fs/_ops.py b/openviking/storage/viking_fs/_ops.pyindex cba385e17..d289d514b 100644--- a/openviking/storage/viking_fs/_ops.py+++ b/openviking/storage/viking_fs/_ops.py@@ -1257,6 +1257,80 @@ class _OpsMixin:abstract = abstract[: abs_limit - 3] + "..."entries[index]["abstract"] = abstract+ async def _finalize_listing_entries(+ self,+ entries: List[Dict[str, Any]],+ output: str,+ abs_limit: int,+ extra_fields: Optional[List[str]],+ recursive: bool,+ ctx: Optional[RequestContext] = None,+ ) -> List[Dict[str, Any]]:+ """Format and enrich entries after visible-page selection.++ Args:+ entries: Selected entries in original format.+ output: Requested output format.+ abs_limit: Maximum abstract length.+ extra_fields: Optional original-output fields.+ recursive: Whether entries came from a tree traversal.+ ctx: Request identity used for enrichment.++ Returns:+ Entries in the requested output format.+ """+ if output == "original":+ if extra_fields:+ await self._augment_entries_extra_fields(entries, extra_fields, ctx=ctx)+ return entries+ if output != "agent":+ raise ValueError(f"Invalid output format: {output}")++ fallback_time = datetime.now(timezone.utc)+ result: List[Dict[str, Any]] = []+ for entry in entries:+ is_dir = bool(entry.get("isDir", False))+ if entry.get("access") == "denied":+ item = {+ "uri": entry.get("uri", ""),+ "isDir": is_dir,+ "access": "denied",+ }+ if recursive:+ item["rel_path"] = entry.get("rel_path", "")+ else:+ item["name"] = entry.get("name", "")+ else:+ raw_time = entry.get("modTime", "")+ parsed_time = fallback_time+ if isinstance(raw_time, (int, float)):+ parsed_time = datetime.fromtimestamp(raw_time, tz=timezone.utc)+ elif raw_time:+ if len(raw_time) > 26 and "+" in raw_time:+ parts = raw_time.split("+")+ raw_time = parts[0][:26] + "+" + parts[1]+ parsed_time = parse_iso_datetime(raw_time)+ elif isinstance(entry.get("mtime"), (int, float)):+ parsed_time = datetime.fromtimestamp(entry["mtime"], tz=timezone.utc)+ item = {+ "uri": entry.get("uri", ""),+ "size": 0 if is_dir else entry.get("size", 0),+ "isDir": is_dir,+ "modTime": format_iso8601(parsed_time),+ }+ if recursive:+ item["rel_path"] = entry.get("rel_path", "")+ if "tags" in entry:+ item["tags"] = entry["tags"]+ result.append(item)++ await self._batch_fetch_abstracts(+ [entry for entry in result if entry.get("access") != "denied"],+ abs_limit,+ ctx=ctx,+ )+ return result+async def tree(self,uri: str = "viking://",@@ -1267,6 +1341,9 @@ class _OpsMixin:level_limit: Optional[int] = 3,ctx: Optional[RequestContext] = None,extra_fields: Optional[List[str]] = None,+ offset: int = 0,+ sort_by: Optional[str] = None,+ sort_order: str = "asc",) -> List[Dict[str, Any]]:"""Recursively list all contents (includes rel_path).@@ -1286,15 +1363,32 @@ class _OpsMixin:output="agent"[{'uri': 'viking://resources...', 'size': 100, 'isDir': False, 'modTime': '2026-02-11T08:52:16.256Z', 'rel_path': '.abstract.md', 'abstract': "..."}]"""+ if offset < 0:+ raise ValueError("offset must be non-negative")await self._ensure_access(uri, ctx)extra_fields = extra_fields or []if output == "original":entries = await self._tree_original(- uri, show_all_hidden, node_limit, level_limit, ctx=ctx+ uri,+ show_all_hidden,+ node_limit,+ level_limit,+ offset=offset,+ sort_by=sort_by,+ sort_order=sort_order,+ ctx=ctx,)elif output == "agent":entries = await self._tree_agent(- uri, abs_limit, show_all_hidden, node_limit, level_limit, ctx=ctx+ uri,+ abs_limit,+ show_all_hidden,+ node_limit,+ level_limit,+ offset=offset,+ sort_by=sort_by,+ sort_order=sort_order,+ ctx=ctx,)else:raise ValueError(f"Invalid output format: {output}")@@ -1308,6 +1402,9 @@ class _OpsMixin:show_all_hidden: bool = False,node_limit: Optional[int] = 1000,level_limit: Optional[int] = 3,+ offset: int = 0,+ sort_by: Optional[str] = None,+ sort_order: str = "asc",ctx: Optional[RequestContext] = None,) -> List[Dict[str, Any]]:"""Recursively list all contents (original format)."""@@ -1317,6 +1414,9 @@ class _OpsMixin:show_all_hidden=show_all_hidden,node_limit=node_limit,level_limit=level_limit,+ offset=offset,+ sort_by=sort_by,+ sort_order=sort_order,ctx=ctx,):info = entry["info"]@@ -1353,48 +1453,31 @@ class _OpsMixin:show_all_hidden: bool = False,node_limit: Optional[int] = 1000,level_limit: Optional[int] = 3,+ offset: int = 0,+ sort_by: Optional[str] = None,+ sort_order: str = "asc",ctx: Optional[RequestContext] = None,) -> List[Dict[str, Any]]:"""Recursively list all contents (agent format with abstracts)."""- result = []-- async for entry, entry_uri in self._iter_visible_tree_entries(+ entries = await self._tree_original(uri,- show_all_hidden=show_all_hidden,- node_limit=node_limit,- level_limit=level_limit,+ show_all_hidden,+ node_limit,+ level_limit,+ offset=offset,+ sort_by=sort_by,+ sort_order=sort_order,ctx=ctx,- ):- info = entry["info"]- is_dir = info["isDir"]- if entry.get("access") == "denied":- result.append(- {- "uri": entry_uri,- "isDir": is_dir,- "rel_path": entry["rel_path"],- "access": "denied",- }- )- continue- result.append(- {- "uri": entry_uri,- "size": 0 if is_dir else info["size"],- "isDir": is_dir,- "modTime": format_iso8601(parse_iso_datetime(info["modTime"])),- "rel_path": entry["rel_path"],- }- )-- await self._batch_fetch_abstracts(- [entry for entry in result if entry.get("access") != "denied"],+ )+ return await self._finalize_listing_entries(+ entries,+ "agent",abs_limit,+ None,+ True,ctx=ctx,)- return result-# ========== Vector Sync Helper Methods ==========async def _collect_uris(@@ -1707,6 +1790,7 @@ class _OpsMixin:sort_order: str = "asc",ctx: Optional[RequestContext] = None,extra_fields: Optional[List[str]] = None,+ offset: int = 0,) -> List[Dict[str, Any]]:"""List directory contents (URI version).@@ -1738,6 +1822,7 @@ class _OpsMixin:uri,show_all_hidden,node_limit,+ offset=offset,sort_by=sort_by,sort_order=sort_order,ctx=ctx,@@ -1748,6 +1833,7 @@ class _OpsMixin:abs_limit,show_all_hidden,node_limit,+ offset=offset,sort_by=sort_by,sort_order=sort_order,ctx=ctx,@@ -1788,12 +1874,12 @@ class _OpsMixin:directories = [item for item in entry_items if item[0].get("isDir", False)]files = [item for item in entry_items if not item[0].get("isDir", False)]- if sort_by == "name":-- def name_key(item: tuple[Dict[str, Any], str]) -> tuple[str, str]:- name = str(item[0].get("name", ""))- return name.lower(), name+ def name_key(item: tuple[Dict[str, Any], str]) -> tuple[str, str]:+ """Return the case-insensitive and original entry name."""+ name = str(item[0].get("name", ""))+ return name.lower(), name+ if sort_by == "name":directories.sort(key=name_key, reverse=descending)files.sort(key=name_key, reverse=descending)return directories + files@@ -1809,10 +1895,12 @@ class _OpsMixin:missing.append(item)else:timestamped.append((timestamp, item))+ timestamped.sort(key=lambda pair: name_key(pair[1]))timestamped.sort(key=lambda pair: pair[0],reverse=descending,)+ missing.sort(key=name_key)return [item for _, item in timestamped] + missingreturn sort_by_mtime(directories) + sort_by_mtime(files)@@ -1823,73 +1911,50 @@ class _OpsMixin:abs_limit: int,show_all_hidden: bool,node_limit: int = 1000,+ offset: int = 0,sort_by: Optional[str] = None,sort_order: str = "asc",ctx: Optional[RequestContext] = None,) -> List[Dict[str, Any]]:"""List directory contents (URI version)."""- entry_items = await self._ls_browsable_items(uri, ctx=ctx)- entry_items = self._sort_ls_entry_items(entry_items, sort_by, sort_order)- # basic info- fallback_time = datetime.now(timezone.utc)- all_entries = []- for entry, entry_uri in entry_items:- name = entry.get("name", "")- if entry.get("access") == "denied":- if entry.get("isDir") or not name.startswith(".") or show_all_hidden:- all_entries.append(- {- "name": name,- "uri": entry_uri,- "isDir": bool(entry.get("isDir", False)),- "access": "denied",- }- )- continue- raw_time = entry.get("modTime", "")- parsed_time = fallback_time- if isinstance(raw_time, (int, float)):- parsed_time = datetime.fromtimestamp(raw_time, tz=timezone.utc)- elif raw_time:- if len(raw_time) > 26 and "+" in raw_time:- parts = raw_time.split("+")- raw_time = parts[0][:26] + "+" + parts[1]- parsed_time = parse_iso_datetime(raw_time)- elif isinstance(entry.get("mtime"), (int, float)):- parsed_time = datetime.fromtimestamp(entry["mtime"], tz=timezone.utc)- is_dir = entry.get("isDir", False)- new_entry = {- "uri": entry_uri,- "size": 0 if is_dir else entry.get("size", 0),- "isDir": is_dir,- "modTime": format_iso8601(parsed_time),- }- if is_dir:- all_entries.append(new_entry)- elif not name.startswith("."):- all_entries.append(new_entry)- elif show_all_hidden:- all_entries.append(new_entry)- all_entries = all_entries[:node_limit]- await self._batch_fetch_abstracts(- [entry for entry in all_entries if entry.get("access") != "denied"],+ entries = await self._ls_original(+ uri,+ show_all_hidden=show_all_hidden,+ offset=offset,+ node_limit=node_limit,+ sort_by=sort_by,+ sort_order=sort_order,+ ctx=ctx,+ )+ return await self._finalize_listing_entries(+ entries,+ "agent",abs_limit,+ None,+ False,ctx=ctx,)- return all_entriesasync def _ls_original(self,uri: str,show_all_hidden: bool = False,node_limit: int = 1000,+ offset: int = 0,sort_by: Optional[str] = None,sort_order: str = "asc",ctx: Optional[RequestContext] = None,) -> List[Dict[str, Any]]:"""List directory contents (URI version)."""- entry_items = await self._ls_browsable_items(uri, ctx=ctx)- entry_items = self._sort_ls_entry_items(entry_items, sort_by, sort_order)+ entry_items = await self._ls_browsable_items(+ uri,+ show_all_hidden=show_all_hidden,+ offset=offset,+ node_limit=node_limit,+ sort_by=sort_by,+ sort_order=sort_order,+ ctx=ctx,+ )# AGFS returns read-only structure, need to create new dictall_entries = []for entry, entry_uri in entry_items:@@ -1910,25 +1975,55 @@ class _OpsMixin:all_entries.append(new_entry)elif show_all_hidden:all_entries.append(new_entry)- return all_entries[:node_limit]+ return all_entriesasync def _ls_browsable_items(self,uri: str,+ show_all_hidden: bool = False,+ offset: int = 0,+ node_limit: Optional[int] = None,+ sort_by: Optional[str] = None,+ sort_order: str = "asc",ctx: Optional[RequestContext] = None,) -> List[tuple[Dict[str, Any], str]]:- """Return list entries according to namespace-enumeration semantics."""- entry_items = await self._list_read_path_items(uri, ctx=ctx)- access = await self._can_access_many([entry_uri for _, entry_uri in entry_items], ctx)+ """Return one visible page while preserving RagFS ordering."""+ if offset < 0:+ raise ValueError("offset must be non-negative")+ if node_limit == 0:+ return []++ raw_offset = 0+ raw_limit = None if node_limit is None else max(node_limit, 256)+ remaining_offset = offset+ merge_paths = self._legacy_session_alias(uri) is not None+ browsable: List[tuple[Dict[str, Any], str]] = []expose_resource_names = self._acl_enabled(ctx) and is_acl_uri(uri)- browsable = []- for entry, entry_uri in entry_items:- if access.get(entry_uri, False):- browsable.append((entry, entry_uri))- elif expose_resource_names:- browsable.append(- (+ while True:+ entry_items, consumed, exhausted = await self._list_read_path_items(+ uri,+ raw_offset=raw_offset,+ raw_limit=raw_limit,+ sort_by=sort_by,+ sort_order=sort_order,+ ctx=ctx,+ )+ if merge_paths:+ entry_items = self._sort_ls_entry_items(entry_items, sort_by, sort_order)+ entry_items = [+ item+ for item in entry_items+ if item[0].get("isDir")+ or not str(item[0].get("name", "")).startswith(".")+ or show_all_hidden+ ]+ access = await self._can_access_many([entry_uri for _, entry_uri in entry_items], ctx)+ for entry, entry_uri in entry_items:+ if access.get(entry_uri, False):+ item = (entry, entry_uri)+ elif expose_resource_names:+ item = ({"name": entry.get("name", ""),"isDir": bool(entry.get("isDir", False)),@@ -1936,7 +2031,19 @@ class _OpsMixin:},entry_uri,)- )+ else:+ continue++ if remaining_offset:+ remaining_offset -= 1+ continue+ browsable.append(item)+ if node_limit is not None and len(browsable) >= node_limit:+ return browsable+ if exhausted:+ break+ raw_offset += consumed+return browsableasync def _augment_entries_extra_fields(@@ -2055,16 +2162,34 @@ class _OpsMixin:except Exception as e:logger.warning(f"[VikingFS] Failed to delete temp {temp_uri}: {e}")+ @staticmethod+ def _filter_ls_entries(path: str, entries: List[Dict[str, Any]]) -> List[Dict[str, Any]]:+ """Return entries visible at the given storage path."""+ parts = [p for p in path.strip("/").split("/") if p]+ if len(parts) == 2 and parts[0] == "local":+ return [e for e in entries if e.get("name") in VikingURI.LISTABLE_SCOPES]+ return [e for e in entries if e.get("name") not in STORAGE_INTERNAL_ENTRY_NAMES]+async def _ls_entries(- self, path: str, ctx: Optional[RequestContext] = None+ self,+ path: str,+ offset: int = 0,+ limit: Optional[int] = None,+ sort_by: Optional[str] = None,+ sort_order: str = "asc",+ filter_internal: bool = True,+ ctx: Optional[RequestContext] = None,) -> List[Dict[str, Any]]:"""List directory entries, filtering out internal directories.At account root (/local/{account}), uses LISTABLE_SCOPES whitelist.At other levels, uses the shared storage internal-name blacklist."""- entries = await self._async_agfs.ls(path)- parts = [p for p in path.strip("/").split("/") if p]- if len(parts) == 2 and parts[0] == "local":- return [e for e in entries if e.get("name") in VikingURI.LISTABLE_SCOPES]- return [e for e in entries if e.get("name") not in STORAGE_INTERNAL_ENTRY_NAMES]+ entries = await self._async_agfs.ls(+ path,+ offset=offset,+ limit=limit,+ sort_by=sort_by,+ sort_order=sort_order,+ )+ return self._filter_ls_entries(path, entries) if filter_internal else entriesdiff --git a/sdk/go/client_test.go b/sdk/go/client_test.goindex 1717a8bd3..948ca131c 100644--- a/sdk/go/client_test.go+++ b/sdk/go/client_test.go@@ -237,6 +237,12 @@ func TestListAndTreeSendQueryOptions(t *testing.T) {if got := r.URL.Query().Get("node_limit"); got != "200" {t.Fatalf("node_limit = %q", got)}+ if got := r.URL.Query().Get("offset"); got != "4" {+ t.Fatalf("offset = %q", got)+ }+ if got := r.URL.Query().Get("limit"); got != "5" {+ t.Fatalf("limit = %q", got)+ }if got := r.URL.Query().Get("sort_by"); got != "mtime" {t.Fatalf("sort_by = %q", got)}@@ -251,11 +257,25 @@ func TestListAndTreeSendQueryOptions(t *testing.T) {if got := r.URL.Query().Get("level_limit"); got != "0" {t.Fatalf("level_limit = %q, want 0", got)}+ if got := r.URL.Query().Get("offset"); got != "6" {+ t.Fatalf("offset = %q", got)+ }+ if got := r.URL.Query().Get("limit"); got != "7" {+ t.Fatalf("limit = %q", got)+ }if got := r.URL.Query()["tags"]; !reflect.DeepEqual(got, []string{"env=prod"}) {t.Fatalf("tags = %#v", got)}- } else if got := r.URL.Query().Get("level_limit"); got != "3" {- t.Fatalf("level_limit = %q, want 3", got)+ } else {+ if got := r.URL.Query().Get("level_limit"); got != "3" {+ t.Fatalf("level_limit = %q, want 3", got)+ }+ if _, ok := r.URL.Query()["offset"]; ok {+ t.Fatal("default tree request should omit offset")+ }+ if _, ok := r.URL.Query()["limit"]; ok {+ t.Fatal("default tree request should omit limit")+ }}treeCalls++default:@@ -267,13 +287,21 @@ func TestListAndTreeSendQueryOptions(t *testing.T) {if _, err := client.List(context.Background(), "viking://session", &ListOptions{NodeLimit: 200,+ Offset: 4,+ Limit: 5,SortBy: "mtime",SortOrder: "desc",Tags: []string{"env=prod", "team=search"},}); err != nil {t.Fatal(err)}- if _, err := client.Tree(context.Background(), "viking://resources/docs", &TreeOptions{LevelLimit: Int(0), Tags: []string{"env=prod"}}); err != nil {+ if _, err := client.Tree(context.Background(), "viking://resources/docs", &TreeOptions{+ NodeLimit: 200,+ LevelLimit: Int(0),+ Offset: 6,+ Limit: 7,+ Tags: []string{"env=prod"},+ }); err != nil {t.Fatal(err)}if _, err := client.Tree(context.Background(), "viking://resources/docs", nil); err != nil {diff --git a/sdk/go/filesystem.go b/sdk/go/filesystem.goindex a9ff82e0a..04529a671 100644--- a/sdk/go/filesystem.go+++ b/sdk/go/filesystem.go@@ -32,6 +32,12 @@ func (c *Client) List(ctx context.Context, uri string, opts *ListOptions) ([]anyqueryInt(query, "abs_limit", absLimit)queryBool(query, "show_all_hidden", opts.ShowAllHidden)queryInt(query, "node_limit", nodeLimit)+ if opts.Offset != 0 {+ queryInt(query, "offset", opts.Offset)+ }+ if opts.Limit != 0 {+ queryInt(query, "limit", opts.Limit)+ }if opts.Tags != nil {query["tags"] = opts.Tags}@@ -77,6 +83,12 @@ func (c *Client) Tree(ctx context.Context, uri string, opts *TreeOptions) ([]mapqueryBool(query, "show_all_hidden", opts.ShowAllHidden)queryInt(query, "node_limit", nodeLimit)queryInt(query, "level_limit", levelLimit)+ if opts.Offset != 0 {+ queryInt(query, "offset", opts.Offset)+ }+ if opts.Limit != 0 {+ queryInt(query, "limit", opts.Limit)+ }if opts.Tags != nil {query["tags"] = opts.Tags}diff --git a/sdk/go/types.go b/sdk/go/types.goindex 4f7d2beae..74ab1cd0d 100644--- a/sdk/go/types.go+++ b/sdk/go/types.go@@ -177,6 +177,8 @@ type ListOptions struct {AbsLimit intShowAllHidden boolNodeLimit int+ Offset int+ Limit intSortBy stringSortOrder stringTags []string@@ -190,6 +192,8 @@ type TreeOptions struct {ShowAllHidden boolNodeLimit intLevelLimit *int+ Offset int+ Limit intTags []stringIncludeTags bool}diff --git a/sdk/python/openviking_sdk/client.py b/sdk/python/openviking_sdk/client.pyindex 5fff2ff96..ae1e33f64 100644--- a/sdk/python/openviking_sdk/client.py+++ b/sdk/python/openviking_sdk/client.py@@ -1065,6 +1065,8 @@ class AsyncHTTPClient:extra_fields: Optional[List[str]] = None,tags: Optional[List[str]] = None,include_tags: bool = False,+ offset: int = 0,+ limit: Optional[int] = None,) -> List[Any]:params: Dict[str, Any] = {"uri": VikingURI.normalize(uri),@@ -1074,6 +1076,7 @@ class AsyncHTTPClient:"abs_limit": abs_limit,"show_all_hidden": show_all_hidden,"node_limit": node_limit,+ "offset": offset,}if sort_by is not None:params["sort_by"] = sort_by@@ -1084,6 +1087,8 @@ class AsyncHTTPClient:params["tags"] = tagsif include_tags:params["include_tags"] = True+ if limit is not None:+ params["limit"] = limitresponse = await self._request("GET","/api/v1/fs/ls",@@ -1102,6 +1107,8 @@ class AsyncHTTPClient:extra_fields: Optional[List[str]] = None,tags: Optional[List[str]] = None,include_tags: bool = False,+ offset: int = 0,+ limit: Optional[int] = None,) -> List[Dict[str, Any]]:params: Dict[str, Any] = {"uri": VikingURI.normalize(uri),@@ -1110,6 +1117,7 @@ class AsyncHTTPClient:"show_all_hidden": show_all_hidden,"node_limit": node_limit,"level_limit": level_limit,+ "offset": offset,}if extra_fields:params["extra_fields"] = list(extra_fields)@@ -1117,6 +1125,8 @@ class AsyncHTTPClient:params["tags"] = tagsif include_tags:params["include_tags"] = True+ if limit is not None:+ params["limit"] = limitresponse = await self._request("GET","/api/v1/fs/tree",@@ -1300,14 +1310,10 @@ class AsyncHTTPClient:return self._handle_response_data(response).get("result", {})async def acl_get(self, uri: str) -> Dict[str, Any]:- response = await self._http.get(- "/api/v1/acl", params={"uri": VikingURI.normalize(uri)}- )+ response = await self._http.get("/api/v1/acl", params={"uri": VikingURI.normalize(uri)})return self._handle_response_data(response).get("result", {})- async def acl_set(- self, uri: str, entries: List[Dict[str, str]]- ) -> Dict[str, Any]:+ async def acl_set(self, uri: str, entries: List[Dict[str, str]]) -> Dict[str, Any]:response = await self._http.put("/api/v1/acl",json={"uri": VikingURI.normalize(uri), "entries": entries},@@ -1884,14 +1890,10 @@ class AsyncHTTPClient:return self._handle_response(response)async def admin_delete_group(self, account_id: str, group_id: str) -> Dict[str, Any]:- response = await self._http.delete(- f"/api/v1/admin/accounts/{account_id}/groups/{group_id}"- )+ response = await self._http.delete(f"/api/v1/admin/accounts/{account_id}/groups/{group_id}")return self._handle_response(response)- async def admin_list_group_members(- self, account_id: str, group_id: str- ) -> Dict[str, Any]:+ async def admin_list_group_members(self, account_id: str, group_id: str) -> Dict[str, Any]:response = await self._http.get(f"/api/v1/admin/accounts/{account_id}/groups/{group_id}/members")@@ -2386,6 +2388,8 @@ class SyncHTTPClient:extra_fields: Optional[List[str]] = None,tags: Optional[List[str]] = None,include_tags: bool = False,+ offset: int = 0,+ limit: Optional[int] = None,) -> List[Any]:return run_async(self._async_client.ls(@@ -2401,6 +2405,8 @@ class SyncHTTPClient:extra_fields=extra_fields,tags=tags,include_tags=include_tags,+ offset=offset,+ limit=limit,))@@ -2415,6 +2421,8 @@ class SyncHTTPClient:extra_fields: Optional[List[str]] = None,tags: Optional[List[str]] = None,include_tags: bool = False,+ offset: int = 0,+ limit: Optional[int] = None,) -> List[Dict[str, Any]]:return run_async(self._async_client.tree(@@ -2427,6 +2435,8 @@ class SyncHTTPClient:extra_fields=extra_fields,tags=tags,include_tags=include_tags,+ offset=offset,+ limit=limit,))@@ -2504,9 +2514,7 @@ class SyncHTTPClient:options: Optional[SetTagsOptions] = None,) -> Dict[str, Any]:return run_async(- self._async_client.set_tags(- uri, tags, mode=mode, recursive=recursive, options=options- )+ self._async_client.set_tags(uri, tags, mode=mode, recursive=recursive, options=options))def acl_get(self, uri: str) -> Dict[str, Any]:@@ -2795,9 +2803,7 @@ class SyncHTTPClient:limit: Optional[int] = None,page: int = 1,) -> List[Any]:- return run_async(- self._async_client.admin_list_accounts(name=name, limit=limit, page=page)- )+ return run_async(self._async_client.admin_list_accounts(name=name, limit=limit, page=page))def admin_delete_account(self, account_id: str) -> Dict[str, Any]:return run_async(self._async_client.admin_delete_account(account_id))@@ -2860,9 +2866,7 @@ class SyncHTTPClient:def admin_add_group_member(self, account_id: str, group_id: str, user_id: str) -> Dict[str, Any]:- return run_async(- self._async_client.admin_add_group_member(account_id, group_id, user_id)- )+ return run_async(self._async_client.admin_add_group_member(account_id, group_id, user_id))def admin_remove_group_member(self, account_id: str, group_id: str, user_id: str@@ -2891,9 +2895,7 @@ class SyncHTTPClient:experience_uri: str,options: Optional[ExperienceTrajectoryOptions] = None,) -> Dict[str, Any]:- return run_async(- self._async_client.list_experience_trajectories(experience_uri, options)- )+ return run_async(self._async_client.list_experience_trajectories(experience_uri, options))def get_experience_outcomes(self,diff --git a/sdk/python/tests/test_async_client_behaviors.py b/sdk/python/tests/test_async_client_behaviors.pyindex 47212b97b..0220d043f 100644--- a/sdk/python/tests/test_async_client_behaviors.py+++ b/sdk/python/tests/test_async_client_behaviors.py@@ -265,9 +265,7 @@ async def test_async_http_client_sends_event_memory_tag_configuration():client._handle_response_data = lambda _response: {"result": {"status": "ok"}}config = {"events": {"tags": ["team=search", "channel=web"]}}- await client.create_session(- "tagged-session", options={"memory_extraction_config": config}- )+ await client.create_session("tagged-session", options={"memory_extraction_config": config})await client.update_session_config("tagged-session",{@@ -1322,10 +1320,12 @@ async def test_ls_and_tree_pass_query_params():abs_limit=32,show_all_hidden=True,node_limit=44,+ offset=5,+ limit=7,sort_by="mtime",sort_order="desc",)- await client.tree("viking://resources/", level_limit=2)+ await client.tree("viking://resources/", level_limit=2, offset=4, limit=6)await client.tree("viking://resources/", level_limit=0)await client.tree("viking://resources/")@@ -1340,13 +1340,16 @@ async def test_ls_and_tree_pass_query_params():"abs_limit": 32,"show_all_hidden": True,"node_limit": 44,+ "offset": 5,+ "limit": 7,"sort_by": "mtime","sort_order": "desc",},}+ assert fake_http.get.await_args_list[1].kwargs["params"]["offset"] == 4+ assert fake_http.get.await_args_list[1].kwargs["params"]["limit"] == 6assert [- tree_call.kwargs["params"]["level_limit"]- for tree_call in fake_http.get.await_args_list[1:]+ tree_call.kwargs["params"]["level_limit"] for tree_call in fake_http.get.await_args_list[1:]] == [2, 0, 3]diff --git a/sdk/typescript/src/client.ts b/sdk/typescript/src/client.tsindex e4c0c4553..b356f3950 100644--- a/sdk/typescript/src/client.ts+++ b/sdk/typescript/src/client.ts@@ -485,6 +485,8 @@ export class OpenVikingClient {abs_limit: options.absLimit ?? 256,show_all_hidden: options.showAllHidden ?? false,node_limit: options.nodeLimit ?? 1000,+ offset: options.offset,+ limit: options.limit,sort_by: options.sortBy,sort_order: options.sortOrder,tags: options.tags,@@ -502,6 +504,8 @@ export class OpenVikingClient {show_all_hidden: options.showAllHidden ?? false,node_limit: options.nodeLimit ?? 1000,level_limit: options.levelLimit ?? 3,+ offset: options.offset,+ limit: options.limit,tags: options.tags,include_tags: options.includeTags || undefined,},diff --git a/sdk/typescript/src/types.ts b/sdk/typescript/src/types.tsindex 55b289f01..33859c1c8 100644--- a/sdk/typescript/src/types.ts+++ b/sdk/typescript/src/types.ts@@ -202,6 +202,8 @@ export interface ListOptions {absLimit?: number;showAllHidden?: boolean;nodeLimit?: number;+ offset?: number;+ limit?: number;sortBy?: "name" | "mtime";sortOrder?: "asc" | "desc";tags?: string[];@@ -214,6 +216,8 @@ export interface TreeOptions {showAllHidden?: boolean;nodeLimit?: number;levelLimit?: number;+ offset?: number;+ limit?: number;tags?: string[];includeTags?: boolean;}diff --git a/sdk/typescript/tests/client.test.ts b/sdk/typescript/tests/client.test.tsindex 38f65a024..558958f89 100644--- a/sdk/typescript/tests/client.test.ts+++ b/sdk/typescript/tests/client.test.ts@@ -556,21 +556,38 @@ describe("OpenVikingClient", () => {await client.list("viking://session", {nodeLimit: 200,+ offset: 4,+ limit: 5,sortBy: "mtime",sortOrder: "desc",});- await client.tree("viking://resources/docs", { levelLimit: 2 });+ await client.tree("viking://resources/docs", {+ levelLimit: 2,+ offset: 6,+ limit: 7,+ });await client.tree("viking://resources/docs", { levelLimit: 0 });await client.tree("viking://resources/docs");const listUrl = new URL(String(fetcher.mock.calls[0]![0]));expect(listUrl.searchParams.get("node_limit")).toBe("200");+ expect(listUrl.searchParams.get("offset")).toBe("4");+ expect(listUrl.searchParams.get("limit")).toBe("5");expect(listUrl.searchParams.get("sort_by")).toBe("mtime");expect(listUrl.searchParams.get("sort_order")).toBe("desc");- const treeLimits = fetcher.mock.calls+ const treeUrls = fetcher.mock.calls.slice(1)- .map((call) => new URL(String(call[0])).searchParams.get("level_limit"));+ .map((call) => new URL(String(call[0])));+ const treeLimits = treeUrls.map((url) =>+ url.searchParams.get("level_limit"),+ );expect(treeLimits).toEqual(["2", "0", "3"]);+ expect(treeUrls[0]!.searchParams.get("offset")).toBe("6");+ expect(treeUrls[0]!.searchParams.get("limit")).toBe("7");+ expect(treeUrls[1]!.searchParams.has("offset")).toBe(false);+ expect(treeUrls[1]!.searchParams.has("limit")).toBe(false);+ expect(treeUrls[2]!.searchParams.has("offset")).toBe(false);+ expect(treeUrls[2]!.searchParams.has("limit")).toBe(false);});it("sends addResource tags and tagMode to the server", async () => {diff --git a/tests/agfs/test_fs_binding.py b/tests/agfs/test_fs_binding.pyindex a80fde066..9525be1ec 100644--- a/tests/agfs/test_fs_binding.py+++ b/tests/agfs/test_fs_binding.py@@ -61,9 +61,23 @@ class TestVikingFSBindingLocal:entries = await vfs.ls("viking://temp/")assert any(e["name"] == test_filename for e in entries)+ page_dir_uri = f"viking://temp/page_{uuid.uuid4().hex}/"+ await vfs.mkdir(page_dir_uri)+ for name in ("a.txt", "b.txt", "c.txt"):+ await vfs.write(f"{page_dir_uri}{name}", name)+ page = await vfs.ls(+ page_dir_uri,+ output="original",+ node_limit=1,+ offset=1,+ sort_by="name",+ )+ assert [entry["name"] for entry in page] == ["b.txt"]+read_data = await vfs.read(test_uri)assert read_data.decode("utf-8") == test_content+ await vfs.rm(page_dir_uri, recursive=True)await vfs.rm(test_uri)async def test_directory_operations(self, viking_fs_binding_instance):@@ -83,9 +97,17 @@ class TestVikingFSBindingLocal:file_uri = f"{test_dir_uri}inner.txt"await vfs.write(file_uri, "inner content")+ await vfs.write(f"{test_dir_uri}z.txt", "second")sub_entries = await vfs.ls(test_dir_uri)assert any(e["name"] == "inner.txt" for e in sub_entries)+ tree_page = await vfs.tree(+ test_dir_uri,+ output="original",+ node_limit=1,+ offset=1,+ )+ assert [entry["name"] for entry in tree_page] == ["z.txt"]await vfs.rm(test_dir_uri, recursive=True)diff --git a/tests/pyagfs/test_async_client_fs_ctx.py b/tests/pyagfs/test_async_client_fs_ctx.pyindex a05f184e0..01816d053 100644--- a/tests/pyagfs/test_async_client_fs_ctx.py+++ b/tests/pyagfs/test_async_client_fs_ctx.py@@ -13,6 +13,7 @@ class _RecordingClient:def __init__(self) -> None:self.calls: list[tuple[str, str, dict[str, str] | None]] = []+ self.list_options: dict[str, Any] = {}def write(self, path: str, data: bytes, *, ctx: dict[str, str] | None = None) -> str:"""Record write ctx and return a stable fake backend id."""@@ -24,6 +25,18 @@ class _RecordingClient:self.calls.append(("read", path, ctx))return b"payload"+ def ls(+ self,+ path: str,+ *,+ ctx: dict[str, str] | None = None,+ **options: Any,+ ) -> list[dict[str, Any]]:+ """Record listing options and return an empty result."""+ self.calls.append(("ls", path, ctx))+ self.list_options = options+ return []+@pytest.mark.asyncioasync def test_async_client_derives_account_ctx_from_local_agfs_path() -> None:@@ -31,8 +44,24 @@ async def test_async_client_derives_account_ctx_from_local_agfs_path() -> None:agfs = AsyncAGFSClient(client)await agfs.write("/local/acct-1/data/file.txt", b"x")+ await agfs.ls(+ "/local/acct-1/data",+ offset=2,+ limit=3,+ sort_by="mtime",+ sort_order="desc",+ )- assert client.calls == [("write", "/local/acct-1/data/file.txt", {"account_id": "acct-1"})]+ assert client.calls == [+ ("write", "/local/acct-1/data/file.txt", {"account_id": "acct-1"}),+ ("ls", "/local/acct-1/data", {"account_id": "acct-1"}),+ ]+ assert client.list_options == {+ "offset": 2,+ "limit": 3,+ "sort_by": "mtime",+ "sort_order": "desc",+ }@pytest.mark.asynciodiff --git a/tests/server/test_api_fs_ls_sort.py b/tests/server/test_api_fs_ls_sort.pyindex a4b591243..1372c0e13 100644--- a/tests/server/test_api_fs_ls_sort.py+++ b/tests/server/test_api_fs_ls_sort.py@@ -27,20 +27,21 @@ def service(temp_dir):)-async def test_ls_sorts_by_mtime_before_applying_node_limit(client, service):+async def test_ls_sorts_before_applying_offset_and_node_limit(client, service):ctx = RequestContext(user=UserIdentifier.the_default_user(), role=Role.ROOT)root_uri = "viking://resources/mtime-before-limit"await service.viking_fs.mkdir(root_uri, exist_ok=True, ctx=ctx)- for index in range(200):+ for index in range(300):await service.viking_fs.mkdir(f"{root_uri}/a-{index:03d}", ctx=ctx)newest_uri = f"{root_uri}/zz-newest"await service.viking_fs.mkdir(newest_uri, ctx=ctx)+ await service.viking_fs.mkdir(f"{root_uri}/tasks", ctx=ctx)await service.viking_fs.mkdir(f"{newest_uri}/activity", ctx=ctx)await service.viking_fs.write_file(f"{root_uri}/newer-file.md", "newer", ctx=ctx)- response = await client.get(+ mtime_response = await client.get("/api/v1/fs/ls",params={"uri": root_uri,@@ -50,11 +51,48 @@ async def test_ls_sorts_by_mtime_before_applying_node_limit(client, service):"sort_order": "desc",},)+ response = await client.get(+ "/api/v1/fs/ls",+ params={+ "uri": root_uri,+ "output": "original",+ "offset": 1,+ "node_limit": 2,+ "sort_by": "name",+ "sort_order": "desc",+ },+ )+ assert mtime_response.status_code == 200+ assert mtime_response.json()["result"][0]["name"] == "zz-newest"assert response.status_code == 200entries = response.json()["result"]- assert len(entries) == 200- assert entries[0]["name"] == "zz-newest"+ assert [entry["name"] for entry in entries] == ["a-299", "a-298"]++ filtered_page = await client.get(+ "/api/v1/fs/ls",+ params={+ "uri": root_uri,+ "output": "original",+ "limit": 256,+ "sort_by": "name",+ "sort_order": "desc",+ },+ )+ filtered_entries = filtered_page.json()["result"]+ assert len(filtered_entries) == 256+ assert all(entry["name"] != "tasks" for entry in filtered_entries)++ invalid_offset = await client.get(+ "/api/v1/fs/ls",+ params={"uri": root_uri, "offset": -1},+ )+ invalid_limit = await client.get(+ "/api/v1/fs/ls",+ params={"uri": root_uri, "limit": 0},+ )+ assert invalid_offset.status_code == 400+ assert invalid_limit.status_code == 400async def test_session_list_keeps_newest_directory_past_storage_limit(client, service):diff --git a/tests/server/test_filesystem_router.py b/tests/server/test_filesystem_router.pyindex 071e89ee6..48b865c6e 100644--- a/tests/server/test_filesystem_router.py+++ b/tests/server/test_filesystem_router.py@@ -369,23 +369,39 @@ async def test_ls_user_container_lists_only_caller_space(app, client, service):@pytest.mark.asyncio-async def test_ls_forwards_tags_to_filesystem_service(monkeypatch):- seen = {}+async def test_ls_and_tree_forward_pagination_to_filesystem_service(monkeypatch):+ seen = {"ls": {}, "tree": {}}async def fake_ls(uri, **kwargs):- seen.update(uri=uri, **kwargs)+ seen["ls"].update(uri=uri, **kwargs)+ return []++ async def fake_tree(uri, **kwargs):+ seen["tree"].update(uri=uri, **kwargs)return []monkeypatch.setattr(filesystem,"get_service",- lambda: SimpleNamespace(fs=SimpleNamespace(ls=fake_ls)),+ lambda: SimpleNamespace(fs=SimpleNamespace(ls=fake_ls, tree=fake_tree)),)await filesystem.ls(uri="viking://resources",tags=["team=search", "env=prod"],+ offset=4,+ limit=9,+ _ctx=RequestContext(user=UserIdentifier("acct", "alice"), role=Role.USER),+ )+ await filesystem.tree(+ uri="viking://resources",+ offset=3,+ limit=5,_ctx=RequestContext(user=UserIdentifier("acct", "alice"), role=Role.USER),)- assert seen["tags"] == ["team=search", "env=prod"]+ assert seen["ls"]["tags"] == ["team=search", "env=prod"]+ assert seen["ls"]["offset"] == 4+ assert seen["ls"]["node_limit"] == 9+ assert seen["tree"]["offset"] == 3+ assert seen["tree"]["node_limit"] == 5diff --git a/tests/service/test_fs_service.py b/tests/service/test_fs_service.pyindex bbdfbda3d..e378ff8f6 100644--- a/tests/service/test_fs_service.py+++ b/tests/service/test_fs_service.py@@ -530,18 +530,30 @@ async def test_tagged_grep_reuses_tags_returned_by_viking_fs(request_context):@pytest.mark.asyncio-async def test_ls_projects_tags_filters_with_and_before_applying_node_limit(request_context):+async def test_ls_applies_offset_and_node_limit_after_tag_filtering(request_context):entries = [- {"uri": "viking://resources/a.md", "isDir": False},+ {+ "uri": f"viking://resources/unmatched-{index:03d}.md",+ "isDir": False,+ }+ for index in range(256)+ ] + [{"uri": "viking://resources/b.md", "isDir": False},{"uri": "viking://resources/c.md", "isDir": False},]- viking_fs = SimpleNamespace(ls=AsyncMock(return_value=entries))++ async def fake_ls(*_args, offset=0, node_limit=None, **_kwargs):+ return entries[offset:] if node_limit is None else entries[offset : offset + node_limit]++ finalized = [{"uri": "viking://resources/c.md", "isDir": False, "abstract": "summary"}]+ viking_fs = SimpleNamespace(+ ls=AsyncMock(side_effect=fake_ls),+ _finalize_listing_entries=AsyncMock(return_value=finalized),+ )class FakeVikingDB:async def filter(self, **_kwargs):return [- {"uri": "viking://resources/a.md", "level": 2, "search_tags": ["team=search"]},{"uri": "viking://resources/b.md","level": 2,@@ -560,12 +572,19 @@ async def test_ls_projects_tags_filters_with_and_before_applying_node_limit(requctx=request_context,tags=["team=search", "env=prod"],node_limit=1,+ offset=1,+ output="agent",)- assert result == [- {"uri": "viking://resources/b.md", "isDir": False, "tags": ["team=search", "env=prod"]}+ assert result == finalized+ assert viking_fs.ls.await_count == 2+ assert viking_fs.ls.await_args_list[0].kwargs["output"] == "original"+ assert viking_fs.ls.await_args_list[0].kwargs["node_limit"] == 256+ assert viking_fs.ls.await_args_list[1].kwargs["offset"] == 256+ selected = viking_fs._finalize_listing_entries.await_args.args[0]+ assert selected == [+ {"uri": "viking://resources/c.md", "isDir": False, "tags": ["team=search", "env=prod"]}]- assert viking_fs.ls.await_args.kwargs["node_limit"] is None@pytest.mark.asyncio@@ -635,7 +654,7 @@ async def test_tree_projects_directory_tags_from_abstract_and_overview_records(rassert result == [{"uri": "viking://resources/docs", "isDir": True, "tags": ["team=search", "env=prod"]}]- assert viking_fs.tree.await_args.kwargs["node_limit"] is None+ assert viking_fs.tree.await_args.kwargs["node_limit"] == 1000@pytest.mark.asynciodiff --git a/tests/storage/test_viking_fs_tree.py b/tests/storage/test_viking_fs_tree.pyindex 17c3efe51..885b084bc 100644--- a/tests/storage/test_viking_fs_tree.py+++ b/tests/storage/test_viking_fs_tree.py@@ -258,13 +258,13 @@ def test_is_tree_entry_visible_default_ctx(monkeypatch, fs):@pytest.mark.asyncio-async def test_iter_visible_tree_entries_node_limit_amplified_to_rust(monkeypatch, fs):- """PY-ITER-001: node_limit is amplified (× overfetch factor) when pushed to- Rust, keeping memory bounded while preserving the ACL-after-filter semantic."""+async def test_iter_visible_tree_entries_uses_minimum_backend_page_size(monkeypatch, fs):+ """PY-ITER-001: bounded tree reads use the minimum backend page size."""captured = {}async def fake_tree_directory(_path, **kwargs):captured["node_limit"] = kwargs.get("node_limit")+ captured["offset"] = kwargs.get("offset")return []patch_tree_env(monkeypatch, fs, fake_tree_directory)@@ -274,7 +274,7 @@ async def test_iter_visible_tree_entries_node_limit_amplified_to_rust(monkeypatc):pass- assert captured["node_limit"] == 10 * fs._TREE_OVERFETCH_FACTOR+ assert captured == {"node_limit": 256, "offset": 0}@pytest.mark.asyncio@@ -318,8 +318,8 @@ async def test_iter_visible_tree_entries_level_limit_passed_to_rust(monkeypatch,@pytest.mark.asyncio-async def test_iter_visible_tree_entries_node_limit_after_acl(monkeypatch, fs):- """PY-ITER-002: node_limit applied AFTER ACL filtering."""+async def test_iter_visible_tree_entries_offset_and_node_limit_after_acl(monkeypatch, fs):+ """PY-ITER-002: offset and node_limit apply after ACL filtering."""visible_count = 0entries = [@@ -336,41 +336,33 @@ async def test_iter_visible_tree_entries_node_limit_after_acl(monkeypatch, fs):results = []async for entry, _entry_uri in fs._iter_visible_tree_entries(- "viking://resources", node_limit=3, ctx=_default_ctx()+ "viking://resources", offset=1, node_limit=2, ctx=_default_ctx()):results.append(entry)- assert len(results) == 3- assert visible_count == 3, "only 3 entries should have ACL checked before limit hit"+ assert [entry["info"]["name"] for entry in results] == ["b", "c"]+ assert visible_count == 3, "only skipped and returned entries should be ACL checked"@pytest.mark.asyncio-async def test_iter_visible_tree_entries_refetch_when_under_limit(monkeypatch, fs):- """PY-ITER-004: when ACL filtering leaves too few visible entries and Rust- returned a full page, the raw limit is doubled and re-fetched (zero-regression- bounded over-fetch)."""- factor = fs._TREE_OVERFETCH_FACTOR+async def test_iter_visible_tree_entries_reads_next_page_when_filtering_is_sparse(monkeypatch, fs):+ """PY-ITER-004: sparse visible results advance the RagFS offset."""node_limit = 2- # First page (size == raw_limit) is entirely invisible; second page after- # doubling contains the visible entries.invisible = [- make_entry(f"/local/test_account/resources/h{i}/x", "x", is_dir=False)- for i in range(node_limit * factor)+ make_entry(f"/local/test_account/resources/h{i}/x", "x", is_dir=False) for i in range(256)]visible = [make_entry(f"/local/test_account/resources/v{i}", f"v{i}", is_dir=False)for i in range(node_limit)]- captured_limits = []+ entries = invisible + visible+ captured_pages = []async def fake_tree_directory(_path, **kwargs):+ raw_offset = kwargs.get("offset")raw_limit = kwargs.get("node_limit")- captured_limits.append(raw_limit)- # First call returns a full page of invisible entries; subsequent call- # (doubled limit) returns invisible + visible.- if len(captured_limits) == 1:- return invisible[:raw_limit]- return invisible + visible+ captured_pages.append((raw_offset, raw_limit))+ return entries[raw_offset : raw_offset + raw_limit]def fake_is_accessible(uri, _ctx):# Entries under an "hN" directory are invisible (ACL denied).@@ -385,9 +377,7 @@ async def test_iter_visible_tree_entries_refetch_when_under_limit(monkeypatch, fresults.append(entry)assert len(results) == node_limit- # Re-fetch happened: first raw_limit = node_limit*factor, then doubled.- assert captured_limits[0] == node_limit * factor- assert captured_limits[1] == node_limit * factor * 2+ assert captured_pages == [(0, 256), (256, 256)]@pytest.mark.asyncio@@ -657,6 +647,14 @@ async def test_ls_agent_modtime_is_raw_utc_iso(monkeypatch, fs):"isDir": True,"access": "denied",}+ tied = [+ ({"name": name, "isDir": False, "modTime": "2026-01-01T00:00:00Z"}, name)+ for name in ["b.md", "a.md"]+ ]+ assert [entry["name"] for entry, _ in fs._sort_ls_entry_items(tied, "mtime", "desc")] == [+ "a.md",+ "b.md",+ ]@pytest.mark.asynciodiff --git a/tests/utils/mock_agfs.py b/tests/utils/mock_agfs.pyindex ecb080f6f..ee061d89d 100644--- a/tests/utils/mock_agfs.py+++ b/tests/utils/mock_agfs.py@@ -34,6 +34,7 @@ class MockLocalAGFS:self._resolve(path).mkdir(parents=parents, exist_ok=exist_ok)def ls(self, path, ctx=None, **kwargs):+ """List test entries with the same sorting and pagination contract as RagFS."""p = self._resolve(path)if not p.exists():return []@@ -49,7 +50,28 @@ class MockLocalAGFS:"uri": f"viking://{path}/{item.name}".replace("//", "/"),})- return res+ sort_by = kwargs.get("sort_by")+ reverse = kwargs.get("sort_order", "asc") == "desc"+ if sort_by:+ key = (+ (lambda entry: (str(entry["name"]).lower(), str(entry["name"])))+ if sort_by == "name"+ else (+ lambda entry: (+ entry["mtime"],+ str(entry["name"]).lower(),+ str(entry["name"]),+ )+ )+ )+ directories = sorted(+ (entry for entry in res if entry["isDir"]), key=key, reverse=reverse+ )+ files = sorted((entry for entry in res if not entry["isDir"]), key=key, reverse=reverse)+ res = directories + files+ offset = kwargs.get("offset", 0)+ limit = kwargs.get("limit")+ return res[offset:] if limit is None else res[offset : offset + limit]def glob_directory(self,