@microsoft/agents-hosting 1.7.1 → 1.8.0-beta.34.g5d543f96c0

package/src/agent-client/createAgentResponseHandler.ts

@@ -14,11 +14,18 @@ import { normalizeIncomingActivity } from '../activityWireCompat'
 import { Errors } from '../errorHelper'
 import { debug } from '@microsoft/agents-telemetry'
 import { ConversationState } from '../state'
+import { getAuthorizedAudience } from '../auth/jwt-middleware'
 
 const logger = debug('agents:agent-client')
 
 interface ConversationReferenceState {
   conversationReference: ConversationReference
+  expectedAgentClientId?: string
+}
+
+interface DelegatedConversationState {
+  conversationReference: ConversationReference
+  expectedAgentClientId: string
 }
 
 /**
@@ -31,7 +38,7 @@ export interface AgentResponseHandlerParams {
 }
 
 /**
- * Framework-agnostic handler signature for the agent response controller endpoint.
+ * Framework-agnostic handler signature for the SDK-specific Activity callback endpoint.
  *
  * @remarks
  * The handler is intended to be invoked by a thin framework-specific wrapper (such
@@ -45,7 +52,7 @@ export type AgentResponseHandler = (
 ) => Promise<void>
 
 /**
- * Creates a framework-agnostic handler for the agent response controller endpoint.
+ * Creates a framework-agnostic handler for the authenticated Activity callback endpoint.
  *
  * This is the core, Express-free implementation used by:
  * - `configureResponseController` in `@microsoft/agents-hosting-express`
@@ -54,6 +61,11 @@ export type AgentResponseHandler = (
  * Both wrappers register the canonical route
  * `POST /api/agentresponse/v3/conversations/:conversationId/activities/:activityId`
  * and forward the parsed body + path parameters to the handler returned here.
+ * The handler returns `401` for failed JWT authentication and `403` when the
+ * authenticated caller does not match the delegated agent stored for the
+ * conversation, or when that delegated state is missing or malformed.
+ *
+ * This callback contract is SDK-specific and is not the open A2A protocol.
  *
  * @param adapter - The CloudAdapter used for processing activities and managing conversations.
  * @param agent - The ActivityHandler containing the agent logic.
@@ -65,21 +77,57 @@ export const createAgentResponseHandler = (
   agent: ActivityHandler,
   conversationState: ConversationState
 ): AgentResponseHandler => {
+  const appId = adapter.getClientId() ?? ''
+  const anonymousDevelopment = appId.length === 0 && process.env.NODE_ENV !== 'production'
+  if (anonymousDevelopment) {
+    emitAgentResponseWarning(
+      'The agent-response endpoint is using anonymous authentication outside production. Callback ownership cannot be cryptographically verified; configure a client ID before deployment.'
+    )
+  }
+
   return async (req: Request, res: WebResponse, params: AgentResponseHandlerParams) => {
+    let middlewareError: any
+    let nextCalled = false
+    await adapter.authorizeRequest(req, res, (err?: any) => {
+      nextCalled = true
+      middlewareError = err
+    })
+    if (middlewareError) {
+      throw middlewareError
+    }
+    if (!nextCalled || res.headersSent) {
+      return
+    }
+
     if (!req.body) {
       throw ExceptionHelper.generateException(TypeError, Errors.MissingRequestBody)
     }
     const incoming = normalizeIncomingActivity(req.body)
     const activity = Activity.fromObject(incoming)
 
-    logger.debug('received response: ', activity)
+    logger.debug('received delegated agent response')
 
-    const connection = adapter.connectionManager.getDefaultConnection()
-    const appId = connection?.connectionSettings?.clientId ?? ''
-
-    const myTurnContext = new TurnContext(adapter, activity, CloudAdapter.createIdentity(appId))
+    const continuationAudience = getAuthorizedAudience(req) ?? appId
+    const myTurnContext = new TurnContext(adapter, activity, CloudAdapter.createIdentity(continuationAudience))
     const conversationDataAccessor = conversationState.createProperty<ConversationReferenceState>(params.conversationId)
-    const conversationRefState = await conversationDataAccessor.get(myTurnContext, undefined, { channelId: activity.channelId!, conversationId: params.conversationId })
+    const incomingChannelId = activity.channelId!
+    const conversationRefState = await conversationDataAccessor.get(myTurnContext, undefined, { channelId: incomingChannelId, conversationId: params.conversationId })
+    if (!isDelegatedConversationState(conversationRefState)) {
+      res.status(403).send({ 'agent-response-auth-error': 'caller is not authorized for this conversation' })
+      return
+    }
+
+    const callerClientId = req.user?.azp ?? req.user?.appid
+    const anonymousCaller = anonymousDevelopment && req.user?.name === 'anonymous'
+    const delegatedAgentMatches = anonymousCaller || (
+      typeof callerClientId === 'string' &&
+      callerClientId.length > 0 &&
+      callerClientId.toLowerCase() === conversationRefState.expectedAgentClientId.toLowerCase()
+    )
+    if (!delegatedAgentMatches) {
+      res.status(403).send({ 'agent-response-auth-error': 'caller is not authorized for this conversation' })
+      return
+    }
 
     const callback = async (turnContext: TurnContext) => {
       activity.applyConversationReference(conversationRefState.conversationReference)
@@ -88,7 +136,7 @@ export const createAgentResponseHandler = (
       let response: unknown
       let responseContentType: string | undefined
       if (activity.type === ActivityTypes.EndOfConversation) {
-        await conversationDataAccessor.delete(turnContext, { channelId: activity.channelId!, conversationId: activity.conversation!.id })
+        await conversationState.delete(myTurnContext, { channelId: incomingChannelId, conversationId: params.conversationId })
 
         applyActivityToTurnContext(turnContext, activity)
         await agent.run(turnContext)
@@ -101,6 +149,7 @@ export const createAgentResponseHandler = (
       } else {
         response = await turnContext.sendActivity(activity)
       }
+
       if (responseContentType !== undefined) {
         res.setHeader('content-type', responseContentType)
       }
@@ -111,6 +160,18 @@ export const createAgentResponseHandler = (
   }
 }
 
+function isDelegatedConversationState (state: ConversationReferenceState | undefined): state is DelegatedConversationState {
+  return typeof state?.conversationReference === 'object' &&
+    state.conversationReference !== null &&
+    typeof state.expectedAgentClientId === 'string' &&
+    state.expectedAgentClientId.trim().length > 0
+}
+
+function emitAgentResponseWarning (message: string): void {
+  console.warn(`[agents:agent-client] ${message}`)
+  logger.warn(message)
+}
+
 const applyActivityToTurnContext = (turnContext: TurnContext, activity: Activity) => {
   turnContext.activity.channelData = activity.channelData
   turnContext.activity.code = activity.code

package/src/app/adaptiveCards/activityValueParsers.ts

@@ -5,7 +5,6 @@
 
 import { z } from 'zod'
 import { activityZodSchema, AdaptiveCardInvokeAction, adaptiveCardInvokeActionZodSchema, ExceptionHelper } from '@microsoft/agents-activity'
-// import { MessagingExtensionQuery, messagingExtensionQueryZodSchema } from '../messageExtension/messagingExtensionQuery'
 import { adaptiveCardsSearchParamsZodSchema } from './adaptiveCardsSearchParams'
 import { Errors } from '../../errorHelper'
 
@@ -52,10 +51,7 @@ export function parseValueContinuation (value: unknown): string {
 }
 
 interface ValueAction {
-  action: {
-    type: string;
-    verb: string;
-  }
+  action: AdaptiveCardInvokeAction
 }
 
 /**
@@ -71,7 +67,7 @@ export function parseValueActionExecuteSelector (value: unknown): ValueAction |
   const actionZodSchema = z.object({
     type: z.string().min(1),
     verb: z.string().min(1)
-  })
+  }).passthrough()
   const actionValueExecuteSelector = z.object({
     action: actionZodSchema
   })
@@ -81,10 +77,7 @@ export function parseValueActionExecuteSelector (value: unknown): ValueAction |
   }
   const parsedValue = safeParsedValue.data
   return {
-    action: {
-      type: parsedValue.action.type,
-      verb: parsedValue.action.verb
-    }
+    action: parsedValue.action as unknown as AdaptiveCardInvokeAction
   }
 }
 

package/src/app/adaptiveCards/adaptiveCardsActions.ts

@@ -4,6 +4,7 @@
  */
 
 import { Activity, ActivityTypes, ExceptionHelper } from '@microsoft/agents-activity'
+import { debug } from '@microsoft/agents-telemetry'
 import { AdaptiveCardInvokeResponse, AgentApplication, CardFactory, INVOKE_RESPONSE_KEY, InvokeResponse, MessageFactory, RouteSelector, TurnContext, TurnState } from '../../'
 import { AdaptiveCardActionExecuteResponseType } from './adaptiveCardActionExecuteResponseType'
 import { parseAdaptiveCardInvokeAction, parseValueActionExecuteSelector, parseValueDataset, parseValueSearchQuery } from './activityValueParsers'
@@ -16,6 +17,7 @@ export const ACTION_INVOKE_NAME = 'adaptiveCard/action'
 const ACTION_EXECUTE_TYPE = 'Action.Execute'
 const DEFAULT_ACTION_SUBMIT_FILTER = 'verb'
 const SEARCH_INVOKE_NAME = 'application/search'
+const logger = debug('agents:adaptive-cards')
 
 enum AdaptiveCardInvokeResponseType {
   /**
@@ -100,12 +102,30 @@ export class AdaptiveCardsActions<TState extends TurnState> {
    * @param verb - A string, RegExp, RouteSelector, or an array of these to match the action verb.
    * @param handler - A function to handle the action execution.
    * @returns The Teams application instance.
+   *
+   * @remarks
+   * The delivery behavior depends on the action trigger and
+   * `adaptiveCardsOptions.actionExecuteResponseType`:
+   *
+   * | Response type | Automatic trigger | Manual trigger |
+   * | --- | --- | --- |
+   * | `REPLACE_FOR_INTERACTOR` | User response | User response |
+   * | `REPLACE_FOR_ALL` | User response | Shared update |
+   * | `NEW_MESSAGE_FOR_ALL` | User response | New message |
+   *
+   * - **User response** — Return an Adaptive Card invoke response only to the requesting or interacting user.
+   * - **Shared update** — Update the shared activity for all users and return an Adaptive Card invoke response to the interacting user.
+   * - **New message** — Send a new activity for all users and return a message acknowledgement to the interacting user.
+   *
+   * Automatic refresh actions always return only an Adaptive Card invoke response.
+   * Updating or sending a refreshable card while processing an automatic refresh
+   * would cause Teams to invoke the refresh action again.
    */
   public actionExecute<TData = Record<string, any>>(
     verb: string | RegExp | RouteSelector | (string | RegExp | RouteSelector)[],
     handler: (context: TurnContext, state: TState, data: TData) => Promise<AdaptiveCard | string>
   ): AgentApplication<TState> {
-    let actionExecuteResponseType = this._app.options.adaptiveCardsOptions?.actionExecuteResponseType ?? AdaptiveCardActionExecuteResponseType.REPLACE_FOR_INTERACTOR;
+    const actionExecuteResponseType = this._app.options.adaptiveCardsOptions?.actionExecuteResponseType ?? AdaptiveCardActionExecuteResponseType.REPLACE_FOR_INTERACTOR;
     (Array.isArray(verb) ? verb : [verb]).forEach((v) => {
       const selector = createActionExecuteSelector(v)
       this._app.addRoute(
@@ -113,6 +133,7 @@ export class AdaptiveCardsActions<TState extends TurnState> {
         async (context, state) => {
           const a = context?.activity
           const invokeAction = parseValueActionExecuteSelector(a.value)
+          const isAutomaticRefresh = (a.value as { trigger?: string } | undefined)?.trigger === 'automatic'
           if (
             a?.type !== ActivityTypes.Invoke ||
                         a?.name !== ACTION_INVOKE_NAME ||
@@ -121,13 +142,11 @@ export class AdaptiveCardsActions<TState extends TurnState> {
             throw ExceptionHelper.generateException(Error, Errors.UnexpectedActionExecute, undefined, { activityType: invokeAction?.action.type ?? 'undefined' })
           }
 
-          if (invokeAction.action.verb !== v) {
-            // TODO: add logger to this class
-            console.log(`AdaptiveCards.actionExecute() triggered for verb: ${invokeAction.action.verb} does not match expected verb: ${v}`)
+          if (typeof v === 'string' && invokeAction.action.verb !== v) {
+            logger.warn(`AdaptiveCards.actionExecute() triggered for verb: ${invokeAction.action.verb} does not match expected verb: ${v}`)
           }
 
-          // TODO: review any, and check verb
-          const result = await handler(context, state, ((a.value as any).action as TData) ?? {} as TData)
+          const result = await handler(context, state, (invokeAction.action as unknown as TData) ?? {} as TData)
           if (!context.turnState.get(INVOKE_RESPONSE_KEY)) {
             let response: AdaptiveCardInvokeResponse
             if (typeof result === 'string') {
@@ -138,20 +157,14 @@ export class AdaptiveCardsActions<TState extends TurnState> {
               }
               await sendInvokeResponse(context, response)
             } else {
-              if (
-                result.refresh &&
-                                actionExecuteResponseType !== AdaptiveCardActionExecuteResponseType.NEW_MESSAGE_FOR_ALL
-              ) {
-                actionExecuteResponseType = AdaptiveCardActionExecuteResponseType.REPLACE_FOR_ALL
-              }
-
-              const activity = MessageFactory.attachment(CardFactory.adaptiveCard(result))
               response = {
                 statusCode: 200,
                 type: AdaptiveCardInvokeResponseType.ADAPTIVE,
                 value: result
               }
-              if (
+              if (isAutomaticRefresh) {
+                await sendInvokeResponse(context, response)
+              } else if (
                 actionExecuteResponseType === AdaptiveCardActionExecuteResponseType.NEW_MESSAGE_FOR_ALL
               ) {
                 await sendInvokeResponse(context, {
@@ -159,10 +172,11 @@ export class AdaptiveCardsActions<TState extends TurnState> {
                   type: AdaptiveCardInvokeResponseType.MESSAGE,
                   value: 'Your response was sent to the app' as any
                 })
-                await context.sendActivity(activity)
+                await context.sendActivity(MessageFactory.attachment(CardFactory.adaptiveCard(result)))
               } else if (
                 actionExecuteResponseType === AdaptiveCardActionExecuteResponseType.REPLACE_FOR_ALL
               ) {
+                const activity = MessageFactory.attachment(CardFactory.adaptiveCard(result))
                 activity.id = context.activity.replyToId
                 await context.updateActivity(activity)
                 await sendInvokeResponse(context, response)
@@ -270,12 +284,15 @@ function createActionExecuteSelector (verb: string | RegExp | RouteSelector): Ro
   } else if (verb instanceof RegExp) {
     return (context: TurnContext) => {
       const a = context?.activity
-      const valueAction = parseValueActionExecuteSelector(a.value)
       const isInvoke =
                 a?.type === ActivityTypes.Invoke &&
-                a?.name === ACTION_INVOKE_NAME &&
-                valueAction?.action?.type === ACTION_EXECUTE_TYPE
-      if (isInvoke && typeof valueAction.action.verb === 'string') {
+                a?.name === ACTION_INVOKE_NAME
+      if (!isInvoke) {
+        return Promise.resolve(false)
+      }
+
+      const valueAction = tryParseActionExecuteSelectorValue(a.value)
+      if (valueAction?.action?.type === ACTION_EXECUTE_TYPE && typeof valueAction.action.verb === 'string') {
         return Promise.resolve(verb.test(valueAction.action.verb))
       } else {
         return Promise.resolve(false)
@@ -284,12 +301,15 @@ function createActionExecuteSelector (verb: string | RegExp | RouteSelector): Ro
   } else {
     return (context: TurnContext) => {
       const a = context?.activity
-      const valueAction = parseValueActionExecuteSelector(a.value)
       const isInvoke =
                 a?.type === ActivityTypes.Invoke &&
-                a?.name === ACTION_INVOKE_NAME &&
-                valueAction?.action?.type === ACTION_EXECUTE_TYPE
-      if (isInvoke && valueAction.action?.verb === verb) {
+                a?.name === ACTION_INVOKE_NAME
+      if (!isInvoke) {
+        return Promise.resolve(false)
+      }
+
+      const valueAction = tryParseActionExecuteSelectorValue(a.value)
+      if (valueAction?.action?.type === ACTION_EXECUTE_TYPE && valueAction.action?.verb === verb) {
         return Promise.resolve(true)
       } else {
         return Promise.resolve(false)
@@ -298,6 +318,14 @@ function createActionExecuteSelector (verb: string | RegExp | RouteSelector): Ro
   }
 }
 
+function tryParseActionExecuteSelectorValue (value: unknown): ReturnType<typeof parseValueActionExecuteSelector> {
+  try {
+    return parseValueActionExecuteSelector(value)
+  } catch {
+    return undefined
+  }
+}
+
 function createActionSubmitSelector (verb: string | RegExp | RouteSelector, filter: string): RouteSelector {
   if (typeof verb === 'function') {
     return verb

package/src/app/agentApplication.ts

@@ -87,6 +87,12 @@ export type ApplicationEventHandler<TState extends TurnState> = (context: TurnCo
  *
  */
 export class AgentApplication<TState extends TurnState> {
+  /** Turn-state key for the user authorization service configured on this application. */
+  public static readonly UserAuthorizationKey = Symbol('UserAuthorization')
+
+  /** Turn-state key for the token connections configured on this application. */
+  public static readonly ConnectionsKey = Symbol('Connections')
+
   protected readonly _options: AgentApplicationOptions<TState>
   protected readonly _routes: RouteList<TState> = new RouteList<TState>()
   protected readonly _beforeTurn: ApplicationEventHandler<TState>[] = []
@@ -672,7 +678,7 @@ export class AgentApplication<TState extends TurnState> {
 
     if (!authorized) {
       const managed = trace(AgentApplicationTraceDefinitions.run)
-      managed.record({ authorized, activity: context.activity })
+      managed.record({ authorized, activity: Activity.fromObject(context.activity) })
       managed.end()
       // We don't log a message here because it is handled by the authorization manager and could cause confusion during mid sign-in operations.
       return false
@@ -713,75 +719,90 @@ export class AgentApplication<TState extends TurnState> {
    * Executes the turn processing logic for the given context, including routing and handler execution.
    */
   private async runTurn (context: TurnContext): Promise<boolean> {
-    return trace(AgentApplicationTraceDefinitions.run, async ({ record }) => {
-      record({ authorized: true, activity: context.activity })
+    const managed = trace(AgentApplicationTraceDefinitions.run)
+    managed.record({ authorized: true, activity: Activity.fromObject(context.activity) })
 
-      try {
-        if (this._options.startTypingTimer) {
-          this.startTypingTimer(context)
-        }
+    try {
+      if (this._authorizationManager.handlers.length > 0) {
+        context.turnState.set(AgentApplication.UserAuthorizationKey, this._authorization)
+      }
 
-        if (this._options.removeRecipientMention && context.activity.type === ActivityTypes.Message) {
-          context.activity.removeRecipientMention()
-        }
+      const connections = this._options.connections ?? this._adapter?.connectionManager
+      if (connections) {
+        context.turnState.set(AgentApplication.ConnectionsKey, connections)
+      }
 
-        if (this._options.normalizeMentions && context.activity.type === ActivityTypes.Message) {
-          context.activity.normalizeMentions()
-        }
+      if (this._options.startTypingTimer) {
+        this.startTypingTimer(context)
+      }
 
-        const { storage, turnStateFactory } = this._options
-        const state = turnStateFactory()
-        await state.load(context, storage)
+      if (this._options.removeRecipientMention && context.activity.type === ActivityTypes.Message) {
+        context.activity.removeRecipientMention()
+      }
 
-        const route = await this.getRoute(context)
+      if (this._options.normalizeMentions && context.activity.type === ActivityTypes.Message) {
+        context.activity.normalizeMentions()
+      }
 
-        record({ routeMatched: route !== undefined })
+      const { storage, turnStateFactory } = this._options
+      const state = turnStateFactory()
+      await state.load(context, storage)
 
-        if (!route) {
-          logger.debug('No matching route found for activity:', context.activity)
-          return false
-        }
+      const route = await this.getRoute(context)
 
-        const fileDownloaders = this._options.fileDownloaders
-        if (Array.isArray(fileDownloaders) && fileDownloaders.length > 0) {
-          await trace(AgentApplicationTraceDefinitions.downloadFiles, async ({ record }) => {
-            record({ attachmentsCount: context.activity.attachments?.length })
-            for (let i = 0; i < fileDownloaders.length; i++) {
-              await fileDownloaders[i].downloadAndStoreFiles(context, state)
-            }
-          })
-        }
+      managed.record({ routeMatched: route !== undefined })
 
-        if (this._beforeTurn.length > 0) {
-          await trace(AgentApplicationTraceDefinitions.beforeTurn, async () => {
-            if (!(await this.callEventHandlers(context, state, this._beforeTurn))) {
-              await state.save(context, storage)
-              return false
-            }
-          })
-        }
+      if (!route) {
+        logger.debug('No matching route found for activity:', context.activity)
+        return false
+      }
 
-        await trace(AgentApplicationTraceDefinitions.routeHandler, async ({ record }) => {
-          record({ isInvoke: route.isInvokeRoute, isAgentic: route.isAgenticRoute })
-          await route.handler(context, state)
+      const fileDownloaders = this._options.fileDownloaders
+      if (Array.isArray(fileDownloaders) && fileDownloaders.length > 0) {
+        await managed.child(AgentApplicationTraceDefinitions.downloadFiles, async ({ record }) => {
+          record({ attachmentsCount: context.activity.attachments?.length })
+          for (let i = 0; i < fileDownloaders.length; i++) {
+            await fileDownloaders[i].downloadAndStoreFiles(context, state)
+          }
         })
+      }
+
+      if (this._beforeTurn.length > 0) {
+        const continueTurn = await managed.child(AgentApplicationTraceDefinitions.beforeTurn, async () => {
+          if (!(await this.callEventHandlers(context, state, this._beforeTurn))) {
+            await state.save(context, storage)
+            return false
+          }
 
-        if (this._afterTurn.length > 0) {
-          await trace(AgentApplicationTraceDefinitions.afterTurn, async () => {
-            if (await this.callEventHandlers(context, state, this._afterTurn)) {
-              await state.save(context, storage)
-            }
-          })
+          return true
+        })
+
+        if (!continueTurn) {
+          return false
         }
+      }
 
-        return true
-      } catch (err: any) {
-        logger.error(err)
-        throw err
-      } finally {
-        this.stopTypingTimer(context)
+      await managed.child(AgentApplicationTraceDefinitions.routeHandler, async ({ record }) => {
+        record({ isInvoke: route.isInvokeRoute, isAgentic: route.isAgenticRoute })
+        await route.handler(context, state)
+      })
+
+      if (this._afterTurn.length > 0) {
+        await managed.child(AgentApplicationTraceDefinitions.afterTurn, async () => {
+          if (await this.callEventHandlers(context, state, this._afterTurn)) {
+            await state.save(context, storage)
+          }
+        })
       }
-    })
+
+      return true
+    } catch (err: any) {
+      logger.error(err)
+      throw managed.fail(err)
+    } finally {
+      this.stopTypingTimer(context)
+      managed.end()
+    }
   }
 
   /**
@@ -1078,22 +1099,77 @@ export class AgentApplication<TState extends TurnState> {
     handler: (context: TurnContext) => Promise<any>
   ) {
     const activity = Activity.fromObject(context.activity)
-    this.continueConversationAsync(context.identity, activity.getConversationReference(), async (ctx) => {
-      try {
-        Object.assign(ctx.activity, activity)
-        await handler(ctx)
-      } catch (err) {
-        if (this.adapter.onTurnError && err instanceof Error) {
-          await this.adapter.onTurnError(ctx, err)
-        } else {
-          throw err
+    const adapter = context.adapter
+    const identity = context.identity
+    const createErrorContext = () => new TurnContext(adapter, Activity.fromObject(activity), identity)
+
+    try {
+      const reference = activity.getConversationReference()
+      this.continueConversationAsync(identity, reference, async (ctx) => {
+        try {
+          Object.assign(ctx.activity, activity)
+          await handler(ctx)
+        } catch (err) {
+          await this.handleLongRunningCallError(ctx, activity, err)
         }
-      }
-    }).catch(err => {
-      logger.error(`Unhandled error in long-running call for activity '${activity.type}' (id: ${activity.id}):`, err)
+      }).catch(async err => {
+        await this.handleLongRunningCallError(createErrorContext(), activity, err)
+      })
+    } catch (err) {
+      this.handleLongRunningCallError(createErrorContext(), activity, err).catch(handlerErr => {
+        logger.error(`Unhandled error in long-running error handler for activity '${activity.type}' (id: ${activity.id}):`, this.normalizeLongRunningCallError(handlerErr))
+      })
+    }
+  }
+
+  private async handleLongRunningCallError (
+    context: TurnContext,
+    activity: Activity,
+    err: unknown
+  ): Promise<void> {
+    const error = this.normalizeLongRunningCallError(err)
+
+    try {
+      await context.adapter.onTurnError(context, error)
+    } catch (handlerErr) {
+      logger.error(`Unhandled error in long-running error handler for activity '${activity.type}' (id: ${activity.id}):`, this.normalizeLongRunningCallError(handlerErr))
+    }
+  }
+
+  private normalizeLongRunningCallError (err: unknown): Error {
+    if (err instanceof Error) {
+      return err
+    }
+
+    return ExceptionHelper.generateException(Error, Errors.UnknownErrorType, undefined, {
+      errorMessage: this.stringifyThrownValue(err)
     })
   }
 
+  private stringifyThrownValue (value: unknown): string {
+    if (typeof value === 'string') {
+      return value
+    }
+
+    if (value === undefined) {
+      return 'undefined'
+    }
+
+    if (value === null) {
+      return 'null'
+    }
+
+    if (typeof value === 'object') {
+      try {
+        return JSON.stringify(value) ?? Object.prototype.toString.call(value)
+      } catch {
+        return Object.prototype.toString.call(value)
+      }
+    }
+
+    return String(value)
+  }
+
   /**
    * Creates a selector function for activity types.
    *