@aigne/core 1.13.0 → 1.14.0

package/lib/esm/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/esm/aigne/message-queue.js

@@ -1,8 +1,40 @@
 import { EventEmitter } from "node:events";
 import { z } from "zod";
-import { checkArguments, orArrayToArray } from "../utils/type-utils.js";
+import { createMessage } from "../prompt/prompt-builder.js";
+import { checkArguments, isNil, orArrayToArray } from "../utils/type-utils.js";
+/**
+ * @hidden
+ */
 export const UserInputTopic = "UserInputTopic";
+/**
+ * @hidden
+ */
 export const UserOutputTopic = "UserOutputTopic";
+function isMessagePayload(payload) {
+    return (!isNil(payload) &&
+        typeof payload === "object" &&
+        "role" in payload &&
+        typeof payload.role === "string" &&
+        ["user", "agent"].includes(payload.role) &&
+        "message" in payload &&
+        !isNil(payload.message));
+}
+/**
+ * @hidden
+ */
+export function toMessagePayload(payload, options) {
+    if (isMessagePayload(payload)) {
+        return { ...payload, message: createMessage(payload.message), ...options };
+    }
+    return {
+        role: options?.role || "user",
+        source: options?.source,
+        message: createMessage(payload),
+    };
+}
+/**
+ * @hidden
+ */
 export class MessageQueue {
     events = new EventEmitter();
     publish(topic, payload) {
@@ -41,23 +73,25 @@ export class MessageQueue {
             topic,
             listener,
         });
-        this.events.off(topic, listener);
+        for (const t of orArrayToArray(topic)) {
+            this.events.off(t, listener);
+        }
     }
 }
 function on(events, event, listener) {
-    events.on(event, listener);
-    return () => events.off(event, listener);
+    orArrayToArray(event).forEach((e) => events.on(e, listener));
+    return () => orArrayToArray(event).forEach((e) => events.off(e, listener));
 }
 function once(events, event, listener) {
-    events.once(event, listener);
-    return () => events.off(event, listener);
+    orArrayToArray(event).forEach((e) => events.once(e, listener));
+    return () => orArrayToArray(event).forEach((e) => events.off(e, listener));
 }
 const subscribeArgsSchema = z.object({
-    topic: z.string(),
+    topic: z.union([z.string(), z.array(z.string())]),
     listener: z.function(z.tuple([z.any()]), z.any()).optional(),
 });
 const unsubscribeArgsSchema = z.object({
-    topic: z.string(),
+    topic: z.union([z.string(), z.array(z.string())]),
     listener: z.function(z.tuple([z.any()]), z.any()),
 });
 const publishArgsSchema = z.object({

package/lib/esm/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/esm/aigne/usage.js

@@ -1,3 +1,6 @@
+/**
+ * @hidden
+ */
 export function newEmptyContextUsage() {
     return {
         inputTokens: 0,

package/lib/esm/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/esm/client/client.js

@@ -1,11 +1,33 @@
+/**
+ * Client module used to interact with the AIGNE framework.
+ */
 import { AgentResponseStreamParser, EventStreamParser } from "../utils/event-stream.js";
 import { tryOrThrow } from "../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}
+ */
 export 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",
@@ -15,17 +37,33 @@ export 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 EventStreamParser())
             .pipeThrough(new 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/esm/client/index.d.ts

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

package/lib/esm/client/index.js

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

package/lib/esm/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/esm/index.js

@@ -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/esm/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/esm/loader/agent-js.js

@@ -15,7 +15,7 @@ const agentJsFileSchema = z.object({
     output_schema: inputOutputSchema
         .nullish()
         .transform((v) => (v ? jsonSchemaToZod(v) : undefined)),
-    fn: z.function(),
+    process: z.function(),
 });
 export async function loadAgentFromJsFile(path) {
     const { default: agent } = await tryOrThrow(() => import(path), (error) => new Error(`Failed to load agent definition from ${path}: ${error.message}`));
@@ -25,6 +25,6 @@ export async function loadAgentFromJsFile(path) {
     return tryOrThrow(() => 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/esm/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/esm/loader/agent-yaml.js

@@ -2,6 +2,7 @@ import { readFile } from "node:fs/promises";
 import { jsonSchemaToZod } from "@aigne/json-schema-to-zod";
 import { parse } from "yaml";
 import { z } from "zod";
+import { AIAgentToolChoice } from "../agents/ai-agent.js";
 import { customCamelize } from "../utils/camelize.js";
 import { tryOrThrow } from "../utils/type-utils.js";
 import { inputOutputSchema } from "./schema.js";
@@ -32,7 +33,7 @@ const agentFileSchema = z.discriminatedUnion("type", [
             .nullish()
             .transform((v) => v ?? undefined),
         tool_choice: z
-            .union([z.literal("auto"), z.literal("none"), z.literal("required"), z.literal("router")])
+            .nativeEnum(AIAgentToolChoice)
             .nullish()
             .transform((v) => v ?? undefined),
         memory: z

package/lib/esm/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/esm/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/esm/memory/default-memory.js

@@ -0,0 +1,63 @@
+import equal from "fast-deep-equal";
+import { MemoryAgent, newMemoryId } from "./memory.js";
+import { MemoryRecorder } from "./recorder.js";
+import { MemoryRetriever, } from "./retriever.js";
+export const DEFAULT_MAX_MEMORY_COUNT = 10;
+export class DefaultMemory extends 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 = 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: newMemoryId(),
+            createdAt: new Date().toISOString(),
+        };
+        this.storage.push(m);
+        return { result: m };
+    }
+}
+class DefaultMemoryRetriever extends MemoryRetriever {
+    memory;
+    constructor(memory) {
+        super({});
+        this.memory = memory;
+    }
+    async process(input) {
+        const { result } = await this.memory.search(input);
+        return { memories: result };
+    }
+}
+class DefaultMemoryRecorder extends 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 (!equal(last?.content, content)) {
+                const { result } = await this.memory.create({ content });
+                newMemories.push(result);
+            }
+        }
+        return {
+            memories: newMemories,
+        };
+    }
+}

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

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

package/lib/esm/memory/index.js

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

package/lib/esm/memory/memory.d.ts

@@ -0,0 +1,89 @@
+import { Agent, type AgentOptions, type Message } from "../agents/agent.js";
+import type { Context } from "../aigne/context.js";
+import type { MessagePayload } from "../aigne/message-queue.js";
+import type { MemoryRecorder, MemoryRecorderInput, MemoryRecorderOutput } from "./recorder.js";
+import type { MemoryRetriever, MemoryRetrieverInput, MemoryRetrieverOutput } from "./retriever.js";
+export interface Memory {
+    id: string;
+    content: unknown;
+    createdAt: string;
+}
+export declare const newMemoryId: () => string;
+export interface MemoryAgentOptions extends Partial<Pick<MemoryAgent, "recorder" | "retriever" | "autoUpdate">>, Pick<AgentOptions, "subscribeTopic" | "skills"> {
+}
+/**
+ * A specialized agent responsible for managing, storing, and retrieving memories within the agent system.
+ *
+ * MemoryAgent serves as a bridge between application logic and memory storage/retrieval mechanisms.
+ * It delegates the actual memory operations to specialized recorder and retriever agents that
+ * are attached as skills. This agent doesn't directly process messages like other agents but
+ * instead provides memory management capabilities to the system.
+ */
+export declare class MemoryAgent extends Agent {
+    /**
+     * Creates a new MemoryAgent instance.
+     */
+    constructor(options: MemoryAgentOptions);
+    private _retriever?;
+    /**
+     * Agent used for retrieving memories from storage.
+     *
+     * This retriever is automatically added to the agent's skills when set.
+     * Setting a new retriever will remove any previously set retriever from skills.
+     */
+    get retriever(): MemoryRetriever | undefined;
+    set retriever(value: MemoryRetriever | undefined);
+    private _recorder?;
+    /**
+     * Agent used for recording and storing new memories.
+     *
+     * This recorder is automatically added to the agent's skills when set.
+     * Setting a new recorder will remove any previously set recorder from skills.
+     */
+    get recorder(): MemoryRecorder | undefined;
+    set recorder(value: MemoryRecorder | undefined);
+    /**
+     * Controls whether to automatically update the memory when agent call completes.
+     *
+     * When true, the agent will automatically record any relevant information
+     * after completing operations, creating a history of interactions.
+     */
+    autoUpdate?: boolean;
+    /**
+     * Indicates whether this agent can be directly called.
+     *
+     * MemoryAgent is designed to be used as a supporting component rather than
+     * being directly invoked for processing, so this returns false.
+     */
+    get isCallable(): boolean;
+    /**
+     * The standard message processing method required by the Agent interface.
+     *
+     * MemoryAgent doesn't directly process messages like other agents, so this method
+     * throws an error when called. Use the specialized retrieve() and record() methods instead.
+     */
+    process(_input: Message, _context: Context): Promise<Message>;
+    /**
+     * Retrieves memories based on the provided input criteria.
+     *
+     * Delegates the actual retrieval operation to the configured retriever agent.
+     *
+     * @param input - The retrieval parameters (can include search terms, limits, etc.)
+     * @param context - The execution context
+     * @returns A promise resolving to the retrieved memories
+     * @throws Error - If no retriever has been initialized
+     */
+    retrieve(input: MemoryRetrieverInput, context: Context): Promise<MemoryRetrieverOutput>;
+    /**
+     * Records new memories based on the provided input content.
+     *
+     * Delegates the actual recording operation to the configured recorder agent.
+     *
+     * @param input - The content to be recorded as memories
+     * @param context - The execution context
+     * @returns A promise resolving to the recorded memories
+     * @throws Error - If no recorder has been initialized
+     */
+    record(input: MemoryRecorderInput, context: Context): Promise<MemoryRecorderOutput>;
+    onMessage({ role, source, message, context }: MessagePayload): Promise<void>;
+}