@aigne/transport 0.1.0

package/lib/esm/http-client/client.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Client module used to interact with the AIGNE framework.
+ */
+import type { AgentInvokeOptions, AgentResponse, AgentResponseStream, Message } from "@aigne/core";
+/**
+ * Configuration options for the AIGNEHTTPClient.
+ */
+export interface AIGNEHTTPClientOptions {
+    /**
+     * 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 AIGNEHTTPClient.
+ * Extends the standard AgentInvokeOptions with client-specific options.
+ */
+export interface AIGNEHTTPClientInvokeOptions 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>;
+}
+/**
+ * Http client for interacting with a remote AIGNE server.
+ * AIGNEHTTPClient 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/http-client/http-client.test.ts#example-aigne-client-simple}
+ *
+ * @example
+ * Here's an example of how to use AIGNEClient with streaming response:
+ * {@includeCode ../../test/http-client/http-client.test.ts#example-aigne-client-streaming}
+ */
+export declare class AIGNEHTTPClient {
+    options: AIGNEHTTPClientOptions;
+    /**
+     * Creates a new AIGNEClient instance.
+     *
+     * @param options - Configuration options for connecting to the AIGNE server
+     */
+    constructor(options: AIGNEHTTPClientOptions);
+    /**
+     * 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/http-client/http-client.test.ts#example-aigne-client-simple}
+     */
+    invoke<I extends Message, O extends Message>(agent: string, input: string | I, options?: AIGNEHTTPClientInvokeOptions & {
+        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/http-client/http-client.test.ts#example-aigne-client-streaming}
+     */
+    invoke<I extends Message, O extends Message>(agent: string, input: string | I, options: AIGNEHTTPClientInvokeOptions & {
+        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: string | I, options?: AIGNEHTTPClientInvokeOptions): 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/http-client/client.js

@@ -0,0 +1,83 @@
+/**
+ * Client module used to interact with the AIGNE framework.
+ */
+import { AgentResponseStreamParser, EventStreamParser } from "@aigne/core/utils/event-stream.js";
+import { tryOrThrow } from "@aigne/core/utils/type-utils.js";
+/**
+ * Http client for interacting with a remote AIGNE server.
+ * AIGNEHTTPClient 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/http-client/http-client.test.ts#example-aigne-client-simple}
+ *
+ * @example
+ * Here's an example of how to use AIGNEClient with streaming response:
+ * {@includeCode ../../test/http-client/http-client.test.ts#example-aigne-client-streaming}
+ */
+export class AIGNEHTTPClient {
+    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",
+            headers: {
+                "Content-Type": "application/json",
+                ...options?.fetchOptions?.headers,
+            },
+            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) {
+            let message;
+            try {
+                const text = await result.text();
+                const json = tryOrThrow(() => JSON.parse(text));
+                message = json?.error?.message || text;
+            }
+            catch {
+                // ignore
+            }
+            throw new Error(`Failed to fetch url ${args[0]} with status ${result.status}: ${message}`);
+        }
+        return result;
+    }
+}

package/lib/esm/http-client/index.d.ts

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

package/lib/esm/http-client/index.js

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

package/lib/esm/http-server/error.d.ts

@@ -0,0 +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/esm/http-server/error.js

@@ -0,0 +1,18 @@
+/**
+ * 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 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/esm/http-server/index.d.ts

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

package/lib/esm/http-server/index.js

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

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

@@ -0,0 +1,135 @@
+import { IncomingMessage, ServerResponse } from "node:http";
+import type { AIGNE } from "@aigne/core";
+import { z } from "zod";
+/**
+ * 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.ZodUnion<[z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>]>;
+    options: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        streaming: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    }, "strip", z.ZodTypeAny, {
+        streaming?: boolean | null | undefined;
+    }, {
+        streaming?: boolean | null | undefined;
+    }>>>;
+}, "strip", z.ZodTypeAny, {
+    agent: string;
+    input: string | Record<string, unknown>;
+    options?: {
+        streaming?: boolean | null | undefined;
+    } | null | undefined;
+}, {
+    agent: string;
+    input: string | Record<string, unknown>;
+    options?: {
+        streaming?: boolean | null | undefined;
+    } | null | undefined;
+}>;
+/**
+ * Configuration options for the AIGNEHTTPServer.
+ * These options control various aspects of server behavior including
+ * request parsing, payload limits, and response handling.
+ */
+export interface AIGNEHTTPServerOptions {
+    /**
+     * 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;
+}
+/**
+ * AIGNEHTTPServer 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/http-server/http-server.test.ts#example-aigne-server-express}
+ *
+ * @example
+ * Here's an example of how to use AIGNEServer with Hono:
+ * {@includeCode ../../test/http-server/http-server.test.ts#example-aigne-server-hono}
+ */
+export declare class AIGNEHTTPServer {
+    engine: AIGNE;
+    options?: AIGNEHTTPServerOptions | 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?: AIGNEHTTPServerOptions | undefined);
+    /**
+     * 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/http-server/http-server.test.ts#example-aigne-server-hono}
+     */
+    invoke(request: Record<string, unknown> | Request | IncomingMessage): Promise<Response>;
+    /**
+     * 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/http-server/http-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/http-server/server.js

@@ -0,0 +1,180 @@
+import { IncomingMessage, ServerResponse } from "node:http";
+import { AgentResponseStreamSSE } from "@aigne/core/utils/event-stream.js";
+import { checkArguments, isRecord, tryOrThrow } from "@aigne/core/utils/type-utils.js";
+import contentType from "content-type";
+import getRawBody from "raw-body";
+import { z } from "zod";
+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.union([z.string(), z.record(z.string(), z.unknown())]),
+    options: z
+        .object({
+        streaming: z.boolean().nullish(),
+    })
+        .nullish(),
+});
+/**
+ * AIGNEHTTPServer 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/http-server/http-server.test.ts#example-aigne-server-express}
+ *
+ * @example
+ * Here's an example of how to use AIGNEServer with Hono:
+ * {@includeCode ../../test/http-server/http-server.test.ts#example-aigne-server-hono}
+ */
+export class AIGNEHTTPServer {
+    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;
+    }
+    async invoke(request, response) {
+        const result = await this._invoke(request);
+        if (response instanceof ServerResponse) {
+            await this._writeResponse(result, response);
+            return;
+        }
+        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 {
+            const payload = await this._prepareInput(request);
+            const { agent: agentName, input, options, } = tryOrThrow(() => checkArguments(`Invoke agent ${payload.agent}`, invokePayloadSchema, payload), (error) => new ServerError(400, error.message));
+            const agent = engine.agents[agentName];
+            if (!agent)
+                throw new ServerError(404, `Agent ${agentName} not found`);
+            if (!options?.streaming) {
+                const result = await engine.invoke(agent, input);
+                return new Response(JSON.stringify(result), {
+                    headers: { "Content-Type": "application/json" },
+                });
+            }
+            const stream = await engine.invoke(agent, input, { streaming: true });
+            return new Response(new AgentResponseStreamSSE(stream), {
+                headers: {
+                    "Content-Type": "text/event-stream",
+                    "Cache-Control": "no-cache",
+                    "X-Accel-Buffering": "no",
+                },
+            });
+        }
+        catch (error) {
+            return new Response(JSON.stringify({ error: { message: error.message } }), {
+                status: error instanceof ServerError ? error.status : 500,
+                headers: { "Content-Type": "application/json" },
+            });
+        }
+    }
+    /**
+     * 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) {
+            // Support for express with json() middleware
+            if ("body" in request && typeof request.body === "object") {
+                if (!isRecord(request.body))
+                    throw contentTypeError;
+                return request.body;
+            }
+            // Support vanilla nodejs http server
+            const maximumBodySize = this.options?.maximumBodySize || DEFAULT_MAXIMUM_BODY_SIZE;
+            const ct = request.headers["content-type"];
+            if (!ct || !ct.includes("application/json"))
+                throw contentTypeError;
+            const parsedCt = contentType.parse(ct);
+            const raw = await getRawBody(request, {
+                limit: maximumBodySize,
+                encoding: parsedCt.parameters.charset ?? "utf-8",
+            });
+            return tryOrThrow(() => JSON.parse(raw.toString()), (error) => new ServerError(400, `Parse request body to json error: ${error.message}`));
+        }
+        if (request instanceof Request) {
+            if (!request.headers.get("content-type")?.includes("application/json")) {
+                throw contentTypeError;
+            }
+            return await request.json();
+        }
+        if (!isRecord(request))
+            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, Object.fromEntries(response.headers.entries()));
+            res.flushHeaders();
+            if (!response.body)
+                throw new Error("Response body is empty");
+            for await (const chunk of response.body) {
+                res.write(chunk);
+                // Support for express with compression middleware
+                if ("flush" in res && typeof res.flush === "function") {
+                    res.flush();
+                }
+            }
+        }
+        catch (error) {
+            if (!res.headersSent) {
+                res.writeHead(error instanceof ServerError ? error.status : 500, {
+                    "Content-Type": "application/json",
+                });
+            }
+            if (res.writable) {
+                res.write(JSON.stringify({ error: { message: error.message } }));
+            }
+        }
+        finally {
+            res.end();
+        }
+    }
+}

package/lib/esm/index.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/esm/index.js

@@ -0,0 +1 @@
+export {};

package/lib/esm/package.json

@@ -0,0 +1 @@
+{"type": "module"}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@aigne/transport",
+  "version": "0.1.0",
+  "description": "AIGNE Transport SDK providing HTTP client and server implementations for communication between AIGNE components",
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": "Arcblock <blocklet@arcblock.io> https://github.com/blocklet",
+  "homepage": "https://github.com/AIGNE-io/aigne-framework",
+  "license": "Elastic-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AIGNE-io/aigne-framework"
+  },
+  "files": [
+    "lib/cjs",
+    "lib/dts",
+    "lib/esm",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "type": "module",
+  "main": "./lib/cjs/index.js",
+  "module": "./lib/esm/index.js",
+  "types": "./lib/dts/index.d.ts",
+  "exports": {
+    "./*": {
+      "import": "./lib/esm/*",
+      "require": "./lib/cjs/*",
+      "types": "./lib/dts/*"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "*": [
+        "./lib/dts/*"
+      ]
+    }
+  },
+  "dependencies": {
+    "@aigne/openai": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.2.12",
+    "@types/express": "^5.0.1",
+    "@types/node": "^22.15.15",
+    "compression": "^1.8.0",
+    "detect-port": "^2.1.0",
+    "express": "^5.1.0",
+    "hono": "^4.7.10",
+    "npm-run-all": "^4.1.5",
+    "rimraf": "^6.0.1",
+    "typescript": "^5.8.3",
+    "@aigne/core": "^1.16.0",
+    "@aigne/test-utils": "^0.3.0"
+  },
+  "scripts": {
+    "lint": "tsc --noEmit",
+    "build": "tsc --build scripts/tsconfig.build.json",
+    "clean": "rimraf lib test/coverage",
+    "test": "bun test",
+    "test:coverage": "bun test --coverage --coverage-reporter=lcov --coverage-reporter=text",
+    "postbuild": "echo '{\"type\": \"module\"}' > lib/esm/package.json && echo '{\"type\": \"commonjs\"}' > lib/cjs/package.json"
+  }
+}