@aigne/afs 1.3.0 → 1.4.0-beta.10

package/lib/cjs/type.d.ts

@@ -1,71 +1,180 @@
 import type { Emitter } from "strict-event-emitter";
-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;
     };
-    recursive?: boolean;
     maxDepth?: number;
     limit?: number;
     orderBy?: [string, "asc" | "desc"][];
+    maxChildren?: number;
+    onOverflow?: "truncate";
+    /**
+     * Whether to disable .gitignore files when listing files.
+     * @default false
+     */
+    disableGitignore?: boolean;
+    /**
+     * Glob pattern to filter entries by path.
+     * Examples: "*.ts", "**\/*.js", "src/**\/*.{ts,tsx}"
+     */
+    pattern?: string;
+}
+export interface AFSListResult {
+    data: AFSEntry[];
+    message?: string;
 }
-export interface AFSSearchOptions {
+export interface AFSSearchOptions extends AFSOperationOptions {
     limit?: number;
     caseSensitive?: boolean;
 }
-export interface AFSDeleteOptions {
+export interface AFSSearchResult {
+    data: AFSEntry[];
+    message?: string;
+}
+export interface AFSReadOptions extends AFSOperationOptions {
+    filter?: AFSListOptions["filter"];
+}
+export interface AFSReadResult {
+    data?: AFSEntry;
+    message?: string;
+}
+export interface AFSDeleteOptions extends AFSOperationOptions {
     recursive?: boolean;
 }
-export interface AFSRenameOptions {
+export interface AFSDeleteResult {
+    message?: string;
+}
+export interface AFSRenameOptions extends AFSOperationOptions {
     overwrite?: boolean;
 }
-export interface AFSWriteOptions {
+export interface AFSRenameResult {
+    message?: string;
+}
+export interface AFSWriteOptions extends AFSOperationOptions {
     append?: boolean;
 }
+export interface AFSWriteResult {
+    data: AFSEntry;
+    message?: string;
+    context?: any;
+}
 export interface AFSWriteEntryPayload extends Omit<AFSEntry, "id" | "path"> {
 }
+export interface AFSExecOptions extends AFSOperationOptions {
+}
+export interface AFSExecResult {
+    data: Record<string, any>;
+}
 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;
-    list?(path: string, options?: AFSListOptions): Promise<{
-        list: AFSEntry[];
-        message?: string;
-    }>;
-    read?(path: string): Promise<{
-        result?: AFSEntry;
-        message?: string;
-    }>;
-    write?(path: string, content: AFSWriteEntryPayload, options?: AFSWriteOptions): Promise<{
-        result: AFSEntry;
-        message?: string;
-    }>;
-    delete?(path: string, options?: AFSDeleteOptions): Promise<{
-        message?: string;
-    }>;
-    rename?(oldPath: string, newPath: string, options?: AFSRenameOptions): Promise<{
-        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>;
-    }>;
+    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>;
+    delete?(path: string, options?: AFSDeleteOptions): Promise<AFSDeleteResult>;
+    rename?(oldPath: string, newPath: string, options?: AFSRenameOptions): Promise<AFSRenameResult>;
+    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;
+}
+export interface AFSRootListResult extends Omit<AFSListResult, "data"> {
+    data: any;
+}
+export interface AFSRootSearchOptions extends AFSSearchOptions, AFSContextPreset {
+    preset?: string;
+}
+export interface AFSRootSearchResult extends Omit<AFSSearchResult, "data"> {
+    data: any;
+}
 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?: {
@@ -75,12 +184,15 @@ export interface AFSEntryMetadata extends Record<string, any> {
         outputSchema?: 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;
@@ -89,3 +201,42 @@ export interface AFSEntry<T = any> {
     linkTo?: string | null;
     content?: T;
 }
+export declare const afsEntrySchema: ZodType<AFSEntry>;
+export interface AFSContextPreset {
+    /**
+     * The view template for presenting the search results.
+     */
+    view?: string;
+    select?: AFSContextPresetOptionAgent<{
+        path: string;
+        query?: string;
+    }, {
+        data: string[];
+    }>;
+    per?: AFSContextPresetOptionAgent<{
+        data: AFSEntry;
+    }, {
+        data: unknown;
+    }>;
+    dedupe?: AFSContextPresetOptionAgent<{
+        data: unknown[];
+    }, {
+        data: unknown;
+    }>;
+    format?: "default" | "simple-list" | "tree" | AFSContextPresetOptionAgent<{
+        data: unknown;
+    }, {
+        data: unknown;
+    }>;
+}
+export interface AFSContextPresetOptionAgent<I = any, O = any> {
+    invoke(input: I, options?: any): Promise<O>;
+}
+export interface AFSContext {
+    search?: {
+        presets?: Record<string, AFSContextPreset>;
+    };
+    list?: {
+        presets?: Record<string, AFSContextPreset>;
+    };
+}

package/lib/cjs/type.js

@@ -1,2 +1,25 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+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(),
+    updatedAt: zod_1.z.date().optional(),
+    path: zod_1.z.string(),
+    userId: zod_1.z.string().nullable().optional(),
+    sessionId: zod_1.z.string().nullable().optional(),
+    summary: zod_1.z.string().nullable().optional(),
+    description: zod_1.z.string().nullable().optional(),
+    metadata: zod_1.z.record(zod_1.z.any()).nullable().optional(),
+    linkTo: zod_1.z.string().nullable().optional(),
+    content: zod_1.z.any().optional(),
+});

package/lib/dts/afs.d.ts

@@ -1,12 +1,19 @@
 import { Emitter } from "strict-event-emitter";
-import type { AFSDeleteOptions, AFSEntry, AFSListOptions, AFSModule, AFSRenameOptions, AFSRoot, AFSRootEvents, AFSSearchOptions, AFSWriteEntryPayload, AFSWriteOptions } from "./type.js";
+import { type AFSContext, type AFSDeleteOptions, type AFSDeleteResult, type AFSExecOptions, type AFSExecResult, type AFSModule, type AFSReadOptions, type AFSReadResult, type AFSRenameOptions, type AFSRenameResult, type AFSRoot, type AFSRootEvents, type AFSRootListOptions, type AFSRootListResult, type AFSRootSearchOptions, type AFSRootSearchResult, type AFSWriteEntryPayload, type AFSWriteOptions, type AFSWriteResult } from "./type.js";
 export interface AFSOptions {
     modules?: AFSModule[];
+    context?: AFSContext;
 }
 export declare class AFS extends Emitter<AFSRootEvents> implements AFSRoot {
+    options: AFSOptions;
     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;
@@ -14,32 +21,22 @@ export declare class AFS extends Emitter<AFSRootEvents> implements AFSRoot {
         description?: string;
         module: AFSModule;
     }[]>;
-    list(path: string, options?: AFSListOptions): Promise<{
-        list: AFSEntry[];
-        message?: string;
-    }>;
-    read(path: string): Promise<{
-        result?: AFSEntry;
-        message?: string;
-    }>;
-    write(path: string, content: AFSWriteEntryPayload, options?: AFSWriteOptions): Promise<{
-        result: AFSEntry;
-        message?: string;
-    }>;
-    delete(path: string, options?: AFSDeleteOptions): Promise<{
-        message?: string;
-    }>;
-    rename(oldPath: string, newPath: string, options?: AFSRenameOptions): Promise<{
-        message?: string;
-    }>;
-    search(path: string, query: string, options?: AFSSearchOptions): Promise<{
-        list: AFSEntry[];
-        message?: string;
-    }>;
+    list(path: string, options?: AFSRootListOptions): Promise<AFSRootListResult>;
+    private _list;
+    read(path: string, _options?: AFSReadOptions): Promise<AFSReadResult>;
+    write(path: string, content: AFSWriteEntryPayload, options?: AFSWriteOptions): Promise<AFSWriteResult>;
+    delete(path: string, options?: AFSDeleteOptions): Promise<AFSDeleteResult>;
+    rename(oldPath: string, newPath: string, options?: AFSRenameOptions): Promise<AFSRenameResult>;
+    search(path: string, query: string, options?: AFSRootSearchOptions): Promise<AFSRootSearchResult>;
+    private processWithPreset;
+    private _select;
+    private _search;
     private findModules;
-    exec(path: string, args: Record<string, any>, options: {
-        context: any;
-    }): Promise<{
-        result: Record<string, any>;
-    }>;
+    exec(path: string, args: Record<string, any>, options: AFSExecOptions): Promise<AFSExecResult>;
+    private buildSimpleListView;
+    private buildTreeView;
+    private buildMetadataSuffix;
+    private physicalPath?;
+    initializePhysicalPath(): Promise<string>;
+    cleanupPhysicalPath(): Promise<void>;
 }

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,71 +1,180 @@
 import type { Emitter } from "strict-event-emitter";
-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;
     };
-    recursive?: boolean;
     maxDepth?: number;
     limit?: number;
     orderBy?: [string, "asc" | "desc"][];
+    maxChildren?: number;
+    onOverflow?: "truncate";
+    /**
+     * Whether to disable .gitignore files when listing files.
+     * @default false
+     */
+    disableGitignore?: boolean;
+    /**
+     * Glob pattern to filter entries by path.
+     * Examples: "*.ts", "**\/*.js", "src/**\/*.{ts,tsx}"
+     */
+    pattern?: string;
+}
+export interface AFSListResult {
+    data: AFSEntry[];
+    message?: string;
 }
-export interface AFSSearchOptions {
+export interface AFSSearchOptions extends AFSOperationOptions {
     limit?: number;
     caseSensitive?: boolean;
 }
-export interface AFSDeleteOptions {
+export interface AFSSearchResult {
+    data: AFSEntry[];
+    message?: string;
+}
+export interface AFSReadOptions extends AFSOperationOptions {
+    filter?: AFSListOptions["filter"];
+}
+export interface AFSReadResult {
+    data?: AFSEntry;
+    message?: string;
+}
+export interface AFSDeleteOptions extends AFSOperationOptions {
     recursive?: boolean;
 }
-export interface AFSRenameOptions {
+export interface AFSDeleteResult {
+    message?: string;
+}
+export interface AFSRenameOptions extends AFSOperationOptions {
     overwrite?: boolean;
 }
-export interface AFSWriteOptions {
+export interface AFSRenameResult {
+    message?: string;
+}
+export interface AFSWriteOptions extends AFSOperationOptions {
     append?: boolean;
 }
+export interface AFSWriteResult {
+    data: AFSEntry;
+    message?: string;
+    context?: any;
+}
 export interface AFSWriteEntryPayload extends Omit<AFSEntry, "id" | "path"> {
 }
+export interface AFSExecOptions extends AFSOperationOptions {
+}
+export interface AFSExecResult {
+    data: Record<string, any>;
+}
 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;
-    list?(path: string, options?: AFSListOptions): Promise<{
-        list: AFSEntry[];
-        message?: string;
-    }>;
-    read?(path: string): Promise<{
-        result?: AFSEntry;
-        message?: string;
-    }>;
-    write?(path: string, content: AFSWriteEntryPayload, options?: AFSWriteOptions): Promise<{
-        result: AFSEntry;
-        message?: string;
-    }>;
-    delete?(path: string, options?: AFSDeleteOptions): Promise<{
-        message?: string;
-    }>;
-    rename?(oldPath: string, newPath: string, options?: AFSRenameOptions): Promise<{
-        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>;
-    }>;
+    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>;
+    delete?(path: string, options?: AFSDeleteOptions): Promise<AFSDeleteResult>;
+    rename?(oldPath: string, newPath: string, options?: AFSRenameOptions): Promise<AFSRenameResult>;
+    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;
+}
+export interface AFSRootListResult extends Omit<AFSListResult, "data"> {
+    data: any;
+}
+export interface AFSRootSearchOptions extends AFSSearchOptions, AFSContextPreset {
+    preset?: string;
+}
+export interface AFSRootSearchResult extends Omit<AFSSearchResult, "data"> {
+    data: any;
+}
 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?: {
@@ -75,12 +184,15 @@ export interface AFSEntryMetadata extends Record<string, any> {
         outputSchema?: 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;
@@ -89,3 +201,42 @@ export interface AFSEntry<T = any> {
     linkTo?: string | null;
     content?: T;
 }
+export declare const afsEntrySchema: ZodType<AFSEntry>;
+export interface AFSContextPreset {
+    /**
+     * The view template for presenting the search results.
+     */
+    view?: string;
+    select?: AFSContextPresetOptionAgent<{
+        path: string;
+        query?: string;
+    }, {
+        data: string[];
+    }>;
+    per?: AFSContextPresetOptionAgent<{
+        data: AFSEntry;
+    }, {
+        data: unknown;
+    }>;
+    dedupe?: AFSContextPresetOptionAgent<{
+        data: unknown[];
+    }, {
+        data: unknown;
+    }>;
+    format?: "default" | "simple-list" | "tree" | AFSContextPresetOptionAgent<{
+        data: unknown;
+    }, {
+        data: unknown;
+    }>;
+}
+export interface AFSContextPresetOptionAgent<I = any, O = any> {
+    invoke(input: I, options?: any): Promise<O>;
+}
+export interface AFSContext {
+    search?: {
+        presets?: Record<string, AFSContextPreset>;
+    };
+    list?: {
+        presets?: Record<string, AFSContextPreset>;
+    };
+}