@aigne/afs 1.4.0-beta.1 → 1.4.0-beta.11

package/CHANGELOG.md

@@ -1,5 +1,127 @@
 # Changelog
 
+## [1.4.0-beta.11](https://github.com/AIGNE-io/aigne-framework/compare/afs-v1.4.0-beta.10...afs-v1.4.0-beta.11) (2026-01-16)
+
+
+### Features
+
+* add Agent Skill support ([#787](https://github.com/AIGNE-io/aigne-framework/issues/787)) ([f04fbe7](https://github.com/AIGNE-io/aigne-framework/commit/f04fbe76ec24cf3c59c74adf92d87b0c3784a8f7))
+* add session compact support for AIAgent ([#863](https://github.com/AIGNE-io/aigne-framework/issues/863)) ([9010918](https://github.com/AIGNE-io/aigne-framework/commit/9010918cd3f18b02b5c60ddc9ed5c34b568d0b28))
+* **afs,bash:** add physical path mapping for AFS modules in bash execution ([#881](https://github.com/AIGNE-io/aigne-framework/issues/881)) ([50dbda2](https://github.com/AIGNE-io/aigne-framework/commit/50dbda224bd666d951494d2449779830d8db57fc))
+* **afs:** add basic AFS(AIGNE File System) support ([#505](https://github.com/AIGNE-io/aigne-framework/issues/505)) ([ac2a18a](https://github.com/AIGNE-io/aigne-framework/commit/ac2a18a82470a2f31c466f329386525eb1cdab6d))
+* **afs:** add edit/delete/rename methods for AFS ([#820](https://github.com/AIGNE-io/aigne-framework/issues/820)) ([68cb508](https://github.com/AIGNE-io/aigne-framework/commit/68cb508d1cfc9c516d56303018139f1e567f897e))
+* **afs:** add module access control and schema validation support ([#904](https://github.com/AIGNE-io/aigne-framework/issues/904)) ([d0b279a](https://github.com/AIGNE-io/aigne-framework/commit/d0b279aac07ebe2bcc1fd4148498fc3f6bbcd561))
+* **afs:** add module system fs for afs ([#594](https://github.com/AIGNE-io/aigne-framework/issues/594)) ([83c7b65](https://github.com/AIGNE-io/aigne-framework/commit/83c7b6555d21c606a5005eb05f6686882fb8ffa3))
+* **afs:** improve list behavior to always include current path ([cb91f80](https://github.com/AIGNE-io/aigne-framework/commit/cb91f80c6ea3aa6e93dde26b6feeea8689fceb48))
+* **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))
+* **core:** add session history support ([#858](https://github.com/AIGNE-io/aigne-framework/issues/858)) ([28a070e](https://github.com/AIGNE-io/aigne-framework/commit/28a070ed33b821d1fd344b899706d817ca992b9f))
+* support define agent by third library & orchestrator agent refactor ([#799](https://github.com/AIGNE-io/aigne-framework/issues/799)) ([7264b11](https://github.com/AIGNE-io/aigne-framework/commit/7264b11ab6eed787e928367f09aa08d254968d40))
+* support mount mcp agent into AFS ([#740](https://github.com/AIGNE-io/aigne-framework/issues/740)) ([6d474fc](https://github.com/AIGNE-io/aigne-framework/commit/6d474fc05845a15e2c3e8fa97727b409bdd70945))
+
+
+### Bug Fixes
+
+* **afs:** add case-sensitive option for search with case-insensitive default ([#814](https://github.com/AIGNE-io/aigne-framework/issues/814)) ([9dc9446](https://github.com/AIGNE-io/aigne-framework/commit/9dc944635104fc311e7756b4bde0a20275cfe8ec))
+* **afs:** check module existence on normalized path ([#793](https://github.com/AIGNE-io/aigne-framework/issues/793)) ([0c991bf](https://github.com/AIGNE-io/aigne-framework/commit/0c991bf0caa948ce62948986ce885b5a98437689))
+* **afs:** improve module path resolution and depth handling ([#659](https://github.com/AIGNE-io/aigne-framework/issues/659)) ([c609d4f](https://github.com/AIGNE-io/aigne-framework/commit/c609d4fc9614123afcf4b8f86b3382a613ace417))
+* **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))
+* **afs:** show gitignored files with marker instead of filtering ([c2bdea1](https://github.com/AIGNE-io/aigne-framework/commit/c2bdea155f47c9420f2fe810cdfed79ef70ef899))
+* **afs:** throw errors instead of logging in AFS module operations ([#874](https://github.com/AIGNE-io/aigne-framework/issues/874)) ([f0cc1c4](https://github.com/AIGNE-io/aigne-framework/commit/f0cc1c4056f8b95b631d595892bb12eb75da4b9f))
+* **afs:** use simple-list instead of tree as default type ([#839](https://github.com/AIGNE-io/aigne-framework/issues/839)) ([65a9a40](https://github.com/AIGNE-io/aigne-framework/commit/65a9a4054b3bdad6f7e40357299ef3dc48f7c3e4))
+* bump version ([696560f](https://github.com/AIGNE-io/aigne-framework/commit/696560fa2673eddcb4d00ac0523fbbbde7273cb3))
+* bump version ([70d217c](https://github.com/AIGNE-io/aigne-framework/commit/70d217c8360dd0dda7f5f17011c4e92ec836e801))
+* bump version ([af04b69](https://github.com/AIGNE-io/aigne-framework/commit/af04b6931951afa35d52065430acc7fef4b10087))
+* bump version ([ba7ad18](https://github.com/AIGNE-io/aigne-framework/commit/ba7ad184fcf32b49bf0507a3cb638d20fb00690d))
+* bump version ([93a1c10](https://github.com/AIGNE-io/aigne-framework/commit/93a1c10cf35f88eaafe91092481f5d087bd5b3a9))
+* improve test coverage tracking and reporting ([#903](https://github.com/AIGNE-io/aigne-framework/issues/903)) ([031144e](https://github.com/AIGNE-io/aigne-framework/commit/031144e74f29e882cffe52ffda8f7a18c76ace7f))
+
+## [1.4.0-beta.10](https://github.com/AIGNE-io/aigne-framework/compare/afs-v1.4.0-beta.9...afs-v1.4.0-beta.10) (2026-01-16)
+
+
+### Features
+
+* **afs:** improve list behavior to always include current path ([cb91f80](https://github.com/AIGNE-io/aigne-framework/commit/cb91f80c6ea3aa6e93dde26b6feeea8689fceb48))
+
+## [1.4.0-beta.9](https://github.com/AIGNE-io/aigne-framework/compare/afs-v1.4.0-beta.8...afs-v1.4.0-beta.9) (2026-01-14)
+
+
+### Features
+
+* **afs:** add module access control and schema validation support ([#904](https://github.com/AIGNE-io/aigne-framework/issues/904)) ([d0b279a](https://github.com/AIGNE-io/aigne-framework/commit/d0b279aac07ebe2bcc1fd4148498fc3f6bbcd561))
+
+
+### Bug Fixes
+
+* improve test coverage tracking and reporting ([#903](https://github.com/AIGNE-io/aigne-framework/issues/903)) ([031144e](https://github.com/AIGNE-io/aigne-framework/commit/031144e74f29e882cffe52ffda8f7a18c76ace7f))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @aigne/platform-helpers bumped to 0.6.7-beta.2
+
+## [1.4.0-beta.8](https://github.com/AIGNE-io/aigne-framework/compare/afs-v1.4.0-beta.7...afs-v1.4.0-beta.8) (2026-01-12)
+
+
+### Bug Fixes
+
+* **afs:** show gitignored files with marker instead of filtering ([c2bdea1](https://github.com/AIGNE-io/aigne-framework/commit/c2bdea155f47c9420f2fe810cdfed79ef70ef899))
+
+## [1.4.0-beta.7](https://github.com/AIGNE-io/aigne-framework/compare/afs-v1.4.0-beta.6...afs-v1.4.0-beta.7) (2026-01-08)
+
+
+### Features
+
+* **afs,bash:** add physical path mapping for AFS modules in bash execution ([#881](https://github.com/AIGNE-io/aigne-framework/issues/881)) ([50dbda2](https://github.com/AIGNE-io/aigne-framework/commit/50dbda224bd666d951494d2449779830d8db57fc))
+
+
+### Bug Fixes
+
+* bump version ([696560f](https://github.com/AIGNE-io/aigne-framework/commit/696560fa2673eddcb4d00ac0523fbbbde7273cb3))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @aigne/platform-helpers bumped to 0.6.7-beta.1
+
+## [1.4.0-beta.6](https://github.com/AIGNE-io/aigne-framework/compare/afs-v1.4.0-beta.5...afs-v1.4.0-beta.6) (2026-01-06)
+
+
+### Bug Fixes
+
+* **afs:** throw errors instead of logging in AFS module operations ([#874](https://github.com/AIGNE-io/aigne-framework/issues/874)) ([f0cc1c4](https://github.com/AIGNE-io/aigne-framework/commit/f0cc1c4056f8b95b631d595892bb12eb75da4b9f))
+
+## [1.4.0-beta.5](https://github.com/AIGNE-io/aigne-framework/compare/afs-v1.4.0-beta.4...afs-v1.4.0-beta.5) (2025-12-31)
+
+
+### Features
+
+* add session compact support for AIAgent ([#863](https://github.com/AIGNE-io/aigne-framework/issues/863)) ([9010918](https://github.com/AIGNE-io/aigne-framework/commit/9010918cd3f18b02b5c60ddc9ed5c34b568d0b28))
+
+## [1.4.0-beta.4](https://github.com/AIGNE-io/aigne-framework/compare/afs-v1.4.0-beta.3...afs-v1.4.0-beta.4) (2025-12-26)
+
+
+### Features
+
+* **core:** add session history support ([#858](https://github.com/AIGNE-io/aigne-framework/issues/858)) ([28a070e](https://github.com/AIGNE-io/aigne-framework/commit/28a070ed33b821d1fd344b899706d817ca992b9f))
+
+## [1.4.0-beta.3](https://github.com/AIGNE-io/aigne-framework/compare/afs-v1.4.0-beta.2...afs-v1.4.0-beta.3) (2025-12-24)
+
+
+### Features
+
+* add Agent Skill support ([#787](https://github.com/AIGNE-io/aigne-framework/issues/787)) ([f04fbe7](https://github.com/AIGNE-io/aigne-framework/commit/f04fbe76ec24cf3c59c74adf92d87b0c3784a8f7))
+
+## [1.4.0-beta.2](https://github.com/AIGNE-io/aigne-framework/compare/afs-v1.4.0-beta.1...afs-v1.4.0-beta.2) (2025-12-19)
+
+
+### Bug Fixes
+
+* **afs:** use simple-list instead of tree as default type ([#839](https://github.com/AIGNE-io/aigne-framework/issues/839)) ([65a9a40](https://github.com/AIGNE-io/aigne-framework/commit/65a9a4054b3bdad6f7e40357299ef3dc48f7c3e4))
+
 ## [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)
 
 

package/lib/cjs/afs.d.ts

@@ -9,6 +9,11 @@ export declare class AFS extends Emitter<AFSRootEvents> implements AFSRoot {
     name: string;
     constructor(options?: AFSOptions);
     private modules;
+    /**
+     * Check if write operations are allowed for the given module.
+     * Throws AFSReadonlyError if not allowed.
+     */
+    private checkWritePermission;
     mount(module: AFSModule): this;
     listModules(): Promise<{
         name: string;
@@ -28,5 +33,10 @@ export declare class AFS extends Emitter<AFSRootEvents> implements AFSRoot {
     private _search;
     private findModules;
     exec(path: string, args: Record<string, any>, options: AFSExecOptions): Promise<AFSExecResult>;
+    private buildSimpleListView;
     private buildTreeView;
+    private buildMetadataSuffix;
+    private physicalPath?;
+    initializePhysicalPath(): Promise<string>;
+    cleanupPhysicalPath(): Promise<void>;
 }

package/lib/cjs/afs.js

@@ -1,9 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AFS = void 0;
+const index_js_1 = require("@aigne/platform-helpers/nodejs/index.js");
+const uuid_1 = require("@aigne/uuid");
 const strict_event_emitter_1 = require("strict-event-emitter");
 const ufo_1 = require("ufo");
 const zod_1 = require("zod");
+const error_js_1 = require("./error.js");
 const type_js_1 = require("./type.js");
 const DEFAULT_MAX_DEPTH = 1;
 const MODULES_ROOT_DIR = "/modules";
@@ -18,12 +21,22 @@ class AFS extends strict_event_emitter_1.Emitter {
         }
     }
     modules = new Map();
+    /**
+     * Check if write operations are allowed for the given module.
+     * Throws AFSReadonlyError if not allowed.
+     */
+    checkWritePermission(module, operation, path) {
+        // Module-level readonly (undefined means readonly by default)
+        if (module.accessMode !== "readwrite") {
+            throw new error_js_1.AFSReadonlyError(`Module '${module.name}' is readonly, cannot perform ${operation} to ${path}`);
+        }
+    }
     mount(module) {
-        let path = (0, ufo_1.joinURL)("/", module.name);
-        if (!/^\/[^/]+$/.test(path)) {
-            throw new Error(`Invalid mount path: ${path}. Must start with '/' and contain no other '/'`);
+        // Validate module name (should not contain '/')
+        if (module.name.includes("/")) {
+            throw new Error(`Invalid module name: ${module.name}. Module name must not contain '/'`);
         }
-        path = (0, ufo_1.joinURL)(MODULES_ROOT_DIR, path);
+        const path = (0, ufo_1.joinURL)(MODULES_ROOT_DIR, module.name);
         if (this.modules.has(path)) {
             throw new Error(`Module already mounted at path: ${path}`);
         }
@@ -53,14 +66,36 @@ class AFS extends strict_event_emitter_1.Emitter {
     }
     async _list(path, options = {}) {
         const results = [];
+        // Special case: listing root "/" should return /modules directory
+        if (path === "/" && this.modules.size > 0) {
+            const maxDepth = options?.maxDepth ?? DEFAULT_MAX_DEPTH;
+            // Always include /modules directory first
+            results.push({
+                id: "modules",
+                path: MODULES_ROOT_DIR,
+                summary: "All mounted modules",
+            });
+            if (maxDepth === 1) {
+                // Only show /modules directory
+                return { data: results };
+            }
+            // For maxDepth > 1, also get children of /modules with reduced depth
+            const childrenResult = await this._list(MODULES_ROOT_DIR, {
+                ...options,
+                maxDepth: maxDepth - 1,
+            });
+            results.push(...childrenResult.data);
+            return { data: results };
+        }
         const matches = this.findModules(path, options);
         for (const matched of matches) {
-            const moduleEntry = {
-                id: matched.module.name,
-                path: matched.remainedModulePath,
-                summary: matched.module.description,
-            };
             if (matched.maxDepth === 0) {
+                // When maxDepth is 0, show the module entry
+                const moduleEntry = {
+                    id: matched.module.name,
+                    path: matched.modulePath,
+                    summary: matched.module.description,
+                };
                 results.push(moduleEntry);
                 continue;
             }
@@ -71,18 +106,16 @@ class AFS extends strict_event_emitter_1.Emitter {
                     ...options,
                     maxDepth: matched.maxDepth,
                 });
-                if (data.length) {
-                    results.push(...data.map((entry) => ({
-                        ...entry,
-                        path: (0, ufo_1.joinURL)(matched.modulePath, entry.path),
-                    })));
-                }
-                else {
-                    results.push(moduleEntry);
-                }
+                const children = data.map((entry) => ({
+                    ...entry,
+                    path: (0, ufo_1.joinURL)(matched.modulePath, entry.path),
+                }));
+                // Always include all nodes (including the current path itself)
+                // This ensures consistent behavior across all listing scenarios
+                results.push(...children);
             }
             catch (error) {
-                console.error(`Error listing from module at ${matched.modulePath}`, error);
+                throw new Error(`Error listing from module at ${matched.modulePath}: ${error.message}`);
             }
         }
         return { data: results };
@@ -107,6 +140,7 @@ class AFS extends strict_event_emitter_1.Emitter {
         const module = this.findModules(path, { exactMatch: true })[0];
         if (!module?.module.write)
             throw new Error(`No module found for path: ${path}`);
+        this.checkWritePermission(module.module, "write", path);
         const res = await module.module.write(module.subpath, content, options);
         return {
             ...res,
@@ -120,6 +154,7 @@ class AFS extends strict_event_emitter_1.Emitter {
         const module = this.findModules(path, { exactMatch: true })[0];
         if (!module?.module.delete)
             throw new Error(`No module found for path: ${path}`);
+        this.checkWritePermission(module.module, "delete", path);
         return await module.module.delete(module.subpath, options);
     }
     async rename(oldPath, newPath, options) {
@@ -132,6 +167,7 @@ class AFS extends strict_event_emitter_1.Emitter {
         if (!oldModule.module.rename) {
             throw new Error(`Module does not support rename operation: ${oldModule.modulePath}`);
         }
+        this.checkWritePermission(oldModule.module, "rename", oldPath);
         return await oldModule.module.rename(oldModule.subpath, newModule.subpath, options);
     }
     async search(path, query, options = {}) {
@@ -161,12 +197,14 @@ class AFS extends strict_event_emitter_1.Emitter {
             ? await dedupe.invoke({ data: mapped }, options).then((res) => res.data)
             : mapped;
         let formatted = deduped;
-        if (format === "tree") {
+        if (format === "simple-list" || format === "tree") {
             const valid = zod_1.z.array(type_js_1.afsEntrySchema).safeParse(deduped);
-            if (valid.data)
-                formatted = this.buildTreeView(valid.data);
-            else
+            if (!valid.data)
                 throw new Error("Tree format requires entries to be AFSEntry objects");
+            if (format === "tree")
+                formatted = this.buildTreeView(valid.data);
+            else if (format === "simple-list")
+                formatted = this.buildSimpleListView(valid.data);
         }
         else if (typeof format === "object" && typeof format.invoke === "function") {
             formatted = await format.invoke({ data: deduped }, options).then((res) => res.data);
@@ -194,7 +232,7 @@ class AFS extends strict_event_emitter_1.Emitter {
                     messages.push(message);
             }
             catch (error) {
-                console.error(`Error searching in module at ${modulePath}`, error);
+                throw new Error(`Error searching in module at ${modulePath}: ${error.message}`);
             }
         }
         return { data: results, message: messages.join("; ") };
@@ -233,6 +271,9 @@ 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);
     }
+    buildSimpleListView(entries) {
+        return entries.map((entry) => `${entry.path}${this.buildMetadataSuffix(entry)}`);
+    }
     buildTreeView(entries) {
         const tree = {};
         const entryMap = new Map();
@@ -254,23 +295,7 @@ class AFS extends strict_event_emitter_1.Emitter {
                 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 += `${prefix}${isLast ? "└── " : "├── "}${key}${entry ? this.buildMetadataSuffix(entry) : ""}`;
                 result += `\n`;
                 result += renderTree(node[key], `${prefix}${isLast ? "    " : "│   "}`, fullPath);
             });
@@ -278,5 +303,48 @@ class AFS extends strict_event_emitter_1.Emitter {
         };
         return renderTree(tree);
     }
+    buildMetadataSuffix(entry) {
+        // 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");
+        }
+        // Gitignored
+        if (entry?.metadata?.gitignored) {
+            metadataParts.push("gitignored");
+        }
+        // Executable
+        if (entry?.metadata?.execute) {
+            metadataParts.push("executable");
+        }
+        const metadataSuffix = metadataParts.length > 0 ? ` [${metadataParts.join(", ")}]` : "";
+        return metadataSuffix;
+    }
+    physicalPath;
+    async initializePhysicalPath() {
+        this.physicalPath ??= (async () => {
+            const rootDir = index_js_1.nodejs.path.join(index_js_1.nodejs.os.tmpdir(), (0, uuid_1.v7)());
+            await index_js_1.nodejs.fs.mkdir(rootDir, { recursive: true });
+            for (const [modulePath, module] of this.modules) {
+                const physicalModulePath = index_js_1.nodejs.path.join(rootDir, modulePath);
+                await index_js_1.nodejs.fs.mkdir(index_js_1.nodejs.path.dirname(physicalModulePath), { recursive: true });
+                await module.symlinkToPhysical?.(physicalModulePath);
+            }
+            return rootDir;
+        })();
+        return this.physicalPath;
+    }
+    async cleanupPhysicalPath() {
+        if (this.physicalPath) {
+            await index_js_1.nodejs.fs.rm(await this.physicalPath, { recursive: true, force: true });
+            this.physicalPath = undefined;
+        }
+    }
 }
 exports.AFS = AFS;

package/lib/cjs/error.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Base error class for all AFS errors.
+ */
+export declare class AFSError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+/**
+ * Error thrown when attempting write operations on a readonly AFS or module.
+ */
+export declare class AFSReadonlyError extends AFSError {
+    constructor(message: string);
+}

package/lib/cjs/error.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AFSReadonlyError = exports.AFSError = void 0;
+/**
+ * Base error class for all AFS errors.
+ */
+class AFSError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.name = "AFSError";
+        this.code = code;
+    }
+}
+exports.AFSError = AFSError;
+/**
+ * Error thrown when attempting write operations on a readonly AFS or module.
+ */
+class AFSReadonlyError extends AFSError {
+    constructor(message) {
+        super(message, "AFS_READONLY");
+        this.name = "AFSReadonlyError";
+    }
+}
+exports.AFSReadonlyError = AFSReadonlyError;

package/lib/cjs/index.d.ts

@@ -1,2 +1,3 @@
 export * from "./afs.js";
+export * from "./error.js";
 export * from "./type.js";

package/lib/cjs/index.js

@@ -15,4 +15,5 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./afs.js"), exports);
+__exportStar(require("./error.js"), exports);
 __exportStar(require("./type.js"), exports);

package/lib/cjs/type.d.ts

@@ -1,9 +1,26 @@
 import type { Emitter } from "strict-event-emitter";
-import { type ZodType } from "zod";
-export interface AFSListOptions {
+import { type ZodType, z } from "zod";
+/**
+ * Access mode for AFS modules and root.
+ * - "readonly": Only read operations are allowed (list, read, search)
+ * - "readwrite": All operations are allowed
+ */
+export type AFSAccessMode = "readonly" | "readwrite";
+/**
+ * Zod schema for access mode validation.
+ * Can be reused across modules that support access mode configuration.
+ */
+export declare const accessModeSchema: z.ZodOptional<z.ZodEnum<["readonly", "readwrite"]>>;
+export interface AFSOperationOptions {
+    context?: any;
+}
+export interface AFSListOptions extends AFSOperationOptions {
     filter?: {
+        agentId?: string;
         userId?: string;
         sessionId?: string;
+        before?: string;
+        after?: string;
     };
     maxDepth?: number;
     limit?: number;
@@ -15,46 +32,45 @@ export interface AFSListOptions {
      * @default false
      */
     disableGitignore?: boolean;
-    context?: any;
+    /**
+     * Glob pattern to filter entries by path.
+     * Examples: "*.ts", "**\/*.js", "src/**\/*.{ts,tsx}"
+     */
+    pattern?: string;
 }
 export interface AFSListResult {
     data: AFSEntry[];
     message?: string;
-    context?: any;
 }
-export interface AFSSearchOptions {
+export interface AFSSearchOptions extends AFSOperationOptions {
     limit?: number;
     caseSensitive?: boolean;
-    context?: any;
 }
 export interface AFSSearchResult {
     data: AFSEntry[];
     message?: string;
 }
-export interface AFSReadOptions {
-    context?: any;
+export interface AFSReadOptions extends AFSOperationOptions {
+    filter?: AFSListOptions["filter"];
 }
 export interface AFSReadResult {
     data?: AFSEntry;
     message?: string;
 }
-export interface AFSDeleteOptions {
+export interface AFSDeleteOptions extends AFSOperationOptions {
     recursive?: boolean;
-    context?: any;
 }
 export interface AFSDeleteResult {
     message?: string;
 }
-export interface AFSRenameOptions {
+export interface AFSRenameOptions extends AFSOperationOptions {
     overwrite?: boolean;
-    context?: any;
 }
 export interface AFSRenameResult {
     message?: string;
 }
-export interface AFSWriteOptions {
+export interface AFSWriteOptions extends AFSOperationOptions {
     append?: boolean;
-    context?: any;
 }
 export interface AFSWriteResult {
     data: AFSEntry;
@@ -63,8 +79,7 @@ export interface AFSWriteResult {
 }
 export interface AFSWriteEntryPayload extends Omit<AFSEntry, "id" | "path"> {
 }
-export interface AFSExecOptions {
-    context: any;
+export interface AFSExecOptions extends AFSOperationOptions {
 }
 export interface AFSExecResult {
     data: Record<string, any>;
@@ -72,7 +87,21 @@ export interface AFSExecResult {
 export interface AFSModule {
     readonly name: string;
     readonly description?: string;
+    /**
+     * Access mode for this module.
+     * - "readonly": Only read operations are allowed
+     * - "readwrite": All operations are allowed
+     * Default behavior is implementation-specific.
+     */
+    readonly accessMode?: AFSAccessMode;
+    /**
+     * Enable automatic agent skill scanning for this module.
+     * When set to true, the system will scan this module for agent skills.
+     * @default false
+     */
+    readonly agentSkills?: boolean;
     onMount?(root: AFSRoot): void;
+    symlinkToPhysical?(path: string): Promise<void>;
     list?(path: string, options?: AFSListOptions): Promise<AFSListResult>;
     read?(path: string, options?: AFSReadOptions): Promise<AFSReadResult>;
     write?(path: string, content: AFSWriteEntryPayload, options?: AFSWriteOptions): Promise<AFSWriteResult>;
@@ -81,14 +110,53 @@ export interface AFSModule {
     search?(path: string, query: string, options?: AFSSearchOptions): Promise<AFSSearchResult>;
     exec?(path: string, args: Record<string, any>, options: AFSExecOptions): Promise<AFSExecResult>;
 }
+/**
+ * Parameters for loading a module from configuration.
+ */
+export interface AFSModuleLoadParams {
+    /** Path to the configuration file */
+    filepath: string;
+    /** Parsed configuration object */
+    parsed?: object;
+}
+/**
+ * Interface for module classes that support schema validation and loading from configuration.
+ * This describes the static part of a module class.
+ *
+ * @example
+ * ```typescript
+ * class MyModule implements AFSModule {
+ *   static schema() { return mySchema; }
+ *   static async load(params: AFSModuleLoadParams) { ... }
+ *   // ...
+ * }
+ *
+ * // Type check
+ * const _check: AFSModuleClass<MyModule, MyModuleOptions> = MyModule;
+ * ```
+ */
+export interface AFSModuleClass<T extends AFSModule = AFSModule, O extends object = object> {
+    /** Returns the Zod schema for validating module configuration */
+    schema(): ZodType<O>;
+    /** Loads a module instance from configuration file path and parsed config */
+    load(params: AFSModuleLoadParams): Promise<T>;
+    /** Constructor */
+    new (options: O): T;
+}
 export type AFSRootEvents = {
-    agentSucceed: [{
-        input: object;
-        output: object;
-    }];
+    agentSucceed: [
+        {
+            agentId?: string;
+            userId?: string;
+            sessionId?: string;
+            input: object;
+            output: object;
+            messages?: object[];
+        }
+    ];
     historyCreated: [{
         entry: AFSEntry;
-    }];
+    }, options: AFSOperationOptions];
 };
 export interface AFSRootListOptions extends AFSListOptions, AFSContextPreset {
     preset?: string;
@@ -105,6 +173,8 @@ export interface AFSRootSearchResult extends Omit<AFSSearchResult, "data"> {
 export interface AFSRoot extends Emitter<AFSRootEvents>, AFSModule {
     list(path: string, options?: AFSRootListOptions): Promise<AFSRootListResult>;
     search(path: string, query: string, options: AFSRootSearchOptions): Promise<AFSRootSearchResult>;
+    initializePhysicalPath(): Promise<string>;
+    cleanupPhysicalPath(): Promise<void>;
 }
 export interface AFSEntryMetadata extends Record<string, any> {
     execute?: {
@@ -115,12 +185,14 @@ export interface AFSEntryMetadata extends Record<string, any> {
     };
     childrenCount?: number;
     childrenTruncated?: boolean;
+    gitignored?: boolean;
 }
 export interface AFSEntry<T = any> {
     id: string;
     createdAt?: Date;
     updatedAt?: Date;
     path: string;
+    agentId?: string | null;
     userId?: string | null;
     sessionId?: string | null;
     summary?: string | null;
@@ -151,7 +223,7 @@ export interface AFSContextPreset {
     }, {
         data: unknown;
     }>;
-    format?: "default" | "tree" | AFSContextPresetOptionAgent<{
+    format?: "default" | "simple-list" | "tree" | AFSContextPresetOptionAgent<{
         data: unknown;
     }, {
         data: unknown;