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(fs): 为 ls 和 tree 增加分页状态 (#5330)
hezhang-12166c601a9d4135
diff --git a/crates/ov_cli/src/base_client.rs b/crates/ov_cli/src/base_client.rsindex 471837f2c..cba371bf9 100644--- a/crates/ov_cli/src/base_client.rs+++ b/crates/ov_cli/src/base_client.rs@@ -124,19 +124,31 @@ pub fn unwrap_success_envelope(json: Value, preserve_profile: bool) -> Value {return result.clone();}- let Some(profile) = json.get("profile").filter(|profile| !profile.is_null()) else {+ let profile = json.get("profile").filter(|profile| !profile.is_null());+ let has_more = json.get("has_more").filter(|has_more| !has_more.is_null());+ if profile.is_none() && has_more.is_none() {return result.clone();- };+ }if let Some(result_obj) = result.as_object() {let mut merged = result_obj.clone();- merged.insert("profile".to_string(), profile.clone());+ if let Some(profile) = profile {+ merged.insert("profile".to_string(), profile.clone());+ }+ if let Some(has_more) = has_more {+ merged.insert("has_more".to_string(), has_more.clone());+ }return Value::Object(merged);}let mut wrapped = serde_json::Map::new();wrapped.insert("result".to_string(), result.clone());- wrapped.insert("profile".to_string(), profile.clone());+ if let Some(profile) = profile {+ wrapped.insert("profile".to_string(), profile.clone());+ }+ if let Some(has_more) = has_more {+ wrapped.insert("has_more".to_string(), has_more.clone());+ }Value::Object(wrapped)}@@ -672,6 +684,25 @@ mod tests {);}+ #[test]+ fn unwrap_success_envelope_preserves_listing_metadata_for_value_results() {+ let body = json!({+ "status": "ok",+ "result": [{"name": "a.md"}],+ "has_more": true+ });++ let result = unwrap_success_envelope(body, true);++ assert_eq!(+ result,+ json!({+ "result": [{"name": "a.md"}],+ "has_more": true+ })+ );+ }+#[tokio::test]async fn request_timeout_is_not_reported_as_network_failure() {let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();diff --git a/crates/ov_cli/src/commands/filesystem.rs b/crates/ov_cli/src/commands/filesystem.rsindex 87e6e14cc..5428fd3a5 100644--- a/crates/ov_cli/src/commands/filesystem.rs+++ b/crates/ov_cli/src/commands/filesystem.rs@@ -283,7 +283,7 @@ fn output_filesystem_entries(}if simple {if let Some(rendered) = render_simple_fields(result, &defs, is_tree) {- println!("{rendered}");+ println!("{}", with_more_nodes_hint(rendered, result));} else {output_success(result, output_format, compact);}@@ -293,7 +293,7 @@ fn output_filesystem_entries(} else if let Some(rendered) =render_filesystem_entries_for_table(result, output_format, is_tree, simple){- println!("{rendered}");+ println!("{}", with_more_nodes_hint(rendered, result));} else {output_success(result, output_format, compact);}@@ -354,6 +354,23 @@ fn render_simple_tree_paths(result: &Value) -> Option<String> {render_simple_fields(result, &[path], false)}+fn render_simple_paths(result: &Value) -> Option<String> {+ let entries = result+ .get("result")+ .and_then(Value::as_array)+ .or_else(|| result.as_array())?;+ if entries.iter().all(Value::is_string) {+ return Some(+ entries+ .iter()+ .filter_map(Value::as_str)+ .collect::<Vec<_>>()+ .join("\n"),+ );+ }+ render_simple_tree_paths(result)+}+fn render_fields_table(result: &Value, fields: &[&FieldDef], is_tree: bool) {let (entries, profile) = match filesystem_entries(result) {Some(v) => v,@@ -366,6 +383,7 @@ fn render_fields_table(result: &Value, fields: &[&FieldDef], is_tree: bool) {if entries.is_empty() {lines.push(theme::muted("(empty)").to_string());append_profile_lines(profile, &mut lines);+ append_more_nodes_hint(result, &mut lines);println!("{}", lines.join("\n"));return;}@@ -432,9 +450,25 @@ fn render_fields_table(result: &Value, fields: &[&FieldDef], is_tree: bool) {}append_profile_lines(profile, &mut lines);+ append_more_nodes_hint(result, &mut lines);println!("{}", lines.join("\n"));}+fn append_more_nodes_hint(result: &Value, lines: &mut Vec<String>) {+ if result.get("has_more").and_then(Value::as_bool) == Some(true) {+ lines.push(String::new());+ lines.push(+ theme::muted("More nodes available. Use --offset to view the next page.").to_string(),+ );+ }+}++fn with_more_nodes_hint(rendered: String, result: &Value) -> String {+ let mut lines = vec![rendered];+ append_more_nodes_hint(result, &mut lines);+ lines.join("\n")+}+fn display_width(s: &str) -> usize {s.width()}@@ -483,12 +517,10 @@ fn render_filesystem_entries_for_table(if matches!(output_format, OutputFormat::Json) {return None;}- if is_tree {- if simple {- render_simple_tree_paths(value)- } else {- render_tree_entries_for_table(value)- }+ if simple {+ render_simple_paths(value)+ } else if is_tree {+ render_tree_entries_for_table(value)} else {render_ls_entries_for_table(value)}@@ -959,7 +991,7 @@ fn output_message_result(mod tests {use super::{render_filesystem_entries_for_table, render_ls_entries_for_table, render_simple_fields,- render_tree_entries_for_table,+ render_tree_entries_for_table, with_more_nodes_hint,};use crate::output::render_profiled_scalar_result;use serde_json::json;@@ -1148,6 +1180,21 @@ mod tests {);}+ #[test]+ fn table_output_appends_more_nodes_hint() {+ let result = json!({+ "result": [{"uri": "viking://resources/a.md", "isDir": false}],+ "has_more": true+ });++ let rendered = strip_ansi(&with_more_nodes_hint("a.md".to_string(), &result));++ assert_eq!(+ rendered,+ "a.md\n\nMore nodes available. Use --offset to view the next page."+ );+ }+#[test]fn tree_simple_without_fields_renders_one_path_per_line() {let result = json!([@@ -1165,6 +1212,29 @@ mod tests {assert_eq!(rendered.as_deref(), Some("docs/\ndocs/readme.md"));}+ #[test]+ fn ls_simple_with_pagination_metadata_renders_one_uri_per_line() {+ let result = json!({+ "result": [+ "viking://resources/a.md",+ "viking://resources/b.md"+ ],+ "has_more": true+ });++ let rendered = render_filesystem_entries_for_table(+ &result,+ crate::output::OutputFormat::Table,+ false,+ true,+ );++ assert_eq!(+ rendered.as_deref(),+ Some("viking://resources/a.md\nviking://resources/b.md")+ );+ }+#[test]fn simple_id_field_keeps_complete_record_id() {let record_id = "0123456789abcdef0123456789abcdef";diff --git a/crates/ov_cli/src/output.rs b/crates/ov_cli/src/output.rsindex 712144c21..42bee303b 100644--- a/crates/ov_cli/src/output.rs+++ b/crates/ov_cli/src/output.rs@@ -44,21 +44,33 @@ fn compact_success_value<T: Serialize>(result: T) -> Value {value => return json!({ "ok": true, "result": value }),};- let Some(profile) = obj.remove("profile") else {- return json!({ "ok": true, "result": Value::Object(obj) });+ let had_profile = obj.contains_key("profile");+ let profile = obj.remove("profile").filter(|value| !value.is_null());+ let has_more = if obj.contains_key("result") {+ obj.remove("has_more").filter(|value| !value.is_null())+ } else {+ None};-- let result = if obj.len() == 1 && obj.contains_key("result") {+ let result = if (had_profile || has_more.is_some())+ && obj.len() == 1+ && obj.contains_key("result")+ {obj.remove("result").unwrap_or(Value::Null)} else {Value::Object(obj)};- if profile.is_null() {- return json!({ "ok": true, "result": result });+ let mut response = match profile {+ Some(profile) => json!({ "status": "ok", "result": result, "profile": profile }),+ None => json!({ "ok": true, "result": result }),+ };+ if let Some(has_more) = has_more {+ response+ .as_object_mut()+ .expect("success response must be an object")+ .insert("has_more".to_string(), has_more);}-- json!({ "status": "ok", "result": result, "profile": profile })+ response}fn print_table<T: Serialize>(result: T, compact: bool) {@@ -1232,6 +1244,50 @@ mod tests {);}+ #[test]+ fn test_compact_json_lifts_has_more_next_to_list_result() {+ let value = json!({+ "result": [+ {"uri": "viking://resources/a.md"}+ ],+ "has_more": false+ });++ let rendered = compact_success_value(value);++ assert_eq!(+ rendered,+ json!({+ "ok": true,+ "result": [+ {"uri": "viking://resources/a.md"}+ ],+ "has_more": false+ })+ );+ }++ #[test]+ fn test_compact_json_keeps_business_has_more_inside_result() {+ let value = json!({+ "items": [{"id": "1"}],+ "has_more": true+ });++ let rendered = compact_success_value(value);++ assert_eq!(+ rendered,+ json!({+ "ok": true,+ "result": {+ "items": [{"id": "1"}],+ "has_more": true+ }+ })+ );+ }+#[test]fn test_profile_section_is_not_duplicated_for_plain_object_output() {let value = json!({diff --git a/crates/ov_cli/src/tui/tree.rs b/crates/ov_cli/src/tui/tree.rsindex 995118183..2723865d2 100644--- a/crates/ov_cli/src/tui/tree.rs+++ b/crates/ov_cli/src/tui/tree.rs@@ -21,6 +21,11 @@ impl FsEntry {}}+fn parse_ls_entries(result: serde_json::Value) -> Result<Vec<FsEntry>, String> {+ let entries = result.get("result").unwrap_or(&result);+ serde_json::from_value(entries.clone()).map_err(|e| e.to_string())+}+#[derive(Debug, Clone)]pub struct TreeNode {pub entry: FsEntry,@@ -158,13 +163,7 @@ impl TreeState {.await.map_err(|e| e.to_string())?;- let entries: Vec<FsEntry> = if let Some(arr) = result.as_array() {- arr.iter()- .filter_map(|v| serde_json::from_value(v.clone()).ok())- .collect()- } else {- serde_json::from_value(result).unwrap_or_default()- };+ let entries = parse_ls_entries(result)?;let mut nodes: Vec<TreeNode> = entries.into_iter()@@ -339,3 +338,34 @@ impl TreeState {.any(|s| selected_uri == format!("viking://{}", s))}}++#[cfg(test)]+mod tests {+ use super::*;+ use serde_json::json;++ #[test]+ fn parse_ls_entries_accepts_listing_envelope() {+ let entries = parse_ls_entries(json!({+ "result": [+ {"uri": "viking://resources/a.md", "isDir": false}+ ],+ "has_more": false+ }))+ .unwrap();++ assert_eq!(entries.len(), 1);+ assert_eq!(entries[0].uri, "viking://resources/a.md");+ }++ #[test]+ fn parse_ls_entries_accepts_legacy_array() {+ let entries = parse_ls_entries(json!([+ {"uri": "viking://resources/a.md", "isDir": false}+ ]))+ .unwrap();++ assert_eq!(entries.len(), 1);+ assert_eq!(entries[0].uri, "viking://resources/a.md");+ }+}diff --git a/docs/en/api/03-filesystem.md b/docs/en/api/03-filesystem.mdindex e3bda1f82..8393cbe65 100644--- a/docs/en/api/03-filesystem.md+++ b/docs/en/api/03-filesystem.md@@ -131,6 +131,7 @@ openviking glob "**/*.md" [--uri viking://resources/] [--simple] [--tags team=se`-f`/`--fields` accepts a comma-separated list of columns to display (ps `-o` style), producing a column-aligned table with a header row. Available fields: `name`, `uri`, `path`, `type`, `size`, `mode`, `mtime`, `locked`, `id`, `count`, `abstract`, `tags`. Combining `--simple` with `-f` outputs comma-separated values (no header, no tree indentation), one entry per line — suitable for scripting pipelines. When `--simple` is used without `-f`, the previous behavior (bare URI per line) is preserved.+The HTTP `result` remains an entry array. `has_more=true` means more matching nodes remain after visibility, tags, offset, and limit are applied. The Python, TypeScript, and Go SDKs continue to return the `result` array. When more nodes are available, the CLI appends a pagination hint to its output.**Response**@@ -147,6 +148,7 @@ openviking glob "**/*.md" [--uri viking://resources/] [--simple] [--tags team=se"uri": "viking://resources/docs/"}],+ "has_more": true,"time": 0.1}```@@ -220,6 +222,7 @@ curl -X GET "http://localhost:1933/api/v1/fs/tree?uri=viking://resources/" \openviking tree viking://resources/my-project/```+As with `ls`, the HTTP `result` remains a node array and `has_more` is returned at the top level. When `has_more=true`, the CLI appends a pagination hint to the tree output.**Response**@@ -242,6 +245,7 @@ openviking tree viking://resources/my-project/"uri": "viking://resources/docs/api.md"}],+ "has_more": true,"time": 0.1}```diff --git a/docs/zh/api/03-filesystem.md b/docs/zh/api/03-filesystem.mdindex 069093990..599187509 100644--- a/docs/zh/api/03-filesystem.md+++ b/docs/zh/api/03-filesystem.md@@ -155,6 +155,7 @@ openviking ls viking://resources/ --simple --fields uri,tagsCLI 会按所选列请求 `extra_fields`(`locked`、`id`、`count`);选择 `tags` 列时会请求 `include_tags=true`。这些列选择不改变 `tags` 的 AND 过滤语义。+HTTP 响应中的 `result` 保持为条目数组。`has_more=true` 表示在应用可见性、tags、offset 和 limit 后仍有后续匹配节点;Python、TypeScript 和 Go SDK 继续返回 `result` 数组。CLI 检测到后续节点时会在输出末尾显示翻页提示。**响应**@@ -172,6 +173,7 @@ CLI 会按所选列请求 `extra_fields`(`locked`、`id`、`count`);选择"tags": ["team=search"]}],+ "has_more": true,"time": 0.1}```@@ -265,6 +267,7 @@ openviking tree viking://resources/my-project/ --fields path,type,tagsopenviking tree viking://resources/my-project/ --simple --fields path,tags```+与 `ls` 一致,HTTP 响应中的 `result` 保持为节点数组,`has_more` 位于响应顶层。CLI 检测到 `has_more=true` 时会在树输出末尾显示后续节点提示。**响应**@@ -289,6 +292,7 @@ openviking tree viking://resources/my-project/ --simple --fields path,tags"tags": ["team=search", "env=prod"]}],+ "has_more": true,"time": 0.1}```diff --git a/openviking/server/mcp_endpoint.py b/openviking/server/mcp_endpoint.pyindex 1f848b567..e1d747646 100644--- a/openviking/server/mcp_endpoint.py+++ b/openviking/server/mcp_endpoint.py@@ -818,7 +818,8 @@ async def ls(if sort_by is not None:options["sort_by"] = sort_byoptions["sort_order"] = sort_order- entries = await service.fs.ls(resolved_uri, **options)+ page = await service.fs.ls(resolved_uri, **options)+ entries = page.entriesif not entries:return f"(no entries under {uri})"@@ -831,6 +832,8 @@ async def ls(lines.append(f"[{'dir' if is_dir else 'file'}] {entry_uri}")else:lines.append(f"[{'dir' if is_dir else 'file'}] {name}")+ if page.has_more:+ lines.append("(more entries available; use offset and limit to view the next page)")return "\n".join(lines)@@ -887,7 +890,7 @@ async def tree(output = "agent" if include_abstract else "original"effective_limit = limit if limit is not None else node_limittry:- entries = await service.fs.tree(+ page = await service.fs.tree(resolved_uri,ctx=ctx,output=output,@@ -897,7 +900,8 @@ async def tree(offset=offset,)except NotFoundError:- entries = []+ page = None+ entries = page.entries if page is not None else []if not entries:return f"(nothing under {uri})"@@ -916,7 +920,7 @@ async def tree(abstract = _tree_abstract(e)if include_abstract and abstract:lines.append(f"{indent} - {abstract}")- if len(entries) >= effective_limit:+ if page is not None and page.has_more:lines.append(f"(truncated at node_limit={effective_limit}; narrow the uri or raise node_limit to see more)")diff --git a/openviking/server/models.py b/openviking/server/models.pyindex ab3160150..ac0decc0a 100644--- a/openviking/server/models.py+++ b/openviking/server/models.py@@ -25,6 +25,12 @@ class Response(BaseModel):profile: Optional[list[str]] = None+class ListingResponse(Response):+ """Filesystem listing response with pagination metadata."""++ has_more: bool++# Error code to HTTP status code mappingERROR_CODE_TO_HTTP_STATUS = {"OK": 200,diff --git a/openviking/server/routers/filesystem.py b/openviking/server/routers/filesystem.pyindex 191e5b134..773235b81 100644--- a/openviking/server/routers/filesystem.py+++ b/openviking/server/routers/filesystem.py@@ -15,7 +15,7 @@ from openviking.server.auth import get_request_contextfrom openviking.server.dependencies import get_servicefrom openviking.server.error_mapping import map_exceptionfrom openviking.server.identity import RequestContext-from openviking.server.models import Response+from openviking.server.models import ListingResponse, Responsefrom openviking.server.routers.content import SetTagsRequestfrom openviking.server.routers.content import set_tags as content_set_tagsfrom openviking.storage.acl import AclSpec@@ -95,7 +95,7 @@ async def ls(# Resolve path variablesuri = validate_request_viking_uri(resolve_path_variables(uri), _ctx)try:- result = await service.fs.ls(+ page = await service.fs.ls(uri,ctx=_ctx,recursive=recursive,@@ -118,7 +118,7 @@ async def ls(if mapped is not None:raise mapped from eraise- return Response(status="ok", result=result)+ return ListingResponse(status="ok", result=page.entries, has_more=page.has_more)@router.get("/tree")@@ -144,7 +144,7 @@ async def tree(# Resolve path variablesuri = validate_request_viking_uri(resolve_path_variables(uri), _ctx)try:- result = await service.fs.tree(+ page = await service.fs.tree(uri,ctx=_ctx,output=output,@@ -164,7 +164,7 @@ async def tree(if mapped is not None:raise mapped from eraise- return Response(status="ok", result=result)+ return ListingResponse(status="ok", result=page.entries, has_more=page.has_more)@router.get("/stat")diff --git a/openviking/server/routers/skills.py b/openviking/server/routers/skills.pyindex efb02702c..09659519f 100644--- a/openviking/server/routers/skills.py+++ b/openviking/server/routers/skills.py@@ -138,13 +138,14 @@ async def _list_skills_from_root(nested directories like ``<skill>/scripts`` out of the listing."""try:- entries = await service.fs.ls(+ page = await service.fs.ls(root_uri,ctx=ctx,output="agent",abs_limit=1024,node_limit=node_limit,)+ entries = page.entriesexcept NotFoundError:return []@@ -322,7 +323,7 @@ async def _list_skill_files(child_limit = max(node_limit - len(entries), 0)if child_limit <= 0:break- children = await service.fs.ls(+ page = await service.fs.ls(current_uri,ctx=ctx,output="agent",@@ -330,6 +331,7 @@ async def _list_skill_files(show_all_hidden=True,node_limit=child_limit,)+ children = page.entriesfor entry in children:if not isinstance(entry, dict):continuediff --git a/openviking/server/routers/webdav.py b/openviking/server/routers/webdav.pyindex 5a695bed9..b8102be02 100644--- a/openviking/server/routers/webdav.py+++ b/openviking/server/routers/webdav.py@@ -234,14 +234,14 @@ async def propfind(entries = [_entry_from_stat(request, normalized_path, stat)]if _depth_header(request) > 0 and stat.get("isDir", False):- children = await service.fs.ls(+ page = await service.fs.ls(uri,ctx=_ctx,output="original",show_all_hidden=True,node_limit=10000,)- for child in _exposed_child_entries(children):+ for child in _exposed_child_entries(page.entries):child_name = str(child["name"])child_path = child_name if not normalized_path else f"{normalized_path}/{child_name}"entries.append(_entry_from_stat(request, child_path, child))diff --git a/openviking/service/fs_service.py b/openviking/service/fs_service.pyindex fb8f14420..1b9580e2b 100644--- a/openviking/service/fs_service.py+++ b/openviking/service/fs_service.py@@ -8,6 +8,7 @@ Provides file system operations: ls, mkdir, rm, mv, tree, stat, read, abstract,import asynciofrom collections.abc import Coroutine+from dataclasses import dataclassfrom typing import TYPE_CHECKING, Any, Awaitable, Callable, Dict, List, Literal, Optionalfrom openviking.core.context import ContextLevel@@ -62,6 +63,12 @@ from openviking_cli.utils.config import get_openviking_configlogger = get_logger(__name__)+@dataclass+class ListingPage:+ entries: List[Any]+ has_more: bool++def _may_include_memory_content(uri: str) -> bool:"""Return whether a public subtree read can contain memory files."""if is_session_uri(uri):@@ -202,7 +209,7 @@ class FSService:include_tags: bool,offset: int,node_limit: int,- ) -> List[Dict[str, Any]]:+ ) -> ListingPage:"""Collect a visible page after tag filtering.Args:@@ -214,31 +221,32 @@ class FSService:node_limit: Maximum matched entries to return.Returns:- The requested page of tag-filtered entries.+ The requested page and whether more matched entries are available."""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:]+ return ListingPage(entries=entries[offset:], has_more=False)batch_size = max(node_limit, 256)+ probe_limit = node_limit + 1source_offset = 0remaining_offset = offsetresult: List[Dict[str, Any]] = []- while len(result) < node_limit:+ while len(result) < probe_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)]+ filtered[remaining_offset : remaining_offset + probe_limit - len(result)])remaining_offset = 0if len(entries) < batch_size:breaksource_offset += len(entries)- return result+ return ListingPage(entries=result[:node_limit], has_more=len(result) > node_limit)async def ls(self,@@ -257,7 +265,7 @@ class FSService:tags: Optional[List[str]] = None,include_tags: bool = False,offset: int = 0,- ) -> List[Any]:+ ) -> ListingPage:"""List directory contents.Args:@@ -306,7 +314,7 @@ class FSService:)if tags:- entries = await self._collect_tagged_page(+ page = await self._collect_tagged_page(fetch_page,ctx,tags,@@ -315,22 +323,33 @@ class FSService:node_limit,)else:- entries = await fetch_page(offset, node_limit)+ fetch_limit = node_limit + 1 if node_limit > 0 else node_limit+ entries = await fetch_page(offset, fetch_limit)entries = await self._attach_and_filter_tags(entries, ctx, None, include_tags or "tags" in extra_fields)+ page = ListingPage(+ entries=entries[:node_limit] if node_limit > 0 else entries,+ has_more=node_limit > 0 and len(entries) > node_limit,+ )if use_simple_paths:- return [entry.get("uri", "") for entry in entries]+ return ListingPage(+ entries=[entry.get("uri", "") for entry in page.entries],+ has_more=page.has_more,+ )if tags and (output != "original" or extra_fields):- return await viking_fs._finalize_listing_entries(- entries,- output,- abs_limit,- extra_fields,- recursive,- ctx=ctx,+ return ListingPage(+ entries=await viking_fs._finalize_listing_entries(+ page.entries,+ output,+ abs_limit,+ extra_fields,+ recursive,+ ctx=ctx,+ ),+ has_more=page.has_more,)- return entries+ return page@staticmethoddef _reject_storage_internal_target(uri: str) -> None:@@ -935,7 +954,7 @@ class FSService:tags: Optional[List[str]] = None,include_tags: bool = False,offset: int = 0,- ) -> List[Dict[str, Any]]:+ ) -> ListingPage:"""Get directory tree."""viking_fs = self._ensure_initialized()@@ -954,7 +973,7 @@ class FSService:)if tags:- result = await self._collect_tagged_page(+ page = await self._collect_tagged_page(fetch_page,ctx,tags,@@ -963,19 +982,27 @@ class FSService: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 ListingPage(+ entries=await viking_fs._finalize_listing_entries(+ page.entries,+ output,+ abs_limit,+ extra_fields,+ True,+ ctx=ctx,+ ),+ has_more=page.has_more,)- return result+ return page- 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 [])+ fetch_limit = node_limit + 1 if node_limit > 0 else node_limit+ entries = await fetch_page(offset, fetch_limit)+ entries = await self._attach_and_filter_tags(+ entries, ctx, None, include_tags or "tags" in (extra_fields or [])+ )+ return ListingPage(+ entries=entries[:node_limit] if node_limit > 0 else entries,+ has_more=node_limit > 0 and len(entries) > node_limit,)async def stat(diff --git a/tests/integration/test_agent_memory_e2e.py b/tests/integration/test_agent_memory_e2e.pyindex 3fecdddf4..85124a35d 100644--- a/tests/integration/test_agent_memory_e2e.py+++ b/tests/integration/test_agent_memory_e2e.py@@ -189,7 +189,7 @@ def _list_non_overview_entries(uri: str,) -> List[dict]:try:- entries = run_async(service.fs.ls(uri, ctx=ctx, simple=False)) or []+ entries = run_async(service.fs.ls(uri, ctx=ctx, simple=False)).entriesexcept Exception:return []_INTERNAL_SUFFIXES = (".overview.md", ".abstract.md")diff --git a/tests/integration/test_encryption_integration.py b/tests/integration/test_encryption_integration.pyindex 3b0ce7f07..adcfceba6 100644--- a/tests/integration/test_encryption_integration.py+++ b/tests/integration/test_encryption_integration.py@@ -134,7 +134,7 @@ class TestEncryptionDisabled:reason="Normal operation test",build_index=False,)- entries = await service.fs.ls(result["root_uri"], ctx=request_context)+ entries = (await service.fs.ls(result["root_uri"], ctx=request_context)).entriescontents = [await service.fs.read(data["uri"], ctx=request_context)for data in entriesdiff --git a/tests/integration/test_volcengine_kms_encryption_integration.py b/tests/integration/test_volcengine_kms_encryption_integration.pyindex 83c822863..c4d93590e 100644--- a/tests/integration/test_volcengine_kms_encryption_integration.py+++ b/tests/integration/test_volcengine_kms_encryption_integration.py@@ -253,7 +253,7 @@ class TestVolcengineKMSEncryptionDisabled:reason="Normal operation test",wait=True,)- entries = await service.fs.tree(result["root_uri"], ctx=request_context)+ entries = (await service.fs.tree(result["root_uri"], ctx=request_context)).entriescontents = [await service.fs.read(data["uri"], ctx=request_context)for data in entriesdiff --git a/tests/server/test_content_write_service.py b/tests/server/test_content_write_service.pyindex 3cbf6dd57..da44b0ddc 100644--- a/tests/server/test_content_write_service.py+++ b/tests/server/test_content_write_service.py@@ -188,7 +188,7 @@ async def test_shared_resource_creation_inherits_acl_and_preserves_plain_append(queue_status = await service.resources.wait_processed()assert queue_status["Embedding"]["error_count"] == 0import_root = imported["root_uri"]- children = await service.fs.ls(import_root, ctx=writer, simple=True)+ children = (await service.fs.ls(import_root, ctx=writer, simple=True)).entriesfor target in [import_root, *children]:acl = await service.fs.get_acl(target, ctx=admin)assert acl["direct_entries"] == []@@ -207,7 +207,7 @@ async def test_shared_resource_creation_inherits_acl_and_preserves_plain_append(assert removed_acl["acl_mode"] == "inherit"assert removed_acl["direct_entries"] == []assert removed_acl["effective_entries"] == inherited_entries- assert await service.fs.ls(import_root, ctx=reader, simple=True) == children+ assert (await service.fs.ls(import_root, ctx=reader, simple=True)).entries == childrenawait service.fs.write(uri, content="line2\n", ctx=writer, mode="append", wait=True)assert (await service.fs.get_acl(uri, ctx=admin))["direct_entries"] == []@@ -268,7 +268,9 @@ async def test_shared_resource_creation_inherits_acl_and_preserves_plain_append(assert (await service.fs.get_acl(explicit_import, ctx=admin))["direct_entries"] == inherited_entries- imported_children = await service.fs.ls(explicit_import, ctx=admin, simple=True)+ imported_children = (+ await service.fs.ls(explicit_import, ctx=admin, simple=True)+ ).entriesfor child in imported_children:report = await service.fs.get_acl(child, ctx=admin)assert report["direct_entries"] == []diff --git a/tests/server/test_filesystem_router.py b/tests/server/test_filesystem_router.pyindex 3f85bdc95..7facdc96e 100644--- a/tests/server/test_filesystem_router.py+++ b/tests/server/test_filesystem_router.py@@ -12,6 +12,7 @@ from fastapi import FastAPIfrom openviking.server.auth import get_request_contextfrom openviking.server.identity import RequestContext, Rolefrom openviking.server.routers import filesystem+from openviking.service.fs_service import ListingPagefrom openviking_cli.exceptions import InvalidURIErrorfrom openviking_cli.session.user_id import UserIdentifier@@ -368,6 +369,7 @@ async def test_ls_user_container_lists_only_caller_space(app, client, service):assert response.status_code == 200, response.textnames = {entry["name"] for entry in response.json()["result"]}assert names == {"alice"}+ assert response.json()["has_more"] is False@pytest.mark.asyncio@@ -376,11 +378,11 @@ async def test_ls_and_tree_forward_pagination_to_filesystem_service(monkeypatch)async def fake_ls(uri, **kwargs):seen["ls"].update(uri=uri, **kwargs)- return []+ return ListingPage(entries=[{"name": "a.md"}], has_more=True)async def fake_tree(uri, **kwargs):seen["tree"].update(uri=uri, **kwargs)- return []+ return ListingPage(entries=[{"name": "b.md"}], has_more=False)monkeypatch.setattr(filesystem,@@ -388,14 +390,14 @@ async def test_ls_and_tree_forward_pagination_to_filesystem_service(monkeypatch)lambda: SimpleNamespace(fs=SimpleNamespace(ls=fake_ls, tree=fake_tree)),)- await filesystem.ls(+ ls_response = 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(+ tree_response = await filesystem.tree(uri="viking://resources",offset=3,limit=5,@@ -407,3 +409,7 @@ async def test_ls_and_tree_forward_pagination_to_filesystem_service(monkeypatch)assert seen["ls"]["node_limit"] == 9assert seen["tree"]["offset"] == 3assert seen["tree"]["node_limit"] == 5+ assert ls_response.result == [{"name": "a.md"}]+ assert ls_response.has_more is True+ assert tree_response.result == [{"name": "b.md"}]+ assert tree_response.has_more is Falsediff --git a/tests/server/test_mcp_endpoint.py b/tests/server/test_mcp_endpoint.pyindex 6ceec7df3..3c810aa52 100644--- a/tests/server/test_mcp_endpoint.py+++ b/tests/server/test_mcp_endpoint.py@@ -44,6 +44,7 @@ from openviking.server.mcp_endpoint import (write,)from openviking.server.mcp_endpoint import ls as list_tool+from openviking.service.fs_service import ListingPagefrom openviking_cli.exceptions import (AlreadyExistsError,FailedPreconditionError,@@ -1270,6 +1271,15 @@ async def test_list_empty_dir(service):assert isinstance(result, str)+async def test_list_reports_more_entries(service):+ await write(uri="viking://resources/test_list_limit/f1.md", content="1\n")+ await write(uri="viking://resources/test_list_limit/f2.md", content="2\n")++ result = await list_tool("viking://resources/test_list_limit", limit=1)++ assert "(more entries available;" in result++# ---------------------------------------------------------------------------# store tool# ---------------------------------------------------------------------------@@ -2368,19 +2378,30 @@ async def test_tree_node_limit_adds_truncation_note(service):assert "(truncated at node_limit=1" in result+async def test_tree_exact_node_limit_does_not_add_truncation_note(service):+ await write(uri="viking://resources/test_tree_exact_limit/f1.md", content="1\n")++ result = await tree(uri="viking://resources/test_tree_exact_limit", node_limit=1)++ assert "(truncated at node_limit=1" not in result++async def test_tree_include_abstract_renders_directory_abstracts(service, monkeypatch):captured = {}async def fake_tree(uri, **kwargs):captured.update(kwargs)- return [- {- "rel_path": "pr-review",- "isDir": True,- "abstract": "name: pr-review\ndescription: Review a PR diff",- },- {"rel_path": "pr-review/SKILL.md", "isDir": False, "size": 42, "abstract": ""},- ]+ return ListingPage(+ entries=[+ {+ "rel_path": "pr-review",+ "isDir": True,+ "abstract": "name: pr-review\ndescription: Review a PR diff",+ },+ {"rel_path": "pr-review/SKILL.md", "isDir": False, "size": 42, "abstract": ""},+ ],+ has_more=False,+ )monkeypatch.setattr(service.fs, "tree", fake_tree)@@ -2394,26 +2415,29 @@ async def test_tree_include_abstract_renders_directory_abstracts(service, monkeyasync def test_tree_include_abstract_skips_not_ready_placeholders(service, monkeypatch):async def fake_tree(uri, **kwargs):- return [- {- "rel_path": "pdf",- "uri": "viking://user/test_user/skills/pdf",- "isDir": True,- "abstract": "name: pdf\ndescription: Fill PDF forms",- },- {- "rel_path": "pdf/scripts",- "uri": "viking://user/test_user/skills/pdf/scripts",- "isDir": True,- "abstract": "# viking://user/test_user/skills/pdf/scripts [Directory abstract is not ready]",- },- {- "rel_path": "pdf/references",- "uri": "viking://user/test_user/skills/pdf/references",- "isDir": True,- "abstract": "[.abstract.md is not ready]",- },- ]+ return ListingPage(+ entries=[+ {+ "rel_path": "pdf",+ "uri": "viking://user/test_user/skills/pdf",+ "isDir": True,+ "abstract": "name: pdf\ndescription: Fill PDF forms",+ },+ {+ "rel_path": "pdf/scripts",+ "uri": "viking://user/test_user/skills/pdf/scripts",+ "isDir": True,+ "abstract": "# viking://user/test_user/skills/pdf/scripts [Directory abstract is not ready]",+ },+ {+ "rel_path": "pdf/references",+ "uri": "viking://user/test_user/skills/pdf/references",+ "isDir": True,+ "abstract": "[.abstract.md is not ready]",+ },+ ],+ has_more=False,+ )monkeypatch.setattr(service.fs, "tree", fake_tree)diff --git a/tests/service/test_fs_service.py b/tests/service/test_fs_service.pyindex 83739a82a..2f3e77a7c 100644--- a/tests/service/test_fs_service.py+++ b/tests/service/test_fs_service.py@@ -11,7 +11,7 @@ import pytestfrom openviking.pyagfs.exceptions import AGFSAlreadyExistsErrorfrom openviking.server.identity import RequestContext, Role-from openviking.service.fs_service import FSService+from openviking.service.fs_service import FSService, ListingPagefrom openviking.storage.abstract_overview import body_for_previewfrom openviking.storage.errors import LockAcquisitionErrorfrom openviking_cli.exceptions import InvalidArgumentError@@ -496,8 +496,47 @@ async def test_ls_and_tree_skip_tag_projection_without_tags_or_include_tags(requservice = FSService(viking_fs=viking_fs, vikingdb=FakeVikingDB())- assert await service.ls("viking://resources", ctx=request_context) == entries- assert await service.tree("viking://resources", ctx=request_context) == entries+ assert await service.ls("viking://resources", ctx=request_context) == ListingPage(+ entries=entries, has_more=False+ )+ assert await service.tree("viking://resources", ctx=request_context) == ListingPage(+ entries=entries, has_more=False+ )++[email protected]("method_name", ["ls", "tree"])+ ("entry_count", "expected_has_more"),+ [(1, False), (2, False), (3, True)],+)+async def test_ls_and_tree_detect_more_entries_with_n_plus_one(+ request_context, method_name, entry_count, expected_has_more+):+ entries = [+ {"uri": f"viking://resources/{index}.md", "isDir": False} for index in range(entry_count)+ ]++ async def fetch(*_args, offset=0, node_limit=None, **_kwargs):+ return entries[offset:] if node_limit is None else entries[offset : offset + node_limit]++ viking_fs = SimpleNamespace(+ ls=AsyncMock(side_effect=fetch),+ tree=AsyncMock(side_effect=fetch),+ )+ service = FSService(viking_fs=viking_fs)++ page = await getattr(service, method_name)(+ "viking://resources",+ ctx=request_context,+ offset=0,+ node_limit=2,+ )++ assert page.entries == entries[:2]+ assert page.has_more is expected_has_more+ fetch_mock = getattr(viking_fs, method_name)+ assert fetch_mock.await_args.kwargs["node_limit"] == 3@pytest.mark.asyncio@@ -657,6 +696,7 @@ async def test_ls_applies_offset_and_node_limit_after_tag_filtering(request_cont] + [{"uri": "viking://resources/b.md", "isDir": False},{"uri": "viking://resources/c.md", "isDir": False},+ {"uri": "viking://resources/d.md", "isDir": False},]async def fake_ls(*_args, offset=0, node_limit=None, **_kwargs):@@ -681,6 +721,11 @@ async def test_ls_applies_offset_and_node_limit_after_tag_filtering(request_cont"level": 2,"search_tags": ["team=search", "env=prod"],},+ {+ "uri": "viking://resources/d.md",+ "level": 2,+ "search_tags": ["team=search", "env=prod"],+ },]service = FSService(viking_fs=viking_fs, vikingdb=FakeVikingDB())@@ -693,7 +738,7 @@ async def test_ls_applies_offset_and_node_limit_after_tag_filtering(request_contoutput="agent",)- assert result == finalized+ assert result == ListingPage(entries=finalized, has_more=True)assert viking_fs.ls.await_count == 2assert viking_fs.ls.await_args_list[0].kwargs["output"] == "original"assert viking_fs.ls.await_args_list[0].kwargs["node_limit"] == 256@@ -737,11 +782,13 @@ async def test_ls_tag_filter_keeps_zero_node_limit_unbounded_for_entry_and_simplnode_limit=0,)- assert [entry["uri"] for entry in entry_result] == [+ assert [entry["uri"] for entry in entry_result.entries] == ["viking://resources/a.md","viking://resources/b.md",]- assert simple_result == ["viking://resources/a.md", "viking://resources/b.md"]+ assert simple_result == ListingPage(+ entries=["viking://resources/a.md", "viking://resources/b.md"], has_more=False+ )@pytest.mark.asyncio@@ -768,9 +815,16 @@ async def test_tree_projects_directory_tags_from_abstract_and_overview_records(rtags=["team=search", "env=prod"],)- assert result == [- {"uri": "viking://resources/docs", "isDir": True, "tags": ["team=search", "env=prod"]}- ]+ assert result == ListingPage(+ entries=[+ {+ "uri": "viking://resources/docs",+ "isDir": True,+ "tags": ["team=search", "env=prod"],+ }+ ],+ has_more=False,+ )assert viking_fs.tree.await_args.kwargs["node_limit"] == 1000@@ -793,10 +847,11 @@ async def test_tree_tag_filter_keeps_zero_node_limit_unbounded(request_context):"viking://resources", ctx=request_context, tags=["env=prod"], node_limit=0)- assert [entry["uri"] for entry in result] == [+ assert [entry["uri"] for entry in result.entries] == ["viking://resources/a.md","viking://resources/b.md",]+ assert result.has_more is Falseassert viking_fs.tree.await_args.kwargs["node_limit"] is None