Skip to content

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

feat(ls): 支持返回目录摘要与概览 (#5434)

hezhang-1216acfeb99b4813
diff --git a/crates/ov_cli/src/client.rs b/crates/ov_cli/src/client.rs
index 23f942a2b..177880d6e 100644
--- a/crates/ov_cli/src/client.rs
+++ b/crates/ov_cli/src/client.rs
@@ -560,6 +560,9 @@ impl HttpClient {
recursive: bool,
output: &str,
abs_limit: i32,
+ include_abstract: Option<bool>,
+ include_overview: Option<bool>,
+ overview_limit: i32,
show_all_hidden: bool,
node_limit: i32,
offset: i32,
@@ -576,9 +579,16 @@ impl HttpClient {
("recursive".to_string(), recursive.to_string()),
("output".to_string(), output.to_string()),
("abs_limit".to_string(), abs_limit.to_string()),
+ ("overview_limit".to_string(), overview_limit.to_string()),
("show_all_hidden".to_string(), show_all_hidden.to_string()),
("node_limit".to_string(), node_limit.to_string()),
];
+ if let Some(value) = include_abstract {
+ params.push(("include_abstract".to_string(), value.to_string()));
+ }
+ if let Some(value) = include_overview {
+ params.push(("include_overview".to_string(), value.to_string()));
+ }
if offset != 0 {
params.push(("offset".to_string(), offset.to_string()));
}
@@ -2299,6 +2309,9 @@ mod tests {
false,
"agent",
256,
+ Some(false),
+ Some(true),
+ 512,
false,
20,
4,
@@ -2319,6 +2332,9 @@ mod tests {
assert!(request.contains("limit=5"));
assert!(request.contains("sort_by=mtime"));
assert!(request.contains("sort_order=desc"));
+ assert!(request.contains("include_abstract=false"));
+ assert!(request.contains("include_overview=true"));
+ assert!(request.contains("overview_limit=512"));
assert!(!request.contains("tz="));
assert!(!request.contains("include_mod_time_iso="));
@@ -2331,6 +2347,9 @@ mod tests {
false,
"agent",
256,
+ None,
+ None,
+ 4000,
false,
20,
0,
@@ -2347,6 +2366,9 @@ mod tests {
.await
.expect("default request should be captured");
assert!(!default_request.contains("offset="));
+ assert!(!default_request.contains("include_abstract="));
+ assert!(!default_request.contains("include_overview="));
+ assert!(default_request.contains("overview_limit=4000"));
assert!(!default_request.contains("&limit="));
assert!(!default_request.contains("sort_by="));
assert!(!default_request.contains("sort_order="));
diff --git a/crates/ov_cli/src/commands/filesystem.rs b/crates/ov_cli/src/commands/filesystem.rs
index 8beff0e5e..fb6cad29d 100644
--- a/crates/ov_cli/src/commands/filesystem.rs
+++ b/crates/ov_cli/src/commands/filesystem.rs
@@ -65,7 +65,7 @@ fn resolve_fields(fields: &[String], is_tree: bool) -> Vec<&'static FieldDef> {
}
for name in fields {
let trimmed = name.trim();
- if trimmed.is_empty() || (trimmed == "overview" && !is_tree) {
+ if trimmed.is_empty() {
continue;
}
if let Some(def) = ALL_FIELDS.iter().find(|f| f.name == trimmed) {
@@ -180,6 +180,9 @@ pub async fn ls(
recursive: bool,
output: &str,
abs_limit: i32,
+ include_abstract: Option<bool>,
+ include_overview: Option<bool>,
+ overview_limit: i32,
show_all_hidden: bool,
node_limit: i32,
offset: i32,
@@ -201,6 +204,9 @@ pub async fn ls(
recursive,
output,
abs_limit,
+ include_abstract,
+ include_overview,
+ overview_limit,
show_all_hidden,
node_limit,
offset,
@@ -1323,10 +1329,14 @@ mod tests {
#[test]
fn resolve_fields_prepends_name_when_no_identifier_given_ls() {
- let fields = vec!["size".to_string(), "mtime".to_string()];
+ let fields = vec![
+ "size".to_string(),
+ "mtime".to_string(),
+ "overview".to_string(),
+ ];
let defs = super::resolve_fields(&fields, false);
let names: Vec<&str> = defs.iter().map(|d| d.name).collect();
- assert_eq!(names, vec!["name", "size", "mtime"]);
+ assert_eq!(names, vec!["name", "size", "mtime", "overview"]);
}
#[test]
diff --git a/crates/ov_cli/src/handlers.rs b/crates/ov_cli/src/handlers.rs
index 2fb5e905d..228088959 100644
--- a/crates/ov_cli/src/handlers.rs
+++ b/crates/ov_cli/src/handlers.rs
@@ -1650,6 +1650,9 @@ pub async fn handle_ls(
simple: bool,
recursive: bool,
abs_limit: i32,
+ include_abstract: Option<bool>,
+ include_overview: Option<bool>,
+ overview_limit: i32,
show_all_hidden: bool,
node_limit: i32,
offset: i32,
@@ -1671,6 +1674,15 @@ pub async fn handle_ls(
if recursive {
params.push("-r".to_string());
}
+ if let Some(value) = include_abstract {
+ params.push(format!("--include-abstract={value}"));
+ }
+ if let Some(value) = include_overview {
+ params.push(format!("--include-overview={value}"));
+ }
+ if include_overview == Some(true) {
+ params.push(format!("--overview-limit {overview_limit}"));
+ }
if show_all_hidden {
params.push("-a".to_string());
}
@@ -1700,6 +1712,18 @@ pub async fn handle_ls(
} else {
"agent"
};
+ let include_abstract = include_abstract.or_else(|| {
+ fields
+ .as_ref()
+ .is_some_and(|items| items.iter().any(|item| item == "abstract"))
+ .then_some(true)
+ });
+ let include_overview = include_overview.or_else(|| {
+ fields
+ .as_ref()
+ .is_some_and(|items| items.iter().any(|item| item == "overview"))
+ .then_some(true)
+ });
commands::filesystem::ls(
&client,
&uri,
@@ -1707,6 +1731,9 @@ pub async fn handle_ls(
recursive,
api_output,
abs_limit,
+ include_abstract,
+ include_overview,
+ overview_limit,
show_all_hidden,
node_limit,
offset,
diff --git a/crates/ov_cli/src/main.rs b/crates/ov_cli/src/main.rs
index d925484fa..f1d0a5196 100644
--- a/crates/ov_cli/src/main.rs
+++ b/crates/ov_cli/src/main.rs
@@ -497,6 +497,37 @@ enum Commands {
help_heading = "Advanced options"
)]
abs_limit: i32,
+ /// Include directory L0 abstracts (defaults to the selected output mode)
+ #[arg(
+ long = "include-abstract",
+ default_missing_value = "true",
+ num_args = 0..=1,
+ require_equals = true,
+ action = ArgAction::Set,
+ value_name = "bool",
+ help_heading = "Output options"
+ )]
+ include_abstract: Option<bool>,
+ /// Include directory L1 overviews
+ #[arg(
+ long = "include-overview",
+ default_missing_value = "true",
+ num_args = 0..=1,
+ require_equals = true,
+ action = ArgAction::Set,
+ value_name = "bool",
+ help_heading = "Output options"
+ )]
+ include_overview: Option<bool>,
+ /// Maximum overview content length
+ #[arg(
+ long = "overview-limit",
+ default_value = "4000",
+ value_parser = clap::value_parser!(i32).range(1..),
+ value_name = "n",
+ help_heading = "Advanced options"
+ )]
+ overview_limit: i32,
/// Show all hidden files
#[arg(short, long, help_heading = "Common options")]
all: bool,
@@ -539,8 +570,14 @@ enum Commands {
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")]
+ /// Comma-separated fields to display (name,uri,path,type,size,mode,mtime,locked,id,count,tags,abstract,overview)
+ #[arg(
+ short = 'f',
+ long = "fields",
+ value_delimiter = ',',
+ value_name = "FIELDS",
+ help_heading = "Output options"
+ )]
fields: Option<Vec<String>>,
/// Comma-separated k=v retrieval tags; all tags must match
#[arg(long = "tags", value_delimiter = ',', value_name = "k=v", help_heading = "Common options")]
@@ -3571,6 +3608,9 @@ async fn main() {
simple,
recursive,
abs_limit,
+ include_abstract,
+ include_overview,
+ overview_limit,
all,
node_limit,
offset,
@@ -3585,6 +3625,9 @@ async fn main() {
simple,
recursive,
abs_limit,
+ include_abstract,
+ include_overview,
+ overview_limit,
all,
node_limit,
offset,
@@ -4272,6 +4315,10 @@ mod tests {
"mtime",
"--sort-order",
"desc",
+ "--include-abstract",
+ "--include-overview=false",
+ "--overview-limit",
+ "512",
])
.expect("paged ls should parse");
let paged_tree = Cli::try_parse_from([
@@ -4298,6 +4345,9 @@ mod tests {
sort_by,
sort_order,
node_limit,
+ include_abstract,
+ include_overview,
+ overview_limit,
..
} => {
assert_eq!(offset, 4);
@@ -4305,6 +4355,9 @@ mod tests {
assert_eq!(sort_by.as_deref(), Some("mtime"));
assert_eq!(sort_order.as_deref(), Some("desc"));
assert_eq!(node_limit, 256);
+ assert_eq!(include_abstract, Some(true));
+ assert_eq!(include_overview, Some(false));
+ assert_eq!(overview_limit, 512);
}
_ => panic!("expected ls command"),
}
diff --git a/crates/ov_cli/src/tui/tree.rs b/crates/ov_cli/src/tui/tree.rs
index 2723865d2..cc82076ee 100644
--- a/crates/ov_cli/src/tui/tree.rs
+++ b/crates/ov_cli/src/tui/tree.rs
@@ -150,6 +150,9 @@ impl TreeState {
false,
"original",
256,
+ None,
+ None,
+ 4000,
false,
1000,
0,
diff --git a/docs/en/api/03-filesystem.md b/docs/en/api/03-filesystem.md
index c419ea874..467ebe561 100644
--- a/docs/en/api/03-filesystem.md
+++ b/docs/en/api/03-filesystem.md
@@ -20,7 +20,10 @@ List directory contents.
| simple | bool | No | False | Return only relative paths |
| recursive | bool | No | False | List all subdirectories recursively |
| output | str | No | HTTP: `agent`; SDKs: `original` | Output format: `agent` or `original` |
-| abs_limit | int | No | 256 | Abstract length limit for `agent` output |
+| abs_limit | int | No | 256 | Maximum returned abstract length |
+| include_abstract | bool | No | Unset | Include directory L0 abstracts. When unset, follows the legacy output behavior (`agent`: included; `original`: omitted) |
+| include_overview | bool | No | Unset | Include directory L1 overviews. Unset means omitted |
+| overview_limit | int | No | 4000 | Maximum returned overview length |
| 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 |
@@ -30,7 +33,7 @@ List directory contents.
| 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 `offset` and `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`. L0/L1 content is attached only to the selected page of directory entries and does not consume `node_limit`. An explicit `include_abstract=true|false` overrides the legacy behavior implied by `output`. Tags are included for filtered responses; for an unfiltered response, request `include_tags=true` (CLI: `-f tags`).
**Entry Structure**
@@ -70,37 +73,55 @@ existing hiding rules.
**Python HTTP SDK**
```python
-entries = client.ls(
+page = client.ls_page(
uri="viking://resources/",
offset=100,
limit=100,
sort_by="mtime",
sort_order="desc",
+ include_abstract=True,
+ include_overview=True,
)
-for entry in entries:
+for entry in page["result"]:
type_str = "dir" if entry['isDir'] else "file"
print(f"{entry['name']} - {type_str}")
+print("has more nodes:", page["has_more"])
```
**TypeScript SDK**
```typescript
-const entries = await client.list("viking://resources/docs/", { simple: true });
-console.log(entries);
+const page = await client.listPage("viking://resources/docs/", {
+ includeAbstract: true,
+ includeOverview: true,
+});
+console.log(page.result);
+console.log("has more nodes:", page.hasMore);
```
**Go SDK**
```go
-entries, err := client.List(ctx, "viking://resources/", nil)
+page, err := client.ListPage(ctx, "viking://resources/", &openviking.ListOptions{
+ IncludeAbstract: openviking.Bool(true),
+ AbsLimit: 512,
+ IncludeOverview: openviking.Bool(true),
+ OverviewLimit: 4000,
+})
if err != nil {
return err
}
-for _, entry := range entries {
+for _, entry := range page.Result {
fmt.Println(entry)
}
+fmt.Println("has more nodes:", page.HasMore)
```
+When only the entry array is needed, use the compatibility methods `ls` in
+Python, `list` in TypeScript, and `List` in Go. To detect whether `limit` or
+`node_limit` truncated the result, use `ls_page`, `listPage`, and `ListPage`,
+respectively.
+
**HTTP API**
```
@@ -124,12 +145,12 @@ curl -X GET "http://localhost:1933/api/v1/fs/ls?uri=viking://resources/&recursiv
**CLI**
```bash
-openviking ls viking://resources/ [--simple] [--recursive] [--tags team=search,env=prod] [-f FIELDS]
+openviking ls viking://resources/ [--simple] [--recursive] [--include-abstract[=true|false]] [--include-overview[=true|false]] [--tags team=search,env=prod] [-f FIELDS]
openviking tree viking://resources/my-project/ [--simple] [--tags team=search,env=prod] [-f FIELDS]
openviking glob "**/*.md" [--uri viking://resources/] [--simple] [--tags team=search,env=prod] [-f FIELDS]
```
-`-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.
+`-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`, `overview`, `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.
@@ -184,23 +205,36 @@ Directory filtering and `tags` are applied before `offset` and `limit`. Abstract
**Python HTTP SDK**
```python
-entries = client.tree(uri="viking://resources/", offset=100, limit=100)
-for entry in entries:
+page = client.tree_page(
+ uri="viking://resources/",
+ offset=100,
+ limit=100,
+ include_abstract=True,
+ include_overview=True,
+ directories_only=True,
+)
+for entry in page["result"]:
type_str = "dir" if entry['isDir'] else "file"
print(f"{entry['rel_path']} - {type_str}")
+print("has more nodes:", page["has_more"])
```
**TypeScript SDK**
```typescript
-const tree = await client.tree("viking://resources/docs/", { nodeLimit: 100 });
-console.log(tree);
+const page = await client.treePage("viking://resources/docs/", {
+ nodeLimit: 100,
+ includeAbstract: true,
+ includeOverview: true,
+});
+console.log(page.result);
+console.log("has more nodes:", page.hasMore);
```
**Go SDK**
```go
-entries, err := client.Tree(ctx, "viking://resources/", &openviking.TreeOptions{
+page, err := client.TreePage(ctx, "viking://resources/", &openviking.TreeOptions{
DirectoriesOnly: true,
IncludeAbstract: openviking.Bool(true),
IncludeOverview: openviking.Bool(true),
@@ -208,11 +242,17 @@ entries, err := client.Tree(ctx, "viking://resources/", &openviking.TreeOptions{
if err != nil {
return err
}
-for _, entry := range entries {
+for _, entry := range page.Result {
fmt.Println(entry["rel_path"], entry["isDir"])
}
+fmt.Println("has more nodes:", page.HasMore)
```
+When only the node array is needed, use the compatibility method `tree` in
+Python and TypeScript or `Tree` in Go. To detect whether `limit` or
+`node_limit` truncated the result, use `tree_page`, `treePage`, and `TreePage`,
+respectively.
+
**HTTP API**
```
diff --git a/docs/zh/api/03-filesystem.md b/docs/zh/api/03-filesystem.md
index dfd7100ec..d2e13f806 100644
--- a/docs/zh/api/03-filesystem.md
+++ b/docs/zh/api/03-filesystem.md
@@ -20,7 +20,10 @@ OpenViking 提供类 Unix 的文件系统操作来管理上下文。
| simple | bool | 否 | False | 仅返回相对路径 |
| recursive | bool | 否 | False | 递归列出所有子目录 |
| output | str | 否 | HTTP:`agent`;SDK:`original` | 输出格式:`agent` 或 `original` |
-| abs_limit | int | 否 | 256 | `agent` 输出中的摘要长度限制 |
+| abs_limit | int | 否 | 256 | 返回的摘要最大长度 |
+| include_abstract | bool | 否 | 未设置 | 是否返回目录 L0 摘要。未设置时沿用旧 `output` 语义(`agent` 返回,`original` 不返回) |
+| include_overview | bool | 否 | 未设置 | 是否返回目录 L1 概览。未设置时不返回 |
+| overview_limit | int | 否 | 4000 | 返回的概览最大长度 |
| show_all_hidden | bool | 否 | False | 像 `-a` 一样包含隐藏文件 |
| node_limit | int | 否 | 1000 | 最大返回节点数 |
| offset | int | 否 | 0 | 跳过的可见节点数 |
@@ -30,7 +33,7 @@ OpenViking 提供类 Unix 的文件系统操作来管理上下文。
| extra_fields | list[str] | 否 | None | 额外返回的字段:`locked`、`id`、`count` |
| tags | string[] | 否 | 未设置 | 仅返回同时匹配全部 `k=v` 检索标签的条目 |
-`tags` 使用 AND 语义,并在 `offset` 和 `limit` 前应用。带 tags 过滤的响应会返回 `tags`;未过滤时需传 `include_tags=true`(CLI:`-f tags`)才返回它们。HTTP 的 `simple=true` 保持仅返回路径;CLI 同时指定 `--simple` 和 `--fields` 时会获取条目对象,再按指定列输出。
+`tags` 使用 AND 语义,并在 `offset` 和 `limit` 前应用。L0/L1 内容只附加到分页选中的目录节点,不占用 `node_limit`。显式传入 `include_abstract=true|false` 会覆盖 `output` 隐含的旧行为。带 tags 过滤的响应会返回 `tags`;未过滤时需传 `include_tags=true`(CLI:`-f tags`)才返回它们。HTTP 的 `simple=true` 保持仅返回路径;CLI 同时指定 `--simple` 和 `--fields` 时会获取条目对象,再按指定列输出。
**条目结构**
@@ -68,42 +71,55 @@ OpenViking 提供类 Unix 的文件系统操作来管理上下文。
**Python HTTP SDK**
```python
-entries = client.ls(
+page = client.ls_page(
uri="viking://resources/",
offset=100,
limit=100,
sort_by="mtime",
sort_order="desc",
tags=["team=search", "env=prod"],
+ include_abstract=True,
+ include_overview=True,
)
-for entry in entries:
+for entry in page["result"]:
type_str = "dir" if entry['isDir'] else "file"
print(f"{entry['name']} - {type_str}")
+print("是否还有更多节点:", page["has_more"])
```
**TypeScript SDK**
```typescript
-const entries = await client.list("viking://resources/docs/", {
+const page = await client.listPage("viking://resources/docs/", {
tags: ["team=search", "env=prod"],
+ includeAbstract: true,
+ includeOverview: true,
});
-console.log(entries);
+console.log(page.result);
+console.log("是否还有更多节点:", page.hasMore);
```
**Go SDK**
```go
-entries, err := client.List(ctx, "viking://resources/", &openviking.ListOptions{
- Tags: []string{"team=search", "env=prod"},
+page, err := client.ListPage(ctx, "viking://resources/", &openviking.ListOptions{
+ Tags: []string{"team=search", "env=prod"},
+ IncludeAbstract: openviking.Bool(true),
+ AbsLimit: 512,
+ IncludeOverview: openviking.Bool(true),
+ OverviewLimit: 4000,
})
if err != nil {
return err
}
-for _, entry := range entries {
+for _, entry := range page.Result {
fmt.Println(entry)
}
+fmt.Println("是否还有更多节点:", page.HasMore)
```
+仅需要节点数组时可继续使用兼容接口:Python 使用 `ls`、TypeScript 使用 `list`、Go 使用 `List`。需要判断结果是否因 `limit` 或 `node_limit` 被截断时,分别使用 `ls_page`、`listPage`、`ListPage`。
+
**HTTP API**
```
@@ -140,7 +156,7 @@ curl -G "http://localhost:1933/api/v1/fs/ls" \
**CLI**
```bash
-openviking ls viking://resources/ [--simple] [--recursive] [--tags team=search,env=prod] [-f FIELDS]
+openviking ls viking://resources/ [--simple] [--recursive] [--include-abstract[=true|false]] [--include-overview[=true|false]] [--tags team=search,env=prod] [-f FIELDS]
openviking tree viking://resources/my-project/ [--simple] [--tags team=search,env=prod] [-f FIELDS]
openviking glob "**/*.md" [--uri viking://resources/] [--simple] [--tags team=search,env=prod] [-f FIELDS]
@@ -151,7 +167,7 @@ openviking ls viking://resources/ --fields name,tags
openviking ls viking://resources/ --simple --fields uri,tags
```
-`-f` / `--fields` 接受逗号分隔的列名。在默认的 table 输出模式下,结果为带表头、按列对齐的表格。支持的字段为 `name`、`uri`、`path`、`type`、`size`、`mode`、`mtime`、`locked`、`id`、`count`、`abstract`、`tags`。同时指定 `--simple` 和 `-f` 时,每行输出逗号分隔的字段值,不带表头或树缩进;仅使用 `--simple` 时仍每行输出一个 URI。若未选择 `name`、`uri` 或 `path`,列表会自动补充 `name` 列,树会补充 `path` 列。
+`-f` / `--fields` 接受逗号分隔的列名。在默认的 table 输出模式下,结果为带表头、按列对齐的表格。支持的字段为 `name`、`uri`、`path`、`type`、`size`、`mode`、`mtime`、`locked`、`id`、`count`、`abstract`、`overview`、`tags`。同时指定 `--simple` 和 `-f` 时,每行输出逗号分隔的字段值,不带表头或树缩进;仅使用 `--simple` 时仍每行输出一个 URI。若未选择 `name`、`uri` 或 `path`,列表会自动补充 `name` 列,树会补充 `path` 列。
CLI 会按所选列请求 `extra_fields`(`locked`、`id`、`count`);选择 `tags` 列时会请求 `include_tags=true`。这些列选择不改变 `tags` 的 AND 过滤语义。
@@ -209,31 +225,38 @@ HTTP 响应中的 `result` 保持为条目数组。`has_more=true` 表示在应
**Python HTTP SDK**
```python
-entries = client.tree(
+page = client.tree_page(
uri="viking://resources/",
offset=100,
limit=100,
tags=["team=search", "env=prod"],
+ include_abstract=True,
+ include_overview=True,
+ directories_only=True,
)
-for entry in entries:
+for entry in page["result"]:
type_str = "dir" if entry['isDir'] else "file"
print(f"{entry['rel_path']} - {type_str}")
+print("是否还有更多节点:", page["has_more"])
```
**TypeScript SDK**
```typescript
-const tree = await client.tree("viking://resources/docs/", {
+const page = await client.treePage("viking://resources/docs/", {
nodeLimit: 100,
tags: ["team=search", "env=prod"],
+ includeAbstract: true,
+ includeOverview: true,
});
-console.log(tree);
+console.log(page.result);
+console.log("是否还有更多节点:", page.hasMore);
```
**Go SDK**
```go
-entries, err := client.Tree(ctx, "viking://resources/", &openviking.TreeOptions{
+page, err := client.TreePage(ctx, "viking://resources/", &openviking.TreeOptions{
Tags: []string{"team=search", "env=prod"},
DirectoriesOnly: true,
IncludeAbstract: openviking.Bool(true),
@@ -242,11 +265,14 @@ entries, err := client.Tree(ctx, "viking://resources/", &openviking.TreeOptions{
if err != nil {
return err
}
-for _, entry := range entries {
+for _, entry := range page.Result {
fmt.Println(entry["rel_path"], entry["isDir"])
}
+fmt.Println("是否还有更多节点:", page.HasMore)
```
+仅需要节点数组时可继续使用兼容接口:Python/TypeScript 使用 `tree`、Go 使用 `Tree`。需要判断结果是否因 `limit` 或 `node_limit` 被截断时,分别使用 `tree_page`、`treePage`、`TreePage`。
+
**HTTP API**
```
diff --git a/openviking/server/routers/filesystem.py b/openviking/server/routers/filesystem.py
index d469f7150..720d0cbfa 100644
--- a/openviking/server/routers/filesystem.py
+++ b/openviking/server/routers/filesystem.py
@@ -73,6 +73,11 @@ async def ls(
recursive: bool = Query(False, description="List all subdirectories recursively"),
output: str = Query("agent", description="Output format: original or agent"),
abs_limit: int = Query(256, description="Abstract limit (only for agent output)"),
+ include_abstract: Optional[bool] = Query(
+ None, description="Include directory L0 abstracts; defaults to the output format"
+ ),
+ include_overview: Optional[bool] = Query(None, description="Include directory L1 overviews"),
+ overview_limit: int = Query(4000, ge=1, description="Maximum overview length"),
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"),
offset: int = Query(0, ge=0, description="Number of visible nodes to skip"),
@@ -102,6 +107,9 @@ async def ls(
simple=simple,
output=output,
abs_limit=abs_limit,
+ include_abstract=include_abstract,
+ include_overview=include_overview,
+ overview_limit=overview_limit,
show_all_hidden=show_all_hidden,
node_limit=actual_node_limit,
offset=offset,
diff --git a/openviking/service/fs_service.py b/openviking/service/fs_service.py
index 368332281..07a295c85 100644
--- a/openviking/service/fs_service.py
+++ b/openviking/service/fs_service.py
@@ -256,6 +256,9 @@ class FSService:
simple: bool = False,
output: str = "original",
abs_limit: int = 256,
+ include_abstract: Optional[bool] = None,
+ include_overview: Optional[bool] = None,
+ overview_limit: int = 4000,
show_all_hidden: bool = False,
node_limit: int = 1000,
level_limit: int = 3,
@@ -273,7 +276,10 @@ class FSService:
recursive: List all subdirectories recursively
simple: Return only relative path list
output: str = "original" or "agent"
- abs_limit: int = 256 if output == "agent" else ignore
+ abs_limit: Maximum returned abstract length
+ include_abstract: Include directory L0 abstracts; defaults to the output format
+ include_overview: Include directory L1 overviews
+ overview_limit: Maximum returned overview length
show_all_hidden: bool = False (list all hidden files, like -a)
node_limit: int = 1000 (maximum number of nodes to list)
sort_by: Optional sort field for non-recursive listings
@@ -290,27 +296,33 @@ class FSService:
return await viking_fs.tree(
uri,
ctx=ctx,
- output="original" if tags or use_simple_paths else output,
+ output="original",
abs_limit=abs_limit,
+ include_abstract=None,
+ include_overview=False,
+ overview_limit=overview_limit,
show_all_hidden=show_all_hidden,
node_limit=page_limit,
level_limit=level_limit,
offset=page_offset,
sort_by=sort_by,
sort_order=sort_order,
- extra_fields=None if tags or use_simple_paths else extra_fields,
+ extra_fields=None,
)
return await viking_fs.ls(
uri,
ctx=ctx,
- output="original" if tags or use_simple_paths else output,
+ output="original",
abs_limit=abs_limit,
+ include_abstract=None,
+ include_overview=False,
+ overview_limit=overview_limit,
show_all_hidden=show_all_hidden,
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,
+ extra_fields=None,
)
if tags:
@@ -337,7 +349,12 @@ class FSService:
entries=[entry.get("uri", "") for entry in page.entries],
has_more=page.has_more,
)
- if tags and (output != "original" or extra_fields):
+ if (
+ output != "original"
+ or extra_fields
+ or include_abstract is True
+ or include_overview is True
+ ):
return ListingPage(
entries=await viking_fs._finalize_listing_entries(
page.entries,
@@ -346,6 +363,9 @@ class FSService:
extra_fields,
recursive,
ctx=ctx,
+ include_abstract=include_abstract,
+ include_overview=include_overview is True,
+ overview_limit=overview_limit,
),
has_more=page.has_more,
)
diff --git a/openviking/storage/viking_fs/_ops.py b/openviking/storage/viking_fs/_ops.py
index 7911878fc..2f723c39b 100644
--- a/openviking/storage/viking_fs/_ops.py
+++ b/openviking/storage/viking_fs/_ops.py
@@ -2167,6 +2167,9 @@ class _OpsMixin:
uri: str,
output: str = "original",
abs_limit: int = 256,
+ include_abstract: Optional[bool] = None,
+ include_overview: bool = False,
+ overview_limit: int = 4000,
show_all_hidden: bool = False,
node_limit: int = 1000,
sort_by: Optional[str] = None,
@@ -2181,7 +2184,10 @@ class _OpsMixin:
Args:
uri: Viking URI
output: str = "original"
- abs_limit: int = 256
+ abs_limit: Maximum returned abstract length
+ include_abstract: Include directory L0 abstracts; defaults to the output format
+ include_overview: Include directory L1 overviews
+ overview_limit: Maximum returned overview length
show_all_hidden: bool = False (list all hidden files, like -a)
node_limit: int = 1000 (maximum number of nodes to list)
sort_by: Optional sort field, "name" or "mtime"
@@ -2200,32 +2206,28 @@ class _OpsMixin:
raise ValueError("sort_by must be 'name' or 'mtime'")
if sort_order not in {"asc", "desc"}:
raise ValueError("sort_order must be 'asc' or 'desc'")
- if output == "original":
- entries = await self._ls_original(
- uri,
- show_all_hidden,
- node_limit,
- offset=offset,
- sort_by=sort_by,
- sort_order=sort_order,
- ctx=ctx,
- )
- elif output == "agent":
- entries = await self._ls_agent(
- uri,
- abs_limit,
- show_all_hidden,
- node_limit,
- offset=offset,
- sort_by=sort_by,
- sort_order=sort_order,
- ctx=ctx,
- )
- else:
+ if output not in {"original", "agent"}:
raise ValueError(f"Invalid output format: {output}")
- if extra_fields and output == "original":
- await self._augment_entries_extra_fields(entries, extra_fields, ctx=ctx)
- return entries
+ entries = await self._ls_original(
+ uri,
+ show_all_hidden,
+ node_limit,
+ offset=offset,
+ sort_by=sort_by,
+ sort_order=sort_order,
+ ctx=ctx,
+ )
+ return await self._finalize_listing_entries(
+ entries,
+ output,
+ abs_limit,
+ extra_fields,
+ False,
+ ctx=ctx,
+ include_abstract=include_abstract,
+ include_overview=include_overview,
+ overview_limit=overview_limit,
+ )
@staticmethod
def _ls_entry_mtime(entry: Dict[str, Any]) -> Optional[float]:
@@ -2288,36 +2290,6 @@ class _OpsMixin:
return sort_by_mtime(directories) + sort_by_mtime(files)
- async def _ls_agent(
- self,
- uri: str,
- 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)."""
- 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,
- )
-
async def _ls_original(
self,
uri: str,
diff --git a/sdk/go/README.md b/sdk/go/README.md
index 7d868b60f..1eb0f8dc2 100644
--- a/sdk/go/README.md
+++ b/sdk/go/README.md
@@ -141,6 +141,23 @@ _ = session
_ = commit
```
+## Pagination Metadata
+
+`List` and `Tree` preserve their existing return types for compatibility. Use
+`ListPage` or `TreePage` when the caller needs to know whether the server
+truncated the result because of `limit` or `node_limit`.
+
+```go
+page, err := client.TreePage(ctx, "viking://resources/", &openviking.TreeOptions{
+ NodeLimit: 1000,
+})
+if err != nil {
+ return err
+}
+fmt.Println("nodes:", len(page.Result))
+fmt.Println("has more:", page.HasMore)
+```
+
## API Coverage
The Go SDK v1 intentionally follows the Python HTTP client surface.
@@ -152,7 +169,7 @@ Implemented:
| Resource and skill import | `AddResource`, `AddSkill`, `WaitProcessed` |
| Skill management | `ListSkills`, `FindSkills`, `ValidateSkill`, `GetSkill`, `UpdateSkill`, `DeleteSkill` |
| Watch management | `ListWatches`, `GetWatch`, `UpdateWatch`, `DeleteWatch`, `TriggerWatch` |
-| Filesystem and content | `List`, `Tree`, `Stat`, `Attrs`, `Mkdir`, `Remove`, `Move`, `Read`, `Abstract`, `Overview`, `Write`, `SetTags`, `Reindex` |
+| Filesystem and content | `List`, `ListPage`, `Tree`, `TreePage`, `Stat`, `Attrs`, `Mkdir`, `Remove`, `Move`, `Read`, `Abstract`, `Overview`, `Write`, `SetTags`, `Reindex` |
| Retrieval | `Find`, `Search`, `Grep`, `Glob` |
| Sessions and tasks | `CreateSession`, `ListSessions`, `GetSession`, `UpdateSessionConfig`, `SessionExists`, `GetSessionContext`, `GetSessionArchive`, `DeleteSession`, `AddMessage`, `BatchAddMessages`, `CommitSession`, `GetTask`, `ListTasks` |
| Packs | `ExportOVPack`, `BackupOVPack`, `ImportOVPack`, `RestoreOVPack` |
diff --git a/sdk/go/client_test.go b/sdk/go/client_test.go
index 88ab56b92..e033c2cf1 100644
--- a/sdk/go/client_test.go
+++ b/sdk/go/client_test.go
@@ -232,29 +232,59 @@ func TestFindUsesDefaultLimitAndPreservesEmptyValues(t *testing.T) {
}
}
-func TestListAndTreeSendQueryOptions(t *testing.T) {
+func TestListAndTreePreserveOptionsAndPagination(t *testing.T) {
+ entries := []any{map[string]any{"name": "docs"}}
+ listCalls := 0
treeCalls := 0
client, closeServer := testClient(t, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
switch r.URL.Path {
case "/api/v1/fs/ls":
- 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)
- }
- if got := r.URL.Query().Get("sort_order"); got != "desc" {
- t.Fatalf("sort_order = %q", got)
- }
- if got := r.URL.Query()["tags"]; !reflect.DeepEqual(got, []string{"env=prod", "team=search"}) {
- t.Fatalf("tags = %#v", got)
+ if listCalls == 0 {
+ 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)
+ }
+ if got := r.URL.Query().Get("sort_order"); got != "desc" {
+ t.Fatalf("sort_order = %q", got)
+ }
+ if got := r.URL.Query()["tags"]; !reflect.DeepEqual(got, []string{"env=prod", "team=search"}) {
+ t.Fatalf("tags = %#v", got)
+ }
+ if got := r.URL.Query()["extra_fields"]; !reflect.DeepEqual(got, []string{"locked", "id"}) {
+ t.Fatalf("extra_fields = %#v", got)
+ }
+ if got := r.URL.Query().Get("include_abstract"); got != "false" {
+ t.Fatalf("include_abstract = %q", got)
+ }
+ if got := r.URL.Query().Get("include_overview"); got != "true" {
+ t.Fatalf("include_overview = %q", got)
+ }
+ if got := r.URL.Query().Get("overview_limit"); got != "512" {
+ t.Fatalf("overview_limit = %q", got)
+ }
+ if got := r.URL.Query().Get("abs_limit"); got != "128" {
+ t.Fatalf("abs_limit = %q", got)
+ }
+ } else {
+ if _, ok := r.URL.Query()["include_abstract"]; ok {
+ t.Fatal("default list request should omit include_abstract")
+ }
+ if _, ok := r.URL.Query()["include_overview"]; ok {
+ t.Fatal("default list request should omit include_overview")
+ }
+ if got := r.URL.Query().Get("overview_limit"); got != "4000" {
+ t.Fatalf("overview_limit = %q", got)
+ }
}
+ listCalls++
case "/api/v1/fs/tree":
if treeCalls == 0 {
if got := r.URL.Query().Get("level_limit"); got != "0" {
@@ -269,6 +299,9 @@ func TestListAndTreeSendQueryOptions(t *testing.T) {
if got := r.URL.Query()["tags"]; !reflect.DeepEqual(got, []string{"env=prod"}) {
t.Fatalf("tags = %#v", got)
}
+ if got := r.URL.Query()["extra_fields"]; !reflect.DeepEqual(got, []string{"count"}) {
+ t.Fatalf("extra_fields = %#v", got)
+ }
if got := r.URL.Query().Get("include_abstract"); got != "false" {
t.Fatalf("include_abstract = %q", got)
}
@@ -305,35 +338,59 @@ func TestListAndTreeSendQueryOptions(t *testing.T) {
default:
t.Fatalf("unexpected request %s %s", r.Method, r.URL.Path)
}
- writeOK(t, w, []any{})
+ w.Header().Set("Content-Type", "application/json")
+ if err := json.NewEncoder(w).Encode(map[string]any{
+ "status": "ok", "result": entries, "has_more": r.URL.Path == "/api/v1/fs/ls",
+ }); err != nil {
+ t.Fatal(err)
+ }
}))
defer closeServer()
- 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 {
+ listPage, err := client.ListPage(context.Background(), "viking://session", &ListOptions{
+ NodeLimit: 200,
+ Offset: 4,
+ Limit: 5,
+ SortBy: "mtime",
+ SortOrder: "desc",
+ ExtraFields: []string{"locked", "id"},
+ Tags: []string{"env=prod", "team=search"},
+ AbsLimit: 128,
+ IncludeAbstract: Bool(false),
+ IncludeOverview: Bool(true),
+ OverviewLimit: 512,
+ })
+ if err != nil {
t.Fatal(err)
}
- if _, err := client.Tree(context.Background(), "viking://resources/docs", &TreeOptions{
+ if !listPage.HasMore || !reflect.DeepEqual(listPage.Result, entries) {
+ t.Fatalf("list page = %#v", listPage)
+ }
+ legacyList, err := client.List(context.Background(), "viking://session", nil)
+ if err != nil || !reflect.DeepEqual(legacyList, entries) {
+ t.Fatalf("list = %#v, err = %v", legacyList, err)
+ }
+ treePage, err := client.TreePage(context.Background(), "viking://resources/docs", &TreeOptions{
NodeLimit: 200,
LevelLimit: Int(0),
Offset: 6,
Limit: 7,
+ ExtraFields: []string{"count"},
Tags: []string{"env=prod"},
IncludeAbstract: Bool(false),
IncludeOverview: Bool(true),
OverviewLimit: 512,
DirectoriesOnly: true,
- }); err != nil {
+ })
+ if err != nil {
t.Fatal(err)
}
- if _, err := client.Tree(context.Background(), "viking://resources/docs", nil); err != nil {
- t.Fatal(err)
+ if treePage.HasMore || !reflect.DeepEqual(treePage.Result, []map[string]any{{"name": "docs"}}) {
+ t.Fatalf("tree page = %#v", treePage)
+ }
+ legacyTree, err := client.Tree(context.Background(), "viking://resources/docs", nil)
+ if err != nil || !reflect.DeepEqual(legacyTree, treePage.Result) {
+ t.Fatalf("tree = %#v, err = %v", legacyTree, err)
}
}
diff --git a/sdk/go/filesystem.go b/sdk/go/filesystem.go
index fe256b5fc..7d8e06855 100644
--- a/sdk/go/filesystem.go
+++ b/sdk/go/filesystem.go
@@ -12,6 +12,15 @@ import (
// List lists directory contents.
func (c *Client) List(ctx context.Context, uri string, opts *ListOptions) ([]any, error) {
+ page, err := c.ListPage(ctx, uri, opts)
+ if err != nil {
+ return nil, err
+ }
+ return page.Result, nil
+}
+
+// ListPage lists directory contents with pagination metadata.
+func (c *Client) ListPage(ctx context.Context, uri string, opts *ListOptions) (*ListPage, error) {
if opts == nil {
opts = &ListOptions{Output: "original", AbsLimit: 256, NodeLimit: 1000}
}
@@ -23,6 +32,10 @@ func (c *Client) List(ctx context.Context, uri string, opts *ListOptions) ([]any
if absLimit == 0 {
absLimit = 256
}
+ overviewLimit := opts.OverviewLimit
+ if overviewLimit == 0 {
+ overviewLimit = 4000
+ }
nodeLimit := opts.NodeLimit
if nodeLimit == 0 {
nodeLimit = 1000
@@ -33,6 +46,13 @@ func (c *Client) List(ctx context.Context, uri string, opts *ListOptions) ([]any
queryBool(query, "recursive", opts.Recursive)
query.Set("output", output)
queryInt(query, "abs_limit", absLimit)
+ if opts.IncludeAbstract != nil {
+ queryBool(query, "include_abstract", *opts.IncludeAbstract)
+ }
+ if opts.IncludeOverview != nil {
+ queryBool(query, "include_overview", *opts.IncludeOverview)
+ }
+ queryInt(query, "overview_limit", overviewLimit)
queryBool(query, "show_all_hidden", opts.ShowAllHidden)
queryInt(query, "node_limit", nodeLimit)
if opts.Offset != 0 {
@@ -53,13 +73,28 @@ func (c *Client) List(ctx context.Context, uri string, opts *ListOptions) ([]any
if opts.SortOrder != "" {
query.Set("sort_order", opts.SortOrder)
}
+ if opts.ExtraFields != nil {
+ query["extra_fields"] = opts.ExtraFields
+ }
var result []any
- err := c.doJSON(ctx, http.MethodGet, "/api/v1/fs/ls", query, nil, &result)
- return result, err
+ env, err := c.doJSONEnvelope(ctx, http.MethodGet, "/api/v1/fs/ls", query, nil, &result)
+ if err != nil {
+ return nil, err
+ }
+ return &ListPage{Result: result, HasMore: env.HasMore}, nil
}
// Tree returns a directory tree.
func (c *Client) Tree(ctx context.Context, uri string, opts *TreeOptions) ([]map[string]any, error) {
+ page, err := c.TreePage(ctx, uri, opts)
+ if err != nil {
+ return nil, err
+ }
+ return page.Result, nil
+}
+
+// TreePage returns a directory tree with pagination metadata.
+func (c *Client) TreePage(ctx context.Context, uri string, opts *TreeOptions) (*TreePage, error) {
if opts == nil {
opts = &TreeOptions{Output: "original", AbsLimit: 128, NodeLimit: 1000}
}
@@ -106,6 +141,9 @@ func (c *Client) Tree(ctx context.Context, uri string, opts *TreeOptions) ([]map
if opts.Limit != 0 {
queryInt(query, "limit", opts.Limit)
}
+ if opts.ExtraFields != nil {
+ query["extra_fields"] = opts.ExtraFields
+ }
if opts.Tags != nil {
query["tags"] = opts.Tags
}
@@ -113,8 +151,11 @@ func (c *Client) Tree(ctx context.Context, uri string, opts *TreeOptions) ([]map
query.Set("include_tags", "true")
}
var result []map[string]any
- err := c.doJSON(ctx, http.MethodGet, "/api/v1/fs/tree", query, nil, &result)
- return result, err
+ env, err := c.doJSONEnvelope(ctx, http.MethodGet, "/api/v1/fs/tree", query, nil, &result)
+ if err != nil {
+ return nil, err
+ }
+ return &TreePage{Result: result, HasMore: env.HasMore}, nil
}
// Stat returns metadata for a URI.
diff --git a/sdk/go/transport.go b/sdk/go/transport.go
index abfa5b658..b1d447af7 100644
--- a/sdk/go/transport.go
+++ b/sdk/go/transport.go
@@ -17,6 +17,7 @@ import (
type responseEnvelope struct {
Status string `json:"status"`
Result json.RawMessage `json:"result,omitempty"`
+ HasMore bool `json:"has_more,omitempty"`
Error *ErrorInfo `json:"error,omitempty"`
Telemetry json.RawMessage `json:"telemetry,omitempty"`
Profile []string `json:"profile,omitempty"`
@@ -64,49 +65,57 @@ func (c *Client) newRequest(ctx context.Context, method, path string, query url.
}
func (c *Client) doJSON(ctx context.Context, method, path string, query url.Values, payload any, out any) error {
+ _, err := c.doJSONEnvelope(ctx, method, path, query, payload, out)
+ return err
+}
+
+func (c *Client) doJSONEnvelope(ctx context.Context, method, path string, query url.Values, payload any, out any) (*responseEnvelope, error) {
var body io.Reader
if payload != nil {
buf, err := json.Marshal(payload)
if err != nil {
- return err
+ return nil, err
}
body = bytes.NewReader(buf)
}
req, err := c.newRequest(ctx, method, path, query, body)
if err != nil {
- return err
+ return nil, err
}
if payload != nil {
req.Header.Set("Content-Type", "application/json")
}
resp, err := c.httpClient.Do(req)
if err != nil {
- return err
+ return nil, err
}
defer resp.Body.Close()
data, err := io.ReadAll(resp.Body)
if err != nil {
- return err
+ return nil, err
}
env, err := decodeEnvelope(resp.StatusCode, data)
if err != nil {
- return err
+ return nil, err
}
if env.Error != nil {
- return apiError(resp.StatusCode, env.Error)
+ return nil, apiError(resp.StatusCode, env.Error)
}
if resp.StatusCode < 200 || resp.StatusCode >= 300 {
- return &Error{
+ return nil, &Error{
Code: "UNKNOWN",
Message: envelopeDetail(env, resp.StatusCode, data),
StatusCode: resp.StatusCode,
}
}
if out == nil || len(env.Result) == 0 || string(env.Result) == "null" {
- return nil
+ return env, nil
+ }
+ if err := json.Unmarshal(env.Result, out); err != nil {
+ return nil, err
}
- return json.Unmarshal(env.Result, out)
+ return env, nil
}
func decodeEnvelope(statusCode int, data []byte) (*responseEnvelope, error) {
diff --git a/sdk/go/types.go b/sdk/go/types.go
index f0847deed..139e15217 100644
--- a/sdk/go/types.go
+++ b/sdk/go/types.go
@@ -187,18 +187,28 @@ type UpdateWatchOptions struct {
// ListOptions controls List.
type ListOptions struct {
- Simple bool
- Recursive bool
- Output string
- AbsLimit int
- ShowAllHidden bool
- NodeLimit int
- Offset int
- Limit int
- SortBy string
- SortOrder string
- Tags []string
- IncludeTags bool
+ Simple bool
+ Recursive bool
+ Output string
+ AbsLimit int
+ IncludeAbstract *bool
+ IncludeOverview *bool
+ OverviewLimit int
+ ShowAllHidden bool
+ NodeLimit int
+ Offset int
+ Limit int
+ SortBy string
+ SortOrder string
+ ExtraFields []string
+ Tags []string
+ IncludeTags bool
+}
+
+// ListPage contains a page of directory entries and pagination metadata.
+type ListPage struct {
+ Result []any
+ HasMore bool
}
// TreeOptions controls Tree.
@@ -214,10 +224,17 @@ type TreeOptions struct {
LevelLimit *int
Offset int
Limit int
+ ExtraFields []string
Tags []string
IncludeTags bool
}
+// TreePage contains a page of tree nodes and pagination metadata.
+type TreePage struct {
+ Result []map[string]any
+ HasMore bool
+}
+
// RemoveOptions controls Remove.
type RemoveOptions struct {
Recursive bool
diff --git a/sdk/python/openviking_sdk/__init__.py b/sdk/python/openviking_sdk/__init__.py
index 85b9cdb74..7783c8af4 100644
--- a/sdk/python/openviking_sdk/__init__.py
+++ b/sdk/python/openviking_sdk/__init__.py
@@ -23,6 +23,7 @@ from .options import (
ExperienceOutcomeOptions,
ExperienceTrajectoryOptions,
FindOptions,
+ ListPage,
Message,
PreflightAssetOptions,
ReindexOptions,
@@ -31,6 +32,7 @@ from .options import (
SearchContextResult,
SearchOptions,
SetTagsOptions,
+ TreePage,
UpdateSessionConfigOptions,
UpdateSkillOptions,
WriteOptions,
@@ -54,6 +56,7 @@ __all__ = [
"FindOptions",
"get_actor_peer_id",
"ImagePart",
+ "ListPage",
"Message",
"MessagePart",
"OpenVikingError",
@@ -68,6 +71,7 @@ __all__ = [
"SyncHTTPClient",
"TextPart",
"ToolPart",
+ "TreePage",
"UnimplementedError",
"UpdateSessionConfigOptions",
"UpdateSkillOptions",
diff --git a/sdk/python/openviking_sdk/client.py b/sdk/python/openviking_sdk/client.py
index 82d1a09e6..b2ef5745c 100644
--- a/sdk/python/openviking_sdk/client.py
+++ b/sdk/python/openviking_sdk/client.py
@@ -55,6 +55,7 @@ from .options import (
ExperienceOutcomeOptions,
ExperienceTrajectoryOptions,
FindOptions,
+ ListPage,
Message,
PreflightAssetOptions,
ReindexOptions,
@@ -63,6 +64,7 @@ from .options import (
SearchContextResult,
SearchOptions,
SetTagsOptions,
+ TreePage,
UpdateSessionConfigOptions,
UpdateSkillOptions,
WriteOptions,
@@ -1079,7 +1081,51 @@ class AsyncHTTPClient:
include_tags: bool = False,
offset: int = 0,
limit: Optional[int] = None,
+ include_abstract: Optional[bool] = None,
+ include_overview: Optional[bool] = None,
+ overview_limit: int = 4000,
) -> List[Any]:
+ page = await self.ls_page(
+ uri,
+ simple=simple,
+ recursive=recursive,
+ output=output,
+ abs_limit=abs_limit,
+ show_all_hidden=show_all_hidden,
+ node_limit=node_limit,
+ sort_by=sort_by,
+ sort_order=sort_order,
+ extra_fields=extra_fields,
+ tags=tags,
+ include_tags=include_tags,
+ offset=offset,
+ limit=limit,
+ include_abstract=include_abstract,
+ include_overview=include_overview,
+ overview_limit=overview_limit,
+ )
+ return page["result"]
+
+ async def ls_page(
+ self,
+ uri: str,
+ simple: bool = False,
+ recursive: bool = False,
+ output: str = "original",
+ abs_limit: int = 256,
+ show_all_hidden: bool = False,
+ node_limit: int = 1000,
+ sort_by: Optional[str] = None,
+ sort_order: str = "asc",
+ extra_fields: Optional[List[str]] = None,
+ tags: Optional[List[str]] = None,
+ include_tags: bool = False,
+ offset: int = 0,
+ limit: Optional[int] = None,
+ include_abstract: Optional[bool] = None,
+ include_overview: Optional[bool] = None,
+ overview_limit: int = 4000,
+ ) -> ListPage:
params: Dict[str, Any] = {
"uri": VikingURI.normalize(uri),
"simple": simple,
@@ -1089,7 +1135,12 @@ class AsyncHTTPClient:
"show_all_hidden": show_all_hidden,
"node_limit": node_limit,
"offset": offset,
+ "overview_limit": overview_limit,
}
+ if include_abstract is not None:
+ params["include_abstract"] = include_abstract
+ if include_overview is not None:
+ params["include_overview"] = include_overview
if sort_by is not None:
params["sort_by"] = sort_by
params["sort_order"] = sort_order
@@ -1106,7 +1157,11 @@ class AsyncHTTPClient:
"/api/v1/fs/ls",
params=params,
)
- return self._handle_response(response)
+ data = self._handle_response_data(response)
+ return {
+ "result": data.get("result") or [],
+ "has_more": bool(data.get("has_more", False)),
+ }
async def tree(
self,
@@ -1121,7 +1176,48 @@ class AsyncHTTPClient:
include_tags: bool = False,
offset: int = 0,
limit: Optional[int] = None,
+ include_abstract: Optional[bool] = None,
+ include_overview: Optional[bool] = None,
+ overview_limit: int = 4000,
+ directories_only: bool = False,
) -> List[Dict[str, Any]]:
+ page = await self.tree_page(
+ uri,
+ output=output,
+ abs_limit=abs_limit,
+ show_all_hidden=show_all_hidden,
+ node_limit=node_limit,
+ level_limit=level_limit,
+ extra_fields=extra_fields,
+ tags=tags,
+ include_tags=include_tags,
+ offset=offset,
+ limit=limit,
+ include_abstract=include_abstract,
+ include_overview=include_overview,
+ overview_limit=overview_limit,
+ directories_only=directories_only,
+ )
+ return page["result"]
+
+ async def tree_page(
+ self,
+ uri: str,
+ output: str = "original",
+ abs_limit: int = 128,
+ show_all_hidden: bool = False,
+ node_limit: int = 1000,
+ level_limit: int = 3,
+ extra_fields: Optional[List[str]] = None,
+ tags: Optional[List[str]] = None,
+ include_tags: bool = False,
+ offset: int = 0,
+ limit: Optional[int] = None,
+ include_abstract: Optional[bool] = None,
+ include_overview: Optional[bool] = None,
+ overview_limit: int = 4000,
+ directories_only: bool = False,
+ ) -> TreePage:
params: Dict[str, Any] = {
"uri": VikingURI.normalize(uri),
"output": output,
@@ -1130,7 +1226,14 @@ class AsyncHTTPClient:
"node_limit": node_limit,
"level_limit": level_limit,
"offset": offset,
+ "overview_limit": overview_limit,
}
+ if include_abstract is not None:
+ params["include_abstract"] = include_abstract
+ if include_overview is not None:
+ params["include_overview"] = include_overview
+ if directories_only:
+ params["directories_only"] = True
if extra_fields:
params["extra_fields"] = list(extra_fields)
if tags is not None:
@@ -1144,7 +1247,11 @@ class AsyncHTTPClient:
"/api/v1/fs/tree",
params=params,
)
- return self._handle_response(response)
+ data = self._handle_response_data(response)
+ return {
+ "result": data.get("result") or [],
+ "has_more": bool(data.get("has_more", False)),
+ }
async def stat(self, uri: str) -> Dict[str, Any]:
response = await self._request(
@@ -2465,9 +2572,52 @@ class SyncHTTPClient:
include_tags: bool = False,
offset: int = 0,
limit: Optional[int] = None,
+ include_abstract: Optional[bool] = None,
+ include_overview: Optional[bool] = None,
+ overview_limit: int = 4000,
) -> List[Any]:
+ return self.ls_page(
+ uri,
+ simple=simple,
+ recursive=recursive,
+ output=output,
+ abs_limit=abs_limit,
+ show_all_hidden=show_all_hidden,
+ node_limit=node_limit,
+ sort_by=sort_by,
+ sort_order=sort_order,
+ extra_fields=extra_fields,
+ tags=tags,
+ include_tags=include_tags,
+ offset=offset,
+ limit=limit,
+ include_abstract=include_abstract,
+ include_overview=include_overview,
+ overview_limit=overview_limit,
+ )["result"]
+
+ def ls_page(
+ self,
+ uri: str,
+ simple: bool = False,
+ recursive: bool = False,
+ output: str = "original",
+ abs_limit: int = 256,
+ show_all_hidden: bool = False,
+ node_limit: int = 1000,
+ sort_by: Optional[str] = None,
+ sort_order: str = "asc",
+ extra_fields: Optional[List[str]] = None,
+ tags: Optional[List[str]] = None,
+ include_tags: bool = False,
+ offset: int = 0,
+ limit: Optional[int] = None,
+ include_abstract: Optional[bool] = None,
+ include_overview: Optional[bool] = None,
+ overview_limit: int = 4000,
+ ) -> ListPage:
return run_async(
- self._async_client.ls(
+ self._async_client.ls_page(
uri,
simple=simple,
recursive=recursive,
@@ -2482,6 +2632,9 @@ class SyncHTTPClient:
include_tags=include_tags,
offset=offset,
limit=limit,
+ include_abstract=include_abstract,
+ include_overview=include_overview,
+ overview_limit=overview_limit,
)
)
@@ -2498,9 +2651,49 @@ class SyncHTTPClient:
include_tags: bool = False,
offset: int = 0,
limit: Optional[int] = None,
+ include_abstract: Optional[bool] = None,
+ include_overview: Optional[bool] = None,
+ overview_limit: int = 4000,
+ directories_only: bool = False,
) -> List[Dict[str, Any]]:
+ return self.tree_page(
+ uri,
+ output=output,
+ abs_limit=abs_limit,
+ show_all_hidden=show_all_hidden,
+ node_limit=node_limit,
+ level_limit=level_limit,
+ extra_fields=extra_fields,
+ tags=tags,
+ include_tags=include_tags,
+ offset=offset,
+ limit=limit,
+ include_abstract=include_abstract,
+ include_overview=include_overview,
+ overview_limit=overview_limit,
+ directories_only=directories_only,
+ )["result"]
+
+ def tree_page(
+ self,
+ uri: str,
+ output: str = "original",
+ abs_limit: int = 128,
+ show_all_hidden: bool = False,
+ node_limit: int = 1000,
+ level_limit: int = 3,
+ extra_fields: Optional[List[str]] = None,
+ tags: Optional[List[str]] = None,
+ include_tags: bool = False,
+ offset: int = 0,
+ limit: Optional[int] = None,
+ include_abstract: Optional[bool] = None,
+ include_overview: Optional[bool] = None,
+ overview_limit: int = 4000,
+ directories_only: bool = False,
+ ) -> TreePage:
return run_async(
- self._async_client.tree(
+ self._async_client.tree_page(
uri,
output=output,
abs_limit=abs_limit,
@@ -2512,6 +2705,10 @@ class SyncHTTPClient:
include_tags=include_tags,
offset=offset,
limit=limit,
+ include_abstract=include_abstract,
+ include_overview=include_overview,
+ overview_limit=overview_limit,
+ directories_only=directories_only,
)
)
diff --git a/sdk/python/openviking_sdk/options.py b/sdk/python/openviking_sdk/options.py
index 0358bfd55..2f3539938 100644
--- a/sdk/python/openviking_sdk/options.py
+++ b/sdk/python/openviking_sdk/options.py
@@ -117,6 +117,16 @@ class ReindexOptions(_ExtraOptions, total=False):
tag_mode: Literal["replace", "append", "clear"]
+class ListPage(TypedDict):
+ result: List[Any]
+ has_more: bool
+
+
+class TreePage(TypedDict):
+ result: List[Dict[str, Any]]
+ has_more: bool
+
+
class CreateSessionOptions(_ExtraOptions, total=False):
memory_policy: Dict[str, Any]
auto_commit_policy: Optional[Dict[str, Any]]
diff --git a/sdk/python/tests/test_async_client_behaviors.py b/sdk/python/tests/test_async_client_behaviors.py
index 5c12856fa..e75ff48d8 100644
--- a/sdk/python/tests/test_async_client_behaviors.py
+++ b/sdk/python/tests/test_async_client_behaviors.py
@@ -491,17 +491,26 @@ def test_sync_http_client_reindex_forwards_to_async_client():
def test_sync_http_client_forwards_tags_to_filesystem_methods():
client = SyncHTTPClient(url="http://localhost:1933")
+ entries = [{"name": "docs"}]
+ page = {"result": entries, "has_more": True}
- with patch.object(client._async_client, "ls", return_value=[]) as mock_ls:
- with patch.object(client._async_client, "tree", return_value=[]) as mock_tree:
+ with patch.object(client._async_client, "ls_page", return_value=page) as mock_ls:
+ with patch.object(client._async_client, "tree_page", return_value=page) as mock_tree:
with patch.object(client._async_client, "grep", return_value={}) as mock_grep:
- with patch("openviking_sdk.client.run_async", side_effect=[[], [], {}]):
- client.ls("viking://resources", tags=["env=prod"])
- client.tree("viking://resources", tags=["env=prod"])
- client.grep("viking://resources", "Sample", tags=["env=prod"])
+ assert client.ls("viking://resources", tags=["env=prod"]) == entries
+ assert (
+ client.tree(
+ "viking://resources",
+ tags=["env=prod"],
+ directories_only=True,
+ )
+ == entries
+ )
+ client.grep("viking://resources", "Sample", tags=["env=prod"])
assert mock_ls.call_args.kwargs["tags"] == ["env=prod"]
assert mock_tree.call_args.kwargs["tags"] == ["env=prod"]
+ assert mock_tree.call_args.kwargs["directories_only"] is True
assert mock_grep.call_args.kwargs["tags"] == ["env=prod"]
@@ -1458,13 +1467,21 @@ def test_not_found_reason_is_preserved_by_sdk_error_mapping():
@pytest.mark.asyncio
-async def test_ls_and_tree_pass_query_params():
+async def test_ls_and_tree_preserve_query_options_and_pagination():
+ import httpx
+
client = AsyncHTTPClient(url="http://localhost:1933")
- fake_http = SimpleNamespace(get=AsyncMock(return_value=object()))
+ entries = [{"name": "docs"}]
+ fake_http = SimpleNamespace(
+ get=AsyncMock(
+ return_value=httpx.Response(
+ 200, json={"status": "ok", "result": entries, "has_more": True}
+ )
+ )
+ )
client._http = fake_http
- client._handle_response = lambda _response: []
- await client.ls(
+ page = await client.ls_page(
"/resources/",
simple=True,
recursive=True,
@@ -1476,10 +1493,22 @@ async def test_ls_and_tree_pass_query_params():
limit=7,
sort_by="mtime",
sort_order="desc",
+ include_abstract=False,
+ include_overview=True,
+ overview_limit=512,
+ )
+ assert page == {"result": entries, "has_more": True}
+ fake_http.get.return_value = httpx.Response(200, json={"status": "ok", "result": entries})
+ page = await client.tree_page(
+ "viking://resources/",
+ level_limit=2,
+ offset=4,
+ limit=6,
+ directories_only=True,
)
- 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/")
+ assert page == {"result": entries, "has_more": False}
+ assert await client.tree("viking://resources/", level_limit=0) == entries
+ assert await client.tree("viking://resources/") == entries
ls_call = fake_http.get.await_args_list[0]
assert ls_call.args == ("/api/v1/fs/ls",)
@@ -1490,6 +1519,9 @@ async def test_ls_and_tree_pass_query_params():
"recursive": True,
"output": "agent",
"abs_limit": 32,
+ "include_abstract": False,
+ "include_overview": True,
+ "overview_limit": 512,
"show_all_hidden": True,
"node_limit": 44,
"offset": 5,
@@ -1503,6 +1535,10 @@ async def test_ls_and_tree_pass_query_params():
assert [
tree_call.kwargs["params"]["level_limit"] for tree_call in fake_http.get.await_args_list[1:]
] == [2, 0, 3]
+ assert "include_abstract" not in fake_http.get.await_args_list[1].kwargs["params"]
+ assert "include_overview" not in fake_http.get.await_args_list[1].kwargs["params"]
+ assert fake_http.get.await_args_list[1].kwargs["params"]["overview_limit"] == 4000
+ assert fake_http.get.await_args_list[1].kwargs["params"]["directories_only"] is True
@pytest.mark.asyncio
diff --git a/sdk/typescript/src/client.ts b/sdk/typescript/src/client.ts
index ea7fb1666..503de970c 100644
--- a/sdk/typescript/src/client.ts
+++ b/sdk/typescript/src/client.ts
@@ -27,6 +27,7 @@ import type {
GitCommitOptions,
GitRestoreOptions,
JsonObject,
+ ListPage,
ListOptions,
GetSkillOptions,
GrepOptions,
@@ -44,6 +45,7 @@ import type {
SetTagsOptions,
TaskListOptions,
TreeOptions,
+ TreePage,
UpdateSessionConfigOptions,
UpdateWatchOptions,
WaitOptions,
@@ -489,45 +491,74 @@ export class OpenVikingClient {
});
}
/** List directory contents. */
- list(uri: string, options: ListOptions = {}): Promise<unknown[]> {
- return this.request("GET", "/api/v1/fs/ls", {
- query: {
- uri: normalizeURI(uri),
- simple: options.simple ?? false,
- recursive: options.recursive ?? false,
- output: options.output ?? "original",
- 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,
- include_tags: options.includeTags || undefined,
+ async list(uri: string, options: ListOptions = {}): Promise<unknown[]> {
+ return (await this.listPage(uri, options)).result;
+ }
+ /** List directory contents with pagination metadata. */
+ async listPage(uri: string, options: ListOptions = {}): Promise<ListPage> {
+ const envelope = await this.transport.requestEnvelope<unknown[]>(
+ "GET",
+ "/api/v1/fs/ls",
+ {
+ query: {
+ uri: normalizeURI(uri),
+ simple: options.simple ?? false,
+ recursive: options.recursive ?? false,
+ output: options.output ?? "original",
+ abs_limit: options.absLimit ?? 256,
+ include_abstract: options.includeAbstract,
+ include_overview: options.includeOverview,
+ overview_limit: options.overviewLimit ?? 4000,
+ 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,
+ extra_fields: options.extraFields,
+ tags: options.tags,
+ include_tags: options.includeTags || undefined,
+ },
},
- });
+ );
+ return {
+ result: envelope.result ?? [],
+ hasMore: envelope.has_more ?? false,
+ };
}
/** Return a directory tree. */
- tree(uri: string, options: TreeOptions = {}): Promise<JsonObject[]> {
- return this.request("GET", "/api/v1/fs/tree", {
- query: {
- uri: normalizeURI(uri),
- output: options.output ?? "original",
- abs_limit: options.absLimit ?? 128,
- include_abstract: options.includeAbstract,
- include_overview: options.includeOverview,
- overview_limit: options.overviewLimit ?? 4000,
- show_all_hidden: options.showAllHidden ?? false,
- directories_only: options.directoriesOnly || undefined,
- node_limit: options.nodeLimit ?? 1000,
- level_limit: options.levelLimit ?? 3,
- offset: options.offset,
- limit: options.limit,
- tags: options.tags,
- include_tags: options.includeTags || undefined,
+ async tree(uri: string, options: TreeOptions = {}): Promise<JsonObject[]> {
+ return (await this.treePage(uri, options)).result;
+ }
+ /** Return a directory tree with pagination metadata. */
+ async treePage(uri: string, options: TreeOptions = {}): Promise<TreePage> {
+ const envelope = await this.transport.requestEnvelope<JsonObject[]>(
+ "GET",
+ "/api/v1/fs/tree",
+ {
+ query: {
+ uri: normalizeURI(uri),
+ output: options.output ?? "original",
+ abs_limit: options.absLimit ?? 128,
+ include_abstract: options.includeAbstract,
+ include_overview: options.includeOverview,
+ overview_limit: options.overviewLimit ?? 4000,
+ show_all_hidden: options.showAllHidden ?? false,
+ directories_only: options.directoriesOnly || undefined,
+ node_limit: options.nodeLimit ?? 1000,
+ level_limit: options.levelLimit ?? 3,
+ offset: options.offset,
+ limit: options.limit,
+ extra_fields: options.extraFields,
+ tags: options.tags,
+ include_tags: options.includeTags || undefined,
+ },
},
- });
+ );
+ return {
+ result: envelope.result ?? [],
+ hasMore: envelope.has_more ?? false,
+ };
}
/** Return URI metadata. */
stat(uri: string): Promise<JsonObject> {
diff --git a/sdk/typescript/src/transport.ts b/sdk/typescript/src/transport.ts
index a239ad8d4..4f5a0434a 100644
--- a/sdk/typescript/src/transport.ts
+++ b/sdk/typescript/src/transport.ts
@@ -64,6 +64,16 @@ export class OpenVikingTransport {
);
}
+ requestEnvelope<T>(
+ method: string,
+ path: string,
+ options: TransportOptions = {},
+ ): Promise<ResponseEnvelope<T>> {
+ return this.consume(method, path, options, (response) =>
+ this.parseResponseEnvelope<T>(response),
+ );
+ }
+
async consume<T>(
method: string,
path: string,
@@ -132,6 +142,13 @@ export class OpenVikingTransport {
}
async parseResponse<T>(response: Response): Promise<T> {
+ const envelope = await this.parseResponseEnvelope<T>(response);
+ return envelope.result as T;
+ }
+
+ async parseResponseEnvelope<T>(
+ response: Response,
+ ): Promise<ResponseEnvelope<T>> {
const text = await response.text();
let envelope: ResponseEnvelope<T> = {};
if (text) {
@@ -155,6 +172,6 @@ export class OpenVikingTransport {
}) as { code?: string; details?: JsonObject; statusCode?: number },
);
}
- return envelope.result as T;
+ return envelope;
}
}
diff --git a/sdk/typescript/src/types.ts b/sdk/typescript/src/types.ts
index 77c5dbac2..0f0e092db 100644
--- a/sdk/typescript/src/types.ts
+++ b/sdk/typescript/src/types.ts
@@ -218,12 +218,16 @@ export interface ListOptions {
recursive?: boolean;
output?: string;
absLimit?: number;
+ includeAbstract?: boolean;
+ includeOverview?: boolean;
+ overviewLimit?: number;
showAllHidden?: boolean;
nodeLimit?: number;
offset?: number;
limit?: number;
sortBy?: "name" | "mtime";
sortOrder?: "asc" | "desc";
+ extraFields?: Array<"locked" | "id" | "count">;
tags?: string[];
includeTags?: boolean;
}
@@ -240,9 +244,20 @@ export interface TreeOptions {
levelLimit?: number;
offset?: number;
limit?: number;
+ extraFields?: Array<"locked" | "id" | "count">;
tags?: string[];
includeTags?: boolean;
}
+/** Directory listing page with pagination metadata. */
+export interface ListPage {
+ result: unknown[];
+ hasMore: boolean;
+}
+/** Directory tree page with pagination metadata. */
+export interface TreePage {
+ result: JsonObject[];
+ hasMore: boolean;
+}
/** Session message payload. */
export interface Message {
role: string;
@@ -391,6 +406,7 @@ export interface APIErrorInfo {
export interface ResponseEnvelope<T> {
status?: string;
result?: T;
+ has_more?: boolean;
error?: APIErrorInfo;
telemetry?: unknown;
profile?: string[];
diff --git a/sdk/typescript/tests/client.test.ts b/sdk/typescript/tests/client.test.ts
index e11dc8a25..29d8f16aa 100644
--- a/sdk/typescript/tests/client.test.ts
+++ b/sdk/typescript/tests/client.test.ts
@@ -594,23 +594,39 @@ describe("OpenVikingClient", () => {
);
});
- it("passes directory list ordering and tree depth to the server", async () => {
+ it("preserves listing options, pagination metadata, and legacy results", async () => {
+ const entries = [{ name: "docs" }];
const fetcher = vi
.fn<typeof fetch>()
- .mockImplementation(async () => ok([]));
+ .mockImplementation(async () => ok(entries))
+ .mockResolvedValueOnce(
+ new Response(
+ JSON.stringify({
+ status: "ok",
+ result: entries,
+ has_more: true,
+ }),
+ ),
+ );
const client = new OpenVikingClient({
baseUrl: "https://example.com",
fetch: fetcher,
});
- await client.list("viking://session", {
+ const listPage = await client.listPage("viking://session", {
nodeLimit: 200,
offset: 4,
limit: 5,
sortBy: "mtime",
sortOrder: "desc",
+ includeAbstract: false,
+ includeOverview: true,
+ overviewLimit: 512,
+ extraFields: ["locked", "id"],
});
- await client.tree("viking://resources/docs", {
+ expect(listPage).toEqual({ result: entries, hasMore: true });
+ await expect(client.list("viking://session")).resolves.toEqual(entries);
+ const treePage = await client.treePage("viking://resources/docs", {
levelLimit: 2,
offset: 6,
limit: 7,
@@ -618,8 +634,12 @@ describe("OpenVikingClient", () => {
includeAbstract: false,
includeOverview: true,
overviewLimit: 512,
+ extraFields: ["count"],
});
- await client.tree("viking://resources/docs", { levelLimit: 0 });
+ expect(treePage).toEqual({ result: entries, hasMore: false });
+ await expect(
+ client.tree("viking://resources/docs", { levelLimit: 0 }),
+ ).resolves.toEqual(entries);
await client.tree("viking://resources/docs");
const listUrl = new URL(String(fetcher.mock.calls[0]![0]));
@@ -628,8 +648,19 @@ describe("OpenVikingClient", () => {
expect(listUrl.searchParams.get("limit")).toBe("5");
expect(listUrl.searchParams.get("sort_by")).toBe("mtime");
expect(listUrl.searchParams.get("sort_order")).toBe("desc");
+ expect(listUrl.searchParams.get("include_abstract")).toBe("false");
+ expect(listUrl.searchParams.get("include_overview")).toBe("true");
+ expect(listUrl.searchParams.get("overview_limit")).toBe("512");
+ expect(listUrl.searchParams.getAll("extra_fields")).toEqual([
+ "locked",
+ "id",
+ ]);
+ const defaultListUrl = new URL(String(fetcher.mock.calls[1]![0]));
+ expect(defaultListUrl.searchParams.has("include_abstract")).toBe(false);
+ expect(defaultListUrl.searchParams.has("include_overview")).toBe(false);
+ expect(defaultListUrl.searchParams.get("overview_limit")).toBe("4000");
const treeUrls = fetcher.mock.calls
- .slice(1)
+ .slice(2)
.map((call) => new URL(String(call[0])));
const treeLimits = treeUrls.map((url) =>
url.searchParams.get("level_limit"),
@@ -640,6 +671,7 @@ describe("OpenVikingClient", () => {
expect(treeUrls[0]!.searchParams.get("include_abstract")).toBe("false");
expect(treeUrls[0]!.searchParams.get("include_overview")).toBe("true");
expect(treeUrls[0]!.searchParams.get("overview_limit")).toBe("512");
+ expect(treeUrls[0]!.searchParams.getAll("extra_fields")).toEqual(["count"]);
expect(treeUrls[2]!.searchParams.has("include_abstract")).toBe(false);
expect(treeUrls[2]!.searchParams.has("include_overview")).toBe(false);
expect(treeUrls[2]!.searchParams.get("overview_limit")).toBe("4000");
diff --git a/tests/server/test_filesystem_router.py b/tests/server/test_filesystem_router.py
index 7facdc96e..cada1da78 100644
--- a/tests/server/test_filesystem_router.py
+++ b/tests/server/test_filesystem_router.py
@@ -395,6 +395,9 @@ async def test_ls_and_tree_forward_pagination_to_filesystem_service(monkeypatch)
tags=["team=search", "env=prod"],
offset=4,
limit=9,
+ include_abstract=False,
+ include_overview=True,
+ overview_limit=512,
_ctx=RequestContext(user=UserIdentifier("acct", "alice"), role=Role.USER),
)
tree_response = await filesystem.tree(
@@ -407,6 +410,9 @@ async def test_ls_and_tree_forward_pagination_to_filesystem_service(monkeypatch)
assert seen["ls"]["tags"] == ["team=search", "env=prod"]
assert seen["ls"]["offset"] == 4
assert seen["ls"]["node_limit"] == 9
+ assert seen["ls"]["include_abstract"] is False
+ assert seen["ls"]["include_overview"] is True
+ assert seen["ls"]["overview_limit"] == 512
assert seen["tree"]["offset"] == 3
assert seen["tree"]["node_limit"] == 5
assert ls_response.result == [{"name": "a.md"}]
diff --git a/tests/service/test_fs_service.py b/tests/service/test_fs_service.py
index 473a58f6e..39cef518d 100644
--- a/tests/service/test_fs_service.py
+++ b/tests/service/test_fs_service.py
@@ -484,12 +484,19 @@ async def test_grep_projects_tags_when_include_tags_is_requested(request_context
@pytest.mark.asyncio
-async def test_ls_and_tree_skip_tag_projection_without_tags_or_include_tags(request_context):
- entries = [{"uri": "viking://resources/a.md", "isDir": False}]
- viking_fs = SimpleNamespace(
- ls=AsyncMock(return_value=entries),
- tree=AsyncMock(return_value=entries),
+async def test_plain_listing_reads_only_requested_page_summaries(request_context, monkeypatch):
+ selected = {"uri": "viking://resources/docs", "isDir": True}
+ entries = [selected, {"uri": "viking://resources/probe", "isDir": True}]
+ viking_fs = VikingFS(agfs=SimpleNamespace())
+ monkeypatch.setattr(viking_fs, "_ensure_access", AsyncMock())
+ monkeypatch.setattr(
+ viking_fs, "_ls_original", AsyncMock(return_value=[dict(e) for e in entries])
)
+ monkeypatch.setattr(viking_fs, "_tree_original", AsyncMock(return_value=entries))
+ abstract = AsyncMock(return_value="L0 summary")
+ overview = AsyncMock(return_value="L1 overview")
+ monkeypatch.setattr(viking_fs, "_read_abstract_for_known_dir", abstract)
+ monkeypatch.setattr(viking_fs, "overview", overview)
class FakeVikingDB:
async def filter(self, **_kwargs):
@@ -497,12 +504,21 @@ 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) == ListingPage(
- entries=entries, has_more=False
+ assert await service.ls(
+ "viking://resources",
+ ctx=request_context,
+ node_limit=1,
+ include_abstract=True,
+ include_overview=True,
+ ) == ListingPage(
+ entries=[{**selected, "abstract": "L0 summary", "overview": "L1 overview"}],
+ has_more=True,
)
assert await service.tree("viking://resources", ctx=request_context) == ListingPage(
entries=entries, has_more=False
)
+ abstract.assert_awaited_once_with(selected["uri"], ctx=request_context)
+ overview.assert_awaited_once_with(selected["uri"], ctx=request_context)
@pytest.mark.asyncio
@@ -687,7 +703,7 @@ async def test_tagged_grep_reuses_tags_returned_by_viking_fs(request_context):
@pytest.mark.asyncio
-async def test_ls_applies_offset_and_node_limit_after_tag_filtering(request_context):
+async def test_ls_filters_and_paginates_before_reading_summaries(request_context, monkeypatch):
entries = [
{
"uri": f"viking://resources/unmatched-{index:03d}.md",
@@ -696,18 +712,20 @@ async def test_ls_applies_offset_and_node_limit_after_tag_filtering(request_cont
for index in range(256)
] + [
{"uri": "viking://resources/b.md", "isDir": False},
- {"uri": "viking://resources/c.md", "isDir": False},
+ {"uri": "viking://resources/docs", "isDir": True},
{"uri": "viking://resources/d.md", "isDir": False},
]
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),
- )
+ viking_fs = VikingFS(agfs=SimpleNamespace())
+ monkeypatch.setattr(viking_fs, "_ensure_access", AsyncMock())
+ monkeypatch.setattr(viking_fs, "_ls_original", AsyncMock(side_effect=fake_ls))
+ abstract = AsyncMock(return_value="L0 summary")
+ overview = AsyncMock(return_value="L1 overview")
+ monkeypatch.setattr(viking_fs, "_read_abstract_for_known_dir", abstract)
+ monkeypatch.setattr(viking_fs, "overview", overview)
class FakeVikingDB:
async def filter(self, **_kwargs):
@@ -718,9 +736,14 @@ async def test_ls_applies_offset_and_node_limit_after_tag_filtering(request_cont
"search_tags": ["team=search", "env=prod"],
},
{
- "uri": "viking://resources/c.md",
- "level": 2,
- "search_tags": ["team=search", "env=prod"],
+ "uri": "viking://resources/docs",
+ "level": 0,
+ "search_tags": ["team=search"],
+ },
+ {
+ "uri": "viking://resources/docs",
+ "level": 1,
+ "search_tags": ["env=prod", "team=search"],
},
{
"uri": "viking://resources/d.md",
@@ -736,18 +759,24 @@ async def test_ls_applies_offset_and_node_limit_after_tag_filtering(request_cont
tags=["team=search", "env=prod"],
node_limit=1,
offset=1,
- output="agent",
+ include_abstract=True,
+ include_overview=True,
)
- 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
- 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 result == ListingPage(
+ entries=[
+ {
+ "uri": "viking://resources/docs",
+ "isDir": True,
+ "tags": ["team=search", "env=prod"],
+ "abstract": "L0 summary",
+ "overview": "L1 overview",
+ }
+ ],
+ has_more=True,
+ )
+ abstract.assert_awaited_once_with("viking://resources/docs", ctx=request_context)
+ overview.assert_awaited_once_with("viking://resources/docs", ctx=request_context)
@pytest.mark.asyncio
diff --git a/tests/storage/test_viking_fs_tree.py b/tests/storage/test_viking_fs_tree.py
index 812ee833d..8553ff2ea 100644
--- a/tests/storage/test_viking_fs_tree.py
+++ b/tests/storage/test_viking_fs_tree.py
@@ -733,7 +733,7 @@ async def test_tree_agent_normalizes_modtime_to_utc(monkeypatch, fs):
@pytest.mark.asyncio
-async def test_ls_agent_modtime_is_raw_utc_iso(monkeypatch, fs):
+async def test_ls_agent_preserves_metadata_acl_and_summary_controls(monkeypatch, fs):
async def fake_ls_entries(_path, **_kwargs):
return [
{
@@ -750,6 +750,7 @@ async def test_ls_agent_modtime_is_raw_utc_iso(monkeypatch, fs):
"modTime": "2026-06-11T00:30:18+08:00",
"isDir": True,
},
+ {"name": "docs", "size": 4096, "mode": 0o755, "modTime": "", "isDir": True},
]
monkeypatch.setattr(fs, "_uri_to_path", lambda _uri, **_kwargs: "/local/test_account/resources")
@@ -763,13 +764,18 @@ async def test_ls_agent_modtime_is_raw_utc_iso(monkeypatch, fs):
fs.acl_manager = SimpleNamespace(is_enabled=acl_enabled)
- async def fake_can_access_many(uris, _ctx):
+ async def fake_can_access_many(uris, _ctx, **_kwargs):
return {uri: not uri.endswith("/restricted") for uri in uris}
monkeypatch.setattr(fs, "_can_access_many", fake_can_access_many)
+ abstract = AsyncMock(return_value="L0 summary")
+ overview = AsyncMock(return_value="L1 overview")
+ monkeypatch.setattr(fs, "_read_abstract_for_known_dir", abstract)
+ monkeypatch.setattr(fs, "overview", overview)
- result = await fs._ls_agent(
+ result = await fs.ls(
"viking://resources",
+ output="agent",
abs_limit=256,
show_all_hidden=False,
ctx=_default_ctx(),
@@ -783,6 +789,25 @@ async def test_ls_agent_modtime_is_raw_utc_iso(monkeypatch, fs):
"isDir": True,
"access": "denied",
}
+ assert result[2]["abstract"] == "L0 summary"
+ abstract.assert_awaited_once_with("viking://resources/docs", ctx=_default_ctx())
+ overview.assert_not_awaited()
+ abstract.reset_mock()
+
+ result = await fs.ls(
+ "viking://resources",
+ output="agent",
+ include_abstract=False,
+ include_overview=True,
+ ctx=_default_ctx(),
+ )
+ assert all("abstract" not in entry for entry in result)
+ assert result[0]["overview"] == ""
+ assert "overview" not in result[1]
+ assert result[2]["overview"] == "L1 overview"
+ abstract.assert_not_awaited()
+ overview.assert_awaited_once_with("viking://resources/docs", ctx=_default_ctx())
+
tied = [
({"name": name, "isDir": False, "modTime": "2026-01-01T00:00:00Z"}, name)
for name in ["b.md", "a.md"]