Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

feat(fs): 为 ls 和 tree 增加分页状态 (#5330)

hezhang-12166c601a9d4135
diff --git a/crates/ov_cli/src/base_client.rs b/crates/ov_cli/src/base_client.rs
index 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.rs
index 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.rs
index 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.rs
index 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.md
index 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.md
index 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,tags
CLI 会按所选列请求 `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,tags
openviking 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.py
index 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_by
options["sort_order"] = sort_order
- entries = await service.fs.ls(resolved_uri, **options)
+ page = await service.fs.ls(resolved_uri, **options)
+ entries = page.entries
if 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_limit
try:
- 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.py
index 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 mapping
ERROR_CODE_TO_HTTP_STATUS = {
"OK": 200,
diff --git a/openviking/server/routers/filesystem.py b/openviking/server/routers/filesystem.py
index 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_context
from openviking.server.dependencies import get_service
from openviking.server.error_mapping import map_exception
from openviking.server.identity import RequestContext
-from openviking.server.models import Response
+from openviking.server.models import ListingResponse, Response
from openviking.server.routers.content import SetTagsRequest
from openviking.server.routers.content import set_tags as content_set_tags
from openviking.storage.acl import AclSpec
@@ -95,7 +95,7 @@ async def ls(
# Resolve path variables
uri = 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 e
raise
- 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 variables
uri = 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 e
raise
- 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.py
index 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.entries
except 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.entries
for entry in children:
if not isinstance(entry, dict):
continue
diff --git a/openviking/server/routers/webdav.py b/openviking/server/routers/webdav.py
index 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.py
index 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 asyncio
from collections.abc import Coroutine
+from dataclasses import dataclass
from typing import TYPE_CHECKING, Any, Awaitable, Callable, Dict, List, Literal, Optional
from openviking.core.context import ContextLevel
@@ -62,6 +63,12 @@ from openviking_cli.utils.config import get_openviking_config
logger = 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 + 1
source_offset = 0
remaining_offset = offset
result: 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 = 0
if len(entries) < batch_size:
break
source_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
@staticmethod
def _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.py
index 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)).entries
except Exception:
return []
_INTERNAL_SUFFIXES = (".overview.md", ".abstract.md")
diff --git a/tests/integration/test_encryption_integration.py b/tests/integration/test_encryption_integration.py
index 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)).entries
contents = [
await service.fs.read(data["uri"], ctx=request_context)
for data in entries
diff --git a/tests/integration/test_volcengine_kms_encryption_integration.py b/tests/integration/test_volcengine_kms_encryption_integration.py
index 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)).entries
contents = [
await service.fs.read(data["uri"], ctx=request_context)
for data in entries
diff --git a/tests/server/test_content_write_service.py b/tests/server/test_content_write_service.py
index 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"] == 0
import_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)).entries
for 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 == children
await 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)
+ ).entries
for 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.py
index 3f85bdc95..7facdc96e 100644
--- a/tests/server/test_filesystem_router.py
+++ b/tests/server/test_filesystem_router.py
@@ -12,6 +12,7 @@ from fastapi import FastAPI
from openviking.server.auth import get_request_context
from openviking.server.identity import RequestContext, Role
from openviking.server.routers import filesystem
+from openviking.service.fs_service import ListingPage
from openviking_cli.exceptions import InvalidURIError
from 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.text
names = {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"] == 9
assert seen["tree"]["offset"] == 3
assert 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 False
diff --git a/tests/server/test_mcp_endpoint.py b/tests/server/test_mcp_endpoint.py
index 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 ListingPage
from 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, monkey
async 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.py
index 83739a82a..2f3e77a7c 100644
--- a/tests/service/test_fs_service.py
+++ b/tests/service/test_fs_service.py
@@ -11,7 +11,7 @@ import pytest
from openviking.pyagfs.exceptions import AGFSAlreadyExistsError
from openviking.server.identity import RequestContext, Role
-from openviking.service.fs_service import FSService
+from openviking.service.fs_service import FSService, ListingPage
from openviking.storage.abstract_overview import body_for_preview
from openviking.storage.errors import LockAcquisitionError
from openviking_cli.exceptions import InvalidArgumentError
@@ -496,8 +496,47 @@ async def test_ls_and_tree_skip_tag_projection_without_tags_or_include_tags(requ
service = 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_cont
output="agent",
)
- assert result == finalized
+ assert result == ListingPage(entries=finalized, has_more=True)
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
@@ -737,11 +782,13 @@ async def test_ls_tag_filter_keeps_zero_node_limit_unbounded_for_entry_and_simpl
node_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(r
tags=["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 False
assert viking_fs.tree.await_args.kwargs["node_limit"] is None