@microsoft/agents-hosting-express 1.6.0-beta.24.g285b02c21b → 1.6.0-beta.30.g545c41a189

package/README.md

@@ -2,17 +2,118 @@
 
 ## Overview
 
-Provides integration to host the agent in Express using `startServer`
+Provides integration to host agents with Express. The package offers three levels of abstraction:
+
+- **`startServer`** — Quickest way to get running. Creates an Express app, wires up auth, and starts listening.
+- **`createAgentRequestHandler`** — A handler signature without Express imports, for frameworks that can provide Express-compatible request/response objects.
+- **`createCloudAdapter`** — Low-level factory to get a `CloudAdapter` for full control over request processing.
 
 ## Usage
 
- ```ts
- import { AgentApplication, TurnState } from '@microsoft/agents-hosting';
- import { startServer } from '@microsoft/agents-hosting-express';
- 
- const app = new AgentApplication<TurnState>();
- app.onMessage('hello', async (context, state) => {
-   await context.sendActivity('Hello, world!');
- });
- startServer(app);
-  ```
+### Basic — `startServer`
+
+```ts
+import { AgentApplication, TurnState } from '@microsoft/agents-hosting';
+import { startServer } from '@microsoft/agents-hosting-express';
+
+const app = new AgentApplication<TurnState>();
+app.onActivity('message', async (context) => {
+  await context.sendActivity('Hello, world!');
+});
+startServer(app);
+```
+
+### Custom routes alongside the agent endpoint
+
+Use the `beforeListen` hook to add routes before the server starts listening:
+
+_**Note:** The agent messages route is registered *after* this callback.
+Avoid adding catch-all routes (e.g., `app.all('*', ...)` or `app.use('*', ...)`)
+here, as they will shadow the messages endpoint._
+
+```ts
+import { AgentApplication, TurnState } from '@microsoft/agents-hosting';
+import { startServer } from '@microsoft/agents-hosting-express';
+
+const agent = new AgentApplication<TurnState>();
+
+startServer(agent, {
+  port: 8080,
+  routePath: '/bot/messages',
+  beforeListen: (app) => {
+    app.get('/health', (req, res) => res.json({ status: 'ok' }));
+  }
+});
+```
+
+### Custom Express setup — `createAgentRequestHandler`
+
+If you manage your own Express app (or another framework with an adapter that exposes Express-compatible request/response objects), use `createAgentRequestHandler` to get a handler that includes JWT authorization and activity processing:
+
+```ts
+import express from 'express';
+import { AgentApplication, TurnState } from '@microsoft/agents-hosting';
+import { createAgentRequestHandler } from '@microsoft/agents-hosting-express';
+
+const agent = new AgentApplication<TurnState>();
+const handler = createAgentRequestHandler(agent);
+
+const app = express();
+app.use(express.json());
+app.post('/api/messages', handler);
+app.get('/health', (req, res) => res.json({ status: 'ok' }));
+app.listen(3978);
+```
+
+### Advanced — `createCloudAdapter`
+
+For full control, use `createCloudAdapter` to obtain the `CloudAdapter` directly. This is useful when you need to customize request processing and can provide the request/response shape expected by `CloudAdapter.process`.
+
+`CloudAdapter.process` expects:
+
+- a parsed activity body on `req.body` (for example, via `express.json()` in Express)
+- a response object that supports `status()`, `setHeader()`, `send()`, and `end()`
+
+If your framework does not expose those members directly, add an adapter layer before calling `adapter.process`.
+
+```ts
+import http from 'node:http';
+import { AgentApplication, TurnState, getAuthConfigWithDefaults } from '@microsoft/agents-hosting';
+import { createCloudAdapter } from '@microsoft/agents-hosting-express';
+
+const agent = new AgentApplication<TurnState>();
+const authConfig = getAuthConfigWithDefaults();
+const { adapter, headerPropagation } = createCloudAdapter(agent, authConfig);
+
+const server = http.createServer(async (req, res) => {
+  if (req.method === 'POST' && req.url === '/api/messages') {
+    // Adapt request/response as needed so they match CloudAdapter.process expectations.
+    await adapter.process(req as any, res as any, (context) => agent.run(context), headerPropagation);
+  }
+});
+server.listen(3978);
+```
+
+### Setting up auth middleware manually
+
+If you need to apply JWT authorization on specific routes in your own Express app:
+
+```ts
+import express from 'express';
+import { authorizeJWT, getAuthConfigWithDefaults, AgentApplication, TurnState } from '@microsoft/agents-hosting';
+import { createCloudAdapter } from '@microsoft/agents-hosting-express';
+
+const agent = new AgentApplication<TurnState>();
+const authConfig = getAuthConfigWithDefaults();
+const { adapter, headerPropagation } = createCloudAdapter(agent, authConfig);
+
+const app = express();
+app.use(express.json());
+
+// JWT is applied only on the agent route — custom routes remain unauthenticated
+app.post('/api/messages', authorizeJWT(authConfig), (req, res) =>
+  adapter.process(req, res, (context) => agent.run(context), headerPropagation)
+);
+app.get('/health', (req, res) => res.json({ status: 'ok' }));
+app.listen(3978);
+```

package/dist/package.json

@@ -1,7 +1,7 @@
 {
     "$schema": "https://json.schemastore.org/package.json",
     "name": "@microsoft/agents-hosting-express",
-    "version": "1.6.0-beta.24.g285b02c21b",
+    "version": "1.6.0-beta.30.g545c41a189",
     "homepage": "https://github.com/microsoft/Agents-for-js",
     "repository": {
         "type": "git",
@@ -19,8 +19,10 @@
     "main": "dist/src/index.js",
     "types": "dist/src/index.d.ts",
     "dependencies": {
-        "@microsoft/agents-hosting": "1.6.0-beta.24.g285b02c21b",
-        "express": "5.2.1"
+        "@microsoft/agents-hosting": "1.6.0-beta.30.g545c41a189",
+        "@microsoft/agents-telemetry": "1.6.0-beta.30.g545c41a189",
+        "express": "5.2.1",
+        "express-rate-limit": "8.5.2"
     },
     "license": "MIT",
     "files": [

package/dist/src/createAgentRequestHandler.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { ActivityHandler, AgentApplication, AuthConfiguration, Request, TurnState } from '@microsoft/agents-hosting';
+/**
+ * Minimal response interface describing the methods used by the Agent request handler.
+ * Any framework whose response object satisfies this shape is compatible.
+ */
+export interface WebResponse {
+    status(code: number): this;
+    setHeader(name: string, value: string): this;
+    send(body?: unknown): this;
+    end(): this;
+    headersSent: boolean;
+    writableEnded: boolean;
+}
+/**
+ * A request handler function signature that does not import Express types in its public API.
+ *
+ * @remarks
+ * Runtime processing still depends on the request/response behavior expected by `authorizeJWT` and `CloudAdapter.process`.
+ * Use this with Express directly, or with adapter layers that provide compatible request/response objects.
+ */
+export type AgentRequestHandler = (req: Request, res: WebResponse) => Promise<void>;
+/**
+ * Creates a request handler for processing Agent activities.
+ *
+ * This exposes a handler signature without requiring Express types in consumer code.
+ * It can be used with Express directly, or with frameworks that provide adapted objects compatible with
+ * the requirements of `authorizeJWT` and `CloudAdapter.process`.
+ *
+ * JWT authorization is applied within the handler before processing the activity.
+ * Requests must provide a parsed activity payload at `req.body`.
+ *
+ * @param agent - The AgentApplication or ActivityHandler instance to process incoming activities.
+ * @param authConfiguration - Optional custom authentication configuration. If not provided,
+ * configuration will be loaded from environment variables using loadAuthConfigFromEnv().
+ * @returns A request handler function `(req, res) => Promise<void>`.
+ *
+ * @example
+ * ```typescript
+ * import express from 'express';
+ * import { AgentApplication, TurnState } from '@microsoft/agents-hosting';
+ * import { createAgentRequestHandler } from '@microsoft/agents-hosting-express';
+ *
+ * const agent = new AgentApplication<TurnState>();
+ * const handler = createAgentRequestHandler(agent);
+ *
+ * const app = express();
+ * app.use(express.json());
+ * app.post('/api/messages', handler);
+ * app.get('/health', (req, res) => res.json({ status: 'ok' }));
+ * app.listen(3978);
+ * ```
+ */
+export declare const createAgentRequestHandler: (agent: AgentApplication<TurnState<any, any>> | ActivityHandler, authConfiguration?: AuthConfiguration) => AgentRequestHandler;

package/dist/src/createAgentRequestHandler.js

@@ -0,0 +1,63 @@
+"use strict";
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAgentRequestHandler = void 0;
+const agents_hosting_1 = require("@microsoft/agents-hosting");
+const createCloudAdapter_1 = require("./createCloudAdapter");
+/**
+ * Creates a request handler for processing Agent activities.
+ *
+ * This exposes a handler signature without requiring Express types in consumer code.
+ * It can be used with Express directly, or with frameworks that provide adapted objects compatible with
+ * the requirements of `authorizeJWT` and `CloudAdapter.process`.
+ *
+ * JWT authorization is applied within the handler before processing the activity.
+ * Requests must provide a parsed activity payload at `req.body`.
+ *
+ * @param agent - The AgentApplication or ActivityHandler instance to process incoming activities.
+ * @param authConfiguration - Optional custom authentication configuration. If not provided,
+ * configuration will be loaded from environment variables using loadAuthConfigFromEnv().
+ * @returns A request handler function `(req, res) => Promise<void>`.
+ *
+ * @example
+ * ```typescript
+ * import express from 'express';
+ * import { AgentApplication, TurnState } from '@microsoft/agents-hosting';
+ * import { createAgentRequestHandler } from '@microsoft/agents-hosting-express';
+ *
+ * const agent = new AgentApplication<TurnState>();
+ * const handler = createAgentRequestHandler(agent);
+ *
+ * const app = express();
+ * app.use(express.json());
+ * app.post('/api/messages', handler);
+ * app.get('/health', (req, res) => res.json({ status: 'ok' }));
+ * app.listen(3978);
+ * ```
+ */
+const createAgentRequestHandler = (agent, authConfiguration) => {
+    const authConfig = (0, agents_hosting_1.getAuthConfigWithDefaults)(authConfiguration);
+    const { adapter, headerPropagation } = (0, createCloudAdapter_1.createCloudAdapter)(agent, authConfig);
+    const jwtMiddleware = (0, agents_hosting_1.authorizeJWT)(authConfig);
+    return async (req, res) => {
+        let middlewareError;
+        let nextCalled = false;
+        await jwtMiddleware(req, res, (err) => {
+            nextCalled = true;
+            middlewareError = err;
+        });
+        if (middlewareError) {
+            throw middlewareError;
+        }
+        // If the middleware handled the response without calling next (e.g., 401), don't process the activity.
+        if (!nextCalled || res.headersSent) {
+            return;
+        }
+        await adapter.process(req, res, (context) => agent.run(context), headerPropagation);
+    };
+};
+exports.createAgentRequestHandler = createAgentRequestHandler;
+//# sourceMappingURL=createAgentRequestHandler.js.map

package/dist/src/createAgentRequestHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createAgentRequestHandler.js","sourceRoot":"","sources":["../../src/createAgentRequestHandler.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAGH,8DAA6J;AAC7J,6DAAyD;AAwBzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACI,MAAM,yBAAyB,GAAG,CACvC,KAA8D,EAC9D,iBAAqC,EAChB,EAAE;IACvB,MAAM,UAAU,GAAG,IAAA,0CAAyB,EAAC,iBAAiB,CAAC,CAAA;IAC/D,MAAM,EAAE,OAAO,EAAE,iBAAiB,EAAE,GAAG,IAAA,uCAAkB,EAAC,KAAK,EAAE,UAAU,CAAC,CAAA;IAC5E,MAAM,aAAa,GAAG,IAAA,6BAAY,EAAC,UAAU,CAAC,CAAA;IAE9C,OAAO,KAAK,EAAE,GAAY,EAAE,GAAgB,EAAiB,EAAE;QAC7D,IAAI,eAAoB,CAAA;QACxB,IAAI,UAAU,GAAG,KAAK,CAAA;QAEtB,MAAM,aAAa,CAAC,GAAG,EAAE,GAAe,EAAE,CAAC,GAAS,EAAE,EAAE;YACtD,UAAU,GAAG,IAAI,CAAA;YACjB,eAAe,GAAG,GAAG,CAAA;QACvB,CAAC,CAAC,CAAA;QAEF,IAAI,eAAe,EAAE,CAAC;YACpB,MAAM,eAAe,CAAA;QACvB,CAAC;QAED,uGAAuG;QACvG,IAAI,CAAC,UAAU,IAAI,GAAG,CAAC,WAAW,EAAE,CAAC;YACnC,OAAM;QACR,CAAC;QAED,MAAM,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,GAAe,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,iBAAiB,CAAC,CAAA;IACjG,CAAC,CAAA;AACH,CAAC,CAAA;AA5BY,QAAA,yBAAyB,6BA4BrC"}

package/dist/src/createCloudAdapter.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { ActivityHandler, AgentApplication, AuthConfiguration, CloudAdapter, HeaderPropagationDefinition, TurnState } from '@microsoft/agents-hosting';
+/**
+ * Result of creating a CloudAdapter from an agent.
+ */
+export interface CloudAdapterResult {
+    adapter: CloudAdapter;
+    headerPropagation: HeaderPropagationDefinition | undefined;
+}
+/**
+ * Creates a CloudAdapter for the given agent.
+ *
+ * If the agent is an AgentApplication with a pre-configured adapter, that adapter is reused.
+ * Otherwise, a new CloudAdapter is created.
+ *
+ * @param agent - The AgentApplication or ActivityHandler instance.
+ * @param authConfig - Optional auth configuration used when creating a new CloudAdapter.
+ * If the agent already has an adapter, that adapter is reused and this value is ignored.
+ * @returns An object containing the CloudAdapter and optional header propagation configuration.
+ *
+ * @example
+ * ```typescript
+ * import { AgentApplication, TurnState } from '@microsoft/agents-hosting';
+ * import { createCloudAdapter } from '@microsoft/agents-hosting-express';
+ *
+ * const app = new AgentApplication<TurnState>();
+ * const { adapter, headerPropagation } = createCloudAdapter(app, { clientId: process.env.CLIENT_ID });
+ *
+ * // Use the adapter directly with request/response objects compatible with CloudAdapter.process
+ * adapter.process(req, res, (context) => app.run(context), headerPropagation);
+ * ```
+ */
+export declare const createCloudAdapter: (agent: AgentApplication<TurnState<any, any>> | ActivityHandler, authConfig?: AuthConfiguration) => CloudAdapterResult;

package/dist/src/createCloudAdapter.js

@@ -0,0 +1,45 @@
+"use strict";
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCloudAdapter = void 0;
+const agents_hosting_1 = require("@microsoft/agents-hosting");
+/**
+ * Creates a CloudAdapter for the given agent.
+ *
+ * If the agent is an AgentApplication with a pre-configured adapter, that adapter is reused.
+ * Otherwise, a new CloudAdapter is created.
+ *
+ * @param agent - The AgentApplication or ActivityHandler instance.
+ * @param authConfig - Optional auth configuration used when creating a new CloudAdapter.
+ * If the agent already has an adapter, that adapter is reused and this value is ignored.
+ * @returns An object containing the CloudAdapter and optional header propagation configuration.
+ *
+ * @example
+ * ```typescript
+ * import { AgentApplication, TurnState } from '@microsoft/agents-hosting';
+ * import { createCloudAdapter } from '@microsoft/agents-hosting-express';
+ *
+ * const app = new AgentApplication<TurnState>();
+ * const { adapter, headerPropagation } = createCloudAdapter(app, { clientId: process.env.CLIENT_ID });
+ *
+ * // Use the adapter directly with request/response objects compatible with CloudAdapter.process
+ * adapter.process(req, res, (context) => app.run(context), headerPropagation);
+ * ```
+ */
+const createCloudAdapter = (agent, authConfig) => {
+    let adapter;
+    let headerPropagation;
+    if (agent instanceof agents_hosting_1.ActivityHandler || !agent.adapter) {
+        adapter = new agents_hosting_1.CloudAdapter(authConfig);
+    }
+    else {
+        adapter = agent.adapter;
+        headerPropagation = agent === null || agent === void 0 ? void 0 : agent.options.headerPropagation;
+    }
+    return { adapter, headerPropagation };
+};
+exports.createCloudAdapter = createCloudAdapter;
+//# sourceMappingURL=createCloudAdapter.js.map

package/dist/src/createCloudAdapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createCloudAdapter.js","sourceRoot":"","sources":["../../src/createCloudAdapter.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,8DAAsJ;AAUtJ;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACI,MAAM,kBAAkB,GAAG,CAChC,KAA8D,EAC9D,UAA8B,EACV,EAAE;IACtB,IAAI,OAAqB,CAAA;IACzB,IAAI,iBAA0D,CAAA;IAC9D,IAAI,KAAK,YAAY,gCAAe,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;QACvD,OAAO,GAAG,IAAI,6BAAY,CAAC,UAAU,CAAC,CAAA;IACxC,CAAC;SAAM,CAAC;QACN,OAAO,GAAG,KAAK,CAAC,OAAuB,CAAA;QACvC,iBAAiB,GAAI,KAA+C,aAA/C,KAAK,uBAAL,KAAK,CAA4C,OAAO,CAAC,iBAAiB,CAAA;IACjG,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,iBAAiB,EAAE,CAAA;AACvC,CAAC,CAAA;AAbY,QAAA,kBAAkB,sBAa9B"}

package/dist/src/index.d.ts

@@ -1 +1,3 @@
 export * from './startServer';
+export * from './createCloudAdapter';
+export * from './createAgentRequestHandler';

package/dist/src/index.js

@@ -15,4 +15,6 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./startServer"), exports);
+__exportStar(require("./createCloudAdapter"), exports);
+__exportStar(require("./createAgentRequestHandler"), exports);
 //# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,gDAA6B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,gDAA6B;AAC7B,uDAAoC;AACpC,8DAA2C"}

package/dist/src/startServer.d.ts

@@ -4,32 +4,98 @@
  */
 import express from 'express';
 import { ActivityHandler, AgentApplication, AuthConfiguration, TurnState } from '@microsoft/agents-hosting';
+/**
+ * Options for configuring the Express server started by `startServer`.
+ */
+export interface StartServerOptions {
+    /**
+     * Optional custom authentication configuration.
+     * If not provided, configuration will be loaded from environment variables using loadAuthConfigFromEnv().
+     */
+    authConfig?: AuthConfiguration;
+    /**
+     * The port to listen on. Defaults to `process.env.PORT` or `3978`.
+     */
+    port?: number | string;
+    /**
+     * The route path for the agent messages endpoint. Defaults to `'/api/messages'`.
+     */
+    routePath?: string;
+    /**
+     * Optional rate limiting configuration for the messages endpoint.
+     * If not provided, no rate limiting is applied.
+     * Specify windowMs (in milliseconds) and max (number of requests) to enable rate limiting.
+     *
+     * @example
+     * ```typescript
+     * startServer(agent, {
+     *   rateLimitOptions: {
+     *     windowMs: 15 * 60 * 1000, // 15 minutes
+     *     max: 1000 // limit each IP to 1000 requests per windowMs
+     *   }
+     * });
+     * ```
+     */
+    rateLimitOptions?: {
+        windowMs: number;
+        max: number;
+    };
+    /**
+     * A callback invoked with the Express app before `listen()` is called.
+     * Use this to add custom routes, middleware, or static file serving.
+     *
+     * **Note:** The agent messages route is registered *after* this callback.
+     * Avoid adding catch-all routes (e.g., `app.all('*', ...)` or `app.use('*', ...)`)
+     * here, as they will shadow the messages endpoint.
+     * @example
+     * ```typescript
+     * startServer(agent, {
+     *   beforeListen: (app) => {
+     *     app.get('/health', (req, res) => res.json({ status: 'ok' }));
+     *   }
+     * });
+     * ```
+     */
+    beforeListen?: (app: express.Express) => void;
+}
 /**
  * Starts an Express server for handling Agent requests.
  *
  * @param agent - The AgentApplication or ActivityHandler instance to process incoming activities.
- * @param authConfiguration - Optional custom authentication configuration. If not provided,
- * configuration will be loaded from environment variables using loadAuthConfigFromEnv().
- * @returns {express.Express} - The Express server instance.
+ * @param options - Optional configuration. Accepts either a `StartServerOptions` object or
+ * an `AuthConfiguration` for backward compatibility.
+ * @returns The Express server instance.
  *
  * @remarks
  * This function sets up an Express server with the necessary middleware and routes for handling
- * agent requests. It configures JWT authorization middleware and sets up the message endpoint.
- * The server will listen on the port specified in the PORT environment variable (or 3978 by default)
- * and logs startup information including the SDK version and configured app ID.
+ * agent requests. It configures JWT authorization middleware on the messages route and sets up the endpoint.
+ * The server will listen on the port specified in options, the PORT environment variable, or 3978 by default.
  *
  * @example
  * ```typescript
+ * // Basic usage
  * import { AgentApplication, TurnState } from '@microsoft/agents-hosting';
  * import { startServer } from '@microsoft/agents-hosting-express';
  *
  * const app = new AgentApplication<TurnState>();
- * app.onMessage('hello', async (context, state) => {
- *   await context.sendActivity('Hello, world!');
- * });
- *
  * startServer(app);
  * ```
  *
+ * @example
+ * ```typescript
+ * // With options
+ * import { AgentApplication, TurnState } from '@microsoft/agents-hosting';
+ * import { startServer } from '@microsoft/agents-hosting-express';
+ *
+ * const app = new AgentApplication<TurnState>();
+ * startServer(app, {
+ *   port: 8080,
+ *   routePath: '/bot/messages',
+ *   beforeListen: (server) => {
+ *     server.get('/health', (req, res) => res.json({ status: 'ok' }));
+ *   }
+ * });
+ * ```
  */
-export declare const startServer: (agent: AgentApplication<TurnState<any, any>> | ActivityHandler, authConfiguration?: AuthConfiguration) => express.Express;
+export declare function startServer(agent: AgentApplication<TurnState<any, any>> | ActivityHandler, options?: StartServerOptions): express.Express;
+export declare function startServer(agent: AgentApplication<TurnState<any, any>> | ActivityHandler, authConfiguration?: AuthConfiguration): express.Express;

package/dist/src/startServer.js

@@ -7,58 +7,56 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.startServer = void 0;
+exports.startServer = startServer;
 const express_1 = __importDefault(require("express"));
+const express_rate_limit_1 = __importDefault(require("express-rate-limit"));
 const agents_hosting_1 = require("@microsoft/agents-hosting");
 const package_json_1 = require("@microsoft/agents-hosting/package.json");
-/**
- * Starts an Express server for handling Agent requests.
- *
- * @param agent - The AgentApplication or ActivityHandler instance to process incoming activities.
- * @param authConfiguration - Optional custom authentication configuration. If not provided,
- * configuration will be loaded from environment variables using loadAuthConfigFromEnv().
- * @returns {express.Express} - The Express server instance.
- *
- * @remarks
- * This function sets up an Express server with the necessary middleware and routes for handling
- * agent requests. It configures JWT authorization middleware and sets up the message endpoint.
- * The server will listen on the port specified in the PORT environment variable (or 3978 by default)
- * and logs startup information including the SDK version and configured app ID.
- *
- * @example
- * ```typescript
- * import { AgentApplication, TurnState } from '@microsoft/agents-hosting';
- * import { startServer } from '@microsoft/agents-hosting-express';
- *
- * const app = new AgentApplication<TurnState>();
- * app.onMessage('hello', async (context, state) => {
- *   await context.sendActivity('Hello, world!');
- * });
- *
- * startServer(app);
- * ```
- *
- */
-const startServer = (agent, authConfiguration) => {
-    const authConfig = (0, agents_hosting_1.getAuthConfigWithDefaults)(authConfiguration);
-    let adapter;
-    let headerPropagation;
-    if (agent instanceof agents_hosting_1.ActivityHandler || !agent.adapter) {
-        adapter = new agents_hosting_1.CloudAdapter();
-    }
-    else {
-        adapter = agent.adapter;
-        headerPropagation = agent === null || agent === void 0 ? void 0 : agent.options.headerPropagation;
-    }
+const agents_telemetry_1 = require("@microsoft/agents-telemetry");
+const createCloudAdapter_1 = require("./createCloudAdapter");
+const logger = (0, agents_telemetry_1.debug)('agents:hosting-express');
+function startServer(agent, optionsOrAuth) {
+    var _a, _b, _c;
+    const isOptions = typeof optionsOrAuth === 'object' && optionsOrAuth !== null &&
+        ('authConfig' in optionsOrAuth || 'port' in optionsOrAuth || 'routePath' in optionsOrAuth || 'rateLimitOptions' in optionsOrAuth || 'beforeListen' in optionsOrAuth);
+    const opts = isOptions ? optionsOrAuth : { authConfig: optionsOrAuth };
+    const authConfig = (0, agents_hosting_1.getAuthConfigWithDefaults)(opts.authConfig);
+    const routePath = (_a = opts.routePath) !== null && _a !== void 0 ? _a : '/api/messages';
+    const { adapter, headerPropagation } = (0, createCloudAdapter_1.createCloudAdapter)(agent, authConfig);
     const server = (0, express_1.default)();
     server.use(express_1.default.json());
-    server.use((0, agents_hosting_1.authorizeJWT)(authConfig));
-    server.post('/api/messages', (req, res) => adapter.process(req, res, (context) => agent.run(context), headerPropagation));
-    const port = process.env.PORT || 3978;
+    if (opts.beforeListen && typeof opts.beforeListen === 'function') {
+        opts.beforeListen(server);
+    }
+    const middlewares = [(0, agents_hosting_1.authorizeJWT)(authConfig)];
+    if (opts.rateLimitOptions) {
+        const messagesRateLimiter = (0, express_rate_limit_1.default)({
+            windowMs: opts.rateLimitOptions.windowMs,
+            max: opts.rateLimitOptions.max,
+            standardHeaders: true,
+            legacyHeaders: false
+        });
+        middlewares.unshift(messagesRateLimiter);
+    }
+    server.post(routePath, ...middlewares, (req, res) => adapter.process(req, res, (context) => agent.run(context), headerPropagation));
+    const port = (_c = (_b = opts.port) !== null && _b !== void 0 ? _b : process.env.PORT) !== null && _c !== void 0 ? _c : 3978;
+    const className = (obj) => { var _a, _b; return (_b = (_a = obj === null || obj === void 0 ? void 0 : obj.constructor) === null || _a === void 0 ? void 0 : _a.name) !== null && _b !== void 0 ? _b : (obj ? 'custom' : undefined); };
+    logger.info('Express server settings loaded', {
+        messageEndpoint: `POST ${routePath}`,
+        port: {
+            value: port,
+            source: opts.port ? 'options' : process.env.PORT ? 'env' : 'default',
+        },
+        middlewares: ['express.json', 'authorizeJWT'],
+        adapter: {
+            className: className(adapter),
+            source: agent instanceof agents_hosting_1.ActivityHandler || !agent.adapter ? 'created' : 'agent.adapter',
+        },
+        headerPropagation: headerPropagation !== undefined ? 'enabled' : 'disabled',
+    });
     server.listen(port, async () => {
         console.log(`\nServer listening to port ${port} on sdk ${package_json_1.version} for appId ${authConfig.clientId} debug ${process.env.DEBUG}`);
     }).on('error', console.error);
     return server;
-};
-exports.startServer = startServer;
+}
 //# sourceMappingURL=startServer.js.map

package/dist/src/startServer.js.map

@@ -1 +1 @@
-{"version":3,"file":"startServer.js","sourceRoot":"","sources":["../../src/startServer.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;;;;AAEH,sDAA2C;AAC3C,8DAAwM;AACxM,yEAAgE;AAChE;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACI,MAAM,WAAW,GAAG,CAAC,KAA8D,EAAE,iBAAqC,EAAoB,EAAE;IACrJ,MAAM,UAAU,GAAsB,IAAA,0CAAyB,EAAC,iBAAiB,CAAC,CAAA;IAClF,IAAI,OAAqB,CAAA;IACzB,IAAI,iBAA0D,CAAA;IAC9D,IAAI,KAAK,YAAY,gCAAe,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;QACvD,OAAO,GAAG,IAAI,6BAAY,EAAE,CAAA;IAC9B,CAAC;SAAM,CAAC;QACN,OAAO,GAAG,KAAK,CAAC,OAAuB,CAAA;QACvC,iBAAiB,GAAI,KAA+C,aAA/C,KAAK,uBAAL,KAAK,CAA4C,OAAO,CAAC,iBAAiB,CAAA;IACjG,CAAC;IAED,MAAM,MAAM,GAAG,IAAA,iBAAO,GAAE,CAAA;IACxB,MAAM,CAAC,GAAG,CAAC,iBAAO,CAAC,IAAI,EAAE,CAAC,CAAA;IAC1B,MAAM,CAAC,GAAG,CAAC,IAAA,6BAAY,EAAC,UAAU,CAAC,CAAC,CAAA;IAEpC,MAAM,CAAC,IAAI,CAAC,eAAe,EAAE,CAAC,GAAY,EAAE,GAAa,EAAE,EAAE,CAC3D,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,OAAO,EAAE,EAAE,CACpC,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,EAClB,iBAAiB,CAAC,CACrB,CAAA;IAED,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,IAAI,IAAI,CAAA;IACrC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,IAAI,EAAE;QAC7B,OAAO,CAAC,GAAG,CAAC,8BAA8B,IAAI,WAAW,sBAAO,cAAc,UAAU,CAAC,QAAQ,UAAU,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,CAAA;IACjI,CAAC,CAAC,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,KAAK,CAAC,CAAA;IAC7B,OAAO,MAAM,CAAA;AACf,CAAC,CAAA;AA1BY,QAAA,WAAW,eA0BvB"}
+{"version":3,"file":"startServer.js","sourceRoot":"","sources":["../../src/startServer.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@microsoft/agents-hosting-express",
-  "version": "1.6.0-beta.24.g285b02c21b",
+  "version": "1.6.0-beta.30.g545c41a189",
   "homepage": "https://github.com/microsoft/Agents-for-js",
   "repository": {
     "type": "git",
@@ -19,8 +19,10 @@
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",
   "dependencies": {
-    "@microsoft/agents-hosting": "1.6.0-beta.24.g285b02c21b",
-    "express": "5.2.1"
+    "@microsoft/agents-hosting": "1.6.0-beta.30.g545c41a189",
+    "@microsoft/agents-telemetry": "1.6.0-beta.30.g545c41a189",
+    "express": "5.2.1",
+    "express-rate-limit": "8.5.2"
   },
   "license": "MIT",
   "files": [

package/src/createAgentRequestHandler.ts

@@ -0,0 +1,91 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { type Response } from 'express'
+import { ActivityHandler, AgentApplication, AuthConfiguration, authorizeJWT, getAuthConfigWithDefaults, Request, TurnState } from '@microsoft/agents-hosting'
+import { createCloudAdapter } from './createCloudAdapter'
+
+/**
+ * Minimal response interface describing the methods used by the Agent request handler.
+ * Any framework whose response object satisfies this shape is compatible.
+ */
+export interface WebResponse {
+  status (code: number): this
+  setHeader (name: string, value: string): this
+  send (body?: unknown): this
+  end (): this
+  headersSent: boolean
+  writableEnded: boolean
+}
+
+/**
+ * A request handler function signature that does not import Express types in its public API.
+ *
+ * @remarks
+ * Runtime processing still depends on the request/response behavior expected by `authorizeJWT` and `CloudAdapter.process`.
+ * Use this with Express directly, or with adapter layers that provide compatible request/response objects.
+ */
+export type AgentRequestHandler = (req: Request, res: WebResponse) => Promise<void>
+
+/**
+ * Creates a request handler for processing Agent activities.
+ *
+ * This exposes a handler signature without requiring Express types in consumer code.
+ * It can be used with Express directly, or with frameworks that provide adapted objects compatible with
+ * the requirements of `authorizeJWT` and `CloudAdapter.process`.
+ *
+ * JWT authorization is applied within the handler before processing the activity.
+ * Requests must provide a parsed activity payload at `req.body`.
+ *
+ * @param agent - The AgentApplication or ActivityHandler instance to process incoming activities.
+ * @param authConfiguration - Optional custom authentication configuration. If not provided,
+ * configuration will be loaded from environment variables using loadAuthConfigFromEnv().
+ * @returns A request handler function `(req, res) => Promise<void>`.
+ *
+ * @example
+ * ```typescript
+ * import express from 'express';
+ * import { AgentApplication, TurnState } from '@microsoft/agents-hosting';
+ * import { createAgentRequestHandler } from '@microsoft/agents-hosting-express';
+ *
+ * const agent = new AgentApplication<TurnState>();
+ * const handler = createAgentRequestHandler(agent);
+ *
+ * const app = express();
+ * app.use(express.json());
+ * app.post('/api/messages', handler);
+ * app.get('/health', (req, res) => res.json({ status: 'ok' }));
+ * app.listen(3978);
+ * ```
+ */
+export const createAgentRequestHandler = (
+  agent: AgentApplication<TurnState<any, any>> | ActivityHandler,
+  authConfiguration?: AuthConfiguration
+): AgentRequestHandler => {
+  const authConfig = getAuthConfigWithDefaults(authConfiguration)
+  const { adapter, headerPropagation } = createCloudAdapter(agent, authConfig)
+  const jwtMiddleware = authorizeJWT(authConfig)
+
+  return async (req: Request, res: WebResponse): Promise<void> => {
+    let middlewareError: any
+    let nextCalled = false
+
+    await jwtMiddleware(req, res as Response, (err?: any) => {
+      nextCalled = true
+      middlewareError = err
+    })
+
+    if (middlewareError) {
+      throw middlewareError
+    }
+
+    // If the middleware handled the response without calling next (e.g., 401), don't process the activity.
+    if (!nextCalled || res.headersSent) {
+      return
+    }
+
+    await adapter.process(req, res as Response, (context) => agent.run(context), headerPropagation)
+  }
+}

package/src/createCloudAdapter.ts

@@ -0,0 +1,52 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { ActivityHandler, AgentApplication, AuthConfiguration, CloudAdapter, HeaderPropagationDefinition, TurnState } from '@microsoft/agents-hosting'
+
+/**
+ * Result of creating a CloudAdapter from an agent.
+ */
+export interface CloudAdapterResult {
+  adapter: CloudAdapter
+  headerPropagation: HeaderPropagationDefinition | undefined
+}
+
+/**
+ * Creates a CloudAdapter for the given agent.
+ *
+ * If the agent is an AgentApplication with a pre-configured adapter, that adapter is reused.
+ * Otherwise, a new CloudAdapter is created.
+ *
+ * @param agent - The AgentApplication or ActivityHandler instance.
+ * @param authConfig - Optional auth configuration used when creating a new CloudAdapter.
+ * If the agent already has an adapter, that adapter is reused and this value is ignored.
+ * @returns An object containing the CloudAdapter and optional header propagation configuration.
+ *
+ * @example
+ * ```typescript
+ * import { AgentApplication, TurnState } from '@microsoft/agents-hosting';
+ * import { createCloudAdapter } from '@microsoft/agents-hosting-express';
+ *
+ * const app = new AgentApplication<TurnState>();
+ * const { adapter, headerPropagation } = createCloudAdapter(app, { clientId: process.env.CLIENT_ID });
+ *
+ * // Use the adapter directly with request/response objects compatible with CloudAdapter.process
+ * adapter.process(req, res, (context) => app.run(context), headerPropagation);
+ * ```
+ */
+export const createCloudAdapter = (
+  agent: AgentApplication<TurnState<any, any>> | ActivityHandler,
+  authConfig?: AuthConfiguration
+): CloudAdapterResult => {
+  let adapter: CloudAdapter
+  let headerPropagation: HeaderPropagationDefinition | undefined
+  if (agent instanceof ActivityHandler || !agent.adapter) {
+    adapter = new CloudAdapter(authConfig)
+  } else {
+    adapter = agent.adapter as CloudAdapter
+    headerPropagation = (agent as AgentApplication<TurnState<any, any>>)?.options.headerPropagation
+  }
+  return { adapter, headerPropagation }
+}

package/src/index.ts

@@ -1 +1,3 @@
 export * from './startServer'
+export * from './createCloudAdapter'
+export * from './createAgentRequestHandler'

package/src/startServer.ts

@@ -4,58 +4,159 @@
  */
 
 import express, { Response } from 'express'
-import { ActivityHandler, AgentApplication, AuthConfiguration, authorizeJWT, CloudAdapter, getAuthConfigWithDefaults, HeaderPropagationDefinition, Request, TurnState } from '@microsoft/agents-hosting'
+import rateLimit from 'express-rate-limit'
+import { ActivityHandler, AgentApplication, AuthConfiguration, authorizeJWT, getAuthConfigWithDefaults, Request, TurnState } from '@microsoft/agents-hosting'
 import { version } from '@microsoft/agents-hosting/package.json'
+import { debug } from '@microsoft/agents-telemetry'
+import { createCloudAdapter } from './createCloudAdapter'
+
+const logger = debug('agents:hosting-express')
+
+/**
+ * Options for configuring the Express server started by `startServer`.
+ */
+export interface StartServerOptions {
+  /**
+   * Optional custom authentication configuration.
+   * If not provided, configuration will be loaded from environment variables using loadAuthConfigFromEnv().
+   */
+  authConfig?: AuthConfiguration
+
+  /**
+   * The port to listen on. Defaults to `process.env.PORT` or `3978`.
+   */
+  port?: number | string
+
+  /**
+   * The route path for the agent messages endpoint. Defaults to `'/api/messages'`.
+   */
+  routePath?: string
+
+  /**
+   * Optional rate limiting configuration for the messages endpoint.
+   * If not provided, no rate limiting is applied.
+   * Specify windowMs (in milliseconds) and max (number of requests) to enable rate limiting.
+   *
+   * @example
+   * ```typescript
+   * startServer(agent, {
+   *   rateLimitOptions: {
+   *     windowMs: 15 * 60 * 1000, // 15 minutes
+   *     max: 1000 // limit each IP to 1000 requests per windowMs
+   *   }
+   * });
+   * ```
+   */
+  rateLimitOptions?: { windowMs: number; max: number }
+
+  /**
+   * A callback invoked with the Express app before `listen()` is called.
+   * Use this to add custom routes, middleware, or static file serving.
+   *
+   * **Note:** The agent messages route is registered *after* this callback.
+   * Avoid adding catch-all routes (e.g., `app.all('*', ...)` or `app.use('*', ...)`)
+   * here, as they will shadow the messages endpoint.
+   * @example
+   * ```typescript
+   * startServer(agent, {
+   *   beforeListen: (app) => {
+   *     app.get('/health', (req, res) => res.json({ status: 'ok' }));
+   *   }
+   * });
+   * ```
+   */
+  beforeListen?: (app: express.Express) => void
+}
+
 /**
  * Starts an Express server for handling Agent requests.
  *
  * @param agent - The AgentApplication or ActivityHandler instance to process incoming activities.
- * @param authConfiguration - Optional custom authentication configuration. If not provided,
- * configuration will be loaded from environment variables using loadAuthConfigFromEnv().
- * @returns {express.Express} - The Express server instance.
+ * @param options - Optional configuration. Accepts either a `StartServerOptions` object or
+ * an `AuthConfiguration` for backward compatibility.
+ * @returns The Express server instance.
  *
  * @remarks
  * This function sets up an Express server with the necessary middleware and routes for handling
- * agent requests. It configures JWT authorization middleware and sets up the message endpoint.
- * The server will listen on the port specified in the PORT environment variable (or 3978 by default)
- * and logs startup information including the SDK version and configured app ID.
+ * agent requests. It configures JWT authorization middleware on the messages route and sets up the endpoint.
+ * The server will listen on the port specified in options, the PORT environment variable, or 3978 by default.
  *
  * @example
  * ```typescript
+ * // Basic usage
  * import { AgentApplication, TurnState } from '@microsoft/agents-hosting';
  * import { startServer } from '@microsoft/agents-hosting-express';
  *
  * const app = new AgentApplication<TurnState>();
- * app.onMessage('hello', async (context, state) => {
- *   await context.sendActivity('Hello, world!');
- * });
- *
  * startServer(app);
  * ```
  *
+ * @example
+ * ```typescript
+ * // With options
+ * import { AgentApplication, TurnState } from '@microsoft/agents-hosting';
+ * import { startServer } from '@microsoft/agents-hosting-express';
+ *
+ * const app = new AgentApplication<TurnState>();
+ * startServer(app, {
+ *   port: 8080,
+ *   routePath: '/bot/messages',
+ *   beforeListen: (server) => {
+ *     server.get('/health', (req, res) => res.json({ status: 'ok' }));
+ *   }
+ * });
+ * ```
  */
-export const startServer = (agent: AgentApplication<TurnState<any, any>> | ActivityHandler, authConfiguration?: AuthConfiguration) : express.Express => {
-  const authConfig: AuthConfiguration = getAuthConfigWithDefaults(authConfiguration)
-  let adapter: CloudAdapter
-  let headerPropagation: HeaderPropagationDefinition | undefined
-  if (agent instanceof ActivityHandler || !agent.adapter) {
-    adapter = new CloudAdapter()
-  } else {
-    adapter = agent.adapter as CloudAdapter
-    headerPropagation = (agent as AgentApplication<TurnState<any, any>>)?.options.headerPropagation
-  }
+export function startServer (agent: AgentApplication<TurnState<any, any>> | ActivityHandler, options?: StartServerOptions): express.Express
+export function startServer (agent: AgentApplication<TurnState<any, any>> | ActivityHandler, authConfiguration?: AuthConfiguration): express.Express
+export function startServer (agent: AgentApplication<TurnState<any, any>> | ActivityHandler, optionsOrAuth?: StartServerOptions | AuthConfiguration): express.Express {
+  const isOptions = typeof optionsOrAuth === 'object' && optionsOrAuth !== null &&
+    ('authConfig' in optionsOrAuth || 'port' in optionsOrAuth || 'routePath' in optionsOrAuth || 'rateLimitOptions' in optionsOrAuth || 'beforeListen' in optionsOrAuth)
+
+  const opts: StartServerOptions = isOptions ? optionsOrAuth as StartServerOptions : { authConfig: optionsOrAuth as AuthConfiguration | undefined }
+  const authConfig: AuthConfiguration = getAuthConfigWithDefaults(opts.authConfig)
+  const routePath = opts.routePath ?? '/api/messages'
+  const { adapter, headerPropagation } = createCloudAdapter(agent, authConfig)
 
   const server = express()
   server.use(express.json())
-  server.use(authorizeJWT(authConfig))
 
-  server.post('/api/messages', (req: Request, res: Response) =>
+  if (opts.beforeListen && typeof opts.beforeListen === 'function') {
+    opts.beforeListen(server)
+  }
+
+  const middlewares: express.RequestHandler[] = [authorizeJWT(authConfig)]
+  if (opts.rateLimitOptions) {
+    const messagesRateLimiter = rateLimit({
+      windowMs: opts.rateLimitOptions.windowMs,
+      max: opts.rateLimitOptions.max,
+      standardHeaders: true,
+      legacyHeaders: false
+    })
+    middlewares.unshift(messagesRateLimiter)
+  }
+
+  server.post(routePath, ...middlewares, (req: Request, res: Response) =>
     adapter.process(req, res, (context) =>
       agent.run(context)
     , headerPropagation)
   )
 
-  const port = process.env.PORT || 3978
+  const port = opts.port ?? process.env.PORT ?? 3978
+  const className = (obj: any) => obj?.constructor?.name ?? (obj ? 'custom' : undefined)
+  logger.info('Express server settings loaded', {
+    messageEndpoint: `POST ${routePath}`,
+    port: {
+      value: port,
+      source: opts.port ? 'options' : process.env.PORT ? 'env' : 'default',
+    },
+    middlewares: ['express.json', 'authorizeJWT'],
+    adapter: {
+      className: className(adapter),
+      source: agent instanceof ActivityHandler || !agent.adapter ? 'created' : 'agent.adapter',
+    },
+    headerPropagation: headerPropagation !== undefined ? 'enabled' : 'disabled',
+  })
   server.listen(port, async () => {
     console.log(`\nServer listening to port ${port} on sdk ${version} for appId ${authConfig.clientId} debug ${process.env.DEBUG}`)
   }).on('error', console.error)