@aigne/transport 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## [0.2.0](https://github.com/AIGNE-io/aigne-framework/compare/transport-v0.1.0...transport-v0.2.0) (2025-05-25)
+
+
+### Features
+
+* add user context support ([#131](https://github.com/AIGNE-io/aigne-framework/issues/131)) ([4dd9d20](https://github.com/AIGNE-io/aigne-framework/commit/4dd9d20953f6ac33933723db56efd9b44bafeb02))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @aigne/openai bumped to 0.2.0
+  * devDependencies
+    * @aigne/core bumped to 1.17.0
+    * @aigne/test-utils bumped to 0.3.1
+
 ## [0.1.0](https://github.com/AIGNE-io/aigne-framework/compare/transport-v0.0.1...transport-v0.1.0) (2025-05-23)
 
 

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

@@ -16,7 +16,7 @@ export interface AIGNEHTTPClientOptions {
  * Options for invoking an agent through the AIGNEHTTPClient.
  * Extends the standard AgentInvokeOptions with client-specific options.
  */
-export interface AIGNEHTTPClientInvokeOptions extends AgentInvokeOptions {
+export interface AIGNEHTTPClientInvokeOptions extends Omit<AgentInvokeOptions, "context"> {
     /**
      * Additional fetch API options to customize the HTTP request.
      * These options will be merged with the default options used by the client.

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

@@ -1,5 +1,5 @@
 import { IncomingMessage, ServerResponse } from "node:http";
-import type { AIGNE } from "@aigne/core";
+import type { AIGNE, UserContext } from "@aigne/core";
 import { z } from "zod";
 /**
  * Schema for validating agent invocation payloads.
@@ -10,19 +10,23 @@ import { z } from "zod";
 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<{
+    options: z.ZodEffects<z.ZodOptional<z.ZodNullable<z.ZodObject<{
         streaming: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
     }, "strip", z.ZodTypeAny, {
         streaming?: boolean | null | undefined;
     }, {
         streaming?: boolean | null | undefined;
-    }>>>;
+    }>>>, {
+        streaming?: boolean | null | undefined;
+    } | undefined, {
+        streaming?: boolean | null | undefined;
+    } | null | undefined>;
 }, "strip", z.ZodTypeAny, {
     agent: string;
     input: string | Record<string, unknown>;
     options?: {
         streaming?: boolean | null | undefined;
-    } | null | undefined;
+    } | undefined;
 }, {
     agent: string;
     input: string | Record<string, unknown>;
@@ -46,6 +50,9 @@ export interface AIGNEHTTPServerOptions {
      */
     maximumBodySize?: string;
 }
+export interface AIGNEHTTPServerInvokeOptions<U extends UserContext = UserContext> {
+    userContext?: U;
+}
 /**
  * AIGNEHTTPServer provides HTTP API access to AIGNE capabilities.
  * It handles requests to invoke agents, manages response streaming,
@@ -87,7 +94,7 @@ export declare class AIGNEHTTPServer {
      * 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>;
+    invoke(request: Record<string, unknown> | Request | IncomingMessage, options?: ServerResponse | AIGNEHTTPServerInvokeOptions): 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.
@@ -102,7 +109,7 @@ export declare class AIGNEHTTPServer {
      * 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>;
+    invoke(request: Record<string, unknown> | Request | IncomingMessage, response: ServerResponse, options?: AIGNEHTTPServerInvokeOptions): 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
@@ -112,7 +119,7 @@ export declare class AIGNEHTTPServer {
      * @returns A standard Response object with the invocation result
      * @private
      */
-    _invoke(request: Record<string, unknown> | Request | IncomingMessage): Promise<Response>;
+    _invoke(request: Record<string, unknown> | Request | IncomingMessage, { userContext }?: AIGNEHTTPServerInvokeOptions): Promise<Response>;
     /**
      * Prepares and normalizes the input from various request types.
      * Handles different request formats (Node.js IncomingMessage, Fetch API Request,

package/lib/cjs/http-server/server.js

@@ -28,10 +28,9 @@ exports.invokePayloadSchema = zod_1.z.object({
     agent: zod_1.z.string(),
     input: zod_1.z.union([zod_1.z.string(), zod_1.z.record(zod_1.z.string(), zod_1.z.unknown())]),
     options: zod_1.z
-        .object({
-        streaming: zod_1.z.boolean().nullish(),
-    })
-        .nullish(),
+        .object({ streaming: zod_1.z.boolean().nullish() })
+        .nullish()
+        .transform((v) => v ?? undefined),
 });
 /**
  * AIGNEHTTPServer provides HTTP API access to AIGNE capabilities.
@@ -60,8 +59,9 @@ class AIGNEHTTPServer {
         this.engine = engine;
         this.options = options;
     }
-    async invoke(request, response) {
-        const result = await this._invoke(request);
+    async invoke(request, response, options) {
+        const opts = !(response instanceof node_http_1.ServerResponse) ? options || response : options;
+        const result = await this._invoke(request, { userContext: opts?.userContext });
         if (response instanceof node_http_1.ServerResponse) {
             await this._writeResponse(result, response);
             return;
@@ -77,21 +77,21 @@ class AIGNEHTTPServer {
      * @returns A standard Response object with the invocation result
      * @private
      */
-    async _invoke(request) {
+    async _invoke(request, { userContext } = {}) {
         const { engine } = this;
         try {
             const payload = await this._prepareInput(request);
-            const { agent: agentName, input, options, } = (0, type_utils_js_1.tryOrThrow)(() => (0, type_utils_js_1.checkArguments)(`Invoke agent ${payload.agent}`, exports.invokePayloadSchema, payload), (error) => new error_js_1.ServerError(400, error.message));
+            const { agent: agentName, input, options: { streaming } = {}, } = (0, type_utils_js_1.tryOrThrow)(() => (0, type_utils_js_1.checkArguments)(`Invoke agent ${payload.agent}`, exports.invokePayloadSchema, payload), (error) => new error_js_1.ServerError(400, error.message));
             const agent = engine.agents[agentName];
             if (!agent)
                 throw new error_js_1.ServerError(404, `Agent ${agentName} not found`);
-            if (!options?.streaming) {
-                const result = await engine.invoke(agent, input);
+            if (!streaming) {
+                const result = await engine.invoke(agent, input, { userContext });
                 return new Response(JSON.stringify(result), {
                     headers: { "Content-Type": "application/json" },
                 });
             }
-            const stream = await engine.invoke(agent, input, { streaming: true });
+            const stream = await engine.invoke(agent, input, { userContext, streaming: true });
             return new Response(new event_stream_js_1.AgentResponseStreamSSE(stream), {
                 headers: {
                     "Content-Type": "text/event-stream",

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

@@ -16,7 +16,7 @@ export interface AIGNEHTTPClientOptions {
  * Options for invoking an agent through the AIGNEHTTPClient.
  * Extends the standard AgentInvokeOptions with client-specific options.
  */
-export interface AIGNEHTTPClientInvokeOptions extends AgentInvokeOptions {
+export interface AIGNEHTTPClientInvokeOptions extends Omit<AgentInvokeOptions, "context"> {
     /**
      * Additional fetch API options to customize the HTTP request.
      * These options will be merged with the default options used by the client.

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

@@ -1,5 +1,5 @@
 import { IncomingMessage, ServerResponse } from "node:http";
-import type { AIGNE } from "@aigne/core";
+import type { AIGNE, UserContext } from "@aigne/core";
 import { z } from "zod";
 /**
  * Schema for validating agent invocation payloads.
@@ -10,19 +10,23 @@ import { z } from "zod";
 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<{
+    options: z.ZodEffects<z.ZodOptional<z.ZodNullable<z.ZodObject<{
         streaming: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
     }, "strip", z.ZodTypeAny, {
         streaming?: boolean | null | undefined;
     }, {
         streaming?: boolean | null | undefined;
-    }>>>;
+    }>>>, {
+        streaming?: boolean | null | undefined;
+    } | undefined, {
+        streaming?: boolean | null | undefined;
+    } | null | undefined>;
 }, "strip", z.ZodTypeAny, {
     agent: string;
     input: string | Record<string, unknown>;
     options?: {
         streaming?: boolean | null | undefined;
-    } | null | undefined;
+    } | undefined;
 }, {
     agent: string;
     input: string | Record<string, unknown>;
@@ -46,6 +50,9 @@ export interface AIGNEHTTPServerOptions {
      */
     maximumBodySize?: string;
 }
+export interface AIGNEHTTPServerInvokeOptions<U extends UserContext = UserContext> {
+    userContext?: U;
+}
 /**
  * AIGNEHTTPServer provides HTTP API access to AIGNE capabilities.
  * It handles requests to invoke agents, manages response streaming,
@@ -87,7 +94,7 @@ export declare class AIGNEHTTPServer {
      * 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>;
+    invoke(request: Record<string, unknown> | Request | IncomingMessage, options?: ServerResponse | AIGNEHTTPServerInvokeOptions): 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.
@@ -102,7 +109,7 @@ export declare class AIGNEHTTPServer {
      * 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>;
+    invoke(request: Record<string, unknown> | Request | IncomingMessage, response: ServerResponse, options?: AIGNEHTTPServerInvokeOptions): 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
@@ -112,7 +119,7 @@ export declare class AIGNEHTTPServer {
      * @returns A standard Response object with the invocation result
      * @private
      */
-    _invoke(request: Record<string, unknown> | Request | IncomingMessage): Promise<Response>;
+    _invoke(request: Record<string, unknown> | Request | IncomingMessage, { userContext }?: AIGNEHTTPServerInvokeOptions): Promise<Response>;
     /**
      * Prepares and normalizes the input from various request types.
      * Handles different request formats (Node.js IncomingMessage, Fetch API Request,

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

@@ -16,7 +16,7 @@ export interface AIGNEHTTPClientOptions {
  * Options for invoking an agent through the AIGNEHTTPClient.
  * Extends the standard AgentInvokeOptions with client-specific options.
  */
-export interface AIGNEHTTPClientInvokeOptions extends AgentInvokeOptions {
+export interface AIGNEHTTPClientInvokeOptions extends Omit<AgentInvokeOptions, "context"> {
     /**
      * Additional fetch API options to customize the HTTP request.
      * These options will be merged with the default options used by the client.

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

@@ -1,5 +1,5 @@
 import { IncomingMessage, ServerResponse } from "node:http";
-import type { AIGNE } from "@aigne/core";
+import type { AIGNE, UserContext } from "@aigne/core";
 import { z } from "zod";
 /**
  * Schema for validating agent invocation payloads.
@@ -10,19 +10,23 @@ import { z } from "zod";
 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<{
+    options: z.ZodEffects<z.ZodOptional<z.ZodNullable<z.ZodObject<{
         streaming: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
     }, "strip", z.ZodTypeAny, {
         streaming?: boolean | null | undefined;
     }, {
         streaming?: boolean | null | undefined;
-    }>>>;
+    }>>>, {
+        streaming?: boolean | null | undefined;
+    } | undefined, {
+        streaming?: boolean | null | undefined;
+    } | null | undefined>;
 }, "strip", z.ZodTypeAny, {
     agent: string;
     input: string | Record<string, unknown>;
     options?: {
         streaming?: boolean | null | undefined;
-    } | null | undefined;
+    } | undefined;
 }, {
     agent: string;
     input: string | Record<string, unknown>;
@@ -46,6 +50,9 @@ export interface AIGNEHTTPServerOptions {
      */
     maximumBodySize?: string;
 }
+export interface AIGNEHTTPServerInvokeOptions<U extends UserContext = UserContext> {
+    userContext?: U;
+}
 /**
  * AIGNEHTTPServer provides HTTP API access to AIGNE capabilities.
  * It handles requests to invoke agents, manages response streaming,
@@ -87,7 +94,7 @@ export declare class AIGNEHTTPServer {
      * 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>;
+    invoke(request: Record<string, unknown> | Request | IncomingMessage, options?: ServerResponse | AIGNEHTTPServerInvokeOptions): 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.
@@ -102,7 +109,7 @@ export declare class AIGNEHTTPServer {
      * 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>;
+    invoke(request: Record<string, unknown> | Request | IncomingMessage, response: ServerResponse, options?: AIGNEHTTPServerInvokeOptions): 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
@@ -112,7 +119,7 @@ export declare class AIGNEHTTPServer {
      * @returns A standard Response object with the invocation result
      * @private
      */
-    _invoke(request: Record<string, unknown> | Request | IncomingMessage): Promise<Response>;
+    _invoke(request: Record<string, unknown> | Request | IncomingMessage, { userContext }?: AIGNEHTTPServerInvokeOptions): Promise<Response>;
     /**
      * Prepares and normalizes the input from various request types.
      * Handles different request formats (Node.js IncomingMessage, Fetch API Request,

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

@@ -22,10 +22,9 @@ 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(),
+        .object({ streaming: z.boolean().nullish() })
+        .nullish()
+        .transform((v) => v ?? undefined),
 });
 /**
  * AIGNEHTTPServer provides HTTP API access to AIGNE capabilities.
@@ -54,8 +53,9 @@ export class AIGNEHTTPServer {
         this.engine = engine;
         this.options = options;
     }
-    async invoke(request, response) {
-        const result = await this._invoke(request);
+    async invoke(request, response, options) {
+        const opts = !(response instanceof ServerResponse) ? options || response : options;
+        const result = await this._invoke(request, { userContext: opts?.userContext });
         if (response instanceof ServerResponse) {
             await this._writeResponse(result, response);
             return;
@@ -71,21 +71,21 @@ export class AIGNEHTTPServer {
      * @returns A standard Response object with the invocation result
      * @private
      */
-    async _invoke(request) {
+    async _invoke(request, { userContext } = {}) {
         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: agentName, input, options: { streaming } = {}, } = 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);
+            if (!streaming) {
+                const result = await engine.invoke(agent, input, { userContext });
                 return new Response(JSON.stringify(result), {
                     headers: { "Content-Type": "application/json" },
                 });
             }
-            const stream = await engine.invoke(agent, input, { streaming: true });
+            const stream = await engine.invoke(agent, input, { userContext, streaming: true });
             return new Response(new AgentResponseStreamSSE(stream), {
                 headers: {
                     "Content-Type": "text/event-stream",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigne/transport",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "AIGNE Transport SDK providing HTTP client and server implementations for communication between AIGNE components",
   "publishConfig": {
     "access": "public"
@@ -39,7 +39,7 @@
     }
   },
   "dependencies": {
-    "@aigne/openai": "^0.1.0"
+    "@aigne/openai": "^0.2.0"
   },
   "devDependencies": {
     "@types/bun": "^1.2.12",
@@ -52,8 +52,8 @@
     "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"
+    "@aigne/core": "^1.17.0",
+    "@aigne/test-utils": "^0.3.1"
   },
   "scripts": {
     "lint": "tsc --noEmit",