@microsoft/agents-hosting 1.5.0-beta.6.ga236d9a19c → 1.5.1

package/src/cloudAdapter.ts

@@ -17,7 +17,7 @@ import { Activity, ActivityEventNames, ActivityTypes, Channels, ConversationRefe
 import { Errors } from './errorHelper'
 import { ResourceResponse } from './connector-client/resourceResponse'
 import * as uuid from 'uuid'
-import { debug } from '@microsoft/agents-activity/logger'
+import { debug } from '@microsoft/agents-telemetry'
 import { StatusCodes } from './statusCodes'
 import { InvokeResponse } from './invoke/invokeResponse'
 import { AttachmentData } from './connector-client/attachmentData'
@@ -28,6 +28,8 @@ import { HeaderPropagation, HeaderPropagationCollection, HeaderPropagationDefini
 import { JwtPayload } from 'jsonwebtoken'
 import { getTokenServiceEndpoint } from './oauth/customUserTokenAPI'
 import { Connections } from './auth/connections'
+import { trace } from '@microsoft/agents-telemetry'
+import { AdapterTraceDefinitions } from './observability'
 const logger = debug('agents:cloud-adapter')
 
 /**
@@ -100,15 +102,19 @@ export class CloudAdapter extends BaseAdapter {
     identity: JwtPayload,
     headers?: HeaderPropagationCollection
   ): Promise<ConnectorClient> {
-    // get the correct token provider
-    const tokenProvider = this.connectionManager.getTokenProvider(identity, serviceUrl)
+    return trace(AdapterTraceDefinitions.createConnectorClient, async ({ record }) => {
+      record({ serviceUrl, scope })
 
-    const token = await tokenProvider.getAccessToken(scope)
-    return ConnectorClient.createClientWithToken(
-      serviceUrl,
-      token,
-      headers
-    )
+      // get the correct token provider
+      const tokenProvider = this.connectionManager.getTokenProvider(identity, serviceUrl)
+
+      const token = await tokenProvider.getAccessToken(scope)
+      return ConnectorClient.createClientWithToken(
+        serviceUrl,
+        token,
+        headers
+      )
+    })
   }
 
   /**
@@ -124,55 +130,64 @@ export class CloudAdapter extends BaseAdapter {
     identity: JwtPayload,
     activity: Activity,
     headers?: HeaderPropagationCollection) {
-    if (!identity?.aud) {
-      // anonymous
-      logger.warn('Missing identity or identity.aud when creating connector client. Using anonymous identity')
-      return ConnectorClient.createClientWithToken(
-        activity.serviceUrl!,
-        null!,
-        headers
-      )
-    }
-
-    let connectorClient
-    const tokenProvider = this.connectionManager.getTokenProviderFromActivity(identity, activity)
-    if (activity.isAgenticRequest()) {
-      logger.debug('Activity is from an agentic source, using special scope', activity.recipient)
-      const agenticInstanceId = activity.getAgenticInstanceId()
-      const agenticUserId = activity.getAgenticUser()
-
-      if (activity.recipient?.role?.toLowerCase() === RoleTypes.AgenticIdentity.toLowerCase() && agenticInstanceId) {
-        // get agentic instance token
-        const token = await tokenProvider.getAgenticInstanceToken(activity.getAgenticTenantId() ?? '', agenticInstanceId)
-        connectorClient = ConnectorClient.createClientWithToken(
+    return trace(AdapterTraceDefinitions.createConnectorClient, async ({ record }) => {
+      if (!identity?.aud) {
+        // anonymous
+        logger.warn('Missing identity or identity.aud when creating connector client. Using anonymous identity')
+        return ConnectorClient.createClientWithToken(
           activity.serviceUrl!,
-          token,
+          null!,
           headers
         )
-      } else if (activity.recipient?.role?.toLowerCase() === RoleTypes.AgenticUser.toLowerCase() && agenticInstanceId && agenticUserId) {
-        const scope = tokenProvider.connectionSettings?.scope ?? ApxProductionScope
-        const token = await tokenProvider.getAgenticUserToken(activity.getAgenticTenantId() ?? '', agenticInstanceId, agenticUserId, [scope])
+      }
 
+      let connectorClient
+      const tokenProvider = this.connectionManager.getTokenProviderFromActivity(identity, activity)
+      const isAgentic = activity.isAgenticRequest()
+      let scope
+      if (isAgentic) {
+        logger.debug('Activity is from an agentic source, using special scope', activity.recipient)
+        const agenticInstanceId = activity.getAgenticInstanceId()
+        const agenticUserId = activity.getAgenticUser()
+
+        if (activity.recipient?.role?.toLowerCase() === RoleTypes.AgenticIdentity.toLowerCase() && agenticInstanceId) {
+          // get agentic instance token
+          const token = await tokenProvider.getAgenticInstanceToken(activity.getAgenticTenantId() ?? '', agenticInstanceId)
+          connectorClient = ConnectorClient.createClientWithToken(
+            activity.serviceUrl!,
+            token,
+            headers
+          )
+        } else if (activity.recipient?.role?.toLowerCase() === RoleTypes.AgenticUser.toLowerCase() && agenticInstanceId && agenticUserId) {
+          scope = tokenProvider.connectionSettings?.scope ?? ApxProductionScope
+          const token = await tokenProvider.getAgenticUserToken(activity.getAgenticTenantId() ?? '', agenticInstanceId, agenticUserId, [scope])
+
+          connectorClient = ConnectorClient.createClientWithToken(
+            activity.serviceUrl!,
+            token,
+            headers
+          )
+        } else {
+          throw new Error('Could not create connector client for agentic user')
+        }
+      } else {
+        // ABS tokens will not have an azp/appid so use the botframework scope.
+        // Otherwise use the appId.  This will happen when communicating back to another agent.
+        scope = identity.azp ?? identity.appid ?? 'https://api.botframework.com'
+        const token = await tokenProvider.getAccessToken(scope)
         connectorClient = ConnectorClient.createClientWithToken(
           activity.serviceUrl!,
           token,
           headers
         )
-      } else {
-        throw new Error('Could not create connector client for agentic user')
       }
-    } else {
-      // ABS tokens will not have an azp/appid so use the botframework scope.
-      // Otherwise use the appId.  This will happen when communicating back to another agent.
-      const scope = identity.azp ?? identity.appid ?? 'https://api.botframework.com'
-      const token = await tokenProvider.getAccessToken(scope)
-      connectorClient = ConnectorClient.createClientWithToken(
-        activity.serviceUrl!,
-        token,
-        headers
-      )
-    }
-    return connectorClient
+      record({
+        serviceUrl: activity.serviceUrl,
+        scope,
+        activityIsAgentic: isAgentic
+      })
+      return connectorClient
+    })
   }
 
   /**
@@ -217,25 +232,28 @@ export class CloudAdapter extends BaseAdapter {
     audience: string = 'https://api.botframework.com',
     headers?: HeaderPropagationCollection
   ): Promise<UserTokenClient> {
-    if (!identity?.aud) {
-      // anonymous
+    return trace(AdapterTraceDefinitions.createUserTokenClient, async ({ record }) => {
+      record({ tokenServiceEndpoint, authScope: scope })
+      if (!identity?.aud) {
+        // anonymous
+        return UserTokenClient.createClientWithScope(
+          tokenServiceEndpoint,
+          null!,
+          scope,
+          headers
+        )
+      }
+
+      // get the correct token provider
+      const tokenProvider = this.connectionManager.getTokenProvider(identity, tokenServiceEndpoint)
+
       return UserTokenClient.createClientWithScope(
         tokenServiceEndpoint,
-        null!,
+        tokenProvider,
         scope,
         headers
       )
-    }
-
-    // get the correct token provider
-    const tokenProvider = this.connectionManager.getTokenProvider(identity, tokenServiceEndpoint)
-
-    return UserTokenClient.createClientWithScope(
-      tokenServiceEndpoint,
-      tokenProvider,
-      scope,
-      headers
-    )
+    })
   }
 
   /**
@@ -270,47 +288,51 @@ export class CloudAdapter extends BaseAdapter {
    * @returns A promise representing the array of ResourceResponses for the sent activities.
    */
   async sendActivities (context: TurnContext, activities: Activity[]): Promise<ResourceResponse[]> {
-    if (!context) {
-      throw ExceptionHelper.generateException(TypeError, Errors.ContextParameterRequired)
-    }
+    return trace(AdapterTraceDefinitions.sendActivities, async ({ record, actions }) => {
+      record({ activityCount: activities?.length })
+      if (!context) {
+        throw ExceptionHelper.generateException(TypeError, Errors.ContextParameterRequired)
+      }
 
-    if (!activities) {
-      throw ExceptionHelper.generateException(TypeError, Errors.ActivitiesParameterRequired)
-    }
+      if (!activities) {
+        throw ExceptionHelper.generateException(TypeError, Errors.ActivitiesParameterRequired)
+      }
 
-    if (activities.length === 0) {
-      throw ExceptionHelper.generateException(Error, Errors.EmptyActivitiesArray)
-    }
+      if (activities.length === 0) {
+        throw ExceptionHelper.generateException(Error, Errors.EmptyActivitiesArray)
+      }
 
-    const responses: ResourceResponse[] = []
-    for (const activity of activities) {
-      delete activity.id
-      let response: ResourceResponse = { id: '' }
+      const responses: ResourceResponse[] = []
+      for (const activity of activities) {
+        actions.recordActivity(activity)
+        delete activity.id
+        let response: ResourceResponse = { id: '' }
 
-      if (activity.type === ActivityTypes.InvokeResponse) {
-        context.turnState.set(INVOKE_RESPONSE_KEY, activity)
-      } else if (activity.type === ActivityTypes.Trace && activity.channelId !== Channels.Emulator) {
-        // no-op
-      } else {
-        if (!activity.serviceUrl || (activity.conversation == null) || !activity.conversation.id) {
-          throw ExceptionHelper.generateException(Error, Errors.InvalidActivityObject)
+        if (activity.type === ActivityTypes.InvokeResponse) {
+          context.turnState.set(INVOKE_RESPONSE_KEY, activity)
+        } else if (activity.type === ActivityTypes.Trace && activity.channelId !== Channels.Emulator) {
+          // no-op
+        } else {
+          if (!activity.serviceUrl || (activity.conversation == null) || !activity.conversation.id) {
+            throw ExceptionHelper.generateException(Error, Errors.InvalidActivityObject)
+          }
+
+          if (activity.replyToId) {
+            response = await context.turnState.get(this.ConnectorClientKey).replyToActivity(activity.conversation.id, activity.replyToId, activity)
+          } else {
+            response = await context.turnState.get(this.ConnectorClientKey).sendToConversation(activity.conversation.id, activity)
+          }
         }
 
-        if (activity.replyToId) {
-          response = await context.turnState.get(this.ConnectorClientKey).replyToActivity(activity.conversation.id, activity.replyToId, activity)
-        } else {
-          response = await context.turnState.get(this.ConnectorClientKey).sendToConversation(activity.conversation.id, activity)
+        if (!response) {
+          response = { id: activity.id ?? '' }
         }
-      }
 
-      if (!response) {
-        response = { id: activity.id ?? '' }
+        responses.push(response)
       }
 
-      responses.push(response)
-    }
-
-    return responses
+      return responses
+    })
   }
 
   /**
@@ -329,61 +351,75 @@ export class CloudAdapter extends BaseAdapter {
     res: Response,
     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)
-    }
+    return trace(AdapterTraceDefinitions.process, async ({ record }) => {
+      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) => {
+        if (res.writableEnded) {
+          return
+        }
 
-    const end = (status: StatusCodes, body?: unknown, isInvokeResponseOrExpectReplies: boolean = false) => {
-      res.status(status)
-      if (isInvokeResponseOrExpectReplies) {
-        res.setHeader('content-type', 'application/json')
+        if (res.headersSent) {
+          res.end()
+          return
+        }
+        res.status(status)
+        if (isInvokeResponseOrExpectReplies) {
+          res.setHeader('content-type', 'application/json')
+        }
+        if (body) {
+          res.send(body)
+        }
+        res.end()
       }
-      if (body) {
-        res.send(body)
+      if (!request.body) {
+        throw new TypeError('`request.body` parameter required, make sure express.json() is used as middleware')
       }
-      res.end()
-    }
-    if (!request.body) {
-      throw new TypeError('`request.body` parameter required, make sure express.json() is used as middleware')
-    }
-    const incoming = normalizeIncomingActivity(request.body!)
-    const activity = Activity.fromObject(incoming)
-    logger.info(`--> Processing incoming activity, type:${activity.type} channel:${activity.channelId}`)
+      const incoming = normalizeIncomingActivity(request.body!)
+      const activity = Activity.fromObject(incoming)
+      logger.info(`--> Processing incoming activity, type:${activity.type} channel:${activity.channelId}`)
 
-    if (!this.isValidChannelActivity(activity)) {
-      return end(StatusCodes.BAD_REQUEST)
-    }
+      const isAgentic = activity.isAgenticRequest()
 
-    logger.debug('Received activity: ', activity)
+      record({ activity })
 
-    const context = new TurnContext(this, activity, request.user!)
-    // if Delivery Mode == ExpectReplies, we don't need a connector client.
-    if (this.resolveIfConnectorClientIsNeeded(activity)) {
-      const connectorClient = await this.createConnectorClientWithIdentity(request.user!, activity, headers)
-      this.setConnectorClient(context, connectorClient)
-    }
+      if (!this.isValidChannelActivity(activity)) {
+        return end(StatusCodes.BAD_REQUEST)
+      }
 
-    if (!activity.isAgenticRequest()) {
-      const userTokenClient = await this.createUserTokenClient(request.user!, undefined, undefined, undefined, headers)
-      this.setUserTokenClient(context, userTokenClient)
-    }
+      logger.debug('Received activity: ', activity)
+
+      const context = new TurnContext(this, activity, request.user!)
+      // if Delivery Mode == ExpectReplies, we don't need a connector client.
+      if (this.resolveIfConnectorClientIsNeeded(activity)) {
+        const connectorClient = await this.createConnectorClientWithIdentity(request.user!, activity, headers)
+        this.setConnectorClient(context, connectorClient)
+      }
+
+      if (!isAgentic) {
+        const userTokenClient = await this.createUserTokenClient(request.user!, undefined, undefined, undefined, headers)
+        this.setUserTokenClient(context, userTokenClient)
+      }
+
+      if (
+        activity?.type === ActivityTypes.InvokeResponse ||
+          activity?.type === ActivityTypes.Invoke ||
+          activity?.deliveryMode === DeliveryModes.ExpectReplies
+      ) {
+        await this.runMiddleware(context, logic)
+        const invokeResponse = this.processTurnResults(context)
+        logger.debug('Activity Response (invoke/expect replies): ', invokeResponse)
+        return end(invokeResponse?.status ?? StatusCodes.OK, invokeResponse?.body, true)
+      }
 
-    if (
-      activity?.type === ActivityTypes.InvokeResponse ||
-      activity?.type === ActivityTypes.Invoke ||
-      activity?.deliveryMode === DeliveryModes.ExpectReplies
-    ) {
       await this.runMiddleware(context, logic)
       const invokeResponse = this.processTurnResults(context)
-      logger.debug('Activity Response (invoke/expect replies): ', invokeResponse)
-      return end(invokeResponse?.status ?? StatusCodes.OK, invokeResponse?.body, true)
-    }
-
-    await this.runMiddleware(context, logic)
-    const invokeResponse = this.processTurnResults(context)
-    return end(invokeResponse?.status ?? StatusCodes.OK, invokeResponse?.body)
+      return end(invokeResponse?.status ?? StatusCodes.OK, invokeResponse?.body)
+    })
   }
 
   private isValidChannelActivity (activity: Activity): Boolean {
@@ -412,25 +448,29 @@ export class CloudAdapter extends BaseAdapter {
    * @returns A promise representing the ResourceResponse for the updated activity.
    */
   async updateActivity (context: TurnContext, activity: Activity): Promise<ResourceResponse | void> {
-    if (!context) {
-      throw new TypeError('`context` parameter required')
-    }
+    return trace(AdapterTraceDefinitions.updateActivity, async ({ record }) => {
+      if (!context) {
+        throw new TypeError('`context` parameter required')
+      }
 
-    if (!activity) {
-      throw new TypeError('`activity` parameter required')
-    }
+      if (!activity) {
+        throw new TypeError('`activity` parameter required')
+      }
 
-    if (!activity.serviceUrl || (activity.conversation == null) || !activity.conversation.id || !activity.id) {
-      throw ExceptionHelper.generateException(Error, Errors.InvalidActivityObject)
-    }
+      record({ activity })
 
-    const response = await context.turnState.get(this.ConnectorClientKey).updateActivity(
-      activity.conversation.id,
-      activity.id,
-      activity
-    )
+      if (!activity.serviceUrl || (activity.conversation == null) || !activity.conversation.id || !activity.id) {
+        throw ExceptionHelper.generateException(Error, Errors.InvalidActivityObject)
+      }
 
-    return response.id ? { id: response.id } : undefined
+      const response = await context.turnState.get(this.ConnectorClientKey).updateActivity(
+        activity.conversation.id,
+        activity.id,
+        activity
+      )
+
+      return response.id ? { id: response.id } : undefined
+    })
   }
 
   /**
@@ -440,15 +480,19 @@ export class CloudAdapter extends BaseAdapter {
    * @returns A promise representing the completion of the delete operation.
    */
   async deleteActivity (context: TurnContext, reference: Partial<ConversationReference>): Promise<void> {
-    if (!context) {
-      throw new TypeError('`context` parameter required')
-    }
+    return trace(AdapterTraceDefinitions.deleteActivity, async ({ record }) => {
+      if (!context) {
+        throw new TypeError('`context` parameter required')
+      }
 
-    if (!reference || !reference.serviceUrl || (reference.conversation == null) || !reference.conversation.id || !reference.activityId) {
-      throw ExceptionHelper.generateException(Error, Errors.InvalidConversationReference)
-    }
+      if (!reference || !reference.serviceUrl || (reference.conversation == null) || !reference.conversation.id || !reference.activityId) {
+        throw ExceptionHelper.generateException(Error, Errors.InvalidConversationReference)
+      }
+
+      record({ reference })
 
-    await context.turnState.get(this.ConnectorClientKey).deleteActivity(reference.conversation.id, reference.activityId)
+      await context.turnState.get(this.ConnectorClientKey).deleteActivity(reference.conversation.id, reference.activityId)
+    })
   }
 
   /**
@@ -465,32 +509,43 @@ export class CloudAdapter extends BaseAdapter {
     reference: ConversationReference,
     logic: (revocableContext: TurnContext) => Promise<void>,
     isResponse: Boolean = false): Promise<void> {
-    if (!reference || !reference.serviceUrl || (reference.conversation == null) || !reference.conversation.id) {
-      throw ExceptionHelper.generateException(Error, Errors.ContinueConversationInvalidReference)
-    }
+    return trace(AdapterTraceDefinitions.continueConversation, async ({ record }) => {
+      if (!reference || !reference.serviceUrl || (reference.conversation == null) || !reference.conversation.id) {
+        throw ExceptionHelper.generateException(Error, Errors.ContinueConversationInvalidReference)
+      }
 
-    if (!botAppIdOrIdentity) {
-      throw new TypeError('continueConversation: botAppIdOrIdentity is required')
-    }
-    const botAppId = typeof botAppIdOrIdentity === 'string' ? botAppIdOrIdentity : botAppIdOrIdentity.aud as string
-
-    // Only having the botId will only work against ABS or Agentic.  Proactive to other agents will
-    // not work with just botId.  Use a JwtPayload with property aud (which is botId) and appid populated.
-    const identity =
-        typeof botAppIdOrIdentity !== 'string'
-          ? botAppIdOrIdentity
-          : CloudAdapter.createIdentity(botAppId)
-
-    const context = new TurnContext(this, Activity.getContinuationActivity(reference), identity)
-    const connectorClient = await this.createConnectorClientWithIdentity(identity, context.activity)
-    this.setConnectorClient(context, connectorClient)
-
-    if (!context.activity.isAgenticRequest()) {
-      const userTokenClient = await this.createUserTokenClient(identity)
-      this.setUserTokenClient(context, userTokenClient)
-    }
+      if (!botAppIdOrIdentity) {
+        throw new TypeError('continueConversation: botAppIdOrIdentity is required')
+      }
+      const botAppId = typeof botAppIdOrIdentity === 'string' ? botAppIdOrIdentity : botAppIdOrIdentity.aud as string
 
-    await this.runMiddleware(context, logic)
+      // Only having the botId will only work against ABS or Agentic.  Proactive to other agents will
+      // not work with just botId.  Use a JwtPayload with property aud (which is botId) and appid populated.
+      const identity =
+          typeof botAppIdOrIdentity !== 'string'
+            ? botAppIdOrIdentity
+            : CloudAdapter.createIdentity(botAppId)
+
+      const context = new TurnContext(this, Activity.getContinuationActivity(reference), identity)
+
+      const connectorClient = await this.createConnectorClientWithIdentity(identity, context.activity)
+      this.setConnectorClient(context, connectorClient)
+
+      const isAgentic = context.activity.isAgenticRequest()
+
+      record({
+        botAppId,
+        conversationId: reference.conversation?.id,
+        isAgentic
+      })
+
+      if (!isAgentic) {
+        const userTokenClient = await this.createUserTokenClient(identity)
+        this.setUserTokenClient(context, userTokenClient)
+      }
+
+      await this.runMiddleware(context, logic)
+    })
   }
 
   /**