@microsoft/agents-hosting 0.6.21-g3c2261b2fc → 1.0.0-ge4831811bf

package/src/app/agentApplication.ts

@@ -28,7 +28,7 @@ const TYPING_TIMER_DELAY = 1000
 
 /**
  * Event handler function type for application events.
- * @template TState - The state type extending TurnState.
+ * @typeParam TState - The state type extending TurnState.
  * @param context - The turn context containing activity information.
  * @param state - The current turn state.
  * @returns A promise that resolves to a boolean indicating whether to continue execution.
@@ -36,9 +36,7 @@ const TYPING_TIMER_DELAY = 1000
 export type ApplicationEventHandler<TState extends TurnState> = (context: TurnContext, state: TState) => Promise<boolean>
 
 /**
- * Main application class for handling agent conversations and routing.
- *
- * @template TState - The state type extending TurnState.
+ * @summary Main application class for handling agent conversations and routing.
  *
  * @remarks
  * The AgentApplication class provides a framework for building conversational agents.
@@ -66,6 +64,8 @@ export type ApplicationEventHandler<TState extends TurnState> = (context: TurnCo
  *
  * await app.run(turnContext);
  * ```
+ *
+ * @typeParam TState - The state type extending TurnState.
  */
 export class AgentApplication<TState extends TurnState> {
   protected readonly _options: AgentApplicationOptions<TState>
@@ -79,7 +79,7 @@ export class AgentApplication<TState extends TurnState> {
   private readonly _adaptiveCards: AdaptiveCardsActions<TState>
 
   /**
-   * Creates a new instance of AgentApplication.
+   * @summary Creates a new instance of AgentApplication.
    *
    * @param options - Optional configuration options for the application.
    *
@@ -142,7 +142,7 @@ export class AgentApplication<TState extends TurnState> {
   }
 
   /**
-   * Gets the authorization instance for the application.
+   * @summary Gets the authorization instance for the application.
    *
    * @returns The authorization instance.
    * @throws Error if no authentication options were configured.
@@ -155,7 +155,7 @@ export class AgentApplication<TState extends TurnState> {
   }
 
   /**
-   * Gets the options used to configure the application.
+   * @summary Gets the options used to configure the application.
    *
    * @returns The application options.
    */
@@ -164,7 +164,7 @@ export class AgentApplication<TState extends TurnState> {
   }
 
   /**
-   * Gets the adapter used by the application.
+   * @summary Gets the adapter used by the application.
    *
    * @returns The adapter instance.
    */
@@ -173,7 +173,7 @@ export class AgentApplication<TState extends TurnState> {
   }
 
   /**
-   * Gets the adaptive cards actions handler for the application.
+   * @summary Gets the adaptive cards actions handler for the application.
    *
    * @returns The adaptive cards actions instance.
    *
@@ -766,7 +766,7 @@ export class AgentApplication<TState extends TurnState> {
   /**
    * Registers an extension with the application.
    *
-   * @template T - The extension type extending AgentExtension.
+   * @typeParam T - The extension type extending AgentExtension.
    * @param extension - The extension instance to register.
    * @param regcb - Callback function called after successful registration.
    * @throws Error if the extension is already registered.

package/src/app/agentApplicationBuilder.ts

@@ -11,7 +11,7 @@ import { TurnState } from './turnState'
 
 /**
  * Builder class for creating and configuring AgentApplication instances.
- * @template TState Type extending TurnState that will be used by the application
+ * @typeParam TState Type extending TurnState that will be used by the application
  */
 export class AgentApplicationBuilder<TState extends TurnState = TurnState> {
   protected _options: Partial<AgentApplicationOptions<TState>> = {}

package/src/app/agentApplicationOptions.ts

@@ -10,13 +10,14 @@ import { AdaptiveCardsOptions } from './adaptiveCards'
 import { InputFileDownloader } from './inputFileDownloader'
 import { AuthorizationHandlers } from './authorization'
 import { TurnState } from './turnState'
+import { HeaderPropagationDefinition } from '../headerPropagation'
 
 /**
  * Configuration options for creating and initializing an Agent Application.
  * This interface defines all the configurable aspects of an agent's behavior,
  * including adapter settings, storage, authorization, and various feature flags.
  *
- * @template TState - The type of turn state that extends TurnState, allowing for
+ * @typeParam TState - The type of turn state that extends TurnState, allowing for
  * custom state management specific to your agent's needs.
  */
 export interface AgentApplicationOptions<TState extends TurnState> {
@@ -129,4 +130,13 @@ export interface AgentApplicationOptions<TState extends TurnState> {
    * Optional. The transcript logger to use for logging conversations. If not provided, no logging will occur.
    */
   transcriptLogger?: TranscriptLogger
+
+  /**
+   * Optional. A function to handle header propagation for incoming requests.
+   * This allows the agent to manage headers from incoming requests and propagate
+   * them to outgoing requests as needed.
+   *
+   * @default undefined
+   */
+  headerPropagation?: HeaderPropagationDefinition
 }

package/src/app/appMemory.ts

@@ -23,7 +23,7 @@ export interface AppMemory {
 
   /**
    * Gets a value from the specified path.
-   * @template TValue The expected type of the value
+   * @typeParam TValue The expected type of the value
    * @param path The path to get the value from
    * @returns The value at the specified path cast to type TValue
    */

package/src/app/appRoute.ts

@@ -15,7 +15,7 @@ import { TurnState } from './turnState'
  * a selector function that determines when the route should be activated with a handler
  * function that processes the matched activities.
  *
- * @template TState - The type of turn state that extends TurnState, allowing for
+ * @typeParam TState - The type of turn state that extends TurnState, allowing for
  *                    type-safe access to custom state properties within route handlers
  *
  * @example

package/src/app/extensions.ts

@@ -9,7 +9,7 @@ import { TurnState } from './turnState'
  * Represents an extension that adds channel-specific routing functionality to an agent application.
  * This class allows you to register routes that are only active for a specific channel.
  *
- * @template TState - The type of turn state that extends TurnState
+ * @typeParam TState - The type of turn state that extends TurnState
  */
 export class AgentExtension<TState extends TurnState> {
   /** The channel ID that this extension is associated with */

package/src/app/turnState.ts

@@ -40,7 +40,7 @@ export interface DefaultTempState {
 }
 
 /**
- * Base class defining a collection of turn state scopes.
+ * @summary Base class defining a collection of turn state scopes.
  * @remarks
  * Developers can create a derived class that extends `TurnState` to add additional state scopes.
  *
@@ -70,10 +70,10 @@ export interface DefaultTempState {
  *   }
  * }
  * ```
- * @template TConversationState - Type for conversation-scoped state
- * @template TUserState - Type for user-scoped state
- * @template TTempState - Type for temporary state that exists only for the current turn
- * @template TSSOState - Type for Single Sign-On (SSO) state
+ * @typeParam TConversationState - Type for conversation-scoped state
+ * @typeParam TUserState - Type for user-scoped state
+ * @typeParam TTempState - Type for temporary state that exists only for the current turn
+ * @typeParam TSSOState - Type for Single Sign-On (SSO) state
  */
 export class TurnState<
     TConversationState = DefaultConversationState,
@@ -248,7 +248,7 @@ export class TurnState<
   /**
    * Gets a value from state by dot-notation path.
    * Format: "scope.property" or just "property" (defaults to temp scope)
-   * @template TValue - The type of the value to retrieve
+   * @typeParam TValue - The type of the value to retrieve
    * @param path - The path to the value
    * @returns The value at the specified path
    */

package/src/app/turnStateProperty.ts

@@ -10,7 +10,7 @@ import { TurnState } from './turnState'
 
 /**
  * Maps an application's Turn State property to a State property.
- * @template T Optional. Type of the property being mapped. Defaults to any.
+ * @typeParam T Optional. Type of the property being mapped. Defaults to any.
  */
 export class TurnStateProperty<T = any> implements StatePropertyAccessor<T> {
   private readonly _state: TurnStateEntry
@@ -60,7 +60,7 @@ export class TurnStateProperty<T = any> implements StatePropertyAccessor<T> {
 
   /**
      * Replace's the state property value.
-     * @template T
+     * @typeParam T
      * @param {TurnContext} context The context object for the turn.
      * @param {T} value The value to assign to the state property.
      * @returns {Promise<void>} A promise that represents the work queued to execute.

package/src/auth/authConfiguration.ts

@@ -45,7 +45,15 @@ export interface AuthConfiguration {
   /**
    * The FIC (First-Party Integration Channel) client ID.
    */
-  FICClientId?: string
+  FICClientId?: string,
+
+  /**
+   * Entra Authentication Endpoint to use,  If not populated the Entra Public Cloud endpoint is assumed.
+   * This example of Public Cloud Endpoint is https://login.microsoftonline.com
+   @remarks
+   see also https://learn.microsoft.com/entra/identity-platform/authentication-national-cloud
+   */
+  authority?: string
 }
 
 /**
@@ -63,6 +71,7 @@ export interface AuthConfiguration {
  * FICClientId=your-FIC-client-id
  *
  * connectionName=your-connection-name
+ * authority=your-authority-endpoint
  * ```
  * @remarks
  * - `clientId` is required
@@ -71,6 +80,7 @@ export interface AuthConfiguration {
  */
 export const loadAuthConfigFromEnv: (cnxName?: string) => AuthConfiguration = (cnxName?: string) => {
   if (cnxName === undefined) {
+    const authority = process.env.authorityEndpoint ?? 'https://login.microsoftonline.com'
     if (process.env.clientId === undefined && process.env.NODE_ENV === 'production') {
       throw new Error('ClientId required in production')
     }
@@ -82,13 +92,15 @@ export const loadAuthConfigFromEnv: (cnxName?: string) => AuthConfiguration = (c
       certKeyFile: process.env.certKeyFile,
       connectionName: process.env.connectionName,
       FICClientId: process.env.FICClientId,
+      authority,
       issuers: [
         'https://api.botframework.com',
         `https://sts.windows.net/${process.env.tenantId}/`,
-        `https://login.microsoftonline.com/${process.env.tenantId}/v2.0`
-      ]
+        `${authority}/${process.env.tenantId}/v2.0`
+      ],
     }
   } else {
+    const authority = process.env[`${cnxName}_authorityEndpoint`] ?? 'https://login.microsoftonline.com'
     return {
       tenantId: process.env[`${cnxName}_tenantId`],
       clientId: process.env[`${cnxName}_clientId`] ?? (() => { throw new Error(`ClientId not found for connection: ${cnxName}`) })(),
@@ -97,10 +109,11 @@ export const loadAuthConfigFromEnv: (cnxName?: string) => AuthConfiguration = (c
       certKeyFile: process.env[`${cnxName}_certKeyFile`],
       connectionName: process.env[`${cnxName}_connectionName`],
       FICClientId: process.env[`${cnxName}_FICClientId`],
+      authority,
       issuers: [
         'https://api.botframework.com',
         `https://sts.windows.net/${process.env[`${cnxName}_tenantId`]}/`,
-        `https://login.microsoftonline.com/${process.env[`${cnxName}_tenantId`]}/v2.0`
+        `${authority}/${process.env[`${cnxName}_tenantId`]}/v2.0`
       ]
     }
   }
@@ -122,6 +135,7 @@ export const loadPrevAuthConfigFromEnv: () => AuthConfiguration = () => {
   if (process.env.MicrosoftAppId === undefined && process.env.NODE_ENV === 'production') {
     throw new Error('ClientId required in production')
   }
+  const authority = process.env.authorityEndpoint ?? 'https://login.microsoftonline.com'
   return {
     tenantId: process.env.MicrosoftAppTenantId,
     clientId: process.env.MicrosoftAppId!,
@@ -130,10 +144,11 @@ export const loadPrevAuthConfigFromEnv: () => AuthConfiguration = () => {
     certKeyFile: process.env.certKeyFile,
     connectionName: process.env.connectionName,
     FICClientId: process.env.MicrosoftAppClientId,
+    authority,
     issuers: [
       'https://api.botframework.com',
       `https://sts.windows.net/${process.env.MicrosoftAppTenantId}/`,
-      `https://login.microsoftonline.com/${process.env.MicrosoftAppTenantId}/v2.0`
+      `${authority}/${process.env.MicrosoftAppTenantId}/v2.0`
     ]
   }
 }

package/src/auth/jwt-middleware.ts

@@ -24,7 +24,7 @@ const verifyToken = async (raw: string, config: AuthConfiguration): Promise<JwtP
     logger.debug('jwt.decode ', JSON.stringify(payload))
     const jwksUri: string = payload.iss === 'https://api.botframework.com'
       ? 'https://login.botframework.com/v1/.well-known/keys'
-      : `https://login.microsoftonline.com/${config.tenantId}/discovery/v2.0/keys`
+      : `${config.authority}/${config.tenantId}/discovery/v2.0/keys`
 
     logger.debug(`fetching keys from ${jwksUri}`)
     const jwksClient: JwksClient = jwksRsa({ jwksUri })

package/src/auth/msalTokenProvider.ts

@@ -55,7 +55,7 @@ export class MsalTokenProvider implements AuthProvider {
     const cca = new ConfidentialClientApplication({
       auth: {
         clientId: authConfig.clientId as string,
-        authority: `https://login.microsoftonline.com/${authConfig.tenantId || 'botframework.com'}`,
+        authority: `${authConfig.authority}/${authConfig.tenantId || 'botframework.com'}`,
         clientSecret: authConfig.clientSecret
       },
       system: this.sysOptions
@@ -137,7 +137,7 @@ export class MsalTokenProvider implements AuthProvider {
     const cca = new ConfidentialClientApplication({
       auth: {
         clientId: authConfig.clientId || '',
-        authority: `https://login.microsoftonline.com/${authConfig.tenantId || 'botframework.com'}`,
+        authority: `${authConfig.authority}/${authConfig.tenantId || 'botframework.com'}`,
         clientCertificate: {
           privateKey: privateKey as string,
           thumbprint: pubKeyObject.fingerprint.replaceAll(':', ''),
@@ -163,7 +163,7 @@ export class MsalTokenProvider implements AuthProvider {
     const cca = new ConfidentialClientApplication({
       auth: {
         clientId: authConfig.clientId as string,
-        authority: `https://login.microsoftonline.com/${authConfig.tenantId || 'botframework.com'}`,
+        authority: `${authConfig.authority}/${authConfig.tenantId || 'botframework.com'}`,
         clientSecret: authConfig.clientSecret
       },
       system: this.sysOptions
@@ -187,7 +187,7 @@ export class MsalTokenProvider implements AuthProvider {
     const cca = new ConfidentialClientApplication({
       auth: {
         clientId: authConfig.clientId as string,
-        authority: `https://login.microsoftonline.com/${authConfig.tenantId}`,
+        authority: `${authConfig.authority}/${authConfig.tenantId}`,
         clientAssertion
       },
       system: this.sysOptions

package/src/cloudAdapter.ts

@@ -22,6 +22,7 @@ import { AttachmentInfo } from './connector-client/attachmentInfo'
 import { AttachmentData } from './connector-client/attachmentData'
 import { normalizeIncomingActivity } from './activityWireCompat'
 import { UserTokenClient } from './oauth'
+import { HeaderPropagation, HeaderPropagationCollection, HeaderPropagationDefinition } from './headerPropagation'
 
 const logger = debug('agents:cloud-adapter')
 
@@ -84,18 +85,21 @@ export class CloudAdapter extends BaseAdapter {
    *
    * @param serviceUrl - The URL of the service to connect to
    * @param scope - The authentication scope to use
+   * @param headers - Optional headers to propagate in the request
    * @returns A promise that resolves to a ConnectorClient instance
    * @protected
    */
   protected async createConnectorClient (
     serviceUrl: string,
-    scope: string
+    scope: string,
+    headers?: HeaderPropagationCollection
   ): Promise<ConnectorClient> {
-    return ConnectorClient.createClientWithAuthAsync(
+    return ConnectorClient.createClientWithAuth(
       serviceUrl,
       this.authConfig,
       this.authProvider,
-      scope
+      scope,
+      headers
     )
   }
 
@@ -122,7 +126,7 @@ export class CloudAdapter extends BaseAdapter {
   }
 
   async createTurnContextWithScope (activity: Activity, logic: AgentHandler, scope: string): Promise<TurnContext> {
-    this.connectorClient = await ConnectorClient.createClientWithAuthAsync(activity.serviceUrl!, this.authConfig!, this.authProvider, scope)
+    this.connectorClient = await ConnectorClient.createClientWithAuth(activity.serviceUrl!, this.authConfig!, this.authProvider, scope)
     return new TurnContext(this, activity)
   }
 
@@ -162,9 +166,9 @@ export class CloudAdapter extends BaseAdapter {
         }
 
         if (activity.replyToId) {
-          response = await this.connectorClient.replyToActivityAsync(activity.conversation.id, activity.replyToId, activity)
+          response = await this.connectorClient.replyToActivity(activity.conversation.id, activity.replyToId, activity)
         } else {
-          response = await this.connectorClient.sendToConversationAsync(activity.conversation.id, activity)
+          response = await this.connectorClient.sendToConversation(activity.conversation.id, activity)
         }
       }
 
@@ -187,7 +191,7 @@ export class CloudAdapter extends BaseAdapter {
     if (!activity.serviceUrl || (activity.conversation == null) || !activity.conversation.id || !activity.id) {
       throw new Error('Invalid activity object')
     }
-    return await this.connectorClient.replyToActivityAsync(activity.conversation.id, activity.id, activity)
+    return await this.connectorClient.replyToActivity(activity.conversation.id, activity.id, activity)
   }
 
   /**
@@ -195,11 +199,19 @@ export class CloudAdapter extends BaseAdapter {
    * @param request - The incoming request.
    * @param res - The response to send.
    * @param logic - The logic to execute.
+   * @param headerPropagation - Optional function to handle header propagation.
    */
   public async process (
     request: Request,
     res: Response,
-    logic: (context: TurnContext) => Promise<void>): Promise<void> {
+    logic: (context: TurnContext) => Promise<void>,
+    headerPropagation?: HeaderPropagationDefinition): Promise<void> {
+    const headers = new HeaderPropagation(request.headers)
+    if (headerPropagation && typeof headerPropagation === 'function') {
+      headerPropagation(headers)
+      logger.debug('Headers to propagate: ', headers)
+    }
+
     const end = (status: StatusCodes, body?: unknown, isInvokeResponseOrExpectReplies: boolean = false) => {
       res.status(status)
       if (isInvokeResponseOrExpectReplies) {
@@ -228,7 +240,7 @@ export class CloudAdapter extends BaseAdapter {
     // if Delivery Mode == ExpectReplies, we don't need a connector client.
     if (this.resolveIfConnectorClientIsNeeded(activity)) {
       logger.debug('Creating connector client with scope: ', scope)
-      this.connectorClient = await this.createConnectorClient(activity.serviceUrl!, scope)
+      this.connectorClient = await this.createConnectorClient(activity.serviceUrl!, scope, headers)
       this.setConnectorClient(context)
     }
 
@@ -287,7 +299,7 @@ export class CloudAdapter extends BaseAdapter {
       throw new Error('Invalid activity object')
     }
 
-    const response = await this.connectorClient.updateActivityAsync(
+    const response = await this.connectorClient.updateActivity(
       activity.conversation.id,
       activity.id,
       activity
@@ -311,7 +323,7 @@ export class CloudAdapter extends BaseAdapter {
       throw new Error('Invalid conversation reference object')
     }
 
-    await this.connectorClient.deleteActivityAsync(reference.conversation.id, reference.activityId)
+    await this.connectorClient.deleteActivity(reference.conversation.id, reference.activityId)
   }
 
   /**
@@ -424,7 +436,7 @@ export class CloudAdapter extends BaseAdapter {
     if (!logic) throw new TypeError('`logic` must be defined')
 
     const restClient = await this.createConnectorClient(serviceUrl, audience)
-    const createConversationResult = await restClient.createConversationAsync(conversationParameters)
+    const createConversationResult = await restClient.createConversation(conversationParameters)
     const createActivity = this.createCreateActivity(
       createConversationResult.id,
       channelId,

package/src/connector-client/connectorClient.ts

@@ -11,6 +11,7 @@ import { AttachmentInfo } from './attachmentInfo'
 import { AttachmentData } from './attachmentData'
 import { normalizeOutgoingActivity } from '../activityWireCompat'
 import { getProductInfo } from '../getProductInfo'
+import { HeaderPropagation, HeaderPropagationCollection } from '../headerPropagation'
 const logger = debug('agents:connector-client')
 
 export { getProductInfo }
@@ -27,6 +28,20 @@ export class ConnectorClient {
    */
   protected constructor (axInstance: AxiosInstance) {
     this._axiosInstance = axInstance
+    this._axiosInstance.interceptors.request.use((config) => {
+      const { method, url, data, headers, params } = config
+      // Clone headers and remove Authorization before logging
+      const { Authorization, authorization, ...headersToLog } = headers || {}
+      logger.debug('Request: ', {
+        host: this._axiosInstance.getUri(),
+        url,
+        data,
+        method,
+        params,
+        headers: headersToLog
+      })
+      return config
+    })
     this._axiosInstance.interceptors.response.use(
       (config) => {
         const { status, statusText, config: requestConfig } = config
@@ -66,20 +81,23 @@ export class ConnectorClient {
    * @param authConfig - The authentication configuration.
    * @param authProvider - The authentication provider.
    * @param scope - The scope for the authentication token.
+   * @param headers - Optional headers to propagate in the request.
    * @returns A new instance of ConnectorClient.
    */
-  static async createClientWithAuthAsync (
+  static async createClientWithAuth (
     baseURL: string,
     authConfig: AuthConfiguration,
     authProvider: AuthProvider,
-    scope: string
+    scope: string,
+    headers?: HeaderPropagationCollection
   ): Promise<ConnectorClient> {
+    const headerPropagation = headers ?? new HeaderPropagation({ 'User-Agent': '' })
+    headerPropagation.concat({ 'User-Agent': getProductInfo() })
+    headerPropagation.override({ Accept: 'application/json' })
+
     const axiosInstance = axios.create({
       baseURL,
-      headers: {
-        Accept: 'application/json',
-        'User-Agent': getProductInfo(),
-      },
+      headers: headerPropagation.outgoing,
       transformRequest: [
         (data, headers) => {
           return JSON.stringify(normalizeOutgoingActivity(data))
@@ -98,7 +116,7 @@ export class ConnectorClient {
    * @param continuationToken - The continuation token for pagination.
    * @returns A list of conversations.
    */
-  public async getConversationsAsync (continuationToken?: string): Promise<ConversationsResult> {
+  public async getConversations (continuationToken?: string): Promise<ConversationsResult> {
     const config: AxiosRequestConfig = {
       method: 'get',
       url: '/v3/conversations',
@@ -128,7 +146,7 @@ export class ConnectorClient {
    * @param body - The conversation parameters.
    * @returns The conversation resource response.
    */
-  public async createConversationAsync (body: ConversationParameters): Promise<ConversationResourceResponse> {
+  public async createConversation (body: ConversationParameters): Promise<ConversationResourceResponse> {
     // const payload = normalizeOutgoingConvoParams(body)
     const config: AxiosRequestConfig = {
       method: 'post',
@@ -149,7 +167,7 @@ export class ConnectorClient {
    * @param body - The activity object.
    * @returns The resource response.
    */
-  public async replyToActivityAsync (
+  public async replyToActivity (
     conversationId: string,
     activityId: string,
     body: Activity
@@ -177,7 +195,7 @@ export class ConnectorClient {
    * @param body - The activity object.
    * @returns The resource response.
    */
-  public async sendToConversationAsync (
+  public async sendToConversation (
     conversationId: string,
     body: Activity
   ): Promise<ResourceResponse> {
@@ -204,7 +222,7 @@ export class ConnectorClient {
    * @param body - The activity object.
    * @returns The resource response.
    */
-  public async updateActivityAsync (
+  public async updateActivity (
     conversationId: string,
     activityId: string,
     body: Activity
@@ -230,7 +248,7 @@ export class ConnectorClient {
    * @param activityId - The ID of the activity.
    * @returns A promise that resolves when the activity is deleted.
    */
-  public async deleteActivityAsync (
+  public async deleteActivity (
     conversationId: string,
     activityId: string
   ): Promise<void> {