@aigne/afs 1.4.0-beta.8 → 1.4.0

package/CHANGELOG.md

@@ -1,5 +1,75 @@
 # Changelog
 
+## [1.4.0](https://github.com/AIGNE-io/aigne-framework/compare/afs-v1.4.0-beta.11...afs-v1.4.0) (2026-01-16)
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @aigne/platform-helpers bumped to 0.6.7
+
+## [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)
 
 

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;

package/lib/cjs/afs.js

@@ -6,6 +6,7 @@ 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";
@@ -20,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}`);
         }
@@ -55,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;
             }
@@ -73,15 +106,13 @@ 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) {
                 throw new Error(`Error listing from module at ${matched.modulePath}: ${error.message}`);
@@ -109,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,
@@ -122,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) {
@@ -134,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 = {}) {

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,6 +1,20 @@
 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;
@@ -23,47 +37,40 @@ export interface AFSListOptions {
      * Examples: "*.ts", "**\/*.js", "src/**\/*.{ts,tsx}"
      */
     pattern?: string;
-    context?: any;
 }
 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 {
+export interface AFSReadOptions extends AFSOperationOptions {
     filter?: AFSListOptions["filter"];
-    context?: any;
 }
 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;
@@ -72,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>;
@@ -81,6 +87,19 @@ 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>;
@@ -91,6 +110,39 @@ 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: [
         {
@@ -104,7 +156,7 @@ export type AFSRootEvents = {
     ];
     historyCreated: [{
         entry: AFSEntry;
-    }];
+    }, options: AFSOperationOptions];
 };
 export interface AFSRootListOptions extends AFSListOptions, AFSContextPreset {
     preset?: string;

package/lib/cjs/type.js

@@ -1,7 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.afsEntrySchema = void 0;
+exports.afsEntrySchema = exports.accessModeSchema = void 0;
 const zod_1 = require("zod");
+/**
+ * Zod schema for access mode validation.
+ * Can be reused across modules that support access mode configuration.
+ */
+exports.accessModeSchema = zod_1.z
+    .enum(["readonly", "readwrite"])
+    .describe("Access mode for this module")
+    .optional();
 exports.afsEntrySchema = zod_1.z.object({
     id: zod_1.z.string(),
     createdAt: zod_1.z.date().optional(),

package/lib/dts/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;

package/lib/dts/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/dts/index.d.ts

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

package/lib/dts/type.d.ts

@@ -1,6 +1,20 @@
 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;
@@ -23,47 +37,40 @@ export interface AFSListOptions {
      * Examples: "*.ts", "**\/*.js", "src/**\/*.{ts,tsx}"
      */
     pattern?: string;
-    context?: any;
 }
 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 {
+export interface AFSReadOptions extends AFSOperationOptions {
     filter?: AFSListOptions["filter"];
-    context?: any;
 }
 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;
@@ -72,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>;
@@ -81,6 +87,19 @@ 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>;
@@ -91,6 +110,39 @@ 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: [
         {
@@ -104,7 +156,7 @@ export type AFSRootEvents = {
     ];
     historyCreated: [{
         entry: AFSEntry;
-    }];
+    }, options: AFSOperationOptions];
 };
 export interface AFSRootListOptions extends AFSListOptions, AFSContextPreset {
     preset?: string;

package/lib/esm/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;

package/lib/esm/afs.js

@@ -3,6 +3,7 @@ import { v7 } from "@aigne/uuid";
 import { Emitter } from "strict-event-emitter";
 import { joinURL } from "ufo";
 import { z } from "zod";
+import { AFSReadonlyError } from "./error.js";
 import { afsEntrySchema, } from "./type.js";
 const DEFAULT_MAX_DEPTH = 1;
 const MODULES_ROOT_DIR = "/modules";
@@ -17,12 +18,22 @@ export class AFS extends 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 AFSReadonlyError(`Module '${module.name}' is readonly, cannot perform ${operation} to ${path}`);
+        }
+    }
     mount(module) {
-        let path = 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 = joinURL(MODULES_ROOT_DIR, path);
+        const path = joinURL(MODULES_ROOT_DIR, module.name);
         if (this.modules.has(path)) {
             throw new Error(`Module already mounted at path: ${path}`);
         }
@@ -52,14 +63,36 @@ export class AFS extends 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;
             }
@@ -70,15 +103,13 @@ export class AFS extends Emitter {
                     ...options,
                     maxDepth: matched.maxDepth,
                 });
-                if (data.length) {
-                    results.push(...data.map((entry) => ({
-                        ...entry,
-                        path: joinURL(matched.modulePath, entry.path),
-                    })));
-                }
-                else {
-                    results.push(moduleEntry);
-                }
+                const children = data.map((entry) => ({
+                    ...entry,
+                    path: 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) {
                 throw new Error(`Error listing from module at ${matched.modulePath}: ${error.message}`);
@@ -106,6 +137,7 @@ export class AFS extends 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,
@@ -119,6 +151,7 @@ export class AFS extends 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) {
@@ -131,6 +164,7 @@ export class AFS extends 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 = {}) {

package/lib/esm/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/esm/error.js

@@ -0,0 +1,20 @@
+/**
+ * Base error class for all AFS errors.
+ */
+export class AFSError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.name = "AFSError";
+        this.code = code;
+    }
+}
+/**
+ * Error thrown when attempting write operations on a readonly AFS or module.
+ */
+export class AFSReadonlyError extends AFSError {
+    constructor(message) {
+        super(message, "AFS_READONLY");
+        this.name = "AFSReadonlyError";
+    }
+}

package/lib/esm/index.d.ts

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

package/lib/esm/index.js

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

package/lib/esm/type.d.ts

@@ -1,6 +1,20 @@
 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;
@@ -23,47 +37,40 @@ export interface AFSListOptions {
      * Examples: "*.ts", "**\/*.js", "src/**\/*.{ts,tsx}"
      */
     pattern?: string;
-    context?: any;
 }
 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 {
+export interface AFSReadOptions extends AFSOperationOptions {
     filter?: AFSListOptions["filter"];
-    context?: any;
 }
 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;
@@ -72,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>;
@@ -81,6 +87,19 @@ 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>;
@@ -91,6 +110,39 @@ 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: [
         {
@@ -104,7 +156,7 @@ export type AFSRootEvents = {
     ];
     historyCreated: [{
         entry: AFSEntry;
-    }];
+    }, options: AFSOperationOptions];
 };
 export interface AFSRootListOptions extends AFSListOptions, AFSContextPreset {
     preset?: string;

package/lib/esm/type.js

@@ -1,4 +1,12 @@
 import { z } from "zod";
+/**
+ * Zod schema for access mode validation.
+ * Can be reused across modules that support access mode configuration.
+ */
+export const accessModeSchema = z
+    .enum(["readonly", "readwrite"])
+    .describe("Access mode for this module")
+    .optional();
 export const afsEntrySchema = z.object({
     id: z.string(),
     createdAt: z.date().optional(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigne/afs",
-  "version": "1.4.0-beta.8",
+  "version": "1.4.0",
   "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"
@@ -50,8 +50,9 @@
     "@aigne/uuid": "^13.0.1",
     "strict-event-emitter": "^0.5.1",
     "ufo": "^1.6.1",
+    "yaml": "^2.8.1",
     "zod": "^3.25.67",
-    "@aigne/platform-helpers": "^0.6.7-beta.1"
+    "@aigne/platform-helpers": "^0.6.7"
   },
   "devDependencies": {
     "@types/bun": "^1.2.22",