@microsoft/agents-hosting 1.7.0-beta.1.g8bcd4f11a7 → 1.7.0-beta.11.gb5d3e8c751

package/src/auth/authConfiguration.ts

@@ -8,6 +8,8 @@ import { loadEnvSettings, AuthConfiguration, envParser, envParserUtils, LoadEnv,
 
 export { type AuthConfiguration, type ConnectionSettings, type ConnectionSettingsBase, type MsalConnectionSettings, type SidecarConnectionSettings, AuthType, resolveAuthority, type ConnectionMapItem, resolveAuthType } from './settings'
 import { prune } from '../utils'
+import { ExceptionHelper } from '@microsoft/agents-activity'
+import { Errors } from '../errorHelper'
 
 const logger = debug('agents:authConfiguration')
 
@@ -118,12 +120,12 @@ const connectionsEnv = {
     const map = connectionsMap ?? connectionsMapEnv.connectionsMap
     const name = map?.find((item) => item.serviceUrl === '*')?.connection
     if (!name) {
-      throw new Error('No default connection found in environment connections.')
+      throw ExceptionHelper.generateException(Error, Errors.NoDefaultConnectionFound)
     }
 
     const connection = conn?.get(name ?? '')
     if (!connection) {
-      throw new Error(`Connection "${name}" not found in environment connections.`)
+      throw ExceptionHelper.generateException(Error, Errors.ConnectionNotFoundInEnvironment, undefined, { connectionName: name })
     }
 
     return applyDefaultSettings({ ...connection, connections: conn, connectionsMap: map })
@@ -359,7 +361,7 @@ export const loadAuthConfigFromEnv = (cnxName?: string): AuthConfiguration => {
   // No connections provided, we need to populate the connections map with the old config settings
   const result = applyDefaultSettings(cnxName?.trim() ? legacyPrefixEnv.process(globalEnv.env, cnxName) : globalEnv.legacyPrefixSettings)
   if (cnxName && !result.clientId) {
-    throw new Error(`ClientId not found for connection: ${cnxName}`)
+    throw ExceptionHelper.generateException(Error, Errors.ClientIdNotFoundForConnection, undefined, { connectionName: cnxName })
   }
 
   logger.info('Auth settings loaded from environment', {

package/src/auth/index.ts

@@ -5,5 +5,6 @@ export * from './msal/msalTokenProvider'
 export * from './request'
 export * from './msal/msalTokenCredential'
 export * from './connectionManager'
+export * from './connections'
 export * from './msal/msalConnectionManager'
 export * from './sidecar/sidecarAuthProvider'

package/src/auth/jwt-middleware.ts

@@ -4,8 +4,10 @@
  */
 
 import { AuthConfiguration, resolveAuthority } from './authConfiguration'
-import { Response, NextFunction } from 'express'
 import { Request } from './request'
+import { WebResponse, NextFunction } from '../interfaces/webResponse'
+import { Errors } from '../errorHelper'
+import { ExceptionHelper } from '@microsoft/agents-activity'
 import jwksRsa, { JwksClient, SigningKey } from 'jwks-rsa'
 import jwt, { JwtHeader, JwtPayload, SignCallback, GetPublicKeyOrSecret } from 'jsonwebtoken'
 import { debug } from '@microsoft/agents-telemetry'
@@ -13,6 +15,25 @@ import { debug } from '@microsoft/agents-telemetry'
 const logger = debug('agents:jwt-middleware')
 const jwksClients = new Map<string, JwksClient>()
 const maxJwksClients = 100
+const authorizedAudience = Symbol('authorizedAudience')
+
+interface AuthorizedRequest extends Request {
+  [authorizedAudience]?: string
+}
+
+interface VerifiedToken {
+  payload: JwtPayload
+  audience: string
+}
+
+/**
+ * Gets the configured audience selected while authorizing a request.
+ * @param req The authorized request.
+ * @returns The matched configured client ID, or `undefined` for anonymous requests.
+ */
+export function getAuthorizedAudience (req: Request): string | undefined {
+  return (req as AuthorizedRequest)[authorizedAudience]
+}
 
 /**
  * Clears process-wide JWKS clients.
@@ -57,24 +78,30 @@ export function getJwksClient (jwksUri: string): JwksClient {
  * Verifies the JWT token.
  * @param raw The raw JWT token.
  * @param config The authentication configuration.
- * @returns A promise that resolves to the JWT payload.
+ * @returns A promise that resolves to the verified payload and matched configured audience.
  */
-const verifyToken = async (raw: string, config: AuthConfiguration): Promise<JwtPayload> => {
+const verifyToken = async (raw: string, config: AuthConfiguration): Promise<VerifiedToken> => {
   const payload = jwt.decode(raw) as JwtPayload
   logger.debug('jwt.decode ', JSON.stringify(payload))
 
   if (!payload) {
-    throw new Error('invalid token')
+    throw ExceptionHelper.generateException(Error, Errors.InvalidJwtToken)
   }
-  const audience = payload.aud
+  const audiences = Array.isArray(payload.aud)
+    ? payload.aud
+    : typeof payload.aud === 'string'
+      ? [payload.aud]
+      : []
 
   const matchingEntry = config.connections && config.connections.size > 0
-    ? [...config.connections.entries()].find(([_, configuration]) => configuration.clientId === audience)
+    ? [...config.connections.entries()].find(([_, configuration]) =>
+        typeof configuration.clientId === 'string' && audiences.includes(configuration.clientId)
+      )
     : undefined
 
   if (!matchingEntry) {
-    const err = new Error('Audience mismatch')
-    logger.error(err.message, audience)
+    const err = ExceptionHelper.generateException(Error, Errors.JwtAudienceMismatch)
+    logger.error(err.message, audiences)
     throw err
   }
 
@@ -107,7 +134,7 @@ const verifyToken = async (raw: string, config: AuthConfiguration): Promise<JwtP
     clockTolerance: 300
   }
 
-  return await new Promise((resolve, reject) => {
+  const verifiedPayload = await new Promise<JwtPayload>((resolve, reject) => {
     jwt.verify(raw, getKey, verifyOptions, (err, user) => {
       if (err) {
         logger.error('jwt.verify ', JSON.stringify(err))
@@ -117,6 +144,75 @@ const verifyToken = async (raw: string, config: AuthConfiguration): Promise<JwtP
       resolve(user as JwtPayload)
     })
   })
+  return {
+    payload: verifiedPayload,
+    audience: authConfig.clientId!
+  }
+}
+
+/**
+ * Determines whether an `Authorization` header value is present (non-empty).
+ *
+ * The {@link Request} contract allows `string | string[] | undefined` because
+ * different web frameworks surface headers differently. This treats an empty
+ * string or empty array as "absent" so callers can distinguish a missing header
+ * (anonymous / 401) from a present-but-malformed one (always 401).
+ * @param authorization The raw `Authorization` header value.
+ * @returns `true` when a non-empty header value is present.
+ */
+function hasAuthorizationHeader (authorization: string | string[] | undefined): boolean {
+  if (Array.isArray(authorization)) {
+    return authorization.some((value) => typeof value === 'string' && value.trim().length > 0)
+  }
+  return typeof authorization === 'string' && authorization.trim().length > 0
+}
+
+/**
+ * Parses a single `Authorization` header value and returns its bearer token.
+ *
+ * Validates the `Bearer <token>` scheme, returning `undefined` for anything
+ * malformed (wrong scheme, missing token, or extra whitespace-delimited parts).
+ * @param headerValue A single `Authorization` header value.
+ * @returns The bearer token, or `undefined` if the value is absent or malformed.
+ */
+function parseBearerValue (headerValue: string | undefined): string | undefined {
+  if (typeof headerValue !== 'string') {
+    return undefined
+  }
+  const parts = headerValue.trim().split(/\s+/)
+  if (parts.length !== 2) {
+    return undefined
+  }
+  const [scheme, token] = parts
+  if (scheme.toLowerCase() !== 'bearer' || !token) {
+    return undefined
+  }
+  return token
+}
+
+/**
+ * Extracts the bearer token from a raw `Authorization` header value.
+ *
+ * On Node's core HTTP parser (which both Express and Fastify use) `Authorization`
+ * is always surfaced as a single string holding the *first* header line —
+ * duplicate `Authorization` headers are discarded, not comma-joined. The
+ * `string[]` case is handled only because the {@link Request} contract permits
+ * it for non-Node frameworks; when an array is supplied, every entry is inspected
+ * and the first valid `Bearer <token>` is returned (the bearer value is not
+ * assumed to be first). Returns `undefined` for anything malformed so the caller
+ * can emit a consistent 401 instead of throwing.
+ * @param authorization The raw `Authorization` header value.
+ * @returns The bearer token, or `undefined` if the header is absent or malformed.
+ */
+function extractBearerToken (authorization: string | string[] | undefined): string | undefined {
+  const values = Array.isArray(authorization) ? authorization : [authorization]
+  for (const value of values) {
+    const token = parseBearerValue(value)
+    if (token) {
+      return token
+    }
+  }
+  return undefined
 }
 
 /**
@@ -125,7 +221,7 @@ const verifyToken = async (raw: string, config: AuthConfiguration): Promise<JwtP
  * @returns An Express middleware function.
  */
 export const authorizeJWT = (authConfig: AuthConfiguration) => {
-  return async function (req: Request, res: Response, next: NextFunction) {
+  return async function (req: Request, res: WebResponse, next: NextFunction) {
     let failed = false
     logger.debug('authorizing jwt')
     if (req.method !== 'POST' && req.method !== 'GET') {
@@ -133,18 +229,32 @@ export const authorizeJWT = (authConfig: AuthConfiguration) => {
       logger.warn('Method not allowed', req.method)
       res.status(405).send({ 'jwt-auth-error': 'Method not allowed' })
     } else {
-      const authHeader = req.headers.authorization as string
-      if (authHeader) {
-        const token: string = authHeader.split(' ')[1] // Extract the token from the Bearer string
+      const token = extractBearerToken(req.headers.authorization)
+      if (token) {
         try {
-          const user = await verifyToken(token, authConfig)
-          logger.debug('token verified for ', user)
-          req.user = user
+          const verifiedToken = await verifyToken(token, authConfig)
+          logger.debug('token verified for ', verifiedToken.payload)
+          req.user = verifiedToken.payload
+          const authorizedRequest = req as AuthorizedRequest
+          authorizedRequest[authorizedAudience] = verifiedToken.audience
         } catch (err: Error | any) {
           failed = true
           logger.error(err)
-          res.status(401).send({ 'jwt-auth-error': err.message })
+          // Emit only the human-readable description rather than the
+          // ExceptionHelper-formatted "[code] - description - helplink" string,
+          // so the wire format does not leak internal error codes or help links.
+          // Fall back to a stable string so a thrown non-Error (no description/
+          // message) never serializes to an empty `{}` and drops the detail.
+          const wireMessage: string = err?.description ?? err?.message ?? 'unauthorized'
+          res.status(401).send({ 'jwt-auth-error': wireMessage })
         }
+      } else if (hasAuthorizationHeader(req.headers.authorization)) {
+        // Header is present but not a well-formed `Bearer <token>` (e.g. wrong
+        // scheme, missing token, or an array value). Respond with a consistent
+        // 401 rather than letting malformed input throw before authorization.
+        failed = true
+        logger.warn('malformed authorization header')
+        res.status(401).send({ 'jwt-auth-error': 'invalid authorization header' })
       } else {
         if (!authConfig.clientId && process.env.NODE_ENV !== 'production') {
           logger.info('using anonymous auth')

package/src/auth/msal/msalTokenProvider.ts

@@ -284,7 +284,7 @@ export class MsalTokenProvider implements AuthProvider {
       if (typeof authConfigOrScope === 'string') {
       // Called as getAccessToken(scope)
         if (!this.connectionSettings) {
-          throw new Error('Connection settings must be provided to constructor when calling getAccessToken(scope)')
+          throw ExceptionHelper.generateException(Error, Errors.ConnectionSettingsRequiredForGetAccessTokenScope)
         }
         authConfig = this.connectionSettings
         actualScope = authConfigOrScope
@@ -378,7 +378,7 @@ export class MsalTokenProvider implements AuthProvider {
       if (Array.isArray(authConfigOrScopes)) {
       // Called as acquireTokenOnBehalfOf(scopes, oboAssertion)
         if (!this.connectionSettings) {
-          throw new Error('Connection settings must be provided to constructor when calling acquireTokenOnBehalfOf(scopes, oboAssertion)')
+          throw ExceptionHelper.generateException(Error, Errors.ConnectionSettingsRequiredForAcquireTokenOnBehalfOf)
         }
         authConfig = this.connectionSettings
         actualScopes = authConfigOrScopes
@@ -399,7 +399,7 @@ export class MsalTokenProvider implements AuthProvider {
         scopes: actualScopes
       })
       if (!token?.accessToken) {
-        throw new Error('Failed to acquire token on behalf of user')
+        throw ExceptionHelper.generateException(Error, Errors.FailedToAcquireTokenOnBehalfOf)
       }
 
       return token.accessToken
@@ -412,7 +412,7 @@ export class MsalTokenProvider implements AuthProvider {
       record({ agenticInstanceId: agentAppInstanceId })
 
       if (!this.connectionSettings) {
-        throw new Error('Connection settings must be provided when calling getAgenticInstanceToken')
+        throw ExceptionHelper.generateException(Error, Errors.ConnectionSettingsRequiredForGetAgenticInstanceToken)
       }
 
       const instanceTokenCacheKey = MsalTokenProvider.cacheKey(
@@ -444,7 +444,7 @@ export class MsalTokenProvider implements AuthProvider {
       })
 
       if (!token?.accessToken) {
-        throw new Error(`Failed to acquire instance token for agent instance: ${agentAppInstanceId}`)
+        throw ExceptionHelper.generateException(Error, Errors.FailedToAcquireInstanceTokenForAgentInstance, undefined, { agentAppInstanceId })
       }
 
       this.cacheAgenticAuthenticationResult(instanceTokenCacheKey, token)
@@ -494,7 +494,7 @@ export class MsalTokenProvider implements AuthProvider {
    */
   private async acquireTokenForAgenticScenarios (tenantId: string, clientId: string, clientAssertion: string | undefined, scopes: string[], tokenBodyParameters: { [key: string]: any }): Promise<string | null> {
     if (!this.connectionSettings) {
-      throw new Error('Connection settings must be provided when calling getAgenticInstanceToken')
+      throw ExceptionHelper.generateException(Error, Errors.ConnectionSettingsRequiredForGetAgenticInstanceToken)
     }
 
     logger.debug('acquireTokenForAgenticScenarios clientId=%s tenantId=%s scopes=%o grant_type=%s', clientId, tenantId, scopes, tokenBodyParameters.grant_type)
@@ -585,7 +585,7 @@ export class MsalTokenProvider implements AuthProvider {
       })
 
       if (!token) {
-        throw new Error(`Failed to acquire instance token for user token: ${agentAppInstanceId}`)
+        throw ExceptionHelper.generateException(Error, Errors.FailedToAcquireInstanceTokenForUserToken, undefined, { agentAppInstanceId })
       }
 
       return token
@@ -594,7 +594,7 @@ export class MsalTokenProvider implements AuthProvider {
 
   public async getAgenticApplicationToken (tenantId: string, agentAppInstanceId: string): Promise<string> {
     if (!this.connectionSettings?.clientId) {
-      throw new Error('Connection settings must be provided when calling getAgenticApplicationToken')
+      throw ExceptionHelper.generateException(Error, Errors.ConnectionSettingsRequiredForGetAgenticApplicationToken)
     }
     logger.debug('getAgenticApplicationToken clientId=%s tenantId=%s agentAppInstanceId=%s', this.connectionSettings.clientId, tenantId, agentAppInstanceId)
 
@@ -605,7 +605,7 @@ export class MsalTokenProvider implements AuthProvider {
       if (!this.connectionSettings.idpmResource) {
         resource = 'api://AzureAdTokenExchange/.default'
       } else if (!URL.canParse(this.connectionSettings.idpmResource)) {
-        throw new Error('idpmResource must be a valid absolute URI')
+        throw ExceptionHelper.generateException(Error, Errors.IdpmResourceAbsoluteUriRequired)
       } else {
         resource = this.connectionSettings.idpmResource
       }
@@ -617,7 +617,7 @@ export class MsalTokenProvider implements AuthProvider {
       })
       const tokenResult = await msiApp.acquireToken({ resource })
       if (!tokenResult?.accessToken) {
-        throw new Error(`Failed to acquire token via IdentityProxyManager for agent instance: ${agentAppInstanceId}`)
+        throw ExceptionHelper.generateException(Error, Errors.FailedToAcquireTokenViaIdentityProxyManagerForAgentInstance, undefined, { agentAppInstanceId })
       }
       logger.debug('getAgenticApplicationToken via IdentityProxyManager clientId=%s resource=%s', this.connectionSettings.clientId, resource)
       return tokenResult.accessToken
@@ -655,7 +655,7 @@ export class MsalTokenProvider implements AuthProvider {
     })
 
     if (!token) {
-      throw new Error(`Failed to acquire token for agent instance: ${agentAppInstanceId}`)
+      throw ExceptionHelper.generateException(Error, Errors.FailedToAcquireInstanceTokenForAgentInstance, undefined, { agentAppInstanceId })
     }
 
     return token
@@ -780,7 +780,7 @@ export class MsalTokenProvider implements AuthProvider {
       azureRegion: authConfig.azureRegion
     })
     if (!token?.accessToken) {
-      throw new Error('Failed to acquire token using certificate')
+      throw ExceptionHelper.generateException(Error, Errors.FailedToAcquireTokenUsingCertificate)
     }
     return token.accessToken
   }
@@ -799,7 +799,7 @@ export class MsalTokenProvider implements AuthProvider {
       azureRegion: authConfig.azureRegion
     })
     if (!token?.accessToken) {
-      throw new Error('Failed to acquire token using client secret')
+      throw ExceptionHelper.generateException(Error, Errors.FailedToAcquireTokenUsingClientSecret)
     }
     return token.accessToken
   }
@@ -824,7 +824,7 @@ export class MsalTokenProvider implements AuthProvider {
     const token = await cca.acquireTokenByClientCredential({ scopes, azureRegion: authConfig.azureRegion })
     logger.debug('got token using FIC client assertion')
     if (!token?.accessToken) {
-      throw new Error('Failed to acquire token using FIC client assertion')
+      throw ExceptionHelper.generateException(Error, Errors.FailedToAcquireTokenUsingFICClientAssertion)
     }
     return token.accessToken
   }
@@ -850,7 +850,7 @@ export class MsalTokenProvider implements AuthProvider {
     const token = await cca.acquireTokenByClientCredential({ scopes, azureRegion: authConfig.azureRegion })
     logger.debug('got token using WID client assertion')
     if (!token?.accessToken) {
-      throw new Error('Failed to acquire token using WID client assertion')
+      throw ExceptionHelper.generateException(Error, Errors.FailedToAcquireTokenUsingWIDClientAssertion)
     }
     return token.accessToken
   }
@@ -874,7 +874,7 @@ export class MsalTokenProvider implements AuthProvider {
     })
     logger.debug('got token for FIC')
     if (!response?.accessToken) {
-      throw new Error('Failed to acquire external token for FIC client assertion')
+      throw ExceptionHelper.generateException(Error, Errors.FailedToAcquireExternalTokenForFICClientAssertion)
     }
     return response.accessToken
   }

package/src/baseAdapter.ts

@@ -6,11 +6,12 @@
 import { Middleware, MiddlewareHandler, MiddlewareSet } from './middlewareSet'
 import { TurnContext } from './turnContext'
 import { debug } from '@microsoft/agents-telemetry'
-import { Activity, ConversationReference } from '@microsoft/agents-activity'
+import { Activity, ConversationReference, ExceptionHelper } from '@microsoft/agents-activity'
 import { ResourceResponse } from './connector-client/resourceResponse'
 import { AttachmentData } from './connector-client/attachmentData'
 import { AttachmentInfo } from './connector-client/attachmentInfo'
 import { JwtPayload } from 'jsonwebtoken'
+import { Errors } from './errorHelper'
 
 const logger = debug('agents:base-adapter')
 
@@ -202,7 +203,7 @@ export abstract class BaseAdapter {
         if (err instanceof Error) {
           await this.onTurnError(pContext.proxy, err)
         } else {
-          throw new Error('Unknown error type: ' + err.message)
+          throw ExceptionHelper.generateException(Error, Errors.UnknownErrorType, undefined, { errorMessage: err.message })
         }
       } else {
         throw err

package/src/cloudAdapter.ts

@@ -6,8 +6,8 @@
 import { AgentHandler, INVOKE_RESPONSE_KEY } from './activityHandler'
 import { BaseAdapter } from './baseAdapter'
 import { TurnContext } from './turnContext'
-import { Response } from 'express'
 import { Request } from './auth/request'
+import { NextFunction, WebResponse } from './interfaces/webResponse'
 import { ConnectorClient } from './connector-client/connectorClient'
 import { AuthConfiguration, getAuthConfigWithDefaults } from './auth/authConfiguration'
 import { AuthProvider } from './auth/authProvider'
@@ -32,6 +32,7 @@ import { parseBooleanEnv, suggestClosest } from './utils/env'
 import { trace } from '@microsoft/agents-telemetry'
 import { AdapterTraceDefinitions } from './observability'
 import { applyAgenticHeaders } from './getProductInfo'
+import { authorizeJWT } from './auth/jwt-middleware'
 
 const logger = debug('agents:cloud-adapter')
 
@@ -238,6 +239,7 @@ function truncateActivityForLog (activity: unknown, max = 1024): string {
 
 export class CloudAdapter extends BaseAdapter {
   protected readonly authConfig: AuthConfiguration
+  private readonly jwtMiddleware: ReturnType<typeof authorizeJWT>
   protected _agentName?: string
 
   /**
@@ -257,6 +259,7 @@ export class CloudAdapter extends BaseAdapter {
   constructor (authConfig?: AuthConfiguration, authProvider?: AuthProvider, userTokenClient?: UserTokenClient, options?: CloudAdapterOptions) {
     super()
     this.authConfig = authConfig = getAuthConfigWithDefaults(authConfig)
+    this.jwtMiddleware = authorizeJWT(authConfig)
     this.connectionManager = new MsalConnectionManager(undefined, undefined, authConfig)
     this._options = resolveCloudAdapterOptions(options)
 
@@ -289,7 +292,7 @@ export class CloudAdapter extends BaseAdapter {
    */
   protected resolveIfConnectorClientIsNeeded (activity: Activity): boolean {
     if (!activity) {
-      throw new TypeError('`activity` parameter required')
+      throw ExceptionHelper.generateException(TypeError, Errors.ActivityParameterRequired)
     }
 
     switch (activity.deliveryMode) {
@@ -392,7 +395,7 @@ export class CloudAdapter extends BaseAdapter {
             headers
           )
         } else {
-          throw new Error('Could not create connector client for agentic user')
+          throw ExceptionHelper.generateException(Error, Errors.CannotCreateConnectorClientForAgenticUser)
         }
       } else {
         // ABS tokens will not have an azp/appid so use the botframework scope.
@@ -425,6 +428,24 @@ export class CloudAdapter extends BaseAdapter {
     } as JwtPayload
   }
 
+  /**
+   * Authorizes an incoming web request using this adapter's resolved authentication configuration.
+   * @param req The incoming request.
+   * @param res The outgoing response.
+   * @param next Callback invoked after successful authorization.
+   */
+  public async authorizeRequest (req: Request, res: WebResponse, next: NextFunction): Promise<void> {
+    await this.jwtMiddleware(req, res, next)
+  }
+
+  /**
+   * Gets the client ID used by this adapter's default authentication connection.
+   * @returns The configured client ID, or `undefined` for anonymous development configuration.
+   */
+  public getClientId (): string | undefined {
+    return this.authConfig.clientId
+  }
+
   /**
    * Sets the agent name for M365 agent header propagation.
    * @param agentName The human-friendly agent name to set for header propagation.
@@ -580,7 +601,7 @@ export class CloudAdapter extends BaseAdapter {
    */
   public async process (
     request: Request,
-    res: Response,
+    res: WebResponse,
     logic: (context: TurnContext) => Promise<void>,
     headerPropagation?: HeaderPropagationDefinition): Promise<void> {
     return trace(AdapterTraceDefinitions.process, async ({ record }) => {
@@ -609,7 +630,7 @@ export class CloudAdapter extends BaseAdapter {
         res.end()
       }
       if (!request.body) {
-        throw new TypeError('`request.body` parameter required, make sure express.json() is used as middleware')
+        throw ExceptionHelper.generateException(TypeError, Errors.MissingRequestBody)
       }
       const incoming = normalizeIncomingActivity(request.body!)
       const activity = Activity.fromObject(incoming)
@@ -726,11 +747,11 @@ export class CloudAdapter extends BaseAdapter {
   async updateActivity (context: TurnContext, activity: Activity): Promise<ResourceResponse | void> {
     return trace(AdapterTraceDefinitions.updateActivity, async ({ record }) => {
       if (!context) {
-        throw new TypeError('`context` parameter required')
+        throw ExceptionHelper.generateException(TypeError, Errors.ContextParameterRequired)
       }
 
       if (!activity) {
-        throw new TypeError('`activity` parameter required')
+        throw ExceptionHelper.generateException(TypeError, Errors.ActivityParameterRequired)
       }
 
       record({ activity })
@@ -758,7 +779,7 @@ export class CloudAdapter extends BaseAdapter {
   async deleteActivity (context: TurnContext, reference: Partial<ConversationReference>): Promise<void> {
     return trace(AdapterTraceDefinitions.deleteActivity, async ({ record }) => {
       if (!context) {
-        throw new TypeError('`context` parameter required')
+        throw ExceptionHelper.generateException(TypeError, Errors.ContextParameterRequired)
       }
 
       if (!reference || !reference.serviceUrl || (reference.conversation == null) || !reference.conversation.id || !reference.activityId) {
@@ -791,7 +812,7 @@ export class CloudAdapter extends BaseAdapter {
       }
 
       if (!botAppIdOrIdentity) {
-        throw new TypeError('continueConversation: botAppIdOrIdentity is required')
+        throw ExceptionHelper.generateException(TypeError, Errors.ContinueConversationBotAppIdOrIdentityRequired)
       }
       const botAppId = typeof botAppIdOrIdentity === 'string' ? botAppIdOrIdentity : botAppIdOrIdentity.aud as string
 
@@ -911,10 +932,10 @@ export class CloudAdapter extends BaseAdapter {
     logic: (context: TurnContext) => Promise<void>
   ): Promise<void> {
     if (typeof serviceUrl !== 'string' || !serviceUrl) {
-      throw new TypeError('`serviceUrl` must be a non-empty string')
+      throw ExceptionHelper.generateException(TypeError, Errors.ServiceUrlRequired)
     }
-    if (!conversationParameters) throw new TypeError('`conversationParameters` must be defined')
-    if (!logic) throw new TypeError('`logic` must be defined')
+    if (!conversationParameters) throw ExceptionHelper.generateException(TypeError, Errors.ConversationParametersRequired)
+    if (!logic) throw ExceptionHelper.generateException(TypeError, Errors.LogicParameterRequired)
 
     const identity = CloudAdapter.createIdentity(audience)
     const restClient = await this.createConnectorClient(serviceUrl, audience, identity)

package/src/createCloudAdapter.ts

@@ -0,0 +1,56 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { ActivityHandler } from './activityHandler'
+import { AgentApplication } from './app/agentApplication'
+import { AuthConfiguration } from './auth/authConfiguration'
+import { CloudAdapter } from './cloudAdapter'
+import { HeaderPropagationDefinition } from './headerPropagation'
+import { TurnState } from './app/turnState'
+
+/**
+ * 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, createCloudAdapter } from '@microsoft/agents-hosting';
+ *
+ * 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 => {
+  if (agent instanceof ActivityHandler) {
+    return { adapter: new CloudAdapter(authConfig), headerPropagation: undefined }
+  }
+
+  // AgentApplication: reuse its pre-configured adapter when present, otherwise create one.
+  // headerPropagation is an application-level option, so read it regardless of adapter source.
+  const headerPropagation = agent.options?.headerPropagation
+  const adapter = agent.adapter ?? new CloudAdapter(authConfig)
+  return { adapter, headerPropagation }
+}