@aigne/core 1.13.0 → 1.14.0

package/lib/cjs/aigne/message-queue.d.ts

@@ -1,22 +1,44 @@
 import { EventEmitter } from "node:events";
 import type { Message } from "../agents/agent.js";
 import type { Context } from "./context.js";
+/**
+ * @hidden
+ */
 export declare const UserInputTopic = "UserInputTopic";
+/**
+ * @hidden
+ */
 export declare const UserOutputTopic = "UserOutputTopic";
+/**
+ * @hidden
+ */
 export interface MessagePayload {
     role: "user" | "agent";
     source?: string;
     message: Message;
     context: Context;
 }
+/**
+ * @hidden
+ */
+export declare function toMessagePayload(payload: Omit<MessagePayload, "context"> | string | Message, options?: Partial<Pick<MessagePayload, "role" | "source">>): Omit<MessagePayload, "context">;
+/**
+ * @hidden
+ */
 export type MessageQueueListener = (message: MessagePayload) => void;
+/**
+ * @hidden
+ */
 export type Unsubscribe = () => void;
+/**
+ * @hidden
+ */
 export declare class MessageQueue {
     events: EventEmitter<[never]>;
     publish(topic: string | string[], payload: MessagePayload): void;
     error(error: Error): void;
-    subscribe(topic: string, listener?: undefined): Promise<MessagePayload>;
-    subscribe(topic: string, listener: MessageQueueListener): Unsubscribe;
-    subscribe(topic: string, listener?: MessageQueueListener): Unsubscribe | Promise<MessagePayload>;
-    unsubscribe(topic: string, listener: MessageQueueListener): void;
+    subscribe(topic: string | string[], listener?: undefined): Promise<MessagePayload>;
+    subscribe(topic: string | string[], listener: MessageQueueListener): Unsubscribe;
+    subscribe(topic: string | string[], listener?: MessageQueueListener): Unsubscribe | Promise<MessagePayload>;
+    unsubscribe(topic: string | string[], listener: MessageQueueListener): void;
 }

package/lib/cjs/aigne/message-queue.js

@@ -1,11 +1,44 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MessageQueue = exports.UserOutputTopic = exports.UserInputTopic = void 0;
+exports.toMessagePayload = toMessagePayload;
 const node_events_1 = require("node:events");
 const zod_1 = require("zod");
+const prompt_builder_js_1 = require("../prompt/prompt-builder.js");
 const type_utils_js_1 = require("../utils/type-utils.js");
+/**
+ * @hidden
+ */
 exports.UserInputTopic = "UserInputTopic";
+/**
+ * @hidden
+ */
 exports.UserOutputTopic = "UserOutputTopic";
+function isMessagePayload(payload) {
+    return (!(0, type_utils_js_1.isNil)(payload) &&
+        typeof payload === "object" &&
+        "role" in payload &&
+        typeof payload.role === "string" &&
+        ["user", "agent"].includes(payload.role) &&
+        "message" in payload &&
+        !(0, type_utils_js_1.isNil)(payload.message));
+}
+/**
+ * @hidden
+ */
+function toMessagePayload(payload, options) {
+    if (isMessagePayload(payload)) {
+        return { ...payload, message: (0, prompt_builder_js_1.createMessage)(payload.message), ...options };
+    }
+    return {
+        role: options?.role || "user",
+        source: options?.source,
+        message: (0, prompt_builder_js_1.createMessage)(payload),
+    };
+}
+/**
+ * @hidden
+ */
 class MessageQueue {
     events = new node_events_1.EventEmitter();
     publish(topic, payload) {
@@ -44,24 +77,26 @@ class MessageQueue {
             topic,
             listener,
         });
-        this.events.off(topic, listener);
+        for (const t of (0, type_utils_js_1.orArrayToArray)(topic)) {
+            this.events.off(t, listener);
+        }
     }
 }
 exports.MessageQueue = MessageQueue;
 function on(events, event, listener) {
-    events.on(event, listener);
-    return () => events.off(event, listener);
+    (0, type_utils_js_1.orArrayToArray)(event).forEach((e) => events.on(e, listener));
+    return () => (0, type_utils_js_1.orArrayToArray)(event).forEach((e) => events.off(e, listener));
 }
 function once(events, event, listener) {
-    events.once(event, listener);
-    return () => events.off(event, listener);
+    (0, type_utils_js_1.orArrayToArray)(event).forEach((e) => events.once(e, listener));
+    return () => (0, type_utils_js_1.orArrayToArray)(event).forEach((e) => events.off(e, listener));
 }
 const subscribeArgsSchema = zod_1.z.object({
-    topic: zod_1.z.string(),
+    topic: zod_1.z.union([zod_1.z.string(), zod_1.z.array(zod_1.z.string())]),
     listener: zod_1.z.function(zod_1.z.tuple([zod_1.z.any()]), zod_1.z.any()).optional(),
 });
 const unsubscribeArgsSchema = zod_1.z.object({
-    topic: zod_1.z.string(),
+    topic: zod_1.z.union([zod_1.z.string(), zod_1.z.array(zod_1.z.string())]),
     listener: zod_1.z.function(zod_1.z.tuple([zod_1.z.any()]), zod_1.z.any()),
 });
 const publishArgsSchema = zod_1.z.object({

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

@@ -1,9 +1,18 @@
+/**
+ * @hidden
+ */
 export interface ContextUsage {
     inputTokens: number;
     outputTokens: number;
     agentCalls: number;
 }
+/**
+ * @hidden
+ */
 export declare function newEmptyContextUsage(): ContextUsage;
+/**
+ * @hidden
+ */
 export interface ContextLimits {
     maxTokens?: number;
     maxAgentInvokes?: number;

package/lib/cjs/aigne/usage.js

@@ -1,6 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.newEmptyContextUsage = newEmptyContextUsage;
+/**
+ * @hidden
+ */
 function newEmptyContextUsage() {
     return {
         inputTokens: 0,

package/lib/cjs/client/client.d.ts

@@ -1,19 +1,97 @@
+/**
+ * Client module used to interact with the AIGNE framework.
+ */
 import type { AgentInvokeOptions, AgentResponse, AgentResponseStream, Message } from "../agents/agent.js";
+/**
+ * Configuration options for the AIGNEClient.
+ */
 export interface AIGNEClientOptions {
+    /**
+     * The URL of the AIGNE server to connect to.
+     * This should point to the base endpoint where the AIGNEServer is hosted.
+     */
     url: string;
 }
+/**
+ * Options for invoking an agent through the AIGNEClient.
+ * Extends the standard AgentInvokeOptions with client-specific options.
+ */
 export interface AIGNEClientInvokeOptions extends AgentInvokeOptions {
+    /**
+     * Additional fetch API options to customize the HTTP request.
+     * These options will be merged with the default options used by the client.
+     */
     fetchOptions?: Partial<RequestInit>;
 }
+/**
+ * Client for interacting with a remote AIGNE server.
+ * AIGNEClient provides a client-side interface that matches the AIGNE API,
+ * allowing applications to invoke agents and receive responses from a remote AIGNE instance.
+ *
+ * @example
+ * Here's a simple example of how to use AIGNEClient:
+ * {@includeCode ../../test/client/client.test.ts#example-aigne-client-simple}
+ *
+ * @example
+ * Here's an example of how to use AIGNEClient with streaming response:
+ * {@includeCode ../../test/client/client.test.ts#example-aigne-client-streaming}
+ */
 export declare class AIGNEClient {
     options: AIGNEClientOptions;
+    /**
+     * Creates a new AIGNEClient instance.
+     *
+     * @param options - Configuration options for connecting to the AIGNE server
+     */
     constructor(options: AIGNEClientOptions);
-    invoke<I extends Message, O extends Message>(agent: string, input: I, options: AIGNEClientInvokeOptions & {
-        streaming: true;
-    }): Promise<AgentResponseStream<O>>;
+    /**
+     * Invokes an agent in non-streaming mode and returns the complete response.
+     *
+     * @param agent - Name of the agent to invoke
+     * @param input - Input message for the agent
+     * @param options - Options with streaming mode explicitly set to false or omitted
+     * @returns The complete agent response
+     *
+     * @example
+     * Here's a simple example of how to use AIGNEClient:
+     * {@includeCode ../../test/client/client.test.ts#example-aigne-client-simple}
+     */
     invoke<I extends Message, O extends Message>(agent: string, input: I, options?: AIGNEClientInvokeOptions & {
         streaming?: false;
     }): Promise<O>;
+    /**
+     * Invokes an agent with streaming mode enabled and returns a stream of response chunks.
+     *
+     * @param agent - Name of the agent to invoke
+     * @param input - Input message for the agent
+     * @param options - Options with streaming mode explicitly set to true
+     * @returns A stream of agent response chunks
+     *
+     * @example
+     * Here's an example of how to use AIGNEClient with streaming response:
+     * {@includeCode ../../test/client/client.test.ts#example-aigne-client-streaming}
+     */
+    invoke<I extends Message, O extends Message>(agent: string, input: I, options: AIGNEClientInvokeOptions & {
+        streaming: true;
+    }): Promise<AgentResponseStream<O>>;
+    /**
+     * Invokes an agent with the given input and options.
+     *
+     * @param agent - Name of the agent to invoke
+     * @param input - Input message for the agent
+     * @param options - Options for the invocation
+     * @returns Either a complete response or a response stream depending on the streaming option
+     */
     invoke<I extends Message, O extends Message>(agent: string, input: I, options?: AIGNEClientInvokeOptions): Promise<AgentResponse<O>>;
+    /**
+     * Enhanced fetch method that handles error responses from the AIGNE server.
+     * This method wraps the standard fetch API to provide better error handling and reporting.
+     *
+     * @param args - Standard fetch API arguments (url and options)
+     * @returns A Response object if the request was successful
+     * @throws Error with detailed information if the request failed
+     *
+     * @private
+     */
     fetch(...args: Parameters<typeof globalThis.fetch>): Promise<Response>;
 }

package/lib/cjs/client/client.js

@@ -1,14 +1,36 @@
 "use strict";
+/**
+ * Client module used to interact with the AIGNE framework.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AIGNEClient = void 0;
 const event_stream_js_1 = require("../utils/event-stream.js");
 const type_utils_js_1 = require("../utils/type-utils.js");
+/**
+ * Client for interacting with a remote AIGNE server.
+ * AIGNEClient provides a client-side interface that matches the AIGNE API,
+ * allowing applications to invoke agents and receive responses from a remote AIGNE instance.
+ *
+ * @example
+ * Here's a simple example of how to use AIGNEClient:
+ * {@includeCode ../../test/client/client.test.ts#example-aigne-client-simple}
+ *
+ * @example
+ * Here's an example of how to use AIGNEClient with streaming response:
+ * {@includeCode ../../test/client/client.test.ts#example-aigne-client-streaming}
+ */
 class AIGNEClient {
     options;
+    /**
+     * Creates a new AIGNEClient instance.
+     *
+     * @param options - Configuration options for connecting to the AIGNE server
+     */
     constructor(options) {
         this.options = options;
     }
     async invoke(agent, input, options) {
+        // Send the agent invocation request to the AIGNE server
         const response = await this.fetch(this.options.url, {
             ...options?.fetchOptions,
             method: "POST",
@@ -18,17 +40,33 @@ class AIGNEClient {
             },
             body: JSON.stringify({ agent, input, options }),
         });
+        // For non-streaming responses, simply parse the JSON response and return it
         if (!options?.streaming) {
             return await response.json();
         }
+        // For streaming responses, set up the streaming pipeline
         const stream = response.body;
         if (!stream)
             throw new Error("Response body is not a stream");
+        // Process the stream through a series of transforms:
+        // 1. Convert bytes to text
+        // 2. Parse SSE format into structured events
+        // 3. Convert events into a standardized agent response stream
         return stream
             .pipeThrough(new TextDecoderStream())
             .pipeThrough(new event_stream_js_1.EventStreamParser())
             .pipeThrough(new event_stream_js_1.AgentResponseStreamParser());
     }
+    /**
+     * Enhanced fetch method that handles error responses from the AIGNE server.
+     * This method wraps the standard fetch API to provide better error handling and reporting.
+     *
+     * @param args - Standard fetch API arguments (url and options)
+     * @returns A Response object if the request was successful
+     * @throws Error with detailed information if the request failed
+     *
+     * @private
+     */
     async fetch(...args) {
         const result = await globalThis.fetch(...args);
         if (!result.ok) {

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

@@ -0,0 +1 @@
+export * from "./client.js";

package/lib/cjs/client/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./client.js"), exports);

package/lib/cjs/index.d.ts

@@ -1,7 +1,6 @@
 export * from "./agents/agent.js";
 export * from "./agents/ai-agent.js";
 export * from "./agents/mcp-agent.js";
-export * from "./agents/memory.js";
 export * from "./agents/team-agent.js";
 export * from "./agents/types.js";
 export * from "./agents/user-agent.js";

package/lib/cjs/index.js

@@ -17,7 +17,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./agents/agent.js"), exports);
 __exportStar(require("./agents/ai-agent.js"), exports);
 __exportStar(require("./agents/mcp-agent.js"), exports);
-__exportStar(require("./agents/memory.js"), exports);
 __exportStar(require("./agents/team-agent.js"), exports);
 __exportStar(require("./agents/types.js"), exports);
 __exportStar(require("./agents/user-agent.js"), exports);

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

@@ -2,7 +2,7 @@ import { type ZodObject, type ZodType, z } from "zod";
 import type { Message } from "../agents/agent.js";
 export declare function loadAgentFromJsFile(path: string): Promise<{
     name: string;
-    fn: (args_0: Message) => Message;
+    process: (args_0: Message) => Message;
     description?: string | undefined;
     inputSchema?: ZodObject<Record<string, ZodType<any, z.ZodTypeDef, any>>, z.UnknownKeysParam, z.ZodTypeAny, {
         [x: string]: any;

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

@@ -51,7 +51,7 @@ const agentJsFileSchema = zod_1.z.object({
     output_schema: schema_js_1.inputOutputSchema
         .nullish()
         .transform((v) => (v ? (0, json_schema_to_zod_1.jsonSchemaToZod)(v) : undefined)),
-    fn: zod_1.z.function(),
+    process: zod_1.z.function(),
 });
 async function loadAgentFromJsFile(path) {
     const { default: agent } = await (0, type_utils_js_1.tryOrThrow)(() => Promise.resolve(`${path}`).then(s => __importStar(require(s))), (error) => new Error(`Failed to load agent definition from ${path}: ${error.message}`));
@@ -61,6 +61,6 @@ async function loadAgentFromJsFile(path) {
     return (0, type_utils_js_1.tryOrThrow)(() => (0, camelize_js_1.customCamelize)(agentJsFileSchema.parse({
         ...agent,
         name: agent.agent_name || agent.name,
-        fn: agent,
+        process: agent,
     }), { shallowKeys: ["input_schema", "output_schema"] }), (error) => new Error(`Failed to parse agent from ${path}: ${error.message}`));
 }

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

@@ -1,19 +1,20 @@
 import { type ZodObject, type ZodType, z } from "zod";
+import { AIAgentToolChoice } from "../agents/ai-agent.js";
 export declare function loadAgentFromYamlFile(path: string): Promise<{
     type: "ai";
     name: string;
     description?: string | undefined;
+    skills?: string[] | undefined;
     memory?: true | {
         subscribeTopic?: string[] | undefined;
     } | undefined;
-    skills?: string[] | undefined;
     instructions?: string | undefined;
     inputSchema?: ZodObject<Record<string, ZodType<any, z.ZodTypeDef, any>>, z.UnknownKeysParam, z.ZodTypeAny, {
         [x: string]: any;
     }, {
         [x: string]: any;
     }> | undefined;
-    toolChoice?: "auto" | "none" | "required" | "router" | undefined;
+    toolChoice?: AIAgentToolChoice | undefined;
     outputSchema?: ZodObject<Record<string, ZodType<any, z.ZodTypeDef, any>>, z.UnknownKeysParam, z.ZodTypeAny, {
         [x: string]: any;
     }, {

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

@@ -5,6 +5,7 @@ const promises_1 = require("node:fs/promises");
 const json_schema_to_zod_1 = require("@aigne/json-schema-to-zod");
 const yaml_1 = require("yaml");
 const zod_1 = require("zod");
+const ai_agent_js_1 = require("../agents/ai-agent.js");
 const camelize_js_1 = require("../utils/camelize.js");
 const type_utils_js_1 = require("../utils/type-utils.js");
 const schema_js_1 = require("./schema.js");
@@ -35,7 +36,7 @@ const agentFileSchema = zod_1.z.discriminatedUnion("type", [
             .nullish()
             .transform((v) => v ?? undefined),
         tool_choice: zod_1.z
-            .union([zod_1.z.literal("auto"), zod_1.z.literal("none"), zod_1.z.literal("required"), zod_1.z.literal("router")])
+            .nativeEnum(ai_agent_js_1.AIAgentToolChoice)
             .nullish()
             .transform((v) => v ?? undefined),
         memory: zod_1.z

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

@@ -8,8 +8,8 @@ export declare function load(options: LoadOptions): Promise<{
     model: ChatModel | undefined;
     agents: Agent<import("../agents/agent.js").Message, import("../agents/agent.js").Message>[];
     skills: Agent<import("../agents/agent.js").Message, import("../agents/agent.js").Message>[];
-    description?: string | null | undefined;
     name?: string | null | undefined;
+    description?: string | null | undefined;
     chat_model?: {
         name?: string | null | undefined;
         temperature?: number | null | undefined;
@@ -63,8 +63,8 @@ declare const aigneFileSchema: z.ZodObject<{
     agents: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString, "many">>>;
     skills: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString, "many">>>;
 }, "strip", z.ZodTypeAny, {
-    description?: string | null | undefined;
     name?: string | null | undefined;
+    description?: string | null | undefined;
     skills?: string[] | null | undefined;
     chat_model?: {
         name?: string | null | undefined;
@@ -76,8 +76,8 @@ declare const aigneFileSchema: z.ZodObject<{
     } | null | undefined;
     agents?: string[] | null | undefined;
 }, {
-    description?: string | null | undefined;
     name?: string | null | undefined;
+    description?: string | null | undefined;
     skills?: string[] | null | undefined;
     chat_model?: string | {
         name?: string | null | undefined;
@@ -90,8 +90,8 @@ declare const aigneFileSchema: z.ZodObject<{
     agents?: string[] | null | undefined;
 }>;
 export declare function loadAIGNEFile(path: string): Promise<{
-    description?: string | null | undefined;
     name?: string | null | undefined;
+    description?: string | null | undefined;
     skills?: string[] | null | undefined;
     chat_model?: {
         name?: string | null | undefined;

package/lib/cjs/memory/default-memory.d.ts

@@ -0,0 +1,16 @@
+import { type Memory, MemoryAgent, type MemoryAgentOptions } from "./memory.js";
+export declare const DEFAULT_MAX_MEMORY_COUNT = 10;
+export interface DefaultMemoryOptions extends Partial<MemoryAgentOptions> {
+}
+export declare class DefaultMemory extends MemoryAgent {
+    constructor(options?: DefaultMemoryOptions);
+    storage: Memory[];
+    search(options?: {
+        limit?: number;
+    }): Promise<{
+        result: Memory[];
+    }>;
+    create(memory: Pick<Memory, "content">): Promise<{
+        result: Memory;
+    }>;
+}

package/lib/cjs/memory/default-memory.js

@@ -0,0 +1,70 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DefaultMemory = exports.DEFAULT_MAX_MEMORY_COUNT = void 0;
+const fast_deep_equal_1 = __importDefault(require("fast-deep-equal"));
+const memory_js_1 = require("./memory.js");
+const recorder_js_1 = require("./recorder.js");
+const retriever_js_1 = require("./retriever.js");
+exports.DEFAULT_MAX_MEMORY_COUNT = 10;
+class DefaultMemory extends memory_js_1.MemoryAgent {
+    constructor(options = {}) {
+        super({
+            ...options,
+            autoUpdate: options.autoUpdate ?? true,
+        });
+        if (!this.recorder)
+            this.recorder = new DefaultMemoryRecorder(this);
+        if (!this.retriever)
+            this.retriever = new DefaultMemoryRetriever(this);
+    }
+    storage = [];
+    async search(options = {}) {
+        const { limit = exports.DEFAULT_MAX_MEMORY_COUNT } = options;
+        const result = limit < 0 ? this.storage.slice(limit) : this.storage.slice(0, limit);
+        return { result };
+    }
+    async create(memory) {
+        const m = {
+            ...memory,
+            id: (0, memory_js_1.newMemoryId)(),
+            createdAt: new Date().toISOString(),
+        };
+        this.storage.push(m);
+        return { result: m };
+    }
+}
+exports.DefaultMemory = DefaultMemory;
+class DefaultMemoryRetriever extends retriever_js_1.MemoryRetriever {
+    memory;
+    constructor(memory) {
+        super({});
+        this.memory = memory;
+    }
+    async process(input) {
+        const { result } = await this.memory.search(input);
+        return { memories: result };
+    }
+}
+class DefaultMemoryRecorder extends recorder_js_1.MemoryRecorder {
+    memory;
+    constructor(memory) {
+        super({});
+        this.memory = memory;
+    }
+    async process(input) {
+        const newMemories = [];
+        for (const content of input.content) {
+            const { result: [last], } = await this.memory.search({ limit: -1 });
+            if (!(0, fast_deep_equal_1.default)(last?.content, content)) {
+                const { result } = await this.memory.create({ content });
+                newMemories.push(result);
+            }
+        }
+        return {
+            memories: newMemories,
+        };
+    }
+}

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

@@ -0,0 +1,3 @@
+export * from "./memory.js";
+export * from "./recorder.js";
+export * from "./retriever.js";

package/lib/cjs/memory/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./memory.js"), exports);
+__exportStar(require("./recorder.js"), exports);
+__exportStar(require("./retriever.js"), exports);