@microsoft/agents-hosting 1.7.2 → 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

@@ -51,10 +51,7 @@ export function parseValueContinuation (value: unknown): string {
 }
 
 interface ValueAction {
-  action: {
-    type: string;
-    verb: string;
-  }
+  action: AdaptiveCardInvokeAction
 }
 
 /**
@@ -70,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
   })
@@ -80,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

@@ -678,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
@@ -719,84 +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._authorizationManager.handlers.length > 0) {
-          context.turnState.set(AgentApplication.UserAuthorizationKey, this._authorization)
-        }
+    try {
+      if (this._authorizationManager.handlers.length > 0) {
+        context.turnState.set(AgentApplication.UserAuthorizationKey, this._authorization)
+      }
 
-        const connections = this._options.connections ?? this._adapter?.connectionManager
-        if (connections) {
-          context.turnState.set(AgentApplication.ConnectionsKey, connections)
-        }
+      const connections = this._options.connections ?? this._adapter?.connectionManager
+      if (connections) {
+        context.turnState.set(AgentApplication.ConnectionsKey, connections)
+      }
 
-        if (this._options.startTypingTimer) {
-          this.startTypingTimer(context)
-        }
+      if (this._options.startTypingTimer) {
+        this.startTypingTimer(context)
+      }
 
-        if (this._options.removeRecipientMention && context.activity.type === ActivityTypes.Message) {
-          context.activity.removeRecipientMention()
-        }
+      if (this._options.removeRecipientMention && context.activity.type === ActivityTypes.Message) {
+        context.activity.removeRecipientMention()
+      }
 
-        if (this._options.normalizeMentions && context.activity.type === ActivityTypes.Message) {
-          context.activity.normalizeMentions()
-        }
+      if (this._options.normalizeMentions && context.activity.type === ActivityTypes.Message) {
+        context.activity.normalizeMentions()
+      }
 
-        const { storage, turnStateFactory } = this._options
-        const state = turnStateFactory()
-        await state.load(context, storage)
+      const { storage, turnStateFactory } = this._options
+      const state = turnStateFactory()
+      await state.load(context, storage)
 
-        const route = await this.getRoute(context)
+      const route = await this.getRoute(context)
 
-        record({ routeMatched: route !== undefined })
+      managed.record({ routeMatched: route !== undefined })
 
-        if (!route) {
-          logger.debug('No matching route found for activity:', context.activity)
-          return false
-        }
+      if (!route) {
+        logger.debug('No matching route found for activity:', context.activity)
+        return false
+      }
 
-        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)
-            }
-          })
-        }
+      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) {
-          await trace(AgentApplicationTraceDefinitions.beforeTurn, async () => {
-            if (!(await this.callEventHandlers(context, state, this._beforeTurn))) {
-              await state.save(context, storage)
-              return false
-            }
-          })
-        }
+      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
+          }
 
-        await trace(AgentApplicationTraceDefinitions.routeHandler, async ({ record }) => {
-          record({ isInvoke: route.isInvokeRoute, isAgentic: route.isAgenticRoute })
-          await route.handler(context, state)
+          return true
         })
 
-        if (this._afterTurn.length > 0) {
-          await trace(AgentApplicationTraceDefinitions.afterTurn, async () => {
-            if (await this.callEventHandlers(context, state, this._afterTurn)) {
-              await state.save(context, storage)
-            }
-          })
+        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()
+    }
   }
 
   /**
@@ -1093,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.
    *

package/src/app/attachmentDownloader.ts

@@ -11,6 +11,8 @@ import { Attachment } from '@microsoft/agents-activity'
 import { AuthProvider } from '../auth/authProvider'
 import { debug } from '@microsoft/agents-telemetry'
 import { loadAuthConfigFromEnv, MsalTokenProvider } from '../auth'
+import { createOutboundHostValidator, OutboundUrlPolicy } from '../outboundHostValidator'
+import { Connections } from '../auth/connections'
 
 const logger = debug('agents:attachmentDownloader')
 
@@ -27,16 +29,19 @@ const logger = debug('agents:attachmentDownloader')
 export class AttachmentDownloader<TState extends TurnState = TurnState> implements InputFileDownloader<TState> {
   private _httpClient: HttpClient
   private _stateKey: string
+  private readonly _hostValidator: OutboundUrlPolicy
 
   /**
    * Creates an instance of AttachmentDownloader.
    * This class is responsible for downloading input files from attachments.
    *
    * @param stateKey The key to store files in state. Defaults to 'inputFiles'.
+   * @param outboundHostValidator Optional shared policy used to validate outbound attachment URLs.
    */
-  public constructor (stateKey: string = 'inputFiles') {
+  public constructor (stateKey: string = 'inputFiles', outboundHostValidator?: OutboundUrlPolicy) {
     this._httpClient = new HttpClient()
     this._stateKey = stateKey
+    this._hostValidator = outboundHostValidator ?? createOutboundHostValidator()
   }
 
   /**
@@ -52,10 +57,18 @@ export class AttachmentDownloader<TState extends TurnState = TurnState> implemen
       return Promise.resolve([])
     }
 
-    // TODO: from adapter
-    const authProvider: AuthProvider = new MsalTokenProvider()
-
-    const accessToken = await authProvider.getAccessToken(loadAuthConfigFromEnv(), 'https://api.botframework.com')
+    let accessToken = ''
+    const connectionManager = (context.adapter as { connectionManager?: Connections })?.connectionManager
+    const identity = context.identity
+    if (connectionManager && identity) {
+      const scope = identity.azp ?? identity.appid ?? 'https://api.botframework.com'
+      logger.debug(`Using adapter connection manager token provider for attachment downloads with scope ${scope}`)
+      accessToken = await connectionManager.getTokenProviderFromActivity(identity, context.activity).getAccessToken(scope)
+    } else {
+      logger.debug('Using MsalTokenProvider fallback for attachment downloads')
+      const authProvider: AuthProvider = new MsalTokenProvider()
+      accessToken = await authProvider.getAccessToken(loadAuthConfigFromEnv(), 'https://api.botframework.com')
+    }
 
     const files: InputFile[] = []
     for (const attachment of attachments) {
@@ -90,6 +103,13 @@ export class AttachmentDownloader<TState extends TurnState = TurnState> implemen
       if (accessToken.length > 0) {
         headers.Authorization = `Bearer ${accessToken}`
       }
+      if (!this._hostValidator.isAllowed(attachment.contentUrl)) {
+        let host = '[invalid-url]'
+        try { host = new URL(attachment.contentUrl).hostname } catch { /* invalid */ }
+        logger.warn(`Attachment contentUrl host is not in the configured allowed hosts. Host='${host}'`)
+        return undefined
+      }
+
       const response = await this._httpClient.get(attachment.contentUrl, {
         headers,
         responseType: 'arraybuffer'

package/src/app/auth/handlers/agenticAuthorization.ts

@@ -22,7 +22,7 @@ const logger = debug('agents:authorization:agentic')
  * where `{handlerId}` is the handler's unique identifier and `{propertyName}` matches the property name.
  *
  * @example
- * ```env
+ * ```
  * # For a handler with id "myAuth":
  * AgentApplication__UserAuthorization__handlers__myAuth__settings__type=AgenticUserAuthorization
  * AgentApplication__UserAuthorization__handlers__myAuth__settings__scopes=api://scope1 api://scope2