@aigne/afs 1.1.2 → 1.2.0-beta

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [1.2.0-beta](https://github.com/AIGNE-io/aigne-framework/compare/afs-v1.1.2...afs-v1.2.0-beta) (2025-11-14)
+
+
+### Features
+
+* 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))
+
 ## [1.1.2](https://github.com/AIGNE-io/aigne-framework/compare/afs-v1.1.2-beta...afs-v1.1.2) (2025-11-12)
 
 

package/README.md

@@ -1,19 +1,17 @@
 # @aigne/afs
 
-**@aigne/afs** is the core package of the AIGNE File System (AFS), providing a virtual file system abstraction layer that enables AI agents to access various storage backends through a unified, path-based API.
+**@aigne/afs** is the core package of the Agentic File System (AFS), providing a virtual file system abstraction layer that enables AI agents to access various storage backends through a unified, path-based API.
 
 ## Overview
 
-AFS Core provides the foundational infrastructure for building virtual file systems that can integrate with different storage backends. It includes the base AFS implementation, storage layer abstraction, and the built-in history module for automatic conversation tracking.
+AFS Core provides the foundational infrastructure for building virtual file systems that can integrate with different storage backends. It includes the base AFS implementation, module mounting system, and event-driven architecture for building modular storage solutions.
 
 ## Features
 
-- **Virtual File System**: Hierarchical path-based structure similar to Unix file systems
+- **Virtual File System**: Hierarchical path-based structure with `/modules` root directory
 - **Module System**: Pluggable architecture for custom storage backends
-- **Unified API**: Consistent interface for list, read, write, and search operations
+- **Unified API**: Consistent interface for list, read, write, search, and exec operations
 - **Event System**: Event-driven architecture for module communication
-- **SQLite Storage**: Built-in persistent storage using SQLite
-- **History Tracking**: Automatic conversation history recording (AFSHistory module)
 - **AI Agent Integration**: Seamless integration with AIGNE agents
 
 ## Installation
@@ -30,26 +28,34 @@ pnpm add @aigne/afs
 
 ```typescript
 import { AFS } from "@aigne/afs";
+import { AFSHistory } from "@aigne/afs-history";
 
-// Create AFS instance with SQLite storage
-const afs = new AFS({
+// Create AFS instance
+const afs = new AFS();
+
+// Mount history module (optional)
+afs.mount(new AFSHistory({
   storage: { url: "file:./memory.sqlite3" }
-});
+}));
+
+// All modules are mounted under /modules
+// List modules
+const modules = await afs.listModules();
 
-// List entries
-const { list } = await afs.list('/');
+// List entries in a module
+const { list } = await afs.list('/modules/history');
 
 // Read an entry
-const { result } = await afs.read('/history/some-id');
+const { result } = await afs.read('/modules/history/some-id');
 
-// Write an entry
-await afs.write('/my-data/notes.txt', {
+// Write an entry (if module supports write)
+await afs.write('/modules/history/notes', {
   content: 'My notes',
   summary: 'Personal notes'
 });
 
 // Search for content
-const { list: results } = await afs.search('/', 'search query');
+const { list: results } = await afs.search('/modules/history', 'search query');
 ```
 
 ## Core Concepts
@@ -75,19 +81,19 @@ interface AFSEntry {
 
 ### Modules
 
-Modules are pluggable components that implement storage backends:
+Modules are pluggable components that implement storage backends. All modules are automatically mounted under the `/modules` path prefix:
 
 ```typescript
 interface AFSModule {
-  moduleId: string;               // Unique module identifier
-  path: string;                   // Mount path (e.g., '/history')
+  name: string;                   // Module name (used as mount path)
   description?: string;           // Description for AI agents
 
   // Operations (all optional)
-  list?(path: string, options?: AFSListOptions): Promise<{ list: AFSEntry[] }>;
-  read?(path: string): Promise<{ result?: AFSEntry }>;
-  write?(path: string, entry: AFSWriteEntryPayload): Promise<{ result: AFSEntry }>;
-  search?(path: string, query: string, options?: AFSSearchOptions): Promise<{ list: AFSEntry[] }>;
+  list?(path: string, options?: AFSListOptions): Promise<{ list: AFSEntry[]; message?: string }>;
+  read?(path: string): Promise<{ result?: AFSEntry; message?: string }>;
+  write?(path: string, entry: AFSWriteEntryPayload): Promise<{ result: AFSEntry; message?: string }>;
+  search?(path: string, query: string, options?: AFSSearchOptions): Promise<{ list: AFSEntry[]; message?: string }>;
+  exec?(path: string, args: Record<string, any>, options: { context: any }): Promise<{ result: Record<string, any> }>;
 
   // Lifecycle
   onMount?(afs: AFSRoot): void;
@@ -95,6 +101,8 @@ interface AFSModule {
 }
 ```
 
+**Mount Path Convention**: When you mount a module with name `"my-module"`, it will be accessible at `/modules/my-module`.
+
 ## API Reference
 
 ### AFS Class
@@ -102,21 +110,34 @@ interface AFSModule {
 #### Constructor
 
 ```typescript
-new AFS(options: AFSOptions)
+new AFS(options?: AFSOptions)
 ```
 
 Options:
-- `storage`: Storage configuration (e.g., `{ url: "file:./memory.sqlite3" }`)
-- `historyEnabled`: Enable/disable automatic history tracking (default: `true`)
+- `modules`: Optional array of modules to mount on initialization
 
 #### Methods
 
-##### use(module: AFSModule)
+##### mount(module: AFSModule)
+##### mount(path: string, module: AFSModule)
 
-Mount a module at its specified path:
+Mount a module. The module will be accessible under `/modules/{module.name}` or `/modules/{path}`:
 
 ```typescript
-afs.use(new CustomModule());
+// Mount using module's name
+afs.mount(new CustomModule());
+
+// Mount with custom path (advanced usage)
+afs.mount("/custom-path", new CustomModule());
+```
+
+##### listModules()
+
+Get all mounted modules:
+
+```typescript
+const modules = await afs.listModules();
+// Returns: [{ name: string, path: string, description?: string, module: AFSModule }]
 ```
 
 ##### list(path: string, options?: AFSListOptions)
@@ -124,26 +145,20 @@ afs.use(new CustomModule());
 List entries in a directory:
 
 ```typescript
-const { list, message } = await afs.list('/history', {
-  maxDepth: 2,
-  recursive: true,
-  limit: 10,
-  orderBy: [['createdAt', 'desc']]
+const { list, message } = await afs.list('/modules/history', {
+  maxDepth: 2
 });
 ```
 
 Options:
-- `maxDepth`: Maximum recursion depth
-- `recursive`: Enable recursive listing
-- `limit`: Maximum number of results
-- `orderBy`: Sort order (array of `[field, direction]` tuples)
+- `maxDepth`: Maximum recursion depth (default: 1)
 
 ##### read(path: string)
 
 Read a specific entry:
 
 ```typescript
-const { result, message } = await afs.read('/history/uuid-123');
+const { result, message } = await afs.read('/modules/history/uuid-123');
 ```
 
 ##### write(path: string, content: AFSWriteEntryPayload)
@@ -151,7 +166,7 @@ const { result, message } = await afs.read('/history/uuid-123');
 Write or update an entry:
 
 ```typescript
-const { result, message } = await afs.write('/data/file.txt', {
+const { result, message } = await afs.write('/modules/my-module/file.txt', {
   content: 'Hello, world!',
   summary: 'Greeting file',
   metadata: { type: 'greeting' }
@@ -163,9 +178,15 @@ const { result, message } = await afs.write('/data/file.txt', {
 Search for content:
 
 ```typescript
-const { list, message } = await afs.search('/history', 'authentication', {
-  limit: 5
-});
+const { list, message } = await afs.search('/modules/history', 'authentication');
+```
+
+##### exec(path: string, args: Record<string, any>, options: { context: any })
+
+Execute a module-specific operation:
+
+```typescript
+const { result } = await afs.exec('/modules/my-module/action', { param: 'value' }, { context });
 ```
 
 ### Events
@@ -173,117 +194,116 @@ const { list, message } = await afs.search('/history', 'authentication', {
 AFS uses an event system for module communication:
 
 ```typescript
-afs.on('historyCreated', ({ entry }) => {
-  console.log('New history entry:', entry);
+// Modules can listen to events
+afs.on('agentSucceed', ({ input, output }) => {
+  console.log('Agent succeeded:', input, output);
 });
+
+// Modules can emit custom events
+afs.emit('customEvent', { data: 'value' });
 ```
 
-Available events:
-- `historyCreated`: Emitted when a new history entry is created
+Common events from `AFSRootEvents`:
+- `agentSucceed`: Emitted when an agent successfully completes
+- `agentFail`: Emitted when an agent fails
 
 ## Built-in Modules
 
 ### AFSHistory
 
-The history module automatically tracks conversation history.
+The history module tracks conversation history. It is available as a separate package: `@aigne/afs-history`.
 
 **Features:**
-- Automatically records agent interactions
+- Listens to `agentSucceed` events and records agent interactions
 - Stores input/output pairs with UUID paths
-- Enables conversation history injection into agent prompts
-- Supports semantic search
+- Supports list and read operations
+- Can be extended with search capabilities
+- Persistent SQLite storage
 
-**Usage:**
+**Installation:**
+```bash
+npm install @aigne/afs-history
+```
 
-History is enabled by default. To disable:
+**Usage:**
 
 ```typescript
-const afs = new AFS({
-  storage: { url: "file:./memory.sqlite3" },
-  historyEnabled: false
-});
+import { AFS } from "@aigne/afs";
+import { AFSHistory } from "@aigne/afs-history";
+
+const afs = new AFS();
+afs.mount(new AFSHistory({
+  storage: { url: "file:./memory.sqlite3" }
+}));
+
+// History entries are accessible at /modules/history
+const { list } = await afs.list('/modules/history');
 ```
 
-**Integration with AI Agents:**
+**Configuration:**
+- `storage`: Storage configuration (e.g., `{ url: "file:./memory.sqlite3" }`) or a SharedAFSStorage instance
 
-```typescript
-import { AIAgent, AIGNE } from "@aigne/core";
+**Note:** History is NOT automatically mounted. You must explicitly mount it if needed.
 
-const agent = AIAgent.from({
-  name: "assistant",
-  afs: afs,
-  afsConfig: {
-    injectHistory: true,      // Inject history into prompts
-    historyWindowSize: 10     // Number of recent entries
-  }
-});
-```
+**Documentation:** See [@aigne/afs-history](../history/README.md) for detailed documentation.
 
 ## Creating Custom Modules
 
 Create a custom module by implementing the `AFSModule` interface:
 
 ```typescript
-import { AFSModule, AFSEntry, AFSStorage } from "@aigne/afs";
+import { AFSModule, AFSEntry, AFSListOptions } from "@aigne/afs";
 
 export class CustomModule implements AFSModule {
-  readonly moduleId = "custom-module";
-  readonly path = "/custom";
+  readonly name = "custom-module";
   readonly description = "My custom storage";
 
-  constructor(private storage: AFSStorage) {}
-
-  async list(path: string, options?: AFSListOptions) {
-    const entries = await this.storage.list(options);
-    return { list: entries };
+  async list(path: string, options?: AFSListOptions): Promise<{ list: AFSEntry[]; message?: string }> {
+    // path is the subpath within your module
+    // Implement your list logic
+    return { list: [] };
   }
 
-  async read(path: string) {
-    const entry = await this.storage.read(path);
-    return { result: entry };
+  async read(path: string): Promise<{ result?: AFSEntry; message?: string }> {
+    // Implement your read logic
+    return { result: undefined };
   }
 
-  async write(path: string, content: AFSWriteEntryPayload) {
-    const entry = await this.storage.create({ ...content, path });
+  async write(path: string, content: AFSWriteEntryPayload): Promise<{ result: AFSEntry; message?: string }> {
+    // Implement your write logic
+    const entry: AFSEntry = { id: 'id', path, ...content };
     return { result: entry };
   }
 
-  async search(path: string, query: string, options?: AFSSearchOptions) {
-    const results = await this.storage.list({
-      where: { content: { contains: query } }
-    });
-    return { list: results };
+  async search(path: string, query: string, options?: AFSSearchOptions): Promise<{ list: AFSEntry[]; message?: string }> {
+    // Implement your search logic
+    return { list: [] };
   }
 
   onMount(afs: AFSRoot) {
-    console.log(`${this.moduleId} mounted at ${this.path}`);
+    console.log(`${this.name} mounted`);
 
     // Listen to events
-    afs.on('someEvent', (data) => {
+    afs.on('agentSucceed', (data) => {
       // Handle event
     });
   }
 }
 
-// Use the module
-afs.use(new CustomModule());
+// Mount the module
+afs.mount(new CustomModule());
+// Now accessible at /modules/custom-module
 ```
 
-## Storage Layer
+## Module Path Resolution
 
-AFS Core includes a SQLite-based storage layer that modules can use:
+When a module is mounted, AFS handles path resolution automatically:
 
-```typescript
-// Get module-specific storage
-const storage = afs.storage(myModule);
-
-// Storage operations
-await storage.create({ path: '/data', content: 'value' });
-await storage.read('/data');
-await storage.update('/data', { content: 'new value' });
-await storage.delete('/data');
-await storage.list({ where: { path: { startsWith: '/data' } } });
-```
+1. Module mounted with name `"my-module"` → accessible at `/modules/my-module`
+2. When listing `/modules`, AFS shows all mounted modules
+3. When accessing `/modules/my-module/foo`, the module receives `"/foo"` as the path parameter
+
+This allows modules to focus on their internal logic without worrying about mount paths.
 
 ## Integration with AI Agents
 
@@ -293,22 +313,23 @@ When an agent has AFS configured, these tools are automatically registered:
 - **afs_read**: Read file contents
 - **afs_write**: Write/create files
 - **afs_search**: Search for content
+- **afs_exec**: Execute module operations
 
 Example:
 
 ```typescript
 import { AIAgent, AIGNE } from "@aigne/core";
 import { AFS } from "@aigne/afs";
+import { AFSHistory } from "@aigne/afs-history";
 
-const afs = new AFS({ storage: { url: "file:./memory.sqlite3" } });
+const afs = new AFS();
+afs.mount(new AFSHistory({
+  storage: { url: "file:./memory.sqlite3" }
+}));
 
 const agent = AIAgent.from({
   name: "assistant",
-  afs: afs,
-  afsConfig: {
-    injectHistory: true,
-    historyWindowSize: 10
-  }
+  afs: afs
 });
 
 const context = aigne.newContext();
@@ -319,12 +340,15 @@ const result = await context.invoke(agent, {
 
 ## Related Packages
 
-- [@aigne/afs-system-fs](../system-fs/README.md) - Local file system module
+- [@aigne/afs-history](../history/README.md) - History tracking module
+- [@aigne/afs-local-fs](../local-fs/README.md) - Local file system module
 - [@aigne/afs-user-profile-memory](../user-profile-memory/README.md) - User profile memory module
 
 ## Examples
 
-See the [AFS examples](../../examples/afs-system-fs) for complete usage examples.
+- [AFS Memory Example](../../examples/afs-memory/README.md) - Conversational memory with user profiles
+- [AFS LocalFS Example](../../examples/afs-local-fs/README.md) - File system access with AI agents
+- [AFS MCP Server Example](../../examples/afs-mcp-server/README.md) - Mount MCP servers as AFS modules
 
 ## TypeScript Support
 

package/lib/cjs/afs.d.ts

@@ -1,23 +1,18 @@
 import { Emitter } from "strict-event-emitter";
-import { SharedAFSStorage, type SharedAFSStorageOptions } from "./storage/index.js";
-import type { AFSStorage } from "./storage/type.js";
 import type { AFSEntry, AFSListOptions, AFSModule, AFSRoot, AFSRootEvents, AFSSearchOptions, AFSWriteEntryPayload } from "./type.js";
 export interface AFSOptions {
-    storage?: SharedAFSStorage | SharedAFSStorageOptions;
     modules?: AFSModule[];
 }
 export declare class AFS extends Emitter<AFSRootEvents> implements AFSRoot {
-    moduleId: string;
-    path: string;
+    name: string;
     constructor(options?: AFSOptions);
-    private _storage;
-    storage(module: AFSModule): AFSStorage;
     private modules;
-    use(module: AFSModule): this;
+    mount(module: AFSModule): this;
     listModules(): Promise<{
-        moduleId: string;
+        name: string;
         path: string;
         description?: string;
+        module: AFSModule;
     }[]>;
     list(path: string, options?: AFSListOptions): Promise<{
         list: AFSEntry[];
@@ -36,4 +31,9 @@ export declare class AFS extends Emitter<AFSRootEvents> implements AFSRoot {
         message?: string;
     }>;
     private findModules;
+    exec(path: string, args: Record<string, any>, options: {
+        context: any;
+    }): Promise<{
+        result: Record<string, any>;
+    }>;
 }

package/lib/cjs/afs.js

@@ -3,38 +3,36 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.AFS = void 0;
 const strict_event_emitter_1 = require("strict-event-emitter");
 const ufo_1 = require("ufo");
-const index_js_1 = require("./history/index.js");
-const index_js_2 = require("./storage/index.js");
 const DEFAULT_MAX_DEPTH = 1;
+const MODULES_ROOT_DIR = "/modules";
 class AFS extends strict_event_emitter_1.Emitter {
-    moduleId = "AFSRoot";
-    path = "/";
+    name = "AFSRoot";
     constructor(options) {
         super();
-        this._storage =
-            options?.storage instanceof index_js_2.SharedAFSStorage
-                ? options.storage
-                : new index_js_2.SharedAFSStorage(options?.storage);
-        this.use(new index_js_1.AFSHistory());
         for (const module of options?.modules ?? []) {
-            this.use(module);
+            this.mount(module);
         }
     }
-    _storage;
-    storage(module) {
-        return this._storage.withModule(module);
-    }
     modules = new Map();
-    use(module) {
-        this.modules.set(module.path, module);
+    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 '/'`);
+        }
+        if (this.modules.has(path)) {
+            throw new Error(`Module already mounted at path: ${path}`);
+        }
+        path = (0, ufo_1.joinURL)(MODULES_ROOT_DIR, path);
+        this.modules.set(path, module);
         module.onMount?.(this);
         return this;
     }
     async listModules() {
         return Array.from(this.modules.entries()).map(([path, module]) => ({
-            moduleId: module.moduleId,
             path,
+            name: module.name,
             description: module.description,
+            module,
         }));
     }
     async list(path, options) {
@@ -46,7 +44,7 @@ class AFS extends strict_event_emitter_1.Emitter {
         const matches = this.findModules(path, options);
         for (const matched of matches) {
             const moduleEntry = {
-                id: matched.module.moduleId,
+                id: matched.module.name,
                 path: matched.remainedModulePath,
                 summary: matched.module.description,
             };
@@ -64,7 +62,7 @@ class AFS extends strict_event_emitter_1.Emitter {
                 if (list.length) {
                     results.push(...list.map((entry) => ({
                         ...entry,
-                        path: (0, ufo_1.joinURL)(matched.module.path, entry.path),
+                        path: (0, ufo_1.joinURL)(matched.modulePath, entry.path),
                     })));
                 }
                 else {
@@ -74,21 +72,21 @@ class AFS extends strict_event_emitter_1.Emitter {
                     messages.push(message);
             }
             catch (error) {
-                console.error(`Error listing from module at ${matched.module.path}`, error);
+                console.error(`Error listing from module at ${matched.modulePath}`, error);
             }
         }
         return { list: results, message: messages.join("; ").trim() || undefined };
     }
     async read(path) {
         const modules = this.findModules(path, { exactMatch: true });
-        for (const { module, subpath } of modules) {
+        for (const { module, modulePath, subpath } of modules) {
             const res = await module.read?.(subpath);
             if (res?.result) {
                 return {
                     ...res,
                     result: {
                         ...res.result,
-                        path: (0, ufo_1.joinURL)(module.path, res.result.path),
+                        path: (0, ufo_1.joinURL)(modulePath, res.result.path),
                     },
                 };
             }
@@ -104,27 +102,27 @@ class AFS extends strict_event_emitter_1.Emitter {
             ...res,
             result: {
                 ...res.result,
-                path: (0, ufo_1.joinURL)(module.module.path, res.result.path),
+                path: (0, ufo_1.joinURL)(module.modulePath, res.result.path),
             },
         };
     }
     async search(path, query, options) {
         const results = [];
         const messages = [];
-        for (const { module, subpath } of this.findModules(path)) {
+        for (const { module, modulePath, subpath } of this.findModules(path)) {
             if (!module.search)
                 continue;
             try {
                 const { list, message } = await module.search(subpath, query, options);
                 results.push(...list.map((entry) => ({
                     ...entry,
-                    path: (0, ufo_1.joinURL)(module.path, entry.path),
+                    path: (0, ufo_1.joinURL)(modulePath, entry.path),
                 })));
                 if (message)
                     messages.push(message);
             }
             catch (error) {
-                console.error(`Error searching in module at ${module.path}`, error);
+                console.error(`Error searching in module at ${modulePath}`, error);
             }
         }
         return { list: results, message: messages.join("; ") };
@@ -153,9 +151,15 @@ class AFS extends strict_event_emitter_1.Emitter {
             }
             if (newMaxDepth < 0)
                 continue;
-            matched.push({ module, maxDepth: newMaxDepth, subpath, remainedModulePath });
+            matched.push({ module, modulePath, maxDepth: newMaxDepth, subpath, remainedModulePath });
         }
         return matched;
     }
+    async exec(path, args, options) {
+        const module = this.findModules(path)[0];
+        if (!module?.module.exec)
+            throw new Error(`No module found for path: ${path}`);
+        return await module.module.exec(module.subpath, args, options);
+    }
 }
 exports.AFS = AFS;

package/lib/cjs/index.d.ts

@@ -1,4 +1,2 @@
 export * from "./afs.js";
-export * from "./history/index.js";
-export * from "./storage/index.js";
 export * from "./type.js";

package/lib/cjs/index.js

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