Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
feat(ls): 支持返回目录摘要与概览 (#5434)
hezhang-1216acfeb99b4813
diff --git a/crates/ov_cli/src/client.rs b/crates/ov_cli/src/client.rsindex 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.rsindex 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.rsindex 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.rsindex 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.rsindex 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.mdindex 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.mdindex 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,tagsopenviking 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.pyindex 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.pyindex 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 recursivelysimple: Return only relative path listoutput: 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 lengthshow_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.pyindex 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 URIoutput: 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 lengthshow_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,+ )@staticmethoddef _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.mdindex 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 CoverageThe 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.goindex 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 := 0treeCalls := 0client, 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.goindex 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) ([]anyif absLimit == 0 {absLimit = 256}+ overviewLimit := opts.OverviewLimit+ if overviewLimit == 0 {+ overviewLimit = 4000+ }nodeLimit := opts.NodeLimitif nodeLimit == 0 {nodeLimit = 1000@@ -33,6 +46,13 @@ func (c *Client) List(ctx context.Context, uri string, opts *ListOptions) ([]anyqueryBool(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) ([]anyif 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) ([]mapif 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) ([]mapquery.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.goindex 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.Readerif 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.goindex 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 *intOffset intLimit int+ ExtraFields []stringTags []stringIncludeTags 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 booldiff --git a/sdk/python/openviking_sdk/__init__.py b/sdk/python/openviking_sdk/__init__.pyindex 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.pyindex 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_overviewif sort_by is not None:params["sort_by"] = sort_byparams["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"] = Trueif 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.pyindex 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.pyindex 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 Trueassert 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/") == entriesls_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.asynciodiff --git a/sdk/typescript/src/client.ts b/sdk/typescript/src/client.tsindex 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.tsindex 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.tsindex 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.tsindex 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.pyindex 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"] == 4assert seen["ls"]["node_limit"] == 9+ assert seen["ls"]["include_abstract"] is False+ assert seen["ls"]["include_overview"] is True+ assert seen["ls"]["overview_limit"] == 512assert seen["tree"]["offset"] == 3assert seen["tree"]["node_limit"] == 5assert ls_response.result == [{"name": "a.md"}]diff --git a/tests/service/test_fs_service.py b/tests/service/test_fs_service.pyindex 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(requservice = 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_contfor 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_conttags=["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.asynciodiff --git a/tests/storage/test_viking_fs_tree.py b/tests/storage/test_viking_fs_tree.pyindex 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"]