@aigne/afs 1.4.0-beta.6 → 1.4.0-beta.7

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## [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)
 
 

package/lib/cjs/afs.d.ts

@@ -31,4 +31,7 @@ export declare class AFS extends Emitter<AFSRootEvents> implements AFSRoot {
     private buildSimpleListView;
     private buildTreeView;
     private buildMetadataSuffix;
+    private physicalPath?;
+    initializePhysicalPath(): Promise<string>;
+    cleanupPhysicalPath(): Promise<void>;
 }

package/lib/cjs/afs.js

@@ -1,6 +1,8 @@
 "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");
@@ -286,5 +288,25 @@ class AFS extends strict_event_emitter_1.Emitter {
         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/type.d.ts

@@ -82,6 +82,7 @@ export interface AFSModule {
     readonly name: string;
     readonly description?: string;
     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>;
@@ -120,6 +121,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?: {

package/lib/dts/afs.d.ts

@@ -31,4 +31,7 @@ export declare class AFS extends Emitter<AFSRootEvents> implements AFSRoot {
     private buildSimpleListView;
     private buildTreeView;
     private buildMetadataSuffix;
+    private physicalPath?;
+    initializePhysicalPath(): Promise<string>;
+    cleanupPhysicalPath(): Promise<void>;
 }

package/lib/dts/type.d.ts

@@ -82,6 +82,7 @@ export interface AFSModule {
     readonly name: string;
     readonly description?: string;
     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>;
@@ -120,6 +121,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?: {

package/lib/esm/afs.d.ts

@@ -31,4 +31,7 @@ export declare class AFS extends Emitter<AFSRootEvents> implements AFSRoot {
     private buildSimpleListView;
     private buildTreeView;
     private buildMetadataSuffix;
+    private physicalPath?;
+    initializePhysicalPath(): Promise<string>;
+    cleanupPhysicalPath(): Promise<void>;
 }

package/lib/esm/afs.js

@@ -1,3 +1,5 @@
+import { nodejs } from "@aigne/platform-helpers/nodejs/index.js";
+import { v7 } from "@aigne/uuid";
 import { Emitter } from "strict-event-emitter";
 import { joinURL } from "ufo";
 import { z } from "zod";
@@ -283,4 +285,24 @@ export class AFS extends Emitter {
         const metadataSuffix = metadataParts.length > 0 ? ` [${metadataParts.join(", ")}]` : "";
         return metadataSuffix;
     }
+    physicalPath;
+    async initializePhysicalPath() {
+        this.physicalPath ??= (async () => {
+            const rootDir = nodejs.path.join(nodejs.os.tmpdir(), v7());
+            await nodejs.fs.mkdir(rootDir, { recursive: true });
+            for (const [modulePath, module] of this.modules) {
+                const physicalModulePath = nodejs.path.join(rootDir, modulePath);
+                await nodejs.fs.mkdir(nodejs.path.dirname(physicalModulePath), { recursive: true });
+                await module.symlinkToPhysical?.(physicalModulePath);
+            }
+            return rootDir;
+        })();
+        return this.physicalPath;
+    }
+    async cleanupPhysicalPath() {
+        if (this.physicalPath) {
+            await nodejs.fs.rm(await this.physicalPath, { recursive: true, force: true });
+            this.physicalPath = undefined;
+        }
+    }
 }

package/lib/esm/type.d.ts

@@ -82,6 +82,7 @@ export interface AFSModule {
     readonly name: string;
     readonly description?: string;
     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>;
@@ -120,6 +121,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?: {

package/package.json

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