@aigne/afs 1.3.0 → 1.4.0-beta.1

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## [1.4.0-beta.1](https://github.com/AIGNE-io/aigne-framework/compare/afs-v1.4.0-beta...afs-v1.4.0-beta.1) (2025-12-17)
+
+
+### Bug Fixes
+
+* bump version ([70d217c](https://github.com/AIGNE-io/aigne-framework/commit/70d217c8360dd0dda7f5f17011c4e92ec836e801))
+
+## [1.4.0-beta](https://github.com/AIGNE-io/aigne-framework/compare/afs-v1.3.0...afs-v1.4.0-beta) (2025-12-17)
+
+
+### Features
+
+* **afs:** support expand context into prompt template by call `$afs.xxx` ([#830](https://github.com/AIGNE-io/aigne-framework/issues/830)) ([5616acd](https://github.com/AIGNE-io/aigne-framework/commit/5616acd6ea257c91aa0b766608f45c5ce17f0345))
+
+
+### Bug Fixes
+
+* **afs:** read method should not throw not found error ([#835](https://github.com/AIGNE-io/aigne-framework/issues/835)) ([ebfdfc1](https://github.com/AIGNE-io/aigne-framework/commit/ebfdfc1cdba23efd23ac2ad4621e3f046990fd8b))
+
 ## [1.3.0](https://github.com/AIGNE-io/aigne-framework/compare/afs-v1.3.0-beta.3...afs-v1.3.0) (2025-12-12)
 
 ## [1.3.0-beta.3](https://github.com/AIGNE-io/aigne-framework/compare/afs-v1.3.0-beta.2...afs-v1.3.0-beta.3) (2025-12-11)

package/lib/cjs/afs.d.ts

@@ -1,9 +1,11 @@
 import { Emitter } from "strict-event-emitter";
-import type { AFSDeleteOptions, AFSEntry, AFSListOptions, AFSModule, AFSRenameOptions, AFSRoot, AFSRootEvents, AFSSearchOptions, AFSWriteEntryPayload, AFSWriteOptions } from "./type.js";
+import { type AFSContext, type AFSDeleteOptions, type AFSDeleteResult, type AFSExecOptions, type AFSExecResult, type AFSModule, type AFSReadOptions, type AFSReadResult, type AFSRenameOptions, type AFSRenameResult, type AFSRoot, type AFSRootEvents, type AFSRootListOptions, type AFSRootListResult, type AFSRootSearchOptions, type AFSRootSearchResult, type AFSWriteEntryPayload, type AFSWriteOptions, type AFSWriteResult } from "./type.js";
 export interface AFSOptions {
     modules?: AFSModule[];
+    context?: AFSContext;
 }
 export declare class AFS extends Emitter<AFSRootEvents> implements AFSRoot {
+    options: AFSOptions;
     name: string;
     constructor(options?: AFSOptions);
     private modules;
@@ -14,32 +16,17 @@ export declare class AFS extends Emitter<AFSRootEvents> implements AFSRoot {
         description?: string;
         module: AFSModule;
     }[]>;
-    list(path: string, options?: AFSListOptions): Promise<{
-        list: AFSEntry[];
-        message?: string;
-    }>;
-    read(path: string): Promise<{
-        result?: AFSEntry;
-        message?: string;
-    }>;
-    write(path: string, content: AFSWriteEntryPayload, options?: AFSWriteOptions): Promise<{
-        result: AFSEntry;
-        message?: string;
-    }>;
-    delete(path: string, options?: AFSDeleteOptions): Promise<{
-        message?: string;
-    }>;
-    rename(oldPath: string, newPath: string, options?: AFSRenameOptions): Promise<{
-        message?: string;
-    }>;
-    search(path: string, query: string, options?: AFSSearchOptions): Promise<{
-        list: AFSEntry[];
-        message?: string;
-    }>;
+    list(path: string, options?: AFSRootListOptions): Promise<AFSRootListResult>;
+    private _list;
+    read(path: string, _options?: AFSReadOptions): Promise<AFSReadResult>;
+    write(path: string, content: AFSWriteEntryPayload, options?: AFSWriteOptions): Promise<AFSWriteResult>;
+    delete(path: string, options?: AFSDeleteOptions): Promise<AFSDeleteResult>;
+    rename(oldPath: string, newPath: string, options?: AFSRenameOptions): Promise<AFSRenameResult>;
+    search(path: string, query: string, options?: AFSRootSearchOptions): Promise<AFSRootSearchResult>;
+    private processWithPreset;
+    private _select;
+    private _search;
     private findModules;
-    exec(path: string, args: Record<string, any>, options: {
-        context: any;
-    }): Promise<{
-        result: Record<string, any>;
-    }>;
+    exec(path: string, args: Record<string, any>, options: AFSExecOptions): Promise<AFSExecResult>;
+    private buildTreeView;
 }

package/lib/cjs/afs.js

@@ -3,12 +3,16 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.AFS = void 0;
 const strict_event_emitter_1 = require("strict-event-emitter");
 const ufo_1 = require("ufo");
+const zod_1 = require("zod");
+const type_js_1 = require("./type.js");
 const DEFAULT_MAX_DEPTH = 1;
 const MODULES_ROOT_DIR = "/modules";
 class AFS extends strict_event_emitter_1.Emitter {
+    options;
     name = "AFSRoot";
-    constructor(options) {
+    constructor(options = {}) {
         super();
+        this.options = options;
         for (const module of options?.modules ?? []) {
             this.mount(module);
         }
@@ -35,12 +39,20 @@ class AFS extends strict_event_emitter_1.Emitter {
             module,
         }));
     }
-    async list(path, options) {
-        const maxDepth = options?.maxDepth ?? DEFAULT_MAX_DEPTH;
-        if (!(maxDepth >= 0))
-            throw new Error(`Invalid maxDepth: ${maxDepth}`);
+    async list(path, options = {}) {
+        let preset;
+        if (options.preset) {
+            preset = this.options?.context?.list?.presets?.[options.preset];
+            if (!preset)
+                throw new Error(`Preset not found: ${options.preset}`);
+        }
+        return await this.processWithPreset(path, undefined, preset, {
+            ...options,
+            defaultSelect: () => this._list(path, options),
+        });
+    }
+    async _list(path, options = {}) {
         const results = [];
-        const messages = [];
         const matches = this.findModules(path, options);
         for (const matched of matches) {
             const moduleEntry = {
@@ -55,12 +67,12 @@ class AFS extends strict_event_emitter_1.Emitter {
             if (!matched.module.list)
                 continue;
             try {
-                const { list, message } = await matched.module.list(matched.subpath, {
+                const { data } = await matched.module.list(matched.subpath, {
                     ...options,
                     maxDepth: matched.maxDepth,
                 });
-                if (list.length) {
-                    results.push(...list.map((entry) => ({
+                if (data.length) {
+                    results.push(...data.map((entry) => ({
                         ...entry,
                         path: (0, ufo_1.joinURL)(matched.modulePath, entry.path),
                     })));
@@ -68,30 +80,28 @@ class AFS extends strict_event_emitter_1.Emitter {
                 else {
                     results.push(moduleEntry);
                 }
-                if (message)
-                    messages.push(message);
             }
             catch (error) {
                 console.error(`Error listing from module at ${matched.modulePath}`, error);
             }
         }
-        return { list: results, message: messages.join("; ").trim() || undefined };
+        return { data: results };
     }
-    async read(path) {
+    async read(path, _options) {
         const modules = this.findModules(path, { exactMatch: true });
         for (const { module, modulePath, subpath } of modules) {
             const res = await module.read?.(subpath);
-            if (res?.result) {
+            if (res?.data) {
                 return {
                     ...res,
-                    result: {
-                        ...res.result,
-                        path: (0, ufo_1.joinURL)(modulePath, res.result.path),
+                    data: {
+                        ...res.data,
+                        path: (0, ufo_1.joinURL)(modulePath, res.data.path),
                     },
                 };
             }
         }
-        return { result: undefined, message: "File not found" };
+        return { data: undefined, message: "File not found" };
     }
     async write(path, content, options) {
         const module = this.findModules(path, { exactMatch: true })[0];
@@ -100,9 +110,9 @@ class AFS extends strict_event_emitter_1.Emitter {
         const res = await module.module.write(module.subpath, content, options);
         return {
             ...res,
-            result: {
-                ...res.result,
-                path: (0, ufo_1.joinURL)(module.modulePath, res.result.path),
+            data: {
+                ...res.data,
+                path: (0, ufo_1.joinURL)(module.modulePath, res.data.path),
             },
         };
     }
@@ -124,15 +134,59 @@ class AFS extends strict_event_emitter_1.Emitter {
         }
         return await oldModule.module.rename(oldModule.subpath, newModule.subpath, options);
     }
-    async search(path, query, options) {
+    async search(path, query, options = {}) {
+        let preset;
+        if (options.preset) {
+            preset = this.options?.context?.search?.presets?.[options.preset];
+            if (!preset)
+                throw new Error(`Preset not found: ${options.preset}`);
+        }
+        return await this.processWithPreset(path, query, preset, {
+            ...options,
+            defaultSelect: () => this._search(path, query, options),
+        });
+    }
+    async processWithPreset(path, query, preset, options) {
+        const select = options.select || preset?.select;
+        const per = options.per || preset?.per;
+        const dedupe = options.dedupe || preset?.dedupe;
+        const format = options.format || preset?.format;
+        const entries = select
+            ? (await this._select(path, query, select, options)).data
+            : (await options.defaultSelect()).data;
+        const mapped = per
+            ? await Promise.all(entries.map((data) => per.invoke({ data }, options).then((res) => res.data)))
+            : entries;
+        const deduped = dedupe
+            ? await dedupe.invoke({ data: mapped }, options).then((res) => res.data)
+            : mapped;
+        let formatted = deduped;
+        if (format === "tree") {
+            const valid = zod_1.z.array(type_js_1.afsEntrySchema).safeParse(deduped);
+            if (valid.data)
+                formatted = this.buildTreeView(valid.data);
+            else
+                throw new Error("Tree format requires entries to be AFSEntry objects");
+        }
+        else if (typeof format === "object" && typeof format.invoke === "function") {
+            formatted = await format.invoke({ data: deduped }, options).then((res) => res.data);
+        }
+        return { data: formatted };
+    }
+    async _select(path, query, select, options) {
+        const { data } = await select.invoke({ path, query }, options);
+        const results = (await Promise.all(data.map((p) => this.read(p).then((res) => res.data)))).filter((i) => !!i);
+        return { data: results };
+    }
+    async _search(path, query, options) {
         const results = [];
         const messages = [];
         for (const { module, modulePath, subpath } of this.findModules(path)) {
             if (!module.search)
                 continue;
             try {
-                const { list, message } = await module.search(subpath, query, options);
-                results.push(...list.map((entry) => ({
+                const { data, message } = await module.search(subpath, query, options);
+                results.push(...data.map((entry) => ({
                     ...entry,
                     path: (0, ufo_1.joinURL)(modulePath, entry.path),
                 })));
@@ -143,7 +197,7 @@ class AFS extends strict_event_emitter_1.Emitter {
                 console.error(`Error searching in module at ${modulePath}`, error);
             }
         }
-        return { list: results, message: messages.join("; ") };
+        return { data: results, message: messages.join("; ") };
     }
     findModules(path, options) {
         const maxDepth = Math.max(options?.maxDepth ?? DEFAULT_MAX_DEPTH, 1);
@@ -179,5 +233,50 @@ class AFS extends strict_event_emitter_1.Emitter {
             throw new Error(`No module found for path: ${path}`);
         return await module.module.exec(module.subpath, args, options);
     }
+    buildTreeView(entries) {
+        const tree = {};
+        const entryMap = new Map();
+        for (const entry of entries) {
+            entryMap.set(entry.path, entry);
+            const parts = entry.path.split("/").filter(Boolean);
+            let current = tree;
+            for (const part of parts) {
+                if (!current[part]) {
+                    current[part] = {};
+                }
+                current = current[part];
+            }
+        }
+        const renderTree = (node, prefix = "", currentPath = "") => {
+            let result = "";
+            const keys = Object.keys(node);
+            keys.forEach((key, index) => {
+                const isLast = index === keys.length - 1;
+                const fullPath = currentPath ? `${currentPath}/${key}` : `/${key}`;
+                const entry = entryMap.get(fullPath);
+                // Build metadata suffix
+                const metadataParts = [];
+                // Children count
+                const childrenCount = entry?.metadata?.childrenCount;
+                if (typeof childrenCount === "number") {
+                    metadataParts.push(`${childrenCount} items`);
+                }
+                // Children truncated
+                if (entry?.metadata?.childrenTruncated) {
+                    metadataParts.push("truncated");
+                }
+                // Executable
+                if (entry?.metadata?.execute) {
+                    metadataParts.push("executable");
+                }
+                const metadataSuffix = metadataParts.length > 0 ? ` [${metadataParts.join(", ")}]` : "";
+                result += `${prefix}${isLast ? "└── " : "├── "}${key}${metadataSuffix}`;
+                result += `\n`;
+                result += renderTree(node[key], `${prefix}${isLast ? "    " : "│   "}`, fullPath);
+            });
+            return result;
+        };
+        return renderTree(tree);
+    }
 }
 exports.AFS = AFS;

package/lib/cjs/type.d.ts

@@ -1,60 +1,85 @@
 import type { Emitter } from "strict-event-emitter";
+import { type ZodType } from "zod";
 export interface AFSListOptions {
     filter?: {
         userId?: string;
         sessionId?: string;
     };
-    recursive?: boolean;
     maxDepth?: number;
     limit?: number;
     orderBy?: [string, "asc" | "desc"][];
+    maxChildren?: number;
+    onOverflow?: "truncate";
+    /**
+     * Whether to disable .gitignore files when listing files.
+     * @default false
+     */
+    disableGitignore?: boolean;
+    context?: any;
+}
+export interface AFSListResult {
+    data: AFSEntry[];
+    message?: string;
+    context?: any;
 }
 export interface AFSSearchOptions {
     limit?: number;
     caseSensitive?: boolean;
+    context?: any;
+}
+export interface AFSSearchResult {
+    data: AFSEntry[];
+    message?: string;
+}
+export interface AFSReadOptions {
+    context?: any;
+}
+export interface AFSReadResult {
+    data?: AFSEntry;
+    message?: string;
 }
 export interface AFSDeleteOptions {
     recursive?: boolean;
+    context?: any;
+}
+export interface AFSDeleteResult {
+    message?: string;
 }
 export interface AFSRenameOptions {
     overwrite?: boolean;
+    context?: any;
+}
+export interface AFSRenameResult {
+    message?: string;
 }
 export interface AFSWriteOptions {
     append?: boolean;
+    context?: any;
+}
+export interface AFSWriteResult {
+    data: AFSEntry;
+    message?: string;
+    context?: any;
 }
 export interface AFSWriteEntryPayload extends Omit<AFSEntry, "id" | "path"> {
 }
+export interface AFSExecOptions {
+    context: any;
+}
+export interface AFSExecResult {
+    data: Record<string, any>;
+}
 export interface AFSModule {
     readonly name: string;
     readonly description?: string;
     onMount?(root: AFSRoot): void;
-    list?(path: string, options?: AFSListOptions): Promise<{
-        list: AFSEntry[];
-        message?: string;
-    }>;
-    read?(path: string): Promise<{
-        result?: AFSEntry;
-        message?: string;
-    }>;
-    write?(path: string, content: AFSWriteEntryPayload, options?: AFSWriteOptions): Promise<{
-        result: AFSEntry;
-        message?: string;
-    }>;
-    delete?(path: string, options?: AFSDeleteOptions): Promise<{
-        message?: string;
-    }>;
-    rename?(oldPath: string, newPath: string, options?: AFSRenameOptions): Promise<{
-        message?: string;
-    }>;
-    search?(path: string, query: string, options?: AFSSearchOptions): Promise<{
-        list: AFSEntry[];
-        message?: string;
-    }>;
-    exec?(path: string, args: Record<string, any>, options: {
-        context: any;
-    }): Promise<{
-        result: Record<string, any>;
-    }>;
+    list?(path: string, options?: AFSListOptions): Promise<AFSListResult>;
+    read?(path: string, options?: AFSReadOptions): Promise<AFSReadResult>;
+    write?(path: string, content: AFSWriteEntryPayload, options?: AFSWriteOptions): Promise<AFSWriteResult>;
+    delete?(path: string, options?: AFSDeleteOptions): Promise<AFSDeleteResult>;
+    rename?(oldPath: string, newPath: string, options?: AFSRenameOptions): Promise<AFSRenameResult>;
+    search?(path: string, query: string, options?: AFSSearchOptions): Promise<AFSSearchResult>;
+    exec?(path: string, args: Record<string, any>, options: AFSExecOptions): Promise<AFSExecResult>;
 }
 export type AFSRootEvents = {
     agentSucceed: [{
@@ -65,7 +90,21 @@ export type AFSRootEvents = {
         entry: AFSEntry;
     }];
 };
+export interface AFSRootListOptions extends AFSListOptions, AFSContextPreset {
+    preset?: string;
+}
+export interface AFSRootListResult extends Omit<AFSListResult, "data"> {
+    data: any;
+}
+export interface AFSRootSearchOptions extends AFSSearchOptions, AFSContextPreset {
+    preset?: string;
+}
+export interface AFSRootSearchResult extends Omit<AFSSearchResult, "data"> {
+    data: any;
+}
 export interface AFSRoot extends Emitter<AFSRootEvents>, AFSModule {
+    list(path: string, options?: AFSRootListOptions): Promise<AFSRootListResult>;
+    search(path: string, query: string, options: AFSRootSearchOptions): Promise<AFSRootSearchResult>;
 }
 export interface AFSEntryMetadata extends Record<string, any> {
     execute?: {
@@ -75,6 +114,7 @@ export interface AFSEntryMetadata extends Record<string, any> {
         outputSchema?: Record<string, any>;
     };
     childrenCount?: number;
+    childrenTruncated?: boolean;
 }
 export interface AFSEntry<T = any> {
     id: string;
@@ -89,3 +129,42 @@ export interface AFSEntry<T = any> {
     linkTo?: string | null;
     content?: T;
 }
+export declare const afsEntrySchema: ZodType<AFSEntry>;
+export interface AFSContextPreset {
+    /**
+     * The view template for presenting the search results.
+     */
+    view?: string;
+    select?: AFSContextPresetOptionAgent<{
+        path: string;
+        query?: string;
+    }, {
+        data: string[];
+    }>;
+    per?: AFSContextPresetOptionAgent<{
+        data: AFSEntry;
+    }, {
+        data: unknown;
+    }>;
+    dedupe?: AFSContextPresetOptionAgent<{
+        data: unknown[];
+    }, {
+        data: unknown;
+    }>;
+    format?: "default" | "tree" | AFSContextPresetOptionAgent<{
+        data: unknown;
+    }, {
+        data: unknown;
+    }>;
+}
+export interface AFSContextPresetOptionAgent<I = any, O = any> {
+    invoke(input: I, options?: any): Promise<O>;
+}
+export interface AFSContext {
+    search?: {
+        presets?: Record<string, AFSContextPreset>;
+    };
+    list?: {
+        presets?: Record<string, AFSContextPreset>;
+    };
+}

package/lib/cjs/type.js

@@ -1,2 +1,17 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.afsEntrySchema = void 0;
+const zod_1 = require("zod");
+exports.afsEntrySchema = zod_1.z.object({
+    id: zod_1.z.string(),
+    createdAt: zod_1.z.date().optional(),
+    updatedAt: zod_1.z.date().optional(),
+    path: zod_1.z.string(),
+    userId: zod_1.z.string().nullable().optional(),
+    sessionId: zod_1.z.string().nullable().optional(),
+    summary: zod_1.z.string().nullable().optional(),
+    description: zod_1.z.string().nullable().optional(),
+    metadata: zod_1.z.record(zod_1.z.any()).nullable().optional(),
+    linkTo: zod_1.z.string().nullable().optional(),
+    content: zod_1.z.any().optional(),
+});

package/lib/dts/afs.d.ts

@@ -1,9 +1,11 @@
 import { Emitter } from "strict-event-emitter";
-import type { AFSDeleteOptions, AFSEntry, AFSListOptions, AFSModule, AFSRenameOptions, AFSRoot, AFSRootEvents, AFSSearchOptions, AFSWriteEntryPayload, AFSWriteOptions } from "./type.js";
+import { type AFSContext, type AFSDeleteOptions, type AFSDeleteResult, type AFSExecOptions, type AFSExecResult, type AFSModule, type AFSReadOptions, type AFSReadResult, type AFSRenameOptions, type AFSRenameResult, type AFSRoot, type AFSRootEvents, type AFSRootListOptions, type AFSRootListResult, type AFSRootSearchOptions, type AFSRootSearchResult, type AFSWriteEntryPayload, type AFSWriteOptions, type AFSWriteResult } from "./type.js";
 export interface AFSOptions {
     modules?: AFSModule[];
+    context?: AFSContext;
 }
 export declare class AFS extends Emitter<AFSRootEvents> implements AFSRoot {
+    options: AFSOptions;
     name: string;
     constructor(options?: AFSOptions);
     private modules;
@@ -14,32 +16,17 @@ export declare class AFS extends Emitter<AFSRootEvents> implements AFSRoot {
         description?: string;
         module: AFSModule;
     }[]>;
-    list(path: string, options?: AFSListOptions): Promise<{
-        list: AFSEntry[];
-        message?: string;
-    }>;
-    read(path: string): Promise<{
-        result?: AFSEntry;
-        message?: string;
-    }>;
-    write(path: string, content: AFSWriteEntryPayload, options?: AFSWriteOptions): Promise<{
-        result: AFSEntry;
-        message?: string;
-    }>;
-    delete(path: string, options?: AFSDeleteOptions): Promise<{
-        message?: string;
-    }>;
-    rename(oldPath: string, newPath: string, options?: AFSRenameOptions): Promise<{
-        message?: string;
-    }>;
-    search(path: string, query: string, options?: AFSSearchOptions): Promise<{
-        list: AFSEntry[];
-        message?: string;
-    }>;
+    list(path: string, options?: AFSRootListOptions): Promise<AFSRootListResult>;
+    private _list;
+    read(path: string, _options?: AFSReadOptions): Promise<AFSReadResult>;
+    write(path: string, content: AFSWriteEntryPayload, options?: AFSWriteOptions): Promise<AFSWriteResult>;
+    delete(path: string, options?: AFSDeleteOptions): Promise<AFSDeleteResult>;
+    rename(oldPath: string, newPath: string, options?: AFSRenameOptions): Promise<AFSRenameResult>;
+    search(path: string, query: string, options?: AFSRootSearchOptions): Promise<AFSRootSearchResult>;
+    private processWithPreset;
+    private _select;
+    private _search;
     private findModules;
-    exec(path: string, args: Record<string, any>, options: {
-        context: any;
-    }): Promise<{
-        result: Record<string, any>;
-    }>;
+    exec(path: string, args: Record<string, any>, options: AFSExecOptions): Promise<AFSExecResult>;
+    private buildTreeView;
 }

package/lib/dts/type.d.ts

@@ -1,60 +1,85 @@
 import type { Emitter } from "strict-event-emitter";
+import { type ZodType } from "zod";
 export interface AFSListOptions {
     filter?: {
         userId?: string;
         sessionId?: string;
     };
-    recursive?: boolean;
     maxDepth?: number;
     limit?: number;
     orderBy?: [string, "asc" | "desc"][];
+    maxChildren?: number;
+    onOverflow?: "truncate";
+    /**
+     * Whether to disable .gitignore files when listing files.
+     * @default false
+     */
+    disableGitignore?: boolean;
+    context?: any;
+}
+export interface AFSListResult {
+    data: AFSEntry[];
+    message?: string;
+    context?: any;
 }
 export interface AFSSearchOptions {
     limit?: number;
     caseSensitive?: boolean;
+    context?: any;
+}
+export interface AFSSearchResult {
+    data: AFSEntry[];
+    message?: string;
+}
+export interface AFSReadOptions {
+    context?: any;
+}
+export interface AFSReadResult {
+    data?: AFSEntry;
+    message?: string;
 }
 export interface AFSDeleteOptions {
     recursive?: boolean;
+    context?: any;
+}
+export interface AFSDeleteResult {
+    message?: string;
 }
 export interface AFSRenameOptions {
     overwrite?: boolean;
+    context?: any;
+}
+export interface AFSRenameResult {
+    message?: string;
 }
 export interface AFSWriteOptions {
     append?: boolean;
+    context?: any;
+}
+export interface AFSWriteResult {
+    data: AFSEntry;
+    message?: string;
+    context?: any;
 }
 export interface AFSWriteEntryPayload extends Omit<AFSEntry, "id" | "path"> {
 }
+export interface AFSExecOptions {
+    context: any;
+}
+export interface AFSExecResult {
+    data: Record<string, any>;
+}
 export interface AFSModule {
     readonly name: string;
     readonly description?: string;
     onMount?(root: AFSRoot): void;
-    list?(path: string, options?: AFSListOptions): Promise<{
-        list: AFSEntry[];
-        message?: string;
-    }>;
-    read?(path: string): Promise<{
-        result?: AFSEntry;
-        message?: string;
-    }>;
-    write?(path: string, content: AFSWriteEntryPayload, options?: AFSWriteOptions): Promise<{
-        result: AFSEntry;
-        message?: string;
-    }>;
-    delete?(path: string, options?: AFSDeleteOptions): Promise<{
-        message?: string;
-    }>;
-    rename?(oldPath: string, newPath: string, options?: AFSRenameOptions): Promise<{
-        message?: string;
-    }>;
-    search?(path: string, query: string, options?: AFSSearchOptions): Promise<{
-        list: AFSEntry[];
-        message?: string;
-    }>;
-    exec?(path: string, args: Record<string, any>, options: {
-        context: any;
-    }): Promise<{
-        result: Record<string, any>;
-    }>;
+    list?(path: string, options?: AFSListOptions): Promise<AFSListResult>;
+    read?(path: string, options?: AFSReadOptions): Promise<AFSReadResult>;
+    write?(path: string, content: AFSWriteEntryPayload, options?: AFSWriteOptions): Promise<AFSWriteResult>;
+    delete?(path: string, options?: AFSDeleteOptions): Promise<AFSDeleteResult>;
+    rename?(oldPath: string, newPath: string, options?: AFSRenameOptions): Promise<AFSRenameResult>;
+    search?(path: string, query: string, options?: AFSSearchOptions): Promise<AFSSearchResult>;
+    exec?(path: string, args: Record<string, any>, options: AFSExecOptions): Promise<AFSExecResult>;
 }
 export type AFSRootEvents = {
     agentSucceed: [{
@@ -65,7 +90,21 @@ export type AFSRootEvents = {
         entry: AFSEntry;
     }];
 };
+export interface AFSRootListOptions extends AFSListOptions, AFSContextPreset {
+    preset?: string;
+}
+export interface AFSRootListResult extends Omit<AFSListResult, "data"> {
+    data: any;
+}
+export interface AFSRootSearchOptions extends AFSSearchOptions, AFSContextPreset {
+    preset?: string;
+}
+export interface AFSRootSearchResult extends Omit<AFSSearchResult, "data"> {
+    data: any;
+}
 export interface AFSRoot extends Emitter<AFSRootEvents>, AFSModule {
+    list(path: string, options?: AFSRootListOptions): Promise<AFSRootListResult>;
+    search(path: string, query: string, options: AFSRootSearchOptions): Promise<AFSRootSearchResult>;
 }
 export interface AFSEntryMetadata extends Record<string, any> {
     execute?: {
@@ -75,6 +114,7 @@ export interface AFSEntryMetadata extends Record<string, any> {
         outputSchema?: Record<string, any>;
     };
     childrenCount?: number;
+    childrenTruncated?: boolean;
 }
 export interface AFSEntry<T = any> {
     id: string;
@@ -89,3 +129,42 @@ export interface AFSEntry<T = any> {
     linkTo?: string | null;
     content?: T;
 }
+export declare const afsEntrySchema: ZodType<AFSEntry>;
+export interface AFSContextPreset {
+    /**
+     * The view template for presenting the search results.
+     */
+    view?: string;
+    select?: AFSContextPresetOptionAgent<{
+        path: string;
+        query?: string;
+    }, {
+        data: string[];
+    }>;
+    per?: AFSContextPresetOptionAgent<{
+        data: AFSEntry;
+    }, {
+        data: unknown;
+    }>;
+    dedupe?: AFSContextPresetOptionAgent<{
+        data: unknown[];
+    }, {
+        data: unknown;
+    }>;
+    format?: "default" | "tree" | AFSContextPresetOptionAgent<{
+        data: unknown;
+    }, {
+        data: unknown;
+    }>;
+}
+export interface AFSContextPresetOptionAgent<I = any, O = any> {
+    invoke(input: I, options?: any): Promise<O>;
+}
+export interface AFSContext {
+    search?: {
+        presets?: Record<string, AFSContextPreset>;
+    };
+    list?: {
+        presets?: Record<string, AFSContextPreset>;
+    };
+}

package/lib/esm/afs.d.ts

@@ -1,9 +1,11 @@
 import { Emitter } from "strict-event-emitter";
-import type { AFSDeleteOptions, AFSEntry, AFSListOptions, AFSModule, AFSRenameOptions, AFSRoot, AFSRootEvents, AFSSearchOptions, AFSWriteEntryPayload, AFSWriteOptions } from "./type.js";
+import { type AFSContext, type AFSDeleteOptions, type AFSDeleteResult, type AFSExecOptions, type AFSExecResult, type AFSModule, type AFSReadOptions, type AFSReadResult, type AFSRenameOptions, type AFSRenameResult, type AFSRoot, type AFSRootEvents, type AFSRootListOptions, type AFSRootListResult, type AFSRootSearchOptions, type AFSRootSearchResult, type AFSWriteEntryPayload, type AFSWriteOptions, type AFSWriteResult } from "./type.js";
 export interface AFSOptions {
     modules?: AFSModule[];
+    context?: AFSContext;
 }
 export declare class AFS extends Emitter<AFSRootEvents> implements AFSRoot {
+    options: AFSOptions;
     name: string;
     constructor(options?: AFSOptions);
     private modules;
@@ -14,32 +16,17 @@ export declare class AFS extends Emitter<AFSRootEvents> implements AFSRoot {
         description?: string;
         module: AFSModule;
     }[]>;
-    list(path: string, options?: AFSListOptions): Promise<{
-        list: AFSEntry[];
-        message?: string;
-    }>;
-    read(path: string): Promise<{
-        result?: AFSEntry;
-        message?: string;
-    }>;
-    write(path: string, content: AFSWriteEntryPayload, options?: AFSWriteOptions): Promise<{
-        result: AFSEntry;
-        message?: string;
-    }>;
-    delete(path: string, options?: AFSDeleteOptions): Promise<{
-        message?: string;
-    }>;
-    rename(oldPath: string, newPath: string, options?: AFSRenameOptions): Promise<{
-        message?: string;
-    }>;
-    search(path: string, query: string, options?: AFSSearchOptions): Promise<{
-        list: AFSEntry[];
-        message?: string;
-    }>;
+    list(path: string, options?: AFSRootListOptions): Promise<AFSRootListResult>;
+    private _list;
+    read(path: string, _options?: AFSReadOptions): Promise<AFSReadResult>;
+    write(path: string, content: AFSWriteEntryPayload, options?: AFSWriteOptions): Promise<AFSWriteResult>;
+    delete(path: string, options?: AFSDeleteOptions): Promise<AFSDeleteResult>;
+    rename(oldPath: string, newPath: string, options?: AFSRenameOptions): Promise<AFSRenameResult>;
+    search(path: string, query: string, options?: AFSRootSearchOptions): Promise<AFSRootSearchResult>;
+    private processWithPreset;
+    private _select;
+    private _search;
     private findModules;
-    exec(path: string, args: Record<string, any>, options: {
-        context: any;
-    }): Promise<{
-        result: Record<string, any>;
-    }>;
+    exec(path: string, args: Record<string, any>, options: AFSExecOptions): Promise<AFSExecResult>;
+    private buildTreeView;
 }

package/lib/esm/afs.js

@@ -1,11 +1,15 @@
 import { Emitter } from "strict-event-emitter";
 import { joinURL } from "ufo";
+import { z } from "zod";
+import { afsEntrySchema, } from "./type.js";
 const DEFAULT_MAX_DEPTH = 1;
 const MODULES_ROOT_DIR = "/modules";
 export class AFS extends Emitter {
+    options;
     name = "AFSRoot";
-    constructor(options) {
+    constructor(options = {}) {
         super();
+        this.options = options;
         for (const module of options?.modules ?? []) {
             this.mount(module);
         }
@@ -32,12 +36,20 @@ export class AFS extends Emitter {
             module,
         }));
     }
-    async list(path, options) {
-        const maxDepth = options?.maxDepth ?? DEFAULT_MAX_DEPTH;
-        if (!(maxDepth >= 0))
-            throw new Error(`Invalid maxDepth: ${maxDepth}`);
+    async list(path, options = {}) {
+        let preset;
+        if (options.preset) {
+            preset = this.options?.context?.list?.presets?.[options.preset];
+            if (!preset)
+                throw new Error(`Preset not found: ${options.preset}`);
+        }
+        return await this.processWithPreset(path, undefined, preset, {
+            ...options,
+            defaultSelect: () => this._list(path, options),
+        });
+    }
+    async _list(path, options = {}) {
         const results = [];
-        const messages = [];
         const matches = this.findModules(path, options);
         for (const matched of matches) {
             const moduleEntry = {
@@ -52,12 +64,12 @@ export class AFS extends Emitter {
             if (!matched.module.list)
                 continue;
             try {
-                const { list, message } = await matched.module.list(matched.subpath, {
+                const { data } = await matched.module.list(matched.subpath, {
                     ...options,
                     maxDepth: matched.maxDepth,
                 });
-                if (list.length) {
-                    results.push(...list.map((entry) => ({
+                if (data.length) {
+                    results.push(...data.map((entry) => ({
                         ...entry,
                         path: joinURL(matched.modulePath, entry.path),
                     })));
@@ -65,30 +77,28 @@ export class AFS extends Emitter {
                 else {
                     results.push(moduleEntry);
                 }
-                if (message)
-                    messages.push(message);
             }
             catch (error) {
                 console.error(`Error listing from module at ${matched.modulePath}`, error);
             }
         }
-        return { list: results, message: messages.join("; ").trim() || undefined };
+        return { data: results };
     }
-    async read(path) {
+    async read(path, _options) {
         const modules = this.findModules(path, { exactMatch: true });
         for (const { module, modulePath, subpath } of modules) {
             const res = await module.read?.(subpath);
-            if (res?.result) {
+            if (res?.data) {
                 return {
                     ...res,
-                    result: {
-                        ...res.result,
-                        path: joinURL(modulePath, res.result.path),
+                    data: {
+                        ...res.data,
+                        path: joinURL(modulePath, res.data.path),
                     },
                 };
             }
         }
-        return { result: undefined, message: "File not found" };
+        return { data: undefined, message: "File not found" };
     }
     async write(path, content, options) {
         const module = this.findModules(path, { exactMatch: true })[0];
@@ -97,9 +107,9 @@ export class AFS extends Emitter {
         const res = await module.module.write(module.subpath, content, options);
         return {
             ...res,
-            result: {
-                ...res.result,
-                path: joinURL(module.modulePath, res.result.path),
+            data: {
+                ...res.data,
+                path: joinURL(module.modulePath, res.data.path),
             },
         };
     }
@@ -121,15 +131,59 @@ export class AFS extends Emitter {
         }
         return await oldModule.module.rename(oldModule.subpath, newModule.subpath, options);
     }
-    async search(path, query, options) {
+    async search(path, query, options = {}) {
+        let preset;
+        if (options.preset) {
+            preset = this.options?.context?.search?.presets?.[options.preset];
+            if (!preset)
+                throw new Error(`Preset not found: ${options.preset}`);
+        }
+        return await this.processWithPreset(path, query, preset, {
+            ...options,
+            defaultSelect: () => this._search(path, query, options),
+        });
+    }
+    async processWithPreset(path, query, preset, options) {
+        const select = options.select || preset?.select;
+        const per = options.per || preset?.per;
+        const dedupe = options.dedupe || preset?.dedupe;
+        const format = options.format || preset?.format;
+        const entries = select
+            ? (await this._select(path, query, select, options)).data
+            : (await options.defaultSelect()).data;
+        const mapped = per
+            ? await Promise.all(entries.map((data) => per.invoke({ data }, options).then((res) => res.data)))
+            : entries;
+        const deduped = dedupe
+            ? await dedupe.invoke({ data: mapped }, options).then((res) => res.data)
+            : mapped;
+        let formatted = deduped;
+        if (format === "tree") {
+            const valid = z.array(afsEntrySchema).safeParse(deduped);
+            if (valid.data)
+                formatted = this.buildTreeView(valid.data);
+            else
+                throw new Error("Tree format requires entries to be AFSEntry objects");
+        }
+        else if (typeof format === "object" && typeof format.invoke === "function") {
+            formatted = await format.invoke({ data: deduped }, options).then((res) => res.data);
+        }
+        return { data: formatted };
+    }
+    async _select(path, query, select, options) {
+        const { data } = await select.invoke({ path, query }, options);
+        const results = (await Promise.all(data.map((p) => this.read(p).then((res) => res.data)))).filter((i) => !!i);
+        return { data: results };
+    }
+    async _search(path, query, options) {
         const results = [];
         const messages = [];
         for (const { module, modulePath, subpath } of this.findModules(path)) {
             if (!module.search)
                 continue;
             try {
-                const { list, message } = await module.search(subpath, query, options);
-                results.push(...list.map((entry) => ({
+                const { data, message } = await module.search(subpath, query, options);
+                results.push(...data.map((entry) => ({
                     ...entry,
                     path: joinURL(modulePath, entry.path),
                 })));
@@ -140,7 +194,7 @@ export class AFS extends Emitter {
                 console.error(`Error searching in module at ${modulePath}`, error);
             }
         }
-        return { list: results, message: messages.join("; ") };
+        return { data: results, message: messages.join("; ") };
     }
     findModules(path, options) {
         const maxDepth = Math.max(options?.maxDepth ?? DEFAULT_MAX_DEPTH, 1);
@@ -176,4 +230,49 @@ export class AFS extends Emitter {
             throw new Error(`No module found for path: ${path}`);
         return await module.module.exec(module.subpath, args, options);
     }
+    buildTreeView(entries) {
+        const tree = {};
+        const entryMap = new Map();
+        for (const entry of entries) {
+            entryMap.set(entry.path, entry);
+            const parts = entry.path.split("/").filter(Boolean);
+            let current = tree;
+            for (const part of parts) {
+                if (!current[part]) {
+                    current[part] = {};
+                }
+                current = current[part];
+            }
+        }
+        const renderTree = (node, prefix = "", currentPath = "") => {
+            let result = "";
+            const keys = Object.keys(node);
+            keys.forEach((key, index) => {
+                const isLast = index === keys.length - 1;
+                const fullPath = currentPath ? `${currentPath}/${key}` : `/${key}`;
+                const entry = entryMap.get(fullPath);
+                // Build metadata suffix
+                const metadataParts = [];
+                // Children count
+                const childrenCount = entry?.metadata?.childrenCount;
+                if (typeof childrenCount === "number") {
+                    metadataParts.push(`${childrenCount} items`);
+                }
+                // Children truncated
+                if (entry?.metadata?.childrenTruncated) {
+                    metadataParts.push("truncated");
+                }
+                // Executable
+                if (entry?.metadata?.execute) {
+                    metadataParts.push("executable");
+                }
+                const metadataSuffix = metadataParts.length > 0 ? ` [${metadataParts.join(", ")}]` : "";
+                result += `${prefix}${isLast ? "└── " : "├── "}${key}${metadataSuffix}`;
+                result += `\n`;
+                result += renderTree(node[key], `${prefix}${isLast ? "    " : "│   "}`, fullPath);
+            });
+            return result;
+        };
+        return renderTree(tree);
+    }
 }

package/lib/esm/type.d.ts

@@ -1,60 +1,85 @@
 import type { Emitter } from "strict-event-emitter";
+import { type ZodType } from "zod";
 export interface AFSListOptions {
     filter?: {
         userId?: string;
         sessionId?: string;
     };
-    recursive?: boolean;
     maxDepth?: number;
     limit?: number;
     orderBy?: [string, "asc" | "desc"][];
+    maxChildren?: number;
+    onOverflow?: "truncate";
+    /**
+     * Whether to disable .gitignore files when listing files.
+     * @default false
+     */
+    disableGitignore?: boolean;
+    context?: any;
+}
+export interface AFSListResult {
+    data: AFSEntry[];
+    message?: string;
+    context?: any;
 }
 export interface AFSSearchOptions {
     limit?: number;
     caseSensitive?: boolean;
+    context?: any;
+}
+export interface AFSSearchResult {
+    data: AFSEntry[];
+    message?: string;
+}
+export interface AFSReadOptions {
+    context?: any;
+}
+export interface AFSReadResult {
+    data?: AFSEntry;
+    message?: string;
 }
 export interface AFSDeleteOptions {
     recursive?: boolean;
+    context?: any;
+}
+export interface AFSDeleteResult {
+    message?: string;
 }
 export interface AFSRenameOptions {
     overwrite?: boolean;
+    context?: any;
+}
+export interface AFSRenameResult {
+    message?: string;
 }
 export interface AFSWriteOptions {
     append?: boolean;
+    context?: any;
+}
+export interface AFSWriteResult {
+    data: AFSEntry;
+    message?: string;
+    context?: any;
 }
 export interface AFSWriteEntryPayload extends Omit<AFSEntry, "id" | "path"> {
 }
+export interface AFSExecOptions {
+    context: any;
+}
+export interface AFSExecResult {
+    data: Record<string, any>;
+}
 export interface AFSModule {
     readonly name: string;
     readonly description?: string;
     onMount?(root: AFSRoot): void;
-    list?(path: string, options?: AFSListOptions): Promise<{
-        list: AFSEntry[];
-        message?: string;
-    }>;
-    read?(path: string): Promise<{
-        result?: AFSEntry;
-        message?: string;
-    }>;
-    write?(path: string, content: AFSWriteEntryPayload, options?: AFSWriteOptions): Promise<{
-        result: AFSEntry;
-        message?: string;
-    }>;
-    delete?(path: string, options?: AFSDeleteOptions): Promise<{
-        message?: string;
-    }>;
-    rename?(oldPath: string, newPath: string, options?: AFSRenameOptions): Promise<{
-        message?: string;
-    }>;
-    search?(path: string, query: string, options?: AFSSearchOptions): Promise<{
-        list: AFSEntry[];
-        message?: string;
-    }>;
-    exec?(path: string, args: Record<string, any>, options: {
-        context: any;
-    }): Promise<{
-        result: Record<string, any>;
-    }>;
+    list?(path: string, options?: AFSListOptions): Promise<AFSListResult>;
+    read?(path: string, options?: AFSReadOptions): Promise<AFSReadResult>;
+    write?(path: string, content: AFSWriteEntryPayload, options?: AFSWriteOptions): Promise<AFSWriteResult>;
+    delete?(path: string, options?: AFSDeleteOptions): Promise<AFSDeleteResult>;
+    rename?(oldPath: string, newPath: string, options?: AFSRenameOptions): Promise<AFSRenameResult>;
+    search?(path: string, query: string, options?: AFSSearchOptions): Promise<AFSSearchResult>;
+    exec?(path: string, args: Record<string, any>, options: AFSExecOptions): Promise<AFSExecResult>;
 }
 export type AFSRootEvents = {
     agentSucceed: [{
@@ -65,7 +90,21 @@ export type AFSRootEvents = {
         entry: AFSEntry;
     }];
 };
+export interface AFSRootListOptions extends AFSListOptions, AFSContextPreset {
+    preset?: string;
+}
+export interface AFSRootListResult extends Omit<AFSListResult, "data"> {
+    data: any;
+}
+export interface AFSRootSearchOptions extends AFSSearchOptions, AFSContextPreset {
+    preset?: string;
+}
+export interface AFSRootSearchResult extends Omit<AFSSearchResult, "data"> {
+    data: any;
+}
 export interface AFSRoot extends Emitter<AFSRootEvents>, AFSModule {
+    list(path: string, options?: AFSRootListOptions): Promise<AFSRootListResult>;
+    search(path: string, query: string, options: AFSRootSearchOptions): Promise<AFSRootSearchResult>;
 }
 export interface AFSEntryMetadata extends Record<string, any> {
     execute?: {
@@ -75,6 +114,7 @@ export interface AFSEntryMetadata extends Record<string, any> {
         outputSchema?: Record<string, any>;
     };
     childrenCount?: number;
+    childrenTruncated?: boolean;
 }
 export interface AFSEntry<T = any> {
     id: string;
@@ -89,3 +129,42 @@ export interface AFSEntry<T = any> {
     linkTo?: string | null;
     content?: T;
 }
+export declare const afsEntrySchema: ZodType<AFSEntry>;
+export interface AFSContextPreset {
+    /**
+     * The view template for presenting the search results.
+     */
+    view?: string;
+    select?: AFSContextPresetOptionAgent<{
+        path: string;
+        query?: string;
+    }, {
+        data: string[];
+    }>;
+    per?: AFSContextPresetOptionAgent<{
+        data: AFSEntry;
+    }, {
+        data: unknown;
+    }>;
+    dedupe?: AFSContextPresetOptionAgent<{
+        data: unknown[];
+    }, {
+        data: unknown;
+    }>;
+    format?: "default" | "tree" | AFSContextPresetOptionAgent<{
+        data: unknown;
+    }, {
+        data: unknown;
+    }>;
+}
+export interface AFSContextPresetOptionAgent<I = any, O = any> {
+    invoke(input: I, options?: any): Promise<O>;
+}
+export interface AFSContext {
+    search?: {
+        presets?: Record<string, AFSContextPreset>;
+    };
+    list?: {
+        presets?: Record<string, AFSContextPreset>;
+    };
+}

package/lib/esm/type.js

@@ -1 +1,14 @@
-export {};
+import { z } from "zod";
+export const afsEntrySchema = z.object({
+    id: z.string(),
+    createdAt: z.date().optional(),
+    updatedAt: z.date().optional(),
+    path: z.string(),
+    userId: z.string().nullable().optional(),
+    sessionId: z.string().nullable().optional(),
+    summary: z.string().nullable().optional(),
+    description: z.string().nullable().optional(),
+    metadata: z.record(z.any()).nullable().optional(),
+    linkTo: z.string().nullable().optional(),
+    content: z.any().optional(),
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigne/afs",
-  "version": "1.3.0",
+  "version": "1.4.0-beta.1",
   "description": "Agentic File System (AFS) is a virtual file system that supports various storage backends and provides a unified API for file operations.",
   "publishConfig": {
     "access": "public"
@@ -48,7 +48,8 @@
   },
   "dependencies": {
     "strict-event-emitter": "^0.5.1",
-    "ufo": "^1.6.1"
+    "ufo": "^1.6.1",
+    "zod": "^3.25.67"
   },
   "devDependencies": {
     "@types/bun": "^1.2.22",