@microsoft/agents-hosting 1.1.4-g8d884129e7 → 1.2.0-alpha.18.g3c104e426a

package/src/app/teamsAttachmentDownloader.ts

@@ -0,0 +1,110 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { Attachment, Channels } from '@microsoft/agents-activity'
+import { debug } from '@microsoft/agents-activity/logger'
+import { ConnectorClient } from '../connector-client'
+import { InputFile, InputFileDownloader } from './inputFileDownloader'
+import { TurnContext } from '../turnContext'
+import { TurnState } from './turnState'
+import axios, { AxiosInstance } from 'axios'
+import { z } from 'zod'
+
+const logger = debug('agents:teamsAttachmentDownloader')
+
+/**
+ * Downloads attachments from Teams using the bots access token.
+ */
+export class TeamsAttachmentDownloader<TState extends TurnState = TurnState> implements InputFileDownloader<TState> {
+  private _httpClient: AxiosInstance
+  private _stateKey: string
+
+  public constructor (stateKey: string = 'inputFiles') {
+    this._httpClient = axios.create()
+    this._stateKey = stateKey
+  }
+
+  /**
+   * Download any files relative to the current user's input.
+   *
+   * @param {TurnContext} context Context for the current turn of conversation.
+   * @returns {Promise<InputFile[]>} Promise that resolves to an array of downloaded input files.
+   */
+  public async downloadFiles (context: TurnContext): Promise<InputFile[]> {
+    if (context.activity.channelId !== Channels.Msteams && context.activity.channelId !== Channels.M365Copilot) {
+      return Promise.resolve([])
+    }
+    // Filter out HTML attachments
+    const attachments = context.activity.attachments?.filter((a) => a.contentType && !a.contentType.startsWith('text/html'))
+    if (!attachments || attachments.length === 0) {
+      return Promise.resolve([])
+    }
+
+    const connectorClient : ConnectorClient = context.turnState.get<ConnectorClient>(context.adapter.ConnectorClientKey)
+    this._httpClient.defaults.headers = connectorClient.axiosInstance.defaults.headers
+
+    const files: InputFile[] = []
+    for (const attachment of attachments) {
+      const file = await this.downloadFile(attachment)
+      if (file) {
+        files.push(file)
+      }
+    }
+
+    return files
+  }
+
+  /**
+   * @private
+   * @param {Attachment} attachment - Attachment to download.
+   * @returns {Promise<InputFile>} - Promise that resolves to the downloaded input file.
+   */
+  private async downloadFile (attachment: Attachment): Promise<InputFile | undefined> {
+    let inputFile: InputFile | undefined
+
+    if (attachment.contentUrl && attachment.contentUrl.startsWith('https://')) {
+      try {
+        const contentSchema = z.object({ downloadUrl: z.string().url() })
+        const parsed = contentSchema.safeParse(attachment.content)
+        const downloadUrl = parsed.success ? parsed.data.downloadUrl : attachment.contentUrl
+        const response = await this._httpClient.get(downloadUrl, { responseType: 'arraybuffer' })
+
+        const content = Buffer.from(response.data, 'binary')
+        const contentType = response.headers['content-type'] || 'application/octet-stream'
+        inputFile = { content, contentType, contentUrl: attachment.contentUrl }
+      } catch (error) {
+        logger.error(`Failed to download Teams attachment: ${error}`)
+        return undefined
+      }
+    } else {
+      if (!attachment.content) {
+        logger.error('Attachment missing content')
+        return undefined
+      }
+      if (!(attachment.content instanceof ArrayBuffer) && !Buffer.isBuffer(attachment.content)) {
+        logger.error('Attachment content is not ArrayBuffer or Buffer')
+        return undefined
+      }
+      inputFile = {
+        content: Buffer.from(attachment.content as ArrayBuffer),
+        contentType: attachment.contentType,
+        contentUrl: attachment.contentUrl
+      }
+    }
+    return inputFile
+  }
+
+  /**
+   * Downloads files from the attachments in the current turn context and stores them in state.
+   *
+   * @param context The turn context containing the activity with attachments.
+   * @param state The turn state to store the files in.
+   * @returns A promise that resolves when the downloaded files are stored.
+   */
+  public async downloadAndStoreFiles (context: TurnContext, state: TState): Promise<void> {
+    const files = await this.downloadFiles(context)
+    state.setValue(this._stateKey, files)
+  }
+}

package/src/auth/authProvider.ts

@@ -9,13 +9,20 @@ import { AuthConfiguration } from './authConfiguration'
  * Represents an authentication provider.
  */
 export interface AuthProvider {
+  /**
+   * The AuthConfiguration used for token acquisition.
+   */
+  connectionSettings?: AuthConfiguration
+
   /**
    * Gets an access token for the specified authentication configuration and scope.
    * @param authConfig - The authentication configuration.
    * @param scope - The scope for which the access token is requested.
    * @returns A promise that resolves to the access token.
    */
-  getAccessToken: (authConfig: AuthConfiguration, scope: string) => Promise<string>
+  getAccessToken (authConfig: AuthConfiguration, scope: string): Promise<string>
+  getAccessToken (scope: string): Promise<string>
+  getAccessToken (authConfigOrScope: AuthConfiguration | string, scope?: string): Promise<string>
 
   /**
    * Get an access token for the agentic application

package/src/auth/msalTokenProvider.ts

@@ -211,6 +211,10 @@ export class MsalTokenProvider implements AuthProvider {
       data.client_secret = this.connectionSettings.clientSecret
     }
 
+    if (data.grant_type !== 'user_fic') {
+      data.client_info = '2'
+    }
+
     const token = await axios.post(
       url,
       data,
@@ -234,7 +238,7 @@ export class MsalTokenProvider implements AuthProvider {
     const agentToken = await this.getAgenticApplicationToken(tenantId, agentAppInstanceId)
     const instanceToken = await this.getAgenticInstanceToken(tenantId, agentAppInstanceId)
 
-    const token = await this.acquireTokenByForAgenticScenarios(tenantId, agentToken, instanceToken, scopes, {
+    const token = await this.acquireTokenByForAgenticScenarios(tenantId, agentAppInstanceId, agentToken, scopes, {
       user_id: agenticUserId,
       user_federated_identity_credential: instanceToken,
       grant_type: 'user_fic',
@@ -252,11 +256,8 @@ export class MsalTokenProvider implements AuthProvider {
       throw new Error('Connection settings must be provided when calling getAgenticApplicationToken')
     }
     logger.debug('Getting agentic application token')
-    let clientAssertion
-    if (this.connectionSettings.FICClientId) {
-      clientAssertion = await this.fetchExternalToken(this.connectionSettings.FICClientId as string)
-    }
-    const token = await this.acquireTokenByForAgenticScenarios(tenantId, this.connectionSettings.clientId, clientAssertion, ['api://AzureAdTokenExchange/.default'], {      grant_type: 'client_credentials',
+    const token = await this.acquireTokenByForAgenticScenarios(tenantId, this.connectionSettings.clientId, undefined, ['api://AzureAdTokenExchange/.default'], {
+      grant_type: 'client_credentials',
       fmi_path: agentAppInstanceId,
     })
 

package/src/cloudAdapter.ts

@@ -13,19 +13,21 @@ import { AuthConfiguration, getAuthConfigWithDefaults } from './auth/authConfigu
 import { AuthProvider } from './auth/authProvider'
 import { ApxProductionScope } from './auth/authConstants'
 import { MsalConnectionManager } from './auth/msalConnectionManager'
-import { Activity, ActivityEventNames, ActivityTypes, Channels, ConversationReference, DeliveryModes, ConversationParameters, RoleTypes } from '@microsoft/agents-activity'
+import { Activity, ActivityEventNames, ActivityTypes, Channels, ConversationReference, DeliveryModes, ConversationParameters, RoleTypes, ExceptionHelper } from '@microsoft/agents-activity'
+import { Errors } from './errorHelper'
 import { ResourceResponse } from './connector-client/resourceResponse'
 import * as uuid from 'uuid'
 import { debug } from '@microsoft/agents-activity/logger'
 import { StatusCodes } from './statusCodes'
 import { InvokeResponse } from './invoke/invokeResponse'
-import { AttachmentInfo } from './connector-client/attachmentInfo'
 import { AttachmentData } from './connector-client/attachmentData'
+import { AttachmentInfo } from './connector-client/attachmentInfo'
 import { normalizeIncomingActivity } from './activityWireCompat'
 import { UserTokenClient } from './oauth'
 import { HeaderPropagation, HeaderPropagationCollection, HeaderPropagationDefinition } from './headerPropagation'
 import { JwtPayload } from 'jsonwebtoken'
 import { getTokenServiceEndpoint } from './oauth/customUserTokenAPI'
+import { Connections } from './auth/connections'
 const logger = debug('agents:cloud-adapter')
 
 /**
@@ -41,12 +43,13 @@ export class CloudAdapter extends BaseAdapter {
   /**
    * Client for connecting to the Azure Bot Service
    */
-  connectionManager: MsalConnectionManager
+  connectionManager: Connections
 
   /**
    * Creates an instance of CloudAdapter.
-   * @param authConfig - The authentication configuration for securing communications
-   * @param authProvider - No longer used
+   * @param authConfig - The authentication configuration for securing communications.
+   * @param authProvider - No longer used.
+   * @param userTokenClient - No longer used.
    */
   constructor (authConfig?: AuthConfiguration, authProvider?: AuthProvider, userTokenClient?: UserTokenClient) {
     super()
@@ -84,10 +87,11 @@ export class CloudAdapter extends BaseAdapter {
   /**
    * Creates a connector client for a specific service URL and scope.
    *
-   * @param serviceUrl - The URL of the service to connect to
-   * @param scope - The authentication scope to use
-   * @param headers - Optional headers to propagate in the request
-   * @returns A promise that resolves to a ConnectorClient instance
+   * @param serviceUrl - The URL of the service to connect to.
+   * @param scope - The authentication scope to use.
+   * @param identity - The identity used to select the token provider.
+   * @param headers - Optional headers to propagate in the request.
+   * @returns A promise that resolves to a ConnectorClient instance.
    * @protected
    */
   protected async createConnectorClient (
@@ -107,6 +111,15 @@ export class CloudAdapter extends BaseAdapter {
     )
   }
 
+  /**
+   * Creates a connector client for a specific identity and activity.
+   *
+   * @param identity - The identity used to select the token provider.
+   * @param activity - The activity used to select the token provider.
+   * @param headers - Optional headers to propagate in the request.
+   * @returns A promise that resolves to a ConnectorClient instance.
+   * @protected
+   */
   protected async createConnectorClientWithIdentity (
     identity: JwtPayload,
     activity: Activity,
@@ -161,6 +174,11 @@ export class CloudAdapter extends BaseAdapter {
     return connectorClient
   }
 
+  /**
+   * Creates the JwtPayload object with the provided appId.
+   * @param appId The bot's appId.
+   * @returns The JwtPayload object containing the appId as aud.
+   */
   static createIdentity (appId: string) : JwtPayload {
     return {
       aud: appId
@@ -170,7 +188,7 @@ export class CloudAdapter extends BaseAdapter {
   /**
    * Sets the connector client on the turn context.
    *
-   * @param context - The current turn context
+   * @param context - The current turn context.
    * @protected
    */
   protected setConnectorClient (
@@ -183,10 +201,12 @@ export class CloudAdapter extends BaseAdapter {
   /**
    * Creates a user token client for a specific service URL and scope.
    *
-   * @param serviceUrl - The URL of the service to connect to
-   * @param scope - The authentication scope to use
+   * @param identity - The identity used to select the token provider.
+   * @param tokenServiceEndpoint - The endpoint to connect to.
+   * @param scope - The authentication scope to use.
+   * @param audience - No longer used.
    * @param headers - Optional headers to propagate in the request
-   * @returns A promise that resolves to a ConnectorClient instance
+   * @returns A promise that resolves to a UserTokenClient instance.
    * @protected
    */
   protected async createUserTokenClient (
@@ -220,7 +240,7 @@ export class CloudAdapter extends BaseAdapter {
   /**
    * Sets the user token client on the turn context.
    *
-   * @param context - The current turn context
+   * @param context - The current turn context.
    * @protected
    */
   protected setUserTokenClient (
@@ -235,6 +255,7 @@ export class CloudAdapter extends BaseAdapter {
    * Creates a TurnContext for the given activity and logic.
    * @param activity - The activity to process.
    * @param logic - The logic to execute.
+   * @param identity - The identity used for the new context.
    * @returns The created TurnContext.
    */
   createTurnContext (activity: Activity, logic: AgentHandler, identity?: JwtPayload): TurnContext {
@@ -249,15 +270,15 @@ export class CloudAdapter extends BaseAdapter {
    */
   async sendActivities (context: TurnContext, activities: Activity[]): Promise<ResourceResponse[]> {
     if (!context) {
-      throw new TypeError('`context` parameter required')
+      throw ExceptionHelper.generateException(TypeError, Errors.ContextParameterRequired)
     }
 
     if (!activities) {
-      throw new TypeError('`activities` parameter required')
+      throw ExceptionHelper.generateException(TypeError, Errors.ActivitiesParameterRequired)
     }
 
     if (activities.length === 0) {
-      throw new Error('Expecting one or more activities, but the array was empty.')
+      throw ExceptionHelper.generateException(Error, Errors.EmptyActivitiesArray)
     }
 
     const responses: ResourceResponse[] = []
@@ -271,7 +292,7 @@ export class CloudAdapter extends BaseAdapter {
         // no-op
       } else {
         if (!activity.serviceUrl || (activity.conversation == null) || !activity.conversation.id) {
-          throw new Error('Invalid activity object')
+          throw ExceptionHelper.generateException(Error, Errors.InvalidActivityObject)
         }
 
         if (activity.replyToId) {
@@ -395,7 +416,7 @@ export class CloudAdapter extends BaseAdapter {
     }
 
     if (!activity.serviceUrl || (activity.conversation == null) || !activity.conversation.id || !activity.id) {
-      throw new Error('Invalid activity object')
+      throw ExceptionHelper.generateException(Error, Errors.InvalidActivityObject)
     }
 
     const response = await context.turnState.get(this.ConnectorClientKey).updateActivity(
@@ -419,7 +440,7 @@ export class CloudAdapter extends BaseAdapter {
     }
 
     if (!reference || !reference.serviceUrl || (reference.conversation == null) || !reference.conversation.id || !reference.activityId) {
-      throw new Error('Invalid conversation reference object')
+      throw ExceptionHelper.generateException(Error, Errors.InvalidConversationReference)
     }
 
     await context.turnState.get(this.ConnectorClientKey).deleteActivity(reference.conversation.id, reference.activityId)
@@ -427,8 +448,11 @@ export class CloudAdapter extends BaseAdapter {
 
   /**
    * Continues a conversation.
+   * @param botAppIdOrIdentity - The bot identity to use when continuing the conversation. This can be either:
+   * a string containing the bot's App ID (botId) or a JwtPayload object containing identity claims (must include aud).
    * @param reference - The conversation reference to continue.
    * @param logic - The logic to execute.
+   * @param isResponse - No longer used.
    * @returns A promise representing the completion of the continue operation.
    */
   async continueConversation (
@@ -437,7 +461,7 @@ export class CloudAdapter extends BaseAdapter {
     logic: (revocableContext: TurnContext) => Promise<void>,
     isResponse: Boolean = false): Promise<void> {
     if (!reference || !reference.serviceUrl || (reference.conversation == null) || !reference.conversation.id) {
-      throw new Error('continueConversation: Invalid conversation reference object')
+      throw ExceptionHelper.generateException(Error, Errors.ContinueConversationInvalidReference)
     }
 
     if (!botAppIdOrIdentity) {
@@ -572,21 +596,22 @@ export class CloudAdapter extends BaseAdapter {
   /**
    * @deprecated This function will not be supported in future versions.  Use TurnContext.turnState.get<ConnectorClient>(CloudAdapter.ConnectorClientKey).
    * Uploads an attachment.
+   * @param context - The context for the turn.
    * @param conversationId - The conversation ID.
    * @param attachmentData - The attachment data.
    * @returns A promise representing the ResourceResponse for the uploaded attachment.
    */
   async uploadAttachment (context: TurnContext, conversationId: string, attachmentData: AttachmentData): Promise<ResourceResponse> {
     if (context === undefined) {
-      throw new Error('context is required')
+      throw ExceptionHelper.generateException(Error, Errors.ContextRequired)
     }
 
     if (conversationId === undefined) {
-      throw new Error('conversationId is required')
+      throw ExceptionHelper.generateException(Error, Errors.ConversationIdRequired)
     }
 
     if (attachmentData === undefined) {
-      throw new Error('attachmentData is required')
+      throw ExceptionHelper.generateException(Error, Errors.AttachmentDataRequired)
     }
 
     return await context.turnState.get<ConnectorClient>(this.ConnectorClientKey).uploadAttachment(conversationId, attachmentData)
@@ -595,16 +620,17 @@ export class CloudAdapter extends BaseAdapter {
   /**
    * @deprecated This function will not be supported in future versions.  Use TurnContext.turnState.get<ConnectorClient>(CloudAdapter.ConnectorClientKey).
    * Gets attachment information.
+   * @param context - The context for the turn.
    * @param attachmentId - The attachment ID.
    * @returns A promise representing the AttachmentInfo for the requested attachment.
    */
   async getAttachmentInfo (context: TurnContext, attachmentId: string): Promise<AttachmentInfo> {
     if (context === undefined) {
-      throw new Error('context is required')
+      throw ExceptionHelper.generateException(Error, Errors.ContextRequired)
     }
 
     if (attachmentId === undefined) {
-      throw new Error('attachmentId is required')
+      throw ExceptionHelper.generateException(Error, Errors.AttachmentIdRequired)
     }
 
     return await context.turnState.get<ConnectorClient>(this.ConnectorClientKey).getAttachmentInfo(attachmentId)
@@ -613,21 +639,22 @@ export class CloudAdapter extends BaseAdapter {
   /**
    * @deprecated This function will not be supported in future versions.  Use TurnContext.turnState.get<ConnectorClient>(CloudAdapter.ConnectorClientKey).
    * Gets an attachment.
+   * @param context - The context for the turn.
    * @param attachmentId - The attachment ID.
    * @param viewId - The view ID.
    * @returns A promise representing the NodeJS.ReadableStream for the requested attachment.
    */
   async getAttachment (context: TurnContext, attachmentId: string, viewId: string): Promise<NodeJS.ReadableStream> {
     if (context === undefined) {
-      throw new Error('context is required')
+      throw ExceptionHelper.generateException(Error, Errors.ContextRequired)
     }
 
     if (attachmentId === undefined) {
-      throw new Error('attachmentId is required')
+      throw ExceptionHelper.generateException(Error, Errors.AttachmentIdRequired)
     }
 
     if (viewId === undefined) {
-      throw new Error('viewId is required')
+      throw ExceptionHelper.generateException(Error, Errors.ViewIdRequired)
     }
 
     return await context.turnState.get<ConnectorClient>(this.ConnectorClientKey).getAttachment(attachmentId, viewId)

package/src/connector-client/connectorClient.ts

@@ -3,7 +3,8 @@ import axios, { AxiosInstance, AxiosRequestConfig, AxiosResponse } from 'axios'
 import { AuthConfiguration } from '../auth/authConfiguration'
 import { AuthProvider } from '../auth/authProvider'
 import { debug } from '@microsoft/agents-activity/logger'
-import { Activity, ChannelAccount, ConversationParameters, RoleTypes, Channels } from '@microsoft/agents-activity'
+import { Activity, ChannelAccount, ConversationParameters, RoleTypes, Channels, ExceptionHelper } from '@microsoft/agents-activity'
+import { Errors } from '../errorHelper'
 import { ConversationsResult } from './conversationsResult'
 import { ConversationResourceResponse } from './conversationResourceResponse'
 import { ResourceResponse } from './resourceResponse'
@@ -143,7 +144,7 @@ export class ConnectorClient {
 
   public async getConversationMember (userId: string, conversationId: string): Promise<ChannelAccount> {
     if (!userId || !conversationId) {
-      throw new Error('userId and conversationId are required')
+      throw ExceptionHelper.generateException(Error, Errors.UserIdAndConversationIdRequired)
     }
     const config: AxiosRequestConfig = {
       method: 'get',
@@ -192,7 +193,7 @@ export class ConnectorClient {
   ): Promise<ResourceResponse> {
     logger.debug(`Replying to activity: ${activityId} in conversation: ${conversationId}`)
     if (!conversationId || !activityId) {
-      throw new Error('conversationId and activityId are required')
+      throw ExceptionHelper.generateException(Error, Errors.ConversationIdAndActivityIdRequired)
     }
 
     const trimmedConversationId: string = this.conditionallyTruncateConversationId(conversationId, body)
@@ -242,7 +243,7 @@ export class ConnectorClient {
   ): Promise<ResourceResponse> {
     logger.debug(`Send to conversation: ${conversationId} activity: ${body.id}`)
     if (!conversationId) {
-      throw new Error('conversationId is required')
+      throw ExceptionHelper.generateException(Error, Errors.ConversationIdRequired)
     }
 
     const trimmedConversationId: string = this.conditionallyTruncateConversationId(conversationId, body)
@@ -272,7 +273,7 @@ export class ConnectorClient {
     body: Activity
   ): Promise<ResourceResponse> {
     if (!conversationId || !activityId) {
-      throw new Error('conversationId and activityId are required')
+      throw ExceptionHelper.generateException(Error, Errors.ConversationIdAndActivityIdRequired)
     }
     const config: AxiosRequestConfig = {
       method: 'put',
@@ -297,7 +298,7 @@ export class ConnectorClient {
     activityId: string
   ): Promise<void> {
     if (!conversationId || !activityId) {
-      throw new Error('conversationId and activityId are required')
+      throw ExceptionHelper.generateException(Error, Errors.ConversationIdAndActivityIdRequired)
     }
     const config: AxiosRequestConfig = {
       method: 'delete',
@@ -321,7 +322,7 @@ export class ConnectorClient {
     body: AttachmentData
   ): Promise<ResourceResponse> {
     if (conversationId === undefined) {
-      throw new Error('conversationId is required')
+      throw ExceptionHelper.generateException(Error, Errors.ConversationIdRequired)
     }
     const config: AxiosRequestConfig = {
       method: 'post',
@@ -344,7 +345,7 @@ export class ConnectorClient {
     attachmentId: string
   ): Promise<AttachmentInfo> {
     if (attachmentId === undefined) {
-      throw new Error('attachmentId is required')
+      throw ExceptionHelper.generateException(Error, Errors.AttachmentIdRequired)
     }
     const config: AxiosRequestConfig = {
       method: 'get',
@@ -368,10 +369,10 @@ export class ConnectorClient {
     viewId: string
   ): Promise<NodeJS.ReadableStream> {
     if (attachmentId === undefined) {
-      throw new Error('attachmentId is required')
+      throw ExceptionHelper.generateException(Error, Errors.AttachmentIdRequired)
     }
     if (viewId === undefined) {
-      throw new Error('viewId is required')
+      throw ExceptionHelper.generateException(Error, Errors.ViewIdRequired)
     }
     const config: AxiosRequestConfig = {
       method: 'get',