@aigne/core 1.13.0 → 1.14.0

package/lib/esm/server/server.d.ts

@@ -1,6 +1,12 @@
 import { IncomingMessage, ServerResponse } from "node:http";
 import { z } from "zod";
 import type { AIGNE } from "../aigne/aigne.js";
+/**
+ * Schema for validating agent invocation payloads.
+ * Defines the expected structure for requests to invoke an agent.
+ *
+ * @hidden
+ */
 export declare const invokePayloadSchema: z.ZodObject<{
     agent: z.ZodString;
     input: z.ZodRecord<z.ZodString, z.ZodUnknown>;
@@ -24,31 +30,106 @@ export declare const invokePayloadSchema: z.ZodObject<{
         streaming?: boolean | null | undefined;
     } | null | undefined;
 }>;
+/**
+ * Configuration options for the AIGNEServer.
+ * These options control various aspects of server behavior including
+ * request parsing, payload limits, and response handling.
+ */
 export interface AIGNEServerOptions {
     /**
-     * Maximum body size for the request.
-     * Only used when the request is a Node.js IncomingMessage and no `body` property is present.
+     * Maximum body size for incoming HTTP requests.
+     * This controls the upper limit of request payload size when parsing raw HTTP requests.
+     * Only used when working with Node.js IncomingMessage objects that don't already have
+     * a pre-parsed body property (e.g., when not using Express middleware).
+     *
      * @default "4mb"
      */
     maximumBodySize?: string;
 }
+/**
+ * AIGNEServer provides HTTP API access to AIGNE capabilities.
+ * It handles requests to invoke agents, manages response streaming,
+ * and supports multiple HTTP server frameworks including Node.js http,
+ * Express, and Fetch API compatible environments.
+ *
+ * @example
+ * Here's a simple example of how to use AIGNEServer with express:
+ * {@includeCode ../../test/server/server.test.ts#example-aigne-server-express}
+ *
+ * @example
+ * Here's an example of how to use AIGNEServer with Hono:
+ * {@includeCode ../../test/server/server.test.ts#example-aigne-server-hono}
+ */
 export declare class AIGNEServer {
     engine: AIGNE;
     options?: AIGNEServerOptions | undefined;
+    /**
+     * Creates a new AIGNEServer instance.
+     *
+     * @param engine - The AIGNE engine instance that will process agent invocations
+     * @param options - Configuration options for the server
+     */
     constructor(engine: AIGNE, options?: AIGNEServerOptions | undefined);
     /**
-     * Invoke the agent with the given input.
-     * @param request - The request object, which can be a parsed JSON object, a Fetch API Request object, or a Node.js IncomingMessage object.
-     * @returns The web standard response, you can return it directly in supported frameworks like hono.
+     * Invokes an agent with the provided input and returns a standard web Response.
+     * This method serves as the primary API endpoint for agent invocation.
+     *
+     * The request can be provided in various formats to support different integration scenarios:
+     * - As a pre-parsed JavaScript object
+     * - As a Fetch API Request instance (for modern web frameworks)
+     * - As a Node.js IncomingMessage (for Express, Fastify, etc.)
+     *
+     * @param request - The agent invocation request in any supported format
+     * @returns A web standard Response object that can be returned directly in frameworks
+     *          like Hono, Next.js, or any Fetch API compatible environment
+     *
+     * @example
+     * Here's a simple example of how to use AIGNEServer with Hono:
+     * {@includeCode ../../test/server/server.test.ts#example-aigne-server-hono}
      */
     invoke(request: Record<string, unknown> | Request | IncomingMessage): Promise<Response>;
     /**
-     * Invoke the agent with the given input, and write the SSE response to the Node.js ServerResponse.
-     * @param request - The request object, which can be a parsed JSON object, a Fetch API Request object, or a Node.js IncomingMessage object.
-     * @param response - The Node.js ServerResponse object to write the SSE response to.
+     * Invokes an agent with the provided input and streams the response to a Node.js ServerResponse.
+     * This overload is specifically designed for Node.js HTTP server environments.
+     *
+     * The method handles both regular JSON responses and streaming Server-Sent Events (SSE)
+     * responses based on the options specified in the request.
+     *
+     * @param request - The agent invocation request in any supported format
+     * @param response - The Node.js ServerResponse object to write the response to
+     *
+     * @example
+     * Here's a simple example of how to use AIGNEServer with express:
+     * {@includeCode ../../test/server/server.test.ts#example-aigne-server-express}
      */
     invoke(request: Record<string, unknown> | Request | IncomingMessage, response: ServerResponse): Promise<void>;
+    /**
+     * Internal method that handles the core logic of processing an agent invocation request.
+     * Validates the request payload, finds the requested agent, and processes the invocation
+     * with either streaming or non-streaming response handling.
+     *
+     * @param request - The parsed or raw request to process
+     * @returns A standard Response object with the invocation result
+     * @private
+     */
     _invoke(request: Record<string, unknown> | Request | IncomingMessage): Promise<Response>;
+    /**
+     * Prepares and normalizes the input from various request types.
+     * Handles different request formats (Node.js IncomingMessage, Fetch API Request,
+     * or already parsed object) and extracts the JSON payload.
+     *
+     * @param request - The request object in any supported format
+     * @returns The normalized payload as a JavaScript object
+     * @private
+     */
     _prepareInput(request: Record<string, unknown> | Request | IncomingMessage): Promise<Record<string, unknown>>;
+    /**
+     * Writes a web standard Response object to a Node.js ServerResponse.
+     * Handles streaming responses and error conditions appropriately.
+     *
+     * @param response - The web standard Response object to write
+     * @param res - The Node.js ServerResponse to write to
+     * @private
+     */
     _writeResponse(response: Response, res: ServerResponse): Promise<void>;
 }

package/lib/esm/server/server.js

@@ -6,7 +6,19 @@ import { AgentResponseStreamSSE } from "../utils/event-stream.js";
 import { readableStreamToAsyncIterator } from "../utils/stream-utils.js";
 import { checkArguments, isRecord, tryOrThrow } from "../utils/type-utils.js";
 import { ServerError } from "./error.js";
+/**
+ * Default maximum allowed size for request bodies when parsing raw HTTP requests.
+ * This limits the amount of data that can be uploaded to protect against denial of service attacks.
+ * Can be overridden via AIGNEServerOptions.
+ * @internal
+ */
 const DEFAULT_MAXIMUM_BODY_SIZE = "4mb";
+/**
+ * Schema for validating agent invocation payloads.
+ * Defines the expected structure for requests to invoke an agent.
+ *
+ * @hidden
+ */
 export const invokePayloadSchema = z.object({
     agent: z.string(),
     input: z.record(z.string(), z.unknown()),
@@ -16,9 +28,29 @@ export const invokePayloadSchema = z.object({
     })
         .nullish(),
 });
+/**
+ * AIGNEServer provides HTTP API access to AIGNE capabilities.
+ * It handles requests to invoke agents, manages response streaming,
+ * and supports multiple HTTP server frameworks including Node.js http,
+ * Express, and Fetch API compatible environments.
+ *
+ * @example
+ * Here's a simple example of how to use AIGNEServer with express:
+ * {@includeCode ../../test/server/server.test.ts#example-aigne-server-express}
+ *
+ * @example
+ * Here's an example of how to use AIGNEServer with Hono:
+ * {@includeCode ../../test/server/server.test.ts#example-aigne-server-hono}
+ */
 export class AIGNEServer {
     engine;
     options;
+    /**
+     * Creates a new AIGNEServer instance.
+     *
+     * @param engine - The AIGNE engine instance that will process agent invocations
+     * @param options - Configuration options for the server
+     */
     constructor(engine, options) {
         this.engine = engine;
         this.options = options;
@@ -31,6 +63,15 @@ export class AIGNEServer {
         }
         return result;
     }
+    /**
+     * Internal method that handles the core logic of processing an agent invocation request.
+     * Validates the request payload, finds the requested agent, and processes the invocation
+     * with either streaming or non-streaming response handling.
+     *
+     * @param request - The parsed or raw request to process
+     * @returns A standard Response object with the invocation result
+     * @private
+     */
     async _invoke(request) {
         const { engine } = this;
         try {
@@ -61,6 +102,15 @@ export class AIGNEServer {
             });
         }
     }
+    /**
+     * Prepares and normalizes the input from various request types.
+     * Handles different request formats (Node.js IncomingMessage, Fetch API Request,
+     * or already parsed object) and extracts the JSON payload.
+     *
+     * @param request - The request object in any supported format
+     * @returns The normalized payload as a JavaScript object
+     * @private
+     */
     async _prepareInput(request) {
         const contentTypeError = new ServerError(415, "Unsupported Media Type: Content-Type must be application/json");
         if (request instanceof IncomingMessage) {
@@ -92,6 +142,14 @@ export class AIGNEServer {
             throw contentTypeError;
         return request;
     }
+    /**
+     * Writes a web standard Response object to a Node.js ServerResponse.
+     * Handles streaming responses and error conditions appropriately.
+     *
+     * @param response - The web standard Response object to write
+     * @param res - The Node.js ServerResponse to write to
+     * @private
+     */
     async _writeResponse(response, res) {
         try {
             res.writeHead(response.status, response.headers.toJSON());

package/lib/esm/utils/fs.d.ts

@@ -0,0 +1,2 @@
+export declare function exists(path: string): Promise<boolean>;
+export declare function expandHome(filepath: string): string;

package/lib/esm/utils/fs.js

@@ -0,0 +1,21 @@
+import { stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+export async function exists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch (e) {
+        if (e.code === "ENOENT") {
+            return false;
+        }
+        throw e;
+    }
+}
+export function expandHome(filepath) {
+    if (filepath.startsWith("~/") || filepath === "~") {
+        return join(homedir(), filepath.slice(1));
+    }
+    return filepath;
+}

package/lib/esm/utils/prompts.d.ts

@@ -1 +1,2 @@
 export declare function getJsonOutputPrompt(schema: Record<string, unknown> | string): string;
+export declare function getJsonToolInputPrompt(schema: Record<string, unknown> | string): string;

package/lib/esm/utils/prompts.js

@@ -1,10 +1,18 @@
-export function getJsonOutputPrompt(schema) {
-    let prompt = "Output must be a JSON object containing the following fields only.";
+function buildJsonPrompt(schema, firstLine) {
+    let prompt = firstLine;
     if (typeof schema === "string") {
         prompt += `\n<json_fields>\n${schema}\n</json_fields>`;
     }
     else {
         prompt += `\n<json_fields>\n${JSON.stringify(schema)}\n</json_fields>`;
     }
+    prompt +=
+        "\nDo not include any explanations, comments, or Markdown formatting (such as triple backticks). Return only the raw JSON.";
     return prompt;
 }
+export function getJsonOutputPrompt(schema) {
+    return buildJsonPrompt(schema, "Output must be a JSON object containing the following fields only.");
+}
+export function getJsonToolInputPrompt(schema) {
+    return buildJsonPrompt(schema, "Tool input must be a JSON object containing the following fields only.");
+}

package/lib/esm/utils/type-utils.d.ts

@@ -8,6 +8,7 @@ export declare function isEmpty(obj: unknown): boolean;
 export declare function isNonNullable<T>(value: T): value is NonNullable<T>;
 export declare function isNotEmpty<T>(arr: T[]): arr is [T, ...T[]];
 export declare function duplicates<T>(arr: T[], key?: (item: T) => unknown): T[];
+export declare function remove<T>(arr: T[], remove: T[] | ((item: T) => boolean)): T[];
 export declare function unique<T>(arr: T[], key?: (item: T) => unknown): T[];
 export declare function omitBy<T extends Record<string, unknown>, K extends keyof T>(obj: T, predicate: (value: T[K], key: K) => boolean): Partial<T>;
 export declare function orArrayToArray<T>(value?: T | T[]): T[];

package/lib/esm/utils/type-utils.js

@@ -34,6 +34,19 @@ export function duplicates(arr, key = (item) => item) {
     }
     return Array.from(duplicates);
 }
+export function remove(arr, remove) {
+    const removed = [];
+    for (let i = 0; i < arr.length; i++) {
+        // biome-ignore lint/style/noNonNullAssertion: <explanation>
+        const item = arr[i];
+        if ((Array.isArray(remove) && remove.includes(item)) ||
+            (typeof remove === "function" && remove(item))) {
+            removed.push(...arr.splice(i, 1));
+            i--;
+        }
+    }
+    return removed;
+}
 export function unique(arr, key = (item) => item) {
     const seen = new Set();
     return arr.filter((item) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigne/core",
-  "version": "1.13.0",
+  "version": "1.14.0",
   "description": "AIGNE core library for building AI-powered applications",
   "publishConfig": {
     "access": "public"
@@ -53,6 +53,9 @@
       "models/*": [
         "./lib/dts/models/*"
       ],
+      "memory/*": [
+        "./lib/dts/memory/*"
+      ],
       "prompt/*": [
         "./lib/dts/prompt/*"
       ],
@@ -69,7 +72,7 @@
   },
   "dependencies": {
     "@aigne/json-schema-to-zod": "^1.3.3",
-    "@modelcontextprotocol/sdk": "^1.10.2",
+    "@modelcontextprotocol/sdk": "^1.11.0",
     "@types/debug": "^4.1.12",
     "camelize-ts": "^3.0.0",
     "content-type": "^1.0.5",
@@ -77,7 +80,7 @@
     "eventsource-parser": "^3.0.1",
     "fast-deep-equal": "^3.1.3",
     "immer": "^10.1.1",
-    "inquirer": "^12.5.2",
+    "inquirer": "^12.6.0",
     "mustache": "^4.2.0",
     "nanoid": "^5.1.5",
     "p-retry": "^6.2.1",
@@ -85,7 +88,7 @@
     "ufo": "^1.6.1",
     "uuid": "^11.1.0",
     "yaml": "^2.7.1",
-    "zod": "^3.24.2",
+    "zod": "^3.24.4",
     "zod-to-json-schema": "^3.24.5"
   },
   "peerDependencies": {
@@ -95,20 +98,20 @@
     "openai": "^4.87.3"
   },
   "devDependencies": {
-    "@anthropic-ai/sdk": "^0.39.0",
-    "@google/generative-ai": "^0.24.0",
-    "@types/bun": "^1.2.9",
+    "@anthropic-ai/sdk": "^0.41.0",
+    "@google/generative-ai": "^0.24.1",
+    "@types/bun": "^1.2.12",
     "@types/compression": "^1.7.5",
     "@types/content-type": "^1.1.8",
     "@types/express": "^5.0.1",
-    "@types/mustache": "^4.2.5",
-    "@types/node": "^22.14.1",
+    "@types/mustache": "^4.2.6",
+    "@types/node": "^22.15.15",
     "compression": "^1.8.0",
     "detect-port": "^2.1.0",
     "express": "^5.1.0",
-    "hono": "^4.7.7",
+    "hono": "^4.7.8",
     "npm-run-all": "^4.1.5",
-    "openai": "^4.94.0",
+    "openai": "^4.97.0",
     "rimraf": "^6.0.1",
     "typescript": "^5.8.3"
   },

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

@@ -1,26 +0,0 @@
-import type { Context } from "../aigne/context.js";
-import type { Message } from "./agent.js";
-export interface AgentMemoryOptions {
-    /**
-     * Enable memory, default is true
-     */
-    enabled?: boolean;
-    subscribeTopic?: string | string[];
-    maxMemoriesInChat?: number;
-}
-export interface Memory {
-    role: "user" | "agent";
-    content: Message;
-    source?: string;
-}
-export declare class AgentMemory {
-    constructor(options: AgentMemoryOptions);
-    enabled?: boolean;
-    subscribeTopic?: string | string[];
-    maxMemoriesInChat?: number;
-    memories: Memory[];
-    private subscriptions;
-    addMemory(memory: Memory): void;
-    attach(context: Pick<Context, "subscribe">): void;
-    detach(): void;
-}

package/lib/cjs/agents/memory.js

@@ -1,45 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.AgentMemory = void 0;
-const zod_1 = require("zod");
-const type_utils_js_1 = require("../utils/type-utils.js");
-class AgentMemory {
-    constructor(options) {
-        (0, type_utils_js_1.checkArguments)("AgentMemory", agentMemoryOptionsSchema, options);
-        this.enabled = options.enabled ?? true;
-        this.subscribeTopic = options.subscribeTopic;
-        this.maxMemoriesInChat = options.maxMemoriesInChat;
-    }
-    enabled;
-    subscribeTopic;
-    maxMemoriesInChat;
-    memories = [];
-    subscriptions = [];
-    addMemory(memory) {
-        if (this.memories.at(-1)?.content === memory.content)
-            return;
-        // TODO: save all memories into database instead of in-memory,
-        // and give every memory a unique id to avoid duplication
-        this.memories.push(memory);
-    }
-    attach(context) {
-        for (const topic of (0, type_utils_js_1.orArrayToArray)(this.subscribeTopic)) {
-            const sub = context.subscribe(topic, ({ role, message, source }) => {
-                this.addMemory({ role, source, content: message });
-            });
-            this.subscriptions.push(sub);
-        }
-    }
-    detach() {
-        for (const sub of this.subscriptions) {
-            sub();
-        }
-        this.subscriptions = [];
-    }
-}
-exports.AgentMemory = AgentMemory;
-const agentMemoryOptionsSchema = zod_1.z.object({
-    enabled: zod_1.z.boolean().optional(),
-    subscribeTopic: zod_1.z.union([zod_1.z.string(), zod_1.z.array(zod_1.z.string())]).optional(),
-    maxMemoriesInChat: zod_1.z.number().optional(),
-});

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

@@ -1,26 +0,0 @@
-import type { Context } from "../aigne/context.js";
-import type { Message } from "./agent.js";
-export interface AgentMemoryOptions {
-    /**
-     * Enable memory, default is true
-     */
-    enabled?: boolean;
-    subscribeTopic?: string | string[];
-    maxMemoriesInChat?: number;
-}
-export interface Memory {
-    role: "user" | "agent";
-    content: Message;
-    source?: string;
-}
-export declare class AgentMemory {
-    constructor(options: AgentMemoryOptions);
-    enabled?: boolean;
-    subscribeTopic?: string | string[];
-    maxMemoriesInChat?: number;
-    memories: Memory[];
-    private subscriptions;
-    addMemory(memory: Memory): void;
-    attach(context: Pick<Context, "subscribe">): void;
-    detach(): void;
-}

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

@@ -1,26 +0,0 @@
-import type { Context } from "../aigne/context.js";
-import type { Message } from "./agent.js";
-export interface AgentMemoryOptions {
-    /**
-     * Enable memory, default is true
-     */
-    enabled?: boolean;
-    subscribeTopic?: string | string[];
-    maxMemoriesInChat?: number;
-}
-export interface Memory {
-    role: "user" | "agent";
-    content: Message;
-    source?: string;
-}
-export declare class AgentMemory {
-    constructor(options: AgentMemoryOptions);
-    enabled?: boolean;
-    subscribeTopic?: string | string[];
-    maxMemoriesInChat?: number;
-    memories: Memory[];
-    private subscriptions;
-    addMemory(memory: Memory): void;
-    attach(context: Pick<Context, "subscribe">): void;
-    detach(): void;
-}

package/lib/esm/agents/memory.js

@@ -1,41 +0,0 @@
-import { z } from "zod";
-import { checkArguments, orArrayToArray } from "../utils/type-utils.js";
-export class AgentMemory {
-    constructor(options) {
-        checkArguments("AgentMemory", agentMemoryOptionsSchema, options);
-        this.enabled = options.enabled ?? true;
-        this.subscribeTopic = options.subscribeTopic;
-        this.maxMemoriesInChat = options.maxMemoriesInChat;
-    }
-    enabled;
-    subscribeTopic;
-    maxMemoriesInChat;
-    memories = [];
-    subscriptions = [];
-    addMemory(memory) {
-        if (this.memories.at(-1)?.content === memory.content)
-            return;
-        // TODO: save all memories into database instead of in-memory,
-        // and give every memory a unique id to avoid duplication
-        this.memories.push(memory);
-    }
-    attach(context) {
-        for (const topic of orArrayToArray(this.subscribeTopic)) {
-            const sub = context.subscribe(topic, ({ role, message, source }) => {
-                this.addMemory({ role, source, content: message });
-            });
-            this.subscriptions.push(sub);
-        }
-    }
-    detach() {
-        for (const sub of this.subscriptions) {
-            sub();
-        }
-        this.subscriptions = [];
-    }
-}
-const agentMemoryOptionsSchema = z.object({
-    enabled: z.boolean().optional(),
-    subscribeTopic: z.union([z.string(), z.array(z.string())]).optional(),
-    maxMemoriesInChat: z.number().optional(),
-});