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

package/lib/esm/type.d.ts

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

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