@aigne/core 1.63.0-beta.2 → 1.63.0-beta.4

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## [1.63.0-beta.4](https://github.com/AIGNE-io/aigne-framework/compare/core-v1.63.0-beta.3...core-v1.63.0-beta.4) (2025-10-12)
+
+
+### Features
+
+* **afs:** add configurable history injection to AFS system ([#611](https://github.com/AIGNE-io/aigne-framework/issues/611)) ([689b5d7](https://github.com/AIGNE-io/aigne-framework/commit/689b5d76d8cc82f548e8be74e63f18e7a6216c31))
+
+## [1.63.0-beta.3](https://github.com/AIGNE-io/aigne-framework/compare/core-v1.63.0-beta.2...core-v1.63.0-beta.3) (2025-10-11)
+
+
+### Features
+
+* **afs:** add module system fs for afs ([#594](https://github.com/AIGNE-io/aigne-framework/issues/594)) ([83c7b65](https://github.com/AIGNE-io/aigne-framework/commit/83c7b6555d21c606a5005eb05f6686882fb8ffa3))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @aigne/afs bumped to 1.1.0-beta
+    * @aigne/observability-api bumped to 0.11.2-beta.1
+
 ## [1.63.0-beta.2](https://github.com/AIGNE-io/aigne-framework/compare/core-v1.63.0-beta.1...core-v1.63.0-beta.2) (2025-10-09)
 
 

package/lib/cjs/agents/agent.d.ts

@@ -122,6 +122,7 @@ export interface AgentOptions<I extends Message = Message, O extends Message = M
      */
     memory?: MemoryAgent | MemoryAgent[];
     afs?: true | AFSOptions | AFS | ((afs: AFS) => AFS);
+    afsConfig?: AFSConfig;
     asyncMemoryRecord?: boolean;
     /**
      * Maximum number of memory items to retrieve
@@ -130,6 +131,10 @@ export interface AgentOptions<I extends Message = Message, O extends Message = M
     hooks?: AgentHooks<I, O> | AgentHooks<I, O>[];
     retryOnError?: Agent<I, O>["retryOnError"] | boolean;
 }
+export interface AFSConfig {
+    injectHistory?: boolean;
+    historyWindowSize?: number;
+}
 export declare const agentOptionsSchema: ZodObject<{
     [key in keyof AgentOptions]: ZodType<AgentOptions[key]>;
 }>;
@@ -212,6 +217,7 @@ export declare abstract class Agent<I extends Message = any, O extends Message =
      */
     readonly memories: MemoryAgent[];
     afs?: AFS;
+    afsConfig?: AFSConfig;
     asyncMemoryRecord?: boolean;
     tag?: string;
     /**

package/lib/cjs/agents/agent.js

@@ -161,6 +161,7 @@ class Agent {
                     : options.afs instanceof afs_1.AFS
                         ? options.afs
                         : new afs_1.AFS(options.afs);
+        this.afsConfig = options.afsConfig;
         this.asyncMemoryRecord = options.asyncMemoryRecord;
         this.maxRetrieveMemoryCount = options.maxRetrieveMemoryCount;
         this.hooks = (0, type_utils_js_1.flat)(options.hooks);
@@ -179,6 +180,7 @@ class Agent {
      */
     memories = [];
     afs;
+    afsConfig;
     asyncMemoryRecord;
     tag;
     /**

package/lib/cjs/loader/agent-yaml.d.ts

@@ -1,5 +1,6 @@
+import type { AFSOptions } from "@aigne/afs";
 import { type ZodType, z } from "zod";
-import type { AgentHooks, FunctionAgentFn, TaskRenderMode } from "../agents/agent.js";
+import type { AFSConfig, AgentHooks, FunctionAgentFn, TaskRenderMode } from "../agents/agent.js";
 import { AIAgentToolChoice } from "../agents/ai-agent.js";
 import { type Role } from "../agents/chat-model.js";
 import { ProcessMode, type ReflectionMode } from "../agents/team-agent.js";
@@ -19,6 +20,10 @@ export type NestAgentSchema = string | {
     defaultInput?: Record<string, any>;
     hooks?: HooksSchema | HooksSchema[];
 } | AgentSchema;
+export type AFSModuleSchema = string | {
+    module: string;
+    options?: Record<string, any>;
+};
 export interface BaseAgentSchema {
     name?: string;
     description?: string;
@@ -36,6 +41,10 @@ export interface BaseAgentSchema {
         provider: string;
         subscribeTopic?: string[];
     };
+    afs?: boolean | (Omit<AFSOptions, "modules"> & {
+        modules?: AFSModuleSchema[];
+    });
+    afsConfig?: AFSConfig;
 }
 export type Instructions = {
     role: Exclude<Role, "tool">;

package/lib/cjs/loader/agent-yaml.js

@@ -53,6 +53,25 @@ async function parseAgentFile(path, data) {
                     subscribeTopic: (0, schema_js_1.optionalize)(zod_1.z.array(zod_1.z.string())),
                 })),
             ])),
+            afs: (0, schema_js_1.optionalize)(zod_1.z.union([
+                zod_1.z.boolean(),
+                (0, schema_js_1.camelizeSchema)(zod_1.z.object({
+                    storage: (0, schema_js_1.optionalize)(zod_1.z.object({
+                        url: (0, schema_js_1.optionalize)(zod_1.z.string()),
+                    })),
+                    modules: (0, schema_js_1.optionalize)(zod_1.z.array(zod_1.z.union([
+                        zod_1.z.string(),
+                        zod_1.z.object({
+                            module: zod_1.z.string(),
+                            options: (0, schema_js_1.optionalize)(zod_1.z.record(zod_1.z.any())),
+                        }),
+                    ]))),
+                })),
+            ])),
+            afsConfig: (0, schema_js_1.optionalize)((0, schema_js_1.camelizeSchema)(zod_1.z.object({
+                injectHistory: (0, schema_js_1.optionalize)(zod_1.z.boolean()),
+                historyWindowSize: (0, schema_js_1.optionalize)(zod_1.z.number().int().min(1)),
+            }))),
         });
         const instructionItemSchema = zod_1.z.union([
             zod_1.z.object({

package/lib/cjs/loader/index.d.ts

@@ -1,3 +1,4 @@
+import { type AFSModule } from "@aigne/afs";
 import { type ZodType, z } from "zod";
 import { Agent, type AgentOptions } from "../agents/agent.js";
 import type { ChatModel } from "../agents/chat-model.js";
@@ -11,6 +12,12 @@ export interface LoadOptions {
     }[];
     model?: ChatModel | ((model?: z.infer<typeof aigneFileSchema>["model"]) => PromiseOrValue<ChatModel | undefined>);
     imageModel?: ImageModel | ((model?: z.infer<typeof aigneFileSchema>["imageModel"]) => PromiseOrValue<ImageModel | undefined>);
+    afs?: {
+        availableModules?: {
+            module: string;
+            create: (options?: Record<string, any>) => PromiseOrValue<AFSModule>;
+        }[];
+    };
 }
 export declare function load(path: string, options?: LoadOptions): Promise<AIGNEOptions>;
 export declare function loadAgent(path: string, options?: LoadOptions, agentOptions?: AgentOptions): Promise<Agent>;

package/lib/cjs/loader/index.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.load = load;
 exports.loadAgent = loadAgent;
 exports.loadAIGNEFile = loadAIGNEFile;
+const afs_1 = require("@aigne/afs");
 const index_js_1 = require("@aigne/platform-helpers/nodejs/index.js");
 const yaml_1 = require("yaml");
 const zod_1 = require("zod");
@@ -112,6 +113,26 @@ async function parseAgent(path, agent, options, agentOptions) {
     const memory = "memory" in agent && options?.memories?.length
         ? await loadMemory(options.memories, typeof agent.memory === "object" ? agent.memory.provider : undefined, typeof agent.memory === "object" ? agent.memory : {})
         : undefined;
+    let afs;
+    if (typeof agent.afs === "boolean") {
+        if (agent.afs) {
+            afs = new afs_1.AFS();
+        }
+    }
+    else if (agent.afs) {
+        afs = new afs_1.AFS({
+            ...agent.afs,
+            modules: agent.afs.modules &&
+                (await Promise.all(agent.afs.modules.map((m) => {
+                    const mod = typeof m === "string"
+                        ? options?.afs?.availableModules?.find((mod) => mod.module === m)
+                        : options?.afs?.availableModules?.find((mod) => mod.module === m.module);
+                    if (!mod)
+                        throw new Error(`AFS module not found: ${typeof m === "string" ? m : m.module}`);
+                    return mod.create(typeof m === "string" ? {} : m.options);
+                }))),
+        });
+    }
     const model = agent.model && typeof options?.model === "function"
         ? await options.model(agent.model)
         : undefined;
@@ -129,6 +150,7 @@ async function parseAgent(path, agent, options, agentOptions) {
             ...((await parseHooks(path, agent.hooks, options)) ?? []),
             ...[agentOptions?.hooks].flat().filter(type_utils_js_1.isNonNullable),
         ],
+        afs,
     };
     let instructions;
     if ("instructions" in agent && agent.instructions) {

package/lib/cjs/prompt/prompt-builder.js

@@ -12,8 +12,10 @@ const model_js_1 = require("../agents/model.js");
 const schema_js_1 = require("../loader/schema.js");
 const json_schema_js_1 = require("../utils/json-schema.js");
 const type_utils_js_1 = require("../utils/type-utils.js");
+const afs_builtin_prompt_js_1 = require("./prompts/afs-builtin-prompt.js");
 const memory_message_template_js_1 = require("./prompts/memory-message-template.js");
 const structured_stream_instructions_js_1 = require("./prompts/structured-stream-instructions.js");
+const afs_js_1 = require("./skills/afs.js");
 const template_js_1 = require("./template.js");
 class PromptBuilder {
     static from(instructions, { workingDir } = {}) {
@@ -70,7 +72,7 @@ class PromptBuilder {
                 ? undefined
                 : this.buildResponseFormat(options),
             outputFileType: options.agent?.outputFileType,
-            ...this.buildTools(options),
+            ...(await this.buildTools(options)),
         };
     }
     async buildImagePrompt(options) {
@@ -100,16 +102,19 @@ class PromptBuilder {
             memories.push(...options.context.memories);
         }
         if (options.agent?.afs) {
-            const history = await options.agent.afs.list(afs_1.AFSHistory.Path, {
-                limit: options.agent.maxRetrieveMemoryCount || 1,
-                orderBy: [["createdAt", "desc"]],
-            });
-            if (message) {
-                const result = await options.agent.afs.search("/", message);
-                const ms = result.list.map((entry) => ({ content: (0, yaml_1.stringify)(entry.content) }));
-                memories.push(...ms);
+            messages.push(template_js_1.SystemMessageTemplate.from(await (0, afs_builtin_prompt_js_1.getAFSSystemPrompt)(options.agent.afs)));
+            if (options.agent.afsConfig?.injectHistory) {
+                const history = await options.agent.afs.list(afs_1.AFSHistory.Path, {
+                    limit: options.agent.afsConfig.historyWindowSize || 10,
+                    orderBy: [["createdAt", "desc"]],
+                });
+                if (message) {
+                    const result = await options.agent.afs.search("/", message);
+                    const ms = result.list.map((entry) => ({ content: (0, yaml_1.stringify)(entry.content) }));
+                    memories.push(...ms);
+                }
+                memories.push(...history.list.filter((i) => (0, type_utils_js_1.isNonNullable)(i.content)));
             }
-            memories.push(...history.list.filter((i) => (0, type_utils_js_1.isNonNullable)(i.content)));
         }
         if (memories.length)
             messages.push(...(await this.convertMemoriesToMessages(memories, options)));
@@ -216,11 +221,14 @@ class PromptBuilder {
             }
             : undefined;
     }
-    buildTools(options) {
+    async buildTools(options) {
         const toolAgents = (0, type_utils_js_1.unique)((options.context?.skills ?? [])
             .concat(options.agent?.skills ?? [])
             .concat(options.agent?.memoryAgentsAsTools ? options.agent.memories : [])
             .flatMap((i) => (i.isInvokable ? i : i.skills)), (i) => i.name);
+        if (options.agent?.afs) {
+            toolAgents.push(...(await (0, afs_js_1.getAFSSkills)(options.agent.afs)));
+        }
         const tools = toolAgents.map((i) => ({
             type: "function",
             function: {

package/lib/cjs/prompt/prompts/afs-builtin-prompt.d.ts

@@ -0,0 +1,2 @@
+import type { AFS } from "@aigne/afs";
+export declare function getAFSSystemPrompt(afs: AFS): Promise<string>;

package/lib/cjs/prompt/prompts/afs-builtin-prompt.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getAFSSystemPrompt = getAFSSystemPrompt;
+const yaml_1 = require("yaml");
+async function getAFSSystemPrompt(afs) {
+    return `\
+
+<afs_usage>
+AFS (AIGNE File System) provides tools to interact with a virtual file system, allowing you to list, search, read, and write files. Use these tools to manage and retrieve files as needed.
+
+Modules:
+${(0, yaml_1.stringify)(await afs.listModules())}
+
+Available Tools:
+1. afs_list: Browse directory contents like filesystem ls/tree command - shows files and folders in a given path
+2. afs_search: Find files by content keywords - use specific keywords related to what you're looking for
+3. afs_read: Read file contents - path must be an exact file path from list or search results
+4. afs_write: Write content to a file in the AFS
+
+Workflow: Use afs_list to browse directories, afs_search to find specific content, then afs_read to access file contents.
+</afs_usage>
+`;
+}

package/lib/cjs/prompt/skills/afs.d.ts

@@ -0,0 +1,3 @@
+import type { AFS } from "@aigne/afs";
+import { type Agent } from "../../agents/agent.js";
+export declare function getAFSSkills(afs: AFS): Promise<Agent[]>;

package/lib/cjs/prompt/skills/afs.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getAFSSkills = getAFSSkills;
+const zod_1 = require("zod");
+const agent_js_1 = require("../../agents/agent.js");
+async function getAFSSkills(afs) {
+    return [
+        agent_js_1.FunctionAgent.from({
+            name: "afs_list",
+            description: "Browse directory contents in the AFS like filesystem ls/tree command - shows files and folders in the specified path",
+            inputSchema: zod_1.z.object({
+                path: zod_1.z.string().describe("The directory path to browse (e.g., '/', '/docs', '/src')"),
+                options: zod_1.z
+                    .object({
+                    recursive: zod_1.z.boolean().optional().describe("Whether to list files recursively"),
+                    maxDepth: zod_1.z.number().optional().describe("Maximum depth to list files"),
+                    limit: zod_1.z.number().optional().describe("Maximum number of entries to return"),
+                })
+                    .optional(),
+            }),
+            process: async (input) => {
+                return afs.list(input.path, input.options);
+            },
+        }),
+        agent_js_1.FunctionAgent.from({
+            name: "afs_search",
+            description: "Find files by searching content using keywords - returns matching files with their paths",
+            inputSchema: zod_1.z.object({
+                path: zod_1.z.string().describe("The directory path to search in (e.g., '/', '/docs')"),
+                query: zod_1.z
+                    .string()
+                    .describe("Keywords to search for in file contents (e.g., 'function authentication', 'database config')"),
+                options: zod_1.z
+                    .object({
+                    limit: zod_1.z.number().optional().describe("Maximum number of entries to return"),
+                })
+                    .optional(),
+            }),
+            process: async (input) => {
+                return afs.search(input.path, input.query, input.options);
+            },
+        }),
+        agent_js_1.FunctionAgent.from({
+            name: "afs_read",
+            description: "Read file contents from the AFS - path must be an exact file path from list or search results",
+            inputSchema: zod_1.z.object({
+                path: zod_1.z
+                    .string()
+                    .describe("Exact file path from list or search results (e.g., '/docs/api.md', '/src/utils/helper.js')"),
+            }),
+            process: async (input) => {
+                const file = await afs.read(input.path);
+                return {
+                    file,
+                };
+            },
+        }),
+        agent_js_1.FunctionAgent.from({
+            name: "afs_write",
+            description: "Create or update a file in the AFS with new content - overwrites existing files",
+            inputSchema: zod_1.z.object({
+                path: zod_1.z
+                    .string()
+                    .describe("Full file path where to write content (e.g., '/docs/new-file.md', '/src/component.js')"),
+                content: zod_1.z.string().describe("The text content to write to the file"),
+            }),
+            process: async (input) => {
+                const file = await afs.write(input.path, {
+                    content: input.content,
+                });
+                return { file };
+            },
+        }),
+    ];
+}

package/lib/dts/agents/agent.d.ts

@@ -122,6 +122,7 @@ export interface AgentOptions<I extends Message = Message, O extends Message = M
      */
     memory?: MemoryAgent | MemoryAgent[];
     afs?: true | AFSOptions | AFS | ((afs: AFS) => AFS);
+    afsConfig?: AFSConfig;
     asyncMemoryRecord?: boolean;
     /**
      * Maximum number of memory items to retrieve
@@ -130,6 +131,10 @@ export interface AgentOptions<I extends Message = Message, O extends Message = M
     hooks?: AgentHooks<I, O> | AgentHooks<I, O>[];
     retryOnError?: Agent<I, O>["retryOnError"] | boolean;
 }
+export interface AFSConfig {
+    injectHistory?: boolean;
+    historyWindowSize?: number;
+}
 export declare const agentOptionsSchema: ZodObject<{
     [key in keyof AgentOptions]: ZodType<AgentOptions[key]>;
 }>;
@@ -212,6 +217,7 @@ export declare abstract class Agent<I extends Message = any, O extends Message =
      */
     readonly memories: MemoryAgent[];
     afs?: AFS;
+    afsConfig?: AFSConfig;
     asyncMemoryRecord?: boolean;
     tag?: string;
     /**

package/lib/dts/loader/agent-yaml.d.ts

@@ -1,5 +1,6 @@
+import type { AFSOptions } from "@aigne/afs";
 import { type ZodType, z } from "zod";
-import type { AgentHooks, FunctionAgentFn, TaskRenderMode } from "../agents/agent.js";
+import type { AFSConfig, AgentHooks, FunctionAgentFn, TaskRenderMode } from "../agents/agent.js";
 import { AIAgentToolChoice } from "../agents/ai-agent.js";
 import { type Role } from "../agents/chat-model.js";
 import { ProcessMode, type ReflectionMode } from "../agents/team-agent.js";
@@ -19,6 +20,10 @@ export type NestAgentSchema = string | {
     defaultInput?: Record<string, any>;
     hooks?: HooksSchema | HooksSchema[];
 } | AgentSchema;
+export type AFSModuleSchema = string | {
+    module: string;
+    options?: Record<string, any>;
+};
 export interface BaseAgentSchema {
     name?: string;
     description?: string;
@@ -36,6 +41,10 @@ export interface BaseAgentSchema {
         provider: string;
         subscribeTopic?: string[];
     };
+    afs?: boolean | (Omit<AFSOptions, "modules"> & {
+        modules?: AFSModuleSchema[];
+    });
+    afsConfig?: AFSConfig;
 }
 export type Instructions = {
     role: Exclude<Role, "tool">;

package/lib/dts/loader/index.d.ts

@@ -1,3 +1,4 @@
+import { type AFSModule } from "@aigne/afs";
 import { type ZodType, z } from "zod";
 import { Agent, type AgentOptions } from "../agents/agent.js";
 import type { ChatModel } from "../agents/chat-model.js";
@@ -11,6 +12,12 @@ export interface LoadOptions {
     }[];
     model?: ChatModel | ((model?: z.infer<typeof aigneFileSchema>["model"]) => PromiseOrValue<ChatModel | undefined>);
     imageModel?: ImageModel | ((model?: z.infer<typeof aigneFileSchema>["imageModel"]) => PromiseOrValue<ImageModel | undefined>);
+    afs?: {
+        availableModules?: {
+            module: string;
+            create: (options?: Record<string, any>) => PromiseOrValue<AFSModule>;
+        }[];
+    };
 }
 export declare function load(path: string, options?: LoadOptions): Promise<AIGNEOptions>;
 export declare function loadAgent(path: string, options?: LoadOptions, agentOptions?: AgentOptions): Promise<Agent>;

package/lib/dts/prompt/prompts/afs-builtin-prompt.d.ts

@@ -0,0 +1,2 @@
+import type { AFS } from "@aigne/afs";
+export declare function getAFSSystemPrompt(afs: AFS): Promise<string>;

package/lib/dts/prompt/skills/afs.d.ts

@@ -0,0 +1,3 @@
+import type { AFS } from "@aigne/afs";
+import { type Agent } from "../../agents/agent.js";
+export declare function getAFSSkills(afs: AFS): Promise<Agent[]>;

package/lib/esm/agents/agent.d.ts

@@ -122,6 +122,7 @@ export interface AgentOptions<I extends Message = Message, O extends Message = M
      */
     memory?: MemoryAgent | MemoryAgent[];
     afs?: true | AFSOptions | AFS | ((afs: AFS) => AFS);
+    afsConfig?: AFSConfig;
     asyncMemoryRecord?: boolean;
     /**
      * Maximum number of memory items to retrieve
@@ -130,6 +131,10 @@ export interface AgentOptions<I extends Message = Message, O extends Message = M
     hooks?: AgentHooks<I, O> | AgentHooks<I, O>[];
     retryOnError?: Agent<I, O>["retryOnError"] | boolean;
 }
+export interface AFSConfig {
+    injectHistory?: boolean;
+    historyWindowSize?: number;
+}
 export declare const agentOptionsSchema: ZodObject<{
     [key in keyof AgentOptions]: ZodType<AgentOptions[key]>;
 }>;
@@ -212,6 +217,7 @@ export declare abstract class Agent<I extends Message = any, O extends Message =
      */
     readonly memories: MemoryAgent[];
     afs?: AFS;
+    afsConfig?: AFSConfig;
     asyncMemoryRecord?: boolean;
     tag?: string;
     /**

package/lib/esm/agents/agent.js

@@ -113,6 +113,7 @@ export class Agent {
                     : options.afs instanceof AFS
                         ? options.afs
                         : new AFS(options.afs);
+        this.afsConfig = options.afsConfig;
         this.asyncMemoryRecord = options.asyncMemoryRecord;
         this.maxRetrieveMemoryCount = options.maxRetrieveMemoryCount;
         this.hooks = flat(options.hooks);
@@ -131,6 +132,7 @@ export class Agent {
      */
     memories = [];
     afs;
+    afsConfig;
     asyncMemoryRecord;
     tag;
     /**

package/lib/esm/loader/agent-yaml.d.ts

@@ -1,5 +1,6 @@
+import type { AFSOptions } from "@aigne/afs";
 import { type ZodType, z } from "zod";
-import type { AgentHooks, FunctionAgentFn, TaskRenderMode } from "../agents/agent.js";
+import type { AFSConfig, AgentHooks, FunctionAgentFn, TaskRenderMode } from "../agents/agent.js";
 import { AIAgentToolChoice } from "../agents/ai-agent.js";
 import { type Role } from "../agents/chat-model.js";
 import { ProcessMode, type ReflectionMode } from "../agents/team-agent.js";
@@ -19,6 +20,10 @@ export type NestAgentSchema = string | {
     defaultInput?: Record<string, any>;
     hooks?: HooksSchema | HooksSchema[];
 } | AgentSchema;
+export type AFSModuleSchema = string | {
+    module: string;
+    options?: Record<string, any>;
+};
 export interface BaseAgentSchema {
     name?: string;
     description?: string;
@@ -36,6 +41,10 @@ export interface BaseAgentSchema {
         provider: string;
         subscribeTopic?: string[];
     };
+    afs?: boolean | (Omit<AFSOptions, "modules"> & {
+        modules?: AFSModuleSchema[];
+    });
+    afsConfig?: AFSConfig;
 }
 export type Instructions = {
     role: Exclude<Role, "tool">;

package/lib/esm/loader/agent-yaml.js

@@ -49,6 +49,25 @@ export async function parseAgentFile(path, data) {
                     subscribeTopic: optionalize(z.array(z.string())),
                 })),
             ])),
+            afs: optionalize(z.union([
+                z.boolean(),
+                camelizeSchema(z.object({
+                    storage: optionalize(z.object({
+                        url: optionalize(z.string()),
+                    })),
+                    modules: optionalize(z.array(z.union([
+                        z.string(),
+                        z.object({
+                            module: z.string(),
+                            options: optionalize(z.record(z.any())),
+                        }),
+                    ]))),
+                })),
+            ])),
+            afsConfig: optionalize(camelizeSchema(z.object({
+                injectHistory: optionalize(z.boolean()),
+                historyWindowSize: optionalize(z.number().int().min(1)),
+            }))),
         });
         const instructionItemSchema = z.union([
             z.object({

package/lib/esm/loader/index.d.ts

@@ -1,3 +1,4 @@
+import { type AFSModule } from "@aigne/afs";
 import { type ZodType, z } from "zod";
 import { Agent, type AgentOptions } from "../agents/agent.js";
 import type { ChatModel } from "../agents/chat-model.js";
@@ -11,6 +12,12 @@ export interface LoadOptions {
     }[];
     model?: ChatModel | ((model?: z.infer<typeof aigneFileSchema>["model"]) => PromiseOrValue<ChatModel | undefined>);
     imageModel?: ImageModel | ((model?: z.infer<typeof aigneFileSchema>["imageModel"]) => PromiseOrValue<ImageModel | undefined>);
+    afs?: {
+        availableModules?: {
+            module: string;
+            create: (options?: Record<string, any>) => PromiseOrValue<AFSModule>;
+        }[];
+    };
 }
 export declare function load(path: string, options?: LoadOptions): Promise<AIGNEOptions>;
 export declare function loadAgent(path: string, options?: LoadOptions, agentOptions?: AgentOptions): Promise<Agent>;

package/lib/esm/loader/index.js

@@ -1,3 +1,4 @@
+import { AFS } from "@aigne/afs";
 import { nodejs } from "@aigne/platform-helpers/nodejs/index.js";
 import { parse } from "yaml";
 import { z } from "zod";
@@ -107,6 +108,26 @@ async function parseAgent(path, agent, options, agentOptions) {
     const memory = "memory" in agent && options?.memories?.length
         ? await loadMemory(options.memories, typeof agent.memory === "object" ? agent.memory.provider : undefined, typeof agent.memory === "object" ? agent.memory : {})
         : undefined;
+    let afs;
+    if (typeof agent.afs === "boolean") {
+        if (agent.afs) {
+            afs = new AFS();
+        }
+    }
+    else if (agent.afs) {
+        afs = new AFS({
+            ...agent.afs,
+            modules: agent.afs.modules &&
+                (await Promise.all(agent.afs.modules.map((m) => {
+                    const mod = typeof m === "string"
+                        ? options?.afs?.availableModules?.find((mod) => mod.module === m)
+                        : options?.afs?.availableModules?.find((mod) => mod.module === m.module);
+                    if (!mod)
+                        throw new Error(`AFS module not found: ${typeof m === "string" ? m : m.module}`);
+                    return mod.create(typeof m === "string" ? {} : m.options);
+                }))),
+        });
+    }
     const model = agent.model && typeof options?.model === "function"
         ? await options.model(agent.model)
         : undefined;
@@ -124,6 +145,7 @@ async function parseAgent(path, agent, options, agentOptions) {
             ...((await parseHooks(path, agent.hooks, options)) ?? []),
             ...[agentOptions?.hooks].flat().filter(isNonNullable),
         ],
+        afs,
     };
     let instructions;
     if ("instructions" in agent && agent.instructions) {

package/lib/esm/prompt/prompt-builder.js

@@ -9,8 +9,10 @@ import { fileUnionContentsSchema } from "../agents/model.js";
 import { optionalize } from "../loader/schema.js";
 import { outputSchemaToResponseFormatSchema } from "../utils/json-schema.js";
 import { checkArguments, flat, isNonNullable, isRecord, unique } from "../utils/type-utils.js";
+import { getAFSSystemPrompt } from "./prompts/afs-builtin-prompt.js";
 import { MEMORY_MESSAGE_TEMPLATE } from "./prompts/memory-message-template.js";
 import { STRUCTURED_STREAM_INSTRUCTIONS } from "./prompts/structured-stream-instructions.js";
+import { getAFSSkills } from "./skills/afs.js";
 import { AgentMessageTemplate, ChatMessagesTemplate, PromptTemplate, SystemMessageTemplate, UserMessageTemplate, } from "./template.js";
 export class PromptBuilder {
     static from(instructions, { workingDir } = {}) {
@@ -67,7 +69,7 @@ export class PromptBuilder {
                 ? undefined
                 : this.buildResponseFormat(options),
             outputFileType: options.agent?.outputFileType,
-            ...this.buildTools(options),
+            ...(await this.buildTools(options)),
         };
     }
     async buildImagePrompt(options) {
@@ -97,16 +99,19 @@ export class PromptBuilder {
             memories.push(...options.context.memories);
         }
         if (options.agent?.afs) {
-            const history = await options.agent.afs.list(AFSHistory.Path, {
-                limit: options.agent.maxRetrieveMemoryCount || 1,
-                orderBy: [["createdAt", "desc"]],
-            });
-            if (message) {
-                const result = await options.agent.afs.search("/", message);
-                const ms = result.list.map((entry) => ({ content: stringify(entry.content) }));
-                memories.push(...ms);
+            messages.push(SystemMessageTemplate.from(await getAFSSystemPrompt(options.agent.afs)));
+            if (options.agent.afsConfig?.injectHistory) {
+                const history = await options.agent.afs.list(AFSHistory.Path, {
+                    limit: options.agent.afsConfig.historyWindowSize || 10,
+                    orderBy: [["createdAt", "desc"]],
+                });
+                if (message) {
+                    const result = await options.agent.afs.search("/", message);
+                    const ms = result.list.map((entry) => ({ content: stringify(entry.content) }));
+                    memories.push(...ms);
+                }
+                memories.push(...history.list.filter((i) => isNonNullable(i.content)));
             }
-            memories.push(...history.list.filter((i) => isNonNullable(i.content)));
         }
         if (memories.length)
             messages.push(...(await this.convertMemoriesToMessages(memories, options)));
@@ -213,11 +218,14 @@ export class PromptBuilder {
             }
             : undefined;
     }
-    buildTools(options) {
+    async buildTools(options) {
         const toolAgents = unique((options.context?.skills ?? [])
             .concat(options.agent?.skills ?? [])
             .concat(options.agent?.memoryAgentsAsTools ? options.agent.memories : [])
             .flatMap((i) => (i.isInvokable ? i : i.skills)), (i) => i.name);
+        if (options.agent?.afs) {
+            toolAgents.push(...(await getAFSSkills(options.agent.afs)));
+        }
         const tools = toolAgents.map((i) => ({
             type: "function",
             function: {

package/lib/esm/prompt/prompts/afs-builtin-prompt.d.ts

@@ -0,0 +1,2 @@
+import type { AFS } from "@aigne/afs";
+export declare function getAFSSystemPrompt(afs: AFS): Promise<string>;

package/lib/esm/prompt/prompts/afs-builtin-prompt.js

@@ -0,0 +1,20 @@
+import { stringify } from "yaml";
+export async function getAFSSystemPrompt(afs) {
+    return `\
+
+<afs_usage>
+AFS (AIGNE File System) provides tools to interact with a virtual file system, allowing you to list, search, read, and write files. Use these tools to manage and retrieve files as needed.
+
+Modules:
+${stringify(await afs.listModules())}
+
+Available Tools:
+1. afs_list: Browse directory contents like filesystem ls/tree command - shows files and folders in a given path
+2. afs_search: Find files by content keywords - use specific keywords related to what you're looking for
+3. afs_read: Read file contents - path must be an exact file path from list or search results
+4. afs_write: Write content to a file in the AFS
+
+Workflow: Use afs_list to browse directories, afs_search to find specific content, then afs_read to access file contents.
+</afs_usage>
+`;
+}

package/lib/esm/prompt/skills/afs.d.ts

@@ -0,0 +1,3 @@
+import type { AFS } from "@aigne/afs";
+import { type Agent } from "../../agents/agent.js";
+export declare function getAFSSkills(afs: AFS): Promise<Agent[]>;

package/lib/esm/prompt/skills/afs.js

@@ -0,0 +1,72 @@
+import { z } from "zod";
+import { FunctionAgent } from "../../agents/agent.js";
+export async function getAFSSkills(afs) {
+    return [
+        FunctionAgent.from({
+            name: "afs_list",
+            description: "Browse directory contents in the AFS like filesystem ls/tree command - shows files and folders in the specified path",
+            inputSchema: z.object({
+                path: z.string().describe("The directory path to browse (e.g., '/', '/docs', '/src')"),
+                options: z
+                    .object({
+                    recursive: z.boolean().optional().describe("Whether to list files recursively"),
+                    maxDepth: z.number().optional().describe("Maximum depth to list files"),
+                    limit: z.number().optional().describe("Maximum number of entries to return"),
+                })
+                    .optional(),
+            }),
+            process: async (input) => {
+                return afs.list(input.path, input.options);
+            },
+        }),
+        FunctionAgent.from({
+            name: "afs_search",
+            description: "Find files by searching content using keywords - returns matching files with their paths",
+            inputSchema: z.object({
+                path: z.string().describe("The directory path to search in (e.g., '/', '/docs')"),
+                query: z
+                    .string()
+                    .describe("Keywords to search for in file contents (e.g., 'function authentication', 'database config')"),
+                options: z
+                    .object({
+                    limit: z.number().optional().describe("Maximum number of entries to return"),
+                })
+                    .optional(),
+            }),
+            process: async (input) => {
+                return afs.search(input.path, input.query, input.options);
+            },
+        }),
+        FunctionAgent.from({
+            name: "afs_read",
+            description: "Read file contents from the AFS - path must be an exact file path from list or search results",
+            inputSchema: z.object({
+                path: z
+                    .string()
+                    .describe("Exact file path from list or search results (e.g., '/docs/api.md', '/src/utils/helper.js')"),
+            }),
+            process: async (input) => {
+                const file = await afs.read(input.path);
+                return {
+                    file,
+                };
+            },
+        }),
+        FunctionAgent.from({
+            name: "afs_write",
+            description: "Create or update a file in the AFS with new content - overwrites existing files",
+            inputSchema: z.object({
+                path: z
+                    .string()
+                    .describe("Full file path where to write content (e.g., '/docs/new-file.md', '/src/component.js')"),
+                content: z.string().describe("The text content to write to the file"),
+            }),
+            process: async (input) => {
+                const file = await afs.write(input.path, {
+                    content: input.content,
+                });
+                return { file };
+            },
+        }),
+    ];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigne/core",
-  "version": "1.63.0-beta.2",
+  "version": "1.63.0-beta.4",
   "description": "The functional core of agentic AI",
   "publishConfig": {
     "access": "public"
@@ -92,9 +92,9 @@
     "zod": "^3.25.67",
     "zod-from-json-schema": "^0.0.5",
     "zod-to-json-schema": "^3.24.6",
-    "@aigne/afs": "^1.0.0",
-    "@aigne/platform-helpers": "^0.6.3",
-    "@aigne/observability-api": "^0.11.2-beta"
+    "@aigne/afs": "^1.1.0-beta",
+    "@aigne/observability-api": "^0.11.2-beta.1",
+    "@aigne/platform-helpers": "^0.6.3"
   },
   "devDependencies": {
     "@types/bun": "^1.2.22",