@aigne/core 1.67.0 → 1.68.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## [1.68.0](https://github.com/AIGNE-io/aigne-framework/compare/core-v1.68.0-beta...core-v1.68.0) (2025-11-14)
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @aigne/afs bumped to 1.2.0
+    * @aigne/afs-history bumped to 1.0.1
+
+## [1.68.0-beta](https://github.com/AIGNE-io/aigne-framework/compare/core-v1.67.0...core-v1.68.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))
+
+
+### Bug Fixes
+
+* properly handle SIGINT to flush observability data before exit ([#739](https://github.com/AIGNE-io/aigne-framework/issues/739)) ([99b4503](https://github.com/AIGNE-io/aigne-framework/commit/99b45033d5f3bcc1f830b583f9cca7258b00606f))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @aigne/afs bumped to 1.2.0-beta
+    * @aigne/afs-history bumped to 1.0.0
+
 ## [1.67.0](https://github.com/AIGNE-io/aigne-framework/compare/core-v1.67.0-beta.4...core-v1.67.0) (2025-11-12)
 
 

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

@@ -1,4 +1,4 @@
-import { AFS, type AFSOptions } from "@aigne/afs";
+import { AFS, type AFSEntry, type AFSListOptions, type AFSModule, type AFSOptions, type AFSSearchOptions } from "@aigne/afs";
 import { nodejs } from "@aigne/platform-helpers/nodejs/index.js";
 import type * as prompts from "@inquirer/prompts";
 import { type ZodObject, type ZodType } from "zod";
@@ -123,7 +123,6 @@ 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
@@ -132,10 +131,6 @@ 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]>;
 }>;
@@ -200,7 +195,7 @@ export interface AgentInvokeOptions<U extends UserContext = UserContext> {
  * Here's an example of how to create a custom agent:
  * {@includeCode ../../test/agents/agent.test.ts#example-custom-agent}
  */
-export declare abstract class Agent<I extends Message = any, O extends Message = any> {
+export declare abstract class Agent<I extends Message = any, O extends Message = any> implements AFSModule {
     /**
      * Custom object inspection behavior
      *
@@ -218,7 +213,6 @@ export declare abstract class Agent<I extends Message = any, O extends Message =
      */
     readonly memories: MemoryAgent[];
     afs?: AFS;
-    afsConfig?: AFSConfig;
     asyncMemoryRecord?: boolean;
     tag?: string;
     /**
@@ -564,6 +558,26 @@ export declare abstract class Agent<I extends Message = any, O extends Message =
      * {@includeCode ../../test/agents/agent.test.ts#example-agent-shutdown-by-using}
      */
     [Symbol.asyncDispose](): Promise<void>;
+    /** For AFSModule interface **/
+    private agentToAFSEntry;
+    private findAgentByAFSPath;
+    list(_path: string, _options?: AFSListOptions): Promise<{
+        list: AFSEntry[];
+        message?: string;
+    }>;
+    read(path: string): 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: Context;
+    }): Promise<{
+        result: Record<string, any>;
+    }>;
 }
 export type AgentInput<T extends Agent> = T extends Agent<infer I, any> ? I : never;
 export type AgentOutput<T extends Agent> = T extends Agent<any, infer O> ? O : never;

package/lib/cjs/agents/agent.js

@@ -50,7 +50,9 @@ const afs_1 = require("@aigne/afs");
 const index_js_1 = require("@aigne/platform-helpers/nodejs/index.js");
 const fast_deep_equal_1 = __importDefault(require("fast-deep-equal"));
 const nunjucks_1 = __importDefault(require("nunjucks"));
+const ufo_1 = require("ufo");
 const zod_1 = require("zod");
+const zod_to_json_schema_1 = require("zod-to-json-schema");
 const agent_utils_js_1 = require("../utils/agent-utils.js");
 const json_schema_js_1 = require("../utils/json-schema.js");
 const logger_js_1 = require("../utils/logger.js");
@@ -161,7 +163,6 @@ 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);
@@ -180,7 +181,6 @@ class Agent {
      */
     memories = [];
     afs;
-    afsConfig;
     asyncMemoryRecord;
     tag;
     /**
@@ -737,6 +737,59 @@ class Agent {
     async [Symbol.asyncDispose]() {
         await this.shutdown();
     }
+    /** For AFSModule interface **/
+    agentToAFSEntry(agent) {
+        return {
+            id: `/${this.name}/${agent.name}`,
+            path: agent === this ? "/" : (0, ufo_1.joinURL)("/", agent.name),
+            summary: agent.description,
+            metadata: {
+                execute: agent.isInvokable
+                    ? {
+                        name: agent.name,
+                        description: agent.description,
+                        inputSchema: (0, zod_to_json_schema_1.zodToJsonSchema)(agent.inputSchema),
+                        outputSchema: (0, zod_to_json_schema_1.zodToJsonSchema)(agent.outputSchema),
+                    }
+                    : undefined,
+            },
+        };
+    }
+    findAgentByAFSPath(path) {
+        let agent;
+        if (path === "/") {
+            agent = this;
+        }
+        else {
+            const name = path.split("/")[1];
+            agent = this.skills.find((s) => s.name === name);
+        }
+        return agent;
+    }
+    // TODO: support list skills inside agent path, and use options to filter skills
+    async list(_path, _options) {
+        const agents = [this, ...this.skills];
+        return { list: agents.map((agent) => this.agentToAFSEntry(agent)) };
+    }
+    async read(path) {
+        const agent = this.findAgentByAFSPath(path);
+        if (!agent) {
+            return { message: `Agent not found at path: ${path}` };
+        }
+        return {
+            result: this.agentToAFSEntry(agent),
+        };
+    }
+    // TODO: implement search inside agent skills
+    async search(path, _query, options) {
+        return this.list(path, options);
+    }
+    async exec(path, args, options) {
+        const agent = this.findAgentByAFSPath(path);
+        if (!agent)
+            throw new Error(`Agent not found at path: ${path}`);
+        return { result: await options.context.invoke(agent, args) };
+    }
 }
 exports.Agent = Agent;
 /**

package/lib/cjs/aigne/aigne.js

@@ -221,7 +221,7 @@ class AIGNE {
      * This registers handlers for SIGINT and exit events to properly terminate all agents.
      */
     initProcessExitHandler() {
-        const shutdownAndExit = () => this.shutdown().finally(() => process.exit(0));
+        const shutdownAndExit = () => this.shutdown();
         process.on("SIGINT", shutdownAndExit);
         process.on("exit", shutdownAndExit);
     }

package/lib/cjs/aigne/context.d.ts

@@ -182,6 +182,7 @@ export declare class AIGNEContext implements Context {
     subscribe: Context["subscribe"];
     unsubscribe: Context["unsubscribe"];
     emit<K extends keyof ContextEmitEventMap>(eventName: K, ...args: Args<K, ContextEmitEventMap>): boolean;
+    initProcessExitHandler(): void;
     private trace;
     on<K extends keyof ContextEventMap>(eventName: K, listener: Listener<K, ContextEventMap>): this;
     once<K extends keyof ContextEventMap>(eventName: K, listener: Listener<K, ContextEventMap>): this;

package/lib/cjs/aigne/context.js

@@ -46,6 +46,7 @@ class AIGNEContext {
             this.rootId = this.span?.spanContext?.().traceId ?? (0, uuid_1.v7)();
         }
         this.id = this.span?.spanContext()?.spanId ?? (0, uuid_1.v7)();
+        this.initProcessExitHandler();
     }
     id;
     parentId;
@@ -201,6 +202,23 @@ class AIGNEContext {
         this.trace(eventName, args, b);
         return this.internal.events.emit(eventName, ...newArgs);
     }
+    initProcessExitHandler() {
+        process.on("SIGINT", async () => {
+            try {
+                if (process.env.AIGNE_OBSERVABILITY_DISABLED)
+                    return;
+                const span = this.span;
+                if (!span)
+                    return;
+                span.setStatus({ code: api_1.SpanStatusCode.ERROR, message: "SIGINT" });
+                span.end();
+                await this.observer?.flush(span);
+            }
+            finally {
+                process.exit(0);
+            }
+        });
+    }
     async trace(eventName, args, b) {
         if (process.env.AIGNE_OBSERVABILITY_DISABLED)
             return;

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

@@ -1,6 +1,6 @@
 import type { AFSOptions } from "@aigne/afs";
 import { type ZodType, z } from "zod";
-import type { AFSConfig, AgentHooks, FunctionAgentFn, TaskRenderMode } from "../agents/agent.js";
+import type { 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";
@@ -44,7 +44,6 @@ export interface BaseAgentSchema {
     afs?: boolean | (Omit<AFSOptions, "modules"> & {
         modules?: AFSModuleSchema[];
     });
-    afsConfig?: AFSConfig;
 }
 export type Instructions = {
     role: Exclude<Role, "tool">;

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

@@ -57,22 +57,15 @@ async function parseAgentFile(path, data) {
             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({
+                        (0, schema_js_1.camelizeSchema)(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

@@ -15,6 +15,7 @@ export interface LoadOptions {
     afs?: {
         availableModules?: {
             module: string;
+            alias?: string[];
             create: (options?: Record<string, any>) => PromiseOrValue<AFSModule>;
         }[];
     };

package/lib/cjs/loader/index.js

@@ -119,23 +119,19 @@ async function parseAgent(path, agent, options, agentOptions) {
         : undefined;
     let afs;
     if (typeof agent.afs === "boolean") {
-        if (agent.afs) {
+        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);
-                }))),
-        });
+        afs = new afs_1.AFS();
+        for (const m of agent.afs.modules || []) {
+            const moduleName = typeof m === "string" ? m : m.module;
+            const mod = options?.afs?.availableModules?.find((mod) => mod.module === moduleName || mod.alias?.includes(moduleName));
+            if (!mod)
+                throw new Error(`AFS module not found: ${typeof m === "string" ? m : m.module}`);
+            const module = await mod.create(typeof m === "string" ? {} : m.options);
+            afs.mount(module);
+        }
     }
     const model = agent.model && typeof options?.model === "function"
         ? await options.model({ ...options.aigne?.model, ...(0, type_utils_js_1.omitBy)(agent.model, (v) => (0, type_utils_js_1.isNil)(v)) })

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

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PromptBuilder = void 0;
-const afs_1 = require("@aigne/afs");
+const afs_history_1 = require("@aigne/afs-history");
 const index_js_1 = require("@aigne/platform-helpers/nodejs/index.js");
 const yaml_1 = require("yaml");
 const zod_1 = require("zod");
@@ -113,21 +113,50 @@ class PromptBuilder {
         if (options.agent?.useMemoriesFromContext && options.context?.memories?.length) {
             memories.push(...options.context.memories);
         }
-        if (options.agent?.afs) {
-            messages.push(await template_js_1.SystemMessageTemplate.from(await (0, afs_builtin_prompt_js_1.getAFSSystemPrompt)(options.agent.afs)).format({}));
-            if (options.agent.afsConfig?.injectHistory) {
-                const history = await options.agent.afs.list(afs_1.AFSHistory.Path, {
-                    limit: options.agent.afsConfig.historyWindowSize || 10,
+        const afs = options.agent?.afs;
+        if (afs) {
+            const historyModule = (await afs.listModules()).find((m) => m.module instanceof afs_history_1.AFSHistory);
+            messages.push(await template_js_1.SystemMessageTemplate.from(await (0, afs_builtin_prompt_js_1.getAFSSystemPrompt)(afs)).format({}));
+            if (historyModule) {
+                const history = await afs.list(historyModule.path, {
+                    limit: options.agent?.maxRetrieveMemoryCount || 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
                     .reverse()
                     .filter((i) => (0, type_utils_js_1.isNonNullable)(i.content)));
+                if (message) {
+                    const result = await afs.search("/", message);
+                    const ms = result.list
+                        .map((entry) => {
+                        if (entry.metadata?.execute)
+                            return null;
+                        const content = entry.content || entry.summary;
+                        if (!content)
+                            return null;
+                        return {
+                            content,
+                            description: entry.description,
+                        };
+                    })
+                        .filter(type_utils_js_1.isNonNullable);
+                    memories.push(...ms);
+                    const executable = result.list.filter((i) => !!i.metadata?.execute);
+                    if (executable.length) {
+                        messages.push({
+                            role: "system",
+                            content: await template_js_1.PromptTemplate.from(afs_builtin_prompt_js_1.AFS_EXECUTABLE_TOOLS_PROMPT_TEMPLATE).format({
+                                tools: executable.map((entry) => ({
+                                    path: entry.path,
+                                    name: entry.metadata.execute.name,
+                                    description: entry.metadata.execute.description,
+                                    inputSchema: entry.metadata.execute.inputSchema,
+                                    outputSchema: entry.metadata.execute.outputSchema,
+                                })),
+                            }),
+                        });
+                    }
+                }
             }
         }
         if (memories.length)
@@ -232,7 +261,8 @@ class PromptBuilder {
             result.push({ role: "agent", content: agentMessageContent });
             return result;
         };
-        for (const { content } of memories) {
+        for (const memory of memories) {
+            const { content } = memory;
             if ((0, type_utils_js_1.isRecord)(content) &&
                 "input" in content &&
                 content.input &&
@@ -241,7 +271,7 @@ class PromptBuilder {
                 messages.push(...(await convertMemoryToMessage(content)));
             }
             else {
-                other.push(content);
+                other.push(memory);
             }
         }
         if (other.length) {

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

@@ -1,2 +1,3 @@
 import type { AFS } from "@aigne/afs";
 export declare function getAFSSystemPrompt(afs: AFS): Promise<string>;
+export declare const AFS_EXECUTABLE_TOOLS_PROMPT_TEMPLATE = "<afs_executable_tools>\nHere are the executable tools available in the AFS you can use:\n\n{{ tools | yaml.stringify }}\n</afs_executable_tools>\n";

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

@@ -1,23 +1,33 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.AFS_EXECUTABLE_TOOLS_PROMPT_TEMPLATE = void 0;
 exports.getAFSSystemPrompt = getAFSSystemPrompt;
 const yaml_1 = require("yaml");
+const type_utils_js_1 = require("../../utils/type-utils.js");
 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.
+AFS (Agentic File System) provides tools to interact with a virtual file system,
+allowing you to list, search, read, and write files, or execute a useful tool from the available modules.
+Use these tools to manage and retrieve files as needed.
 
-Modules:
-${(0, yaml_1.stringify)(await afs.listModules())}
+Provided modules:
+${(0, yaml_1.stringify)((await afs.listModules()).map((i) => (0, type_utils_js_1.pick)(i, ["name", "path", "description"])))}
 
-Available Tools:
+Global tools to interact with the AFS:
 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.
+5. afs_exec: Execute a executable tool from the available modules
 </afs_usage>
 `;
 }
+exports.AFS_EXECUTABLE_TOOLS_PROMPT_TEMPLATE = `\
+<afs_executable_tools>
+Here are the executable tools available in the AFS you can use:
+
+{{ tools | yaml.stringify }}
+</afs_executable_tools>
+`;

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

@@ -92,5 +92,18 @@ async function getAFSSkills(afs) {
                 };
             },
         }),
+        agent_js_1.FunctionAgent.from({
+            name: "afs_exec",
+            description: "Execute a function or command available in the AFS modules",
+            inputSchema: zod_1.z.object({
+                path: zod_1.z.string().describe("The exact path to the executable entry in AFS"),
+                args: zod_1.z
+                    .string()
+                    .describe("JSON stringified arguments to pass to the executable, must be an object matching the input schema of the executable"),
+            }),
+            process: async ({ path, args }, options) => {
+                return await afs.exec(path, JSON.parse(args), options);
+            },
+        }),
     ];
 }

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

@@ -1,4 +1,4 @@
-import { AFS, type AFSOptions } from "@aigne/afs";
+import { AFS, type AFSEntry, type AFSListOptions, type AFSModule, type AFSOptions, type AFSSearchOptions } from "@aigne/afs";
 import { nodejs } from "@aigne/platform-helpers/nodejs/index.js";
 import type * as prompts from "@inquirer/prompts";
 import { type ZodObject, type ZodType } from "zod";
@@ -123,7 +123,6 @@ 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
@@ -132,10 +131,6 @@ 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]>;
 }>;
@@ -200,7 +195,7 @@ export interface AgentInvokeOptions<U extends UserContext = UserContext> {
  * Here's an example of how to create a custom agent:
  * {@includeCode ../../test/agents/agent.test.ts#example-custom-agent}
  */
-export declare abstract class Agent<I extends Message = any, O extends Message = any> {
+export declare abstract class Agent<I extends Message = any, O extends Message = any> implements AFSModule {
     /**
      * Custom object inspection behavior
      *
@@ -218,7 +213,6 @@ export declare abstract class Agent<I extends Message = any, O extends Message =
      */
     readonly memories: MemoryAgent[];
     afs?: AFS;
-    afsConfig?: AFSConfig;
     asyncMemoryRecord?: boolean;
     tag?: string;
     /**
@@ -564,6 +558,26 @@ export declare abstract class Agent<I extends Message = any, O extends Message =
      * {@includeCode ../../test/agents/agent.test.ts#example-agent-shutdown-by-using}
      */
     [Symbol.asyncDispose](): Promise<void>;
+    /** For AFSModule interface **/
+    private agentToAFSEntry;
+    private findAgentByAFSPath;
+    list(_path: string, _options?: AFSListOptions): Promise<{
+        list: AFSEntry[];
+        message?: string;
+    }>;
+    read(path: string): 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: Context;
+    }): Promise<{
+        result: Record<string, any>;
+    }>;
 }
 export type AgentInput<T extends Agent> = T extends Agent<infer I, any> ? I : never;
 export type AgentOutput<T extends Agent> = T extends Agent<any, infer O> ? O : never;

package/lib/dts/aigne/context.d.ts

@@ -182,6 +182,7 @@ export declare class AIGNEContext implements Context {
     subscribe: Context["subscribe"];
     unsubscribe: Context["unsubscribe"];
     emit<K extends keyof ContextEmitEventMap>(eventName: K, ...args: Args<K, ContextEmitEventMap>): boolean;
+    initProcessExitHandler(): void;
     private trace;
     on<K extends keyof ContextEventMap>(eventName: K, listener: Listener<K, ContextEventMap>): this;
     once<K extends keyof ContextEventMap>(eventName: K, listener: Listener<K, ContextEventMap>): this;

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

@@ -1,6 +1,6 @@
 import type { AFSOptions } from "@aigne/afs";
 import { type ZodType, z } from "zod";
-import type { AFSConfig, AgentHooks, FunctionAgentFn, TaskRenderMode } from "../agents/agent.js";
+import type { 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";
@@ -44,7 +44,6 @@ export interface BaseAgentSchema {
     afs?: boolean | (Omit<AFSOptions, "modules"> & {
         modules?: AFSModuleSchema[];
     });
-    afsConfig?: AFSConfig;
 }
 export type Instructions = {
     role: Exclude<Role, "tool">;

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

@@ -15,6 +15,7 @@ export interface LoadOptions {
     afs?: {
         availableModules?: {
             module: string;
+            alias?: string[];
             create: (options?: Record<string, any>) => PromiseOrValue<AFSModule>;
         }[];
     };

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

@@ -1,2 +1,3 @@
 import type { AFS } from "@aigne/afs";
 export declare function getAFSSystemPrompt(afs: AFS): Promise<string>;
+export declare const AFS_EXECUTABLE_TOOLS_PROMPT_TEMPLATE = "<afs_executable_tools>\nHere are the executable tools available in the AFS you can use:\n\n{{ tools | yaml.stringify }}\n</afs_executable_tools>\n";

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

@@ -1,4 +1,4 @@
-import { AFS, type AFSOptions } from "@aigne/afs";
+import { AFS, type AFSEntry, type AFSListOptions, type AFSModule, type AFSOptions, type AFSSearchOptions } from "@aigne/afs";
 import { nodejs } from "@aigne/platform-helpers/nodejs/index.js";
 import type * as prompts from "@inquirer/prompts";
 import { type ZodObject, type ZodType } from "zod";
@@ -123,7 +123,6 @@ 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
@@ -132,10 +131,6 @@ 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]>;
 }>;
@@ -200,7 +195,7 @@ export interface AgentInvokeOptions<U extends UserContext = UserContext> {
  * Here's an example of how to create a custom agent:
  * {@includeCode ../../test/agents/agent.test.ts#example-custom-agent}
  */
-export declare abstract class Agent<I extends Message = any, O extends Message = any> {
+export declare abstract class Agent<I extends Message = any, O extends Message = any> implements AFSModule {
     /**
      * Custom object inspection behavior
      *
@@ -218,7 +213,6 @@ export declare abstract class Agent<I extends Message = any, O extends Message =
      */
     readonly memories: MemoryAgent[];
     afs?: AFS;
-    afsConfig?: AFSConfig;
     asyncMemoryRecord?: boolean;
     tag?: string;
     /**
@@ -564,6 +558,26 @@ export declare abstract class Agent<I extends Message = any, O extends Message =
      * {@includeCode ../../test/agents/agent.test.ts#example-agent-shutdown-by-using}
      */
     [Symbol.asyncDispose](): Promise<void>;
+    /** For AFSModule interface **/
+    private agentToAFSEntry;
+    private findAgentByAFSPath;
+    list(_path: string, _options?: AFSListOptions): Promise<{
+        list: AFSEntry[];
+        message?: string;
+    }>;
+    read(path: string): 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: Context;
+    }): Promise<{
+        result: Record<string, any>;
+    }>;
 }
 export type AgentInput<T extends Agent> = T extends Agent<infer I, any> ? I : never;
 export type AgentOutput<T extends Agent> = T extends Agent<any, infer O> ? O : never;

package/lib/esm/agents/agent.js

@@ -1,8 +1,10 @@
-import { AFS } from "@aigne/afs";
+import { AFS, } from "@aigne/afs";
 import { nodejs } from "@aigne/platform-helpers/nodejs/index.js";
 import equal from "fast-deep-equal";
 import nunjucks from "nunjucks";
+import { joinURL } from "ufo";
 import { z } from "zod";
+import { zodToJsonSchema } from "zod-to-json-schema";
 import { sortHooks } from "../utils/agent-utils.js";
 import { isZodSchema } from "../utils/json-schema.js";
 import { logger } from "../utils/logger.js";
@@ -113,7 +115,6 @@ 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);
@@ -132,7 +133,6 @@ export class Agent {
      */
     memories = [];
     afs;
-    afsConfig;
     asyncMemoryRecord;
     tag;
     /**
@@ -689,6 +689,59 @@ export class Agent {
     async [Symbol.asyncDispose]() {
         await this.shutdown();
     }
+    /** For AFSModule interface **/
+    agentToAFSEntry(agent) {
+        return {
+            id: `/${this.name}/${agent.name}`,
+            path: agent === this ? "/" : joinURL("/", agent.name),
+            summary: agent.description,
+            metadata: {
+                execute: agent.isInvokable
+                    ? {
+                        name: agent.name,
+                        description: agent.description,
+                        inputSchema: zodToJsonSchema(agent.inputSchema),
+                        outputSchema: zodToJsonSchema(agent.outputSchema),
+                    }
+                    : undefined,
+            },
+        };
+    }
+    findAgentByAFSPath(path) {
+        let agent;
+        if (path === "/") {
+            agent = this;
+        }
+        else {
+            const name = path.split("/")[1];
+            agent = this.skills.find((s) => s.name === name);
+        }
+        return agent;
+    }
+    // TODO: support list skills inside agent path, and use options to filter skills
+    async list(_path, _options) {
+        const agents = [this, ...this.skills];
+        return { list: agents.map((agent) => this.agentToAFSEntry(agent)) };
+    }
+    async read(path) {
+        const agent = this.findAgentByAFSPath(path);
+        if (!agent) {
+            return { message: `Agent not found at path: ${path}` };
+        }
+        return {
+            result: this.agentToAFSEntry(agent),
+        };
+    }
+    // TODO: implement search inside agent skills
+    async search(path, _query, options) {
+        return this.list(path, options);
+    }
+    async exec(path, args, options) {
+        const agent = this.findAgentByAFSPath(path);
+        if (!agent)
+            throw new Error(`Agent not found at path: ${path}`);
+        return { result: await options.context.invoke(agent, args) };
+    }
 }
 /**
  * Check if a response chunk is empty

package/lib/esm/aigne/aigne.js

@@ -218,7 +218,7 @@ export class AIGNE {
      * This registers handlers for SIGINT and exit events to properly terminate all agents.
      */
     initProcessExitHandler() {
-        const shutdownAndExit = () => this.shutdown().finally(() => process.exit(0));
+        const shutdownAndExit = () => this.shutdown();
         process.on("SIGINT", shutdownAndExit);
         process.on("exit", shutdownAndExit);
     }

package/lib/esm/aigne/context.d.ts

@@ -182,6 +182,7 @@ export declare class AIGNEContext implements Context {
     subscribe: Context["subscribe"];
     unsubscribe: Context["unsubscribe"];
     emit<K extends keyof ContextEmitEventMap>(eventName: K, ...args: Args<K, ContextEmitEventMap>): boolean;
+    initProcessExitHandler(): void;
     private trace;
     on<K extends keyof ContextEventMap>(eventName: K, listener: Listener<K, ContextEventMap>): this;
     once<K extends keyof ContextEventMap>(eventName: K, listener: Listener<K, ContextEventMap>): this;

package/lib/esm/aigne/context.js

@@ -40,6 +40,7 @@ export class AIGNEContext {
             this.rootId = this.span?.spanContext?.().traceId ?? v7();
         }
         this.id = this.span?.spanContext()?.spanId ?? v7();
+        this.initProcessExitHandler();
     }
     id;
     parentId;
@@ -195,6 +196,23 @@ export class AIGNEContext {
         this.trace(eventName, args, b);
         return this.internal.events.emit(eventName, ...newArgs);
     }
+    initProcessExitHandler() {
+        process.on("SIGINT", async () => {
+            try {
+                if (process.env.AIGNE_OBSERVABILITY_DISABLED)
+                    return;
+                const span = this.span;
+                if (!span)
+                    return;
+                span.setStatus({ code: SpanStatusCode.ERROR, message: "SIGINT" });
+                span.end();
+                await this.observer?.flush(span);
+            }
+            finally {
+                process.exit(0);
+            }
+        });
+    }
     async trace(eventName, args, b) {
         if (process.env.AIGNE_OBSERVABILITY_DISABLED)
             return;

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

@@ -1,6 +1,6 @@
 import type { AFSOptions } from "@aigne/afs";
 import { type ZodType, z } from "zod";
-import type { AFSConfig, AgentHooks, FunctionAgentFn, TaskRenderMode } from "../agents/agent.js";
+import type { 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";
@@ -44,7 +44,6 @@ export interface BaseAgentSchema {
     afs?: boolean | (Omit<AFSOptions, "modules"> & {
         modules?: AFSModuleSchema[];
     });
-    afsConfig?: AFSConfig;
 }
 export type Instructions = {
     role: Exclude<Role, "tool">;

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

@@ -53,22 +53,15 @@ export async function parseAgentFile(path, data) {
             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({
+                        camelizeSchema(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

@@ -15,6 +15,7 @@ export interface LoadOptions {
     afs?: {
         availableModules?: {
             module: string;
+            alias?: string[];
             create: (options?: Record<string, any>) => PromiseOrValue<AFSModule>;
         }[];
     };

package/lib/esm/loader/index.js

@@ -114,23 +114,19 @@ async function parseAgent(path, agent, options, agentOptions) {
         : undefined;
     let afs;
     if (typeof agent.afs === "boolean") {
-        if (agent.afs) {
+        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);
-                }))),
-        });
+        afs = new AFS();
+        for (const m of agent.afs.modules || []) {
+            const moduleName = typeof m === "string" ? m : m.module;
+            const mod = options?.afs?.availableModules?.find((mod) => mod.module === moduleName || mod.alias?.includes(moduleName));
+            if (!mod)
+                throw new Error(`AFS module not found: ${typeof m === "string" ? m : m.module}`);
+            const module = await mod.create(typeof m === "string" ? {} : m.options);
+            afs.mount(module);
+        }
     }
     const model = agent.model && typeof options?.model === "function"
         ? await options.model({ ...options.aigne?.model, ...omitBy(agent.model, (v) => isNil(v)) })

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

@@ -1,4 +1,4 @@
-import { AFSHistory } from "@aigne/afs";
+import { AFSHistory } from "@aigne/afs-history";
 import { nodejs } from "@aigne/platform-helpers/nodejs/index.js";
 import { stringify } from "yaml";
 import { ZodObject } from "zod";
@@ -9,7 +9,7 @@ import { fileUnionContentsSchema } from "../agents/model.js";
 import { optionalize } from "../loader/schema.js";
 import { outputSchemaToResponseFormatSchema } from "../utils/json-schema.js";
 import { checkArguments, flat, isNonNullable, isRecord, partition, unique, } from "../utils/type-utils.js";
-import { getAFSSystemPrompt } from "./prompts/afs-builtin-prompt.js";
+import { AFS_EXECUTABLE_TOOLS_PROMPT_TEMPLATE, 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";
@@ -110,21 +110,50 @@ export class PromptBuilder {
         if (options.agent?.useMemoriesFromContext && options.context?.memories?.length) {
             memories.push(...options.context.memories);
         }
-        if (options.agent?.afs) {
-            messages.push(await SystemMessageTemplate.from(await getAFSSystemPrompt(options.agent.afs)).format({}));
-            if (options.agent.afsConfig?.injectHistory) {
-                const history = await options.agent.afs.list(AFSHistory.Path, {
-                    limit: options.agent.afsConfig.historyWindowSize || 10,
+        const afs = options.agent?.afs;
+        if (afs) {
+            const historyModule = (await afs.listModules()).find((m) => m.module instanceof AFSHistory);
+            messages.push(await SystemMessageTemplate.from(await getAFSSystemPrompt(afs)).format({}));
+            if (historyModule) {
+                const history = await afs.list(historyModule.path, {
+                    limit: options.agent?.maxRetrieveMemoryCount || 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
                     .reverse()
                     .filter((i) => isNonNullable(i.content)));
+                if (message) {
+                    const result = await afs.search("/", message);
+                    const ms = result.list
+                        .map((entry) => {
+                        if (entry.metadata?.execute)
+                            return null;
+                        const content = entry.content || entry.summary;
+                        if (!content)
+                            return null;
+                        return {
+                            content,
+                            description: entry.description,
+                        };
+                    })
+                        .filter(isNonNullable);
+                    memories.push(...ms);
+                    const executable = result.list.filter((i) => !!i.metadata?.execute);
+                    if (executable.length) {
+                        messages.push({
+                            role: "system",
+                            content: await PromptTemplate.from(AFS_EXECUTABLE_TOOLS_PROMPT_TEMPLATE).format({
+                                tools: executable.map((entry) => ({
+                                    path: entry.path,
+                                    name: entry.metadata.execute.name,
+                                    description: entry.metadata.execute.description,
+                                    inputSchema: entry.metadata.execute.inputSchema,
+                                    outputSchema: entry.metadata.execute.outputSchema,
+                                })),
+                            }),
+                        });
+                    }
+                }
             }
         }
         if (memories.length)
@@ -229,7 +258,8 @@ export class PromptBuilder {
             result.push({ role: "agent", content: agentMessageContent });
             return result;
         };
-        for (const { content } of memories) {
+        for (const memory of memories) {
+            const { content } = memory;
             if (isRecord(content) &&
                 "input" in content &&
                 content.input &&
@@ -238,7 +268,7 @@ export class PromptBuilder {
                 messages.push(...(await convertMemoryToMessage(content)));
             }
             else {
-                other.push(content);
+                other.push(memory);
             }
         }
         if (other.length) {

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

@@ -1,2 +1,3 @@
 import type { AFS } from "@aigne/afs";
 export declare function getAFSSystemPrompt(afs: AFS): Promise<string>;
+export declare const AFS_EXECUTABLE_TOOLS_PROMPT_TEMPLATE = "<afs_executable_tools>\nHere are the executable tools available in the AFS you can use:\n\n{{ tools | yaml.stringify }}\n</afs_executable_tools>\n";

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

@@ -1,20 +1,29 @@
 import { stringify } from "yaml";
+import { pick } from "../../utils/type-utils.js";
 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.
+AFS (Agentic File System) provides tools to interact with a virtual file system,
+allowing you to list, search, read, and write files, or execute a useful tool from the available modules.
+Use these tools to manage and retrieve files as needed.
 
-Modules:
-${stringify(await afs.listModules())}
+Provided modules:
+${stringify((await afs.listModules()).map((i) => pick(i, ["name", "path", "description"])))}
 
-Available Tools:
+Global tools to interact with the AFS:
 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.
+5. afs_exec: Execute a executable tool from the available modules
 </afs_usage>
 `;
 }
+export const AFS_EXECUTABLE_TOOLS_PROMPT_TEMPLATE = `\
+<afs_executable_tools>
+Here are the executable tools available in the AFS you can use:
+
+{{ tools | yaml.stringify }}
+</afs_executable_tools>
+`;

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

@@ -89,5 +89,18 @@ export async function getAFSSkills(afs) {
                 };
             },
         }),
+        FunctionAgent.from({
+            name: "afs_exec",
+            description: "Execute a function or command available in the AFS modules",
+            inputSchema: z.object({
+                path: z.string().describe("The exact path to the executable entry in AFS"),
+                args: z
+                    .string()
+                    .describe("JSON stringified arguments to pass to the executable, must be an object matching the input schema of the executable"),
+            }),
+            process: async ({ path, args }, options) => {
+                return await afs.exec(path, JSON.parse(args), options);
+            },
+        }),
     ];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigne/core",
-  "version": "1.67.0",
+  "version": "1.68.0",
   "description": "The functional core of agentic AI",
   "publishConfig": {
     "access": "public"
@@ -92,9 +92,10 @@
     "zod": "^3.25.67",
     "zod-from-json-schema": "^0.0.5",
     "zod-to-json-schema": "^3.24.6",
-    "@aigne/observability-api": "^0.11.6",
+    "@aigne/afs": "^1.2.0",
+    "@aigne/afs-history": "^1.0.1",
     "@aigne/platform-helpers": "^0.6.3",
-    "@aigne/afs": "^1.1.2"
+    "@aigne/observability-api": "^0.11.6"
   },
   "devDependencies": {
     "@types/bun": "^1.2.22",