@aigne/core 1.13.0 → 1.14.0

package/lib/cjs/server/error.d.ts

@@ -1,4 +1,15 @@
+/**
+ * Custom error class for AIGNEServer HTTP-related errors.
+ * Extends the standard Error class with an HTTP status code property.
+ * This allows error responses to include appropriate HTTP status codes.
+ */
 export declare class ServerError extends Error {
     status: number;
+    /**
+     * Creates a new ServerError instance.
+     *
+     * @param status - The HTTP status code for this error (e.g., 400, 404, 500)
+     * @param message - The error message describing what went wrong
+     */
     constructor(status: number, message: string);
 }

package/lib/cjs/server/error.js

@@ -1,8 +1,19 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ServerError = void 0;
+/**
+ * Custom error class for AIGNEServer HTTP-related errors.
+ * Extends the standard Error class with an HTTP status code property.
+ * This allows error responses to include appropriate HTTP status codes.
+ */
 class ServerError extends Error {
     status;
+    /**
+     * Creates a new ServerError instance.
+     *
+     * @param status - The HTTP status code for this error (e.g., 400, 404, 500)
+     * @param message - The error message describing what went wrong
+     */
     constructor(status, message) {
         super(message);
         this.status = status;

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

@@ -0,0 +1,2 @@
+export * from "./error.js";
+export * from "./server.js";

package/lib/cjs/server/index.js

@@ -0,0 +1,18 @@
+"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("./error.js"), exports);
+__exportStar(require("./server.js"), exports);

package/lib/cjs/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/cjs/server/server.js

@@ -12,7 +12,19 @@ const event_stream_js_1 = require("../utils/event-stream.js");
 const stream_utils_js_1 = require("../utils/stream-utils.js");
 const type_utils_js_1 = require("../utils/type-utils.js");
 const error_js_1 = require("./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
+ */
 exports.invokePayloadSchema = zod_1.z.object({
     agent: zod_1.z.string(),
     input: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()),
@@ -22,9 +34,29 @@ exports.invokePayloadSchema = zod_1.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}
+ */
 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;
@@ -37,6 +69,15 @@ 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 {
@@ -67,6 +108,15 @@ 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 error_js_1.ServerError(415, "Unsupported Media Type: Content-Type must be application/json");
         if (request instanceof node_http_1.IncomingMessage) {
@@ -98,6 +148,14 @@ 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/cjs/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/cjs/utils/fs.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.exists = exists;
+exports.expandHome = expandHome;
+const promises_1 = require("node:fs/promises");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+async function exists(path) {
+    try {
+        await (0, promises_1.stat)(path);
+        return true;
+    }
+    catch (e) {
+        if (e.code === "ENOENT") {
+            return false;
+        }
+        throw e;
+    }
+}
+function expandHome(filepath) {
+    if (filepath.startsWith("~/") || filepath === "~") {
+        return (0, node_path_1.join)((0, node_os_1.homedir)(), filepath.slice(1));
+    }
+    return filepath;
+}

package/lib/cjs/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/cjs/utils/prompts.js

@@ -1,13 +1,22 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getJsonOutputPrompt = getJsonOutputPrompt;
-function getJsonOutputPrompt(schema) {
-    let prompt = "Output must be a JSON object containing the following fields only.";
+exports.getJsonToolInputPrompt = getJsonToolInputPrompt;
+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;
 }
+function getJsonOutputPrompt(schema) {
+    return buildJsonPrompt(schema, "Output must be a JSON object containing the following fields only.");
+}
+function getJsonToolInputPrompt(schema) {
+    return buildJsonPrompt(schema, "Tool input must be a JSON object containing the following fields only.");
+}

package/lib/cjs/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/cjs/utils/type-utils.js

@@ -6,6 +6,7 @@ exports.isEmpty = isEmpty;
 exports.isNonNullable = isNonNullable;
 exports.isNotEmpty = isNotEmpty;
 exports.duplicates = duplicates;
+exports.remove = remove;
 exports.unique = unique;
 exports.omitBy = omitBy;
 exports.orArrayToArray = orArrayToArray;
@@ -48,6 +49,19 @@ function duplicates(arr, key = (item) => item) {
     }
     return Array.from(duplicates);
 }
+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;
+}
 function unique(arr, key = (item) => item) {
     const seen = new Set();
     return arr.filter((item) => {