@aigne/afs 1.4.0-beta.8 → 1.4.0-beta.9

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## [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,6 +21,16 @@ 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)) {
@@ -109,6 +120,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 +134,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 +147,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,6 +18,16 @@ 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)) {
@@ -106,6 +117,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 +131,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 +144,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-beta.9",
   "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"
@@ -51,7 +51,7 @@
     "strict-event-emitter": "^0.5.1",
     "ufo": "^1.6.1",
     "zod": "^3.25.67",
-    "@aigne/platform-helpers": "^0.6.7-beta.1"
+    "@aigne/platform-helpers": "^0.6.7-beta.2"
   },
   "devDependencies": {
     "@types/bun": "^1.2.22",