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

package/src/connector-client/connectorClient.ts

@@ -2,7 +2,7 @@
 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 { debug } from '@microsoft/agents-telemetry'
 import { Activity, ChannelAccount, ConversationParameters, RoleTypes, Channels, ExceptionHelper } from '@microsoft/agents-activity'
 import { Errors } from '../errorHelper'
 import { ConversationsResult } from './conversationsResult'
@@ -13,6 +13,9 @@ import { AttachmentData } from './attachmentData'
 import { normalizeOutgoingActivity } from '../activityWireCompat'
 import { getProductInfo } from '../getProductInfo'
 import { HeaderPropagation, HeaderPropagationCollection } from '../headerPropagation'
+import { trace } from '@microsoft/agents-telemetry'
+import { ConnectorClientTraceDefinitions } from '../observability'
+
 const logger = debug('agents:connector-client')
 
 export { getProductInfo }
@@ -139,28 +142,34 @@ export class ConnectorClient {
    * @returns A list of conversations.
    */
   public async getConversations (continuationToken?: string): Promise<ConversationsResult> {
-    const config: AxiosRequestConfig = {
-      method: 'get',
-      url: '/v3/conversations',
-      params: continuationToken ? { continuationToken } : undefined
-    }
-    const response = await this._axiosInstance(config)
-    return response.data
+    return trace(ConnectorClientTraceDefinitions.getConversations, async ({ record }) => {
+      const config: AxiosRequestConfig = {
+        method: 'get',
+        url: '/v3/conversations',
+        params: continuationToken ? { continuationToken } : undefined
+      }
+      const response = await this._axiosInstance(config)
+      record({ httpStatusCode: response.status?.toString() })
+      return response.data
+    })
   }
 
   public async getConversationMember (userId: string, conversationId: string): Promise<ChannelAccount> {
-    if (!userId || !conversationId) {
-      throw ExceptionHelper.generateException(Error, Errors.UserIdAndConversationIdRequired)
-    }
-    const config: AxiosRequestConfig = {
-      method: 'get',
-      url: `v3/conversations/${conversationId}/members/${userId}`,
-      headers: {
-        'Content-Type': 'application/json'
+    return trace(ConnectorClientTraceDefinitions.getConversationMember, async ({ record }) => {
+      if (!userId || !conversationId) {
+        throw ExceptionHelper.generateException(Error, Errors.UserIdAndConversationIdRequired)
       }
-    }
-    const response = await this._axiosInstance(config)
-    return response.data
+      const config: AxiosRequestConfig = {
+        method: 'get',
+        url: `v3/conversations/${conversationId}/members/${userId}`,
+        headers: {
+          'Content-Type': 'application/json'
+        }
+      }
+      const response = await this._axiosInstance(config)
+      record({ httpStatusCode: response.status?.toString() })
+      return response.data
+    })
   }
 
   /**
@@ -169,20 +178,23 @@ export class ConnectorClient {
    * @returns The conversation resource response.
    */
   public async createConversation (body: ConversationParameters): Promise<ConversationResourceResponse> {
-    const payload = {
-      ...body,
-      activity: normalizeOutgoingActivity(body.activity)
-    }
-    const config: AxiosRequestConfig = {
-      method: 'post',
-      url: '/v3/conversations',
-      headers: {
-        'Content-Type': 'application/json'
-      },
-      data: payload
-    }
-    const response: AxiosResponse = await this._axiosInstance(config)
-    return response.data
+    return trace(ConnectorClientTraceDefinitions.createConversation, async ({ record }) => {
+      const payload = {
+        ...body,
+        activity: normalizeOutgoingActivity(body.activity)
+      }
+      const config: AxiosRequestConfig = {
+        method: 'post',
+        url: '/v3/conversations',
+        headers: {
+          'Content-Type': 'application/json'
+        },
+        data: payload
+      }
+      const response: AxiosResponse = await this._axiosInstance(config)
+      record({ httpStatusCode: response.status?.toString() })
+      return response.data
+    })
   }
 
   /**
@@ -197,24 +209,29 @@ export class ConnectorClient {
     activityId: string,
     body: Activity
   ): Promise<ResourceResponse> {
-    logger.debug(`Replying to activity: ${activityId} in conversation: ${conversationId}`)
-    if (!conversationId || !activityId) {
-      throw ExceptionHelper.generateException(Error, Errors.ConversationIdAndActivityIdRequired)
-    }
+    return trace(ConnectorClientTraceDefinitions.replyToActivity, async ({ record }) => {
+      logger.debug(`Replying to activity: ${activityId} in conversation: ${conversationId}`)
+      record({ conversationId, activityId })
 
-    const trimmedConversationId: string = this.conditionallyTruncateConversationId(conversationId, body)
+      if (!conversationId || !activityId) {
+        throw ExceptionHelper.generateException(Error, Errors.ConversationIdAndActivityIdRequired)
+      }
 
-    const config: AxiosRequestConfig = {
-      method: 'post',
-      url: `v3/conversations/${trimmedConversationId}/activities/${encodeURIComponent(activityId)}`,
-      headers: {
-        'Content-Type': 'application/json'
-      },
-      data: normalizeOutgoingActivity(body)
-    }
-    const response = await this._axiosInstance(config)
-    logger.info('Reply to conversation/activity: ', response.data.id!, activityId)
-    return response.data
+      const trimmedConversationId: string = this.conditionallyTruncateConversationId(conversationId, body)
+
+      const config: AxiosRequestConfig = {
+        method: 'post',
+        url: `v3/conversations/${trimmedConversationId}/activities/${encodeURIComponent(activityId)}`,
+        headers: {
+          'Content-Type': 'application/json'
+        },
+        data: normalizeOutgoingActivity(body)
+      }
+      const response = await this._axiosInstance(config)
+      record({ httpStatusCode: response.status?.toString() })
+      logger.info('Reply to conversation/activity: ', response.data.id!, activityId)
+      return response.data
+    })
   }
 
   /**
@@ -247,23 +264,28 @@ export class ConnectorClient {
     conversationId: string,
     body: Activity
   ): Promise<ResourceResponse> {
-    logger.debug(`Send to conversation: ${conversationId} activity: ${body.id}`)
-    if (!conversationId) {
-      throw ExceptionHelper.generateException(Error, Errors.ConversationIdRequired)
-    }
+    return trace(ConnectorClientTraceDefinitions.sendToConversation, async ({ record }) => {
+      logger.debug(`Send to conversation: ${conversationId} activity: ${body.id}`)
+      if (!conversationId) {
+        throw ExceptionHelper.generateException(Error, Errors.ConversationIdRequired)
+      }
 
-    const trimmedConversationId: string = this.conditionallyTruncateConversationId(conversationId, body)
+      record({ conversationId })
 
-    const config: AxiosRequestConfig = {
-      method: 'post',
-      url: `v3/conversations/${trimmedConversationId}/activities`,
-      headers: {
-        'Content-Type': 'application/json'
-      },
-      data: normalizeOutgoingActivity(body)
-    }
-    const response = await this._axiosInstance(config)
-    return response.data
+      const trimmedConversationId: string = this.conditionallyTruncateConversationId(conversationId, body)
+
+      const config: AxiosRequestConfig = {
+        method: 'post',
+        url: `v3/conversations/${trimmedConversationId}/activities`,
+        headers: {
+          'Content-Type': 'application/json'
+        },
+        data: normalizeOutgoingActivity(body)
+      }
+      const response = await this._axiosInstance(config)
+      record({ httpStatusCode: response.status?.toString() })
+      return response.data
+    })
   }
 
   /**
@@ -278,19 +300,23 @@ export class ConnectorClient {
     activityId: string,
     body: Activity
   ): Promise<ResourceResponse> {
-    if (!conversationId || !activityId) {
-      throw ExceptionHelper.generateException(Error, Errors.ConversationIdAndActivityIdRequired)
-    }
-    const config: AxiosRequestConfig = {
-      method: 'put',
-      url: `v3/conversations/${conversationId}/activities/${activityId}`,
-      headers: {
-        'Content-Type': 'application/json'
-      },
-      data: normalizeOutgoingActivity(body)
-    }
-    const response = await this._axiosInstance(config)
-    return response.data
+    return trace(ConnectorClientTraceDefinitions.updateActivity, async ({ record }) => {
+      if (!conversationId || !activityId) {
+        throw ExceptionHelper.generateException(Error, Errors.ConversationIdAndActivityIdRequired)
+      }
+      record({ conversationId, activityId })
+      const config: AxiosRequestConfig = {
+        method: 'put',
+        url: `v3/conversations/${conversationId}/activities/${activityId}`,
+        headers: {
+          'Content-Type': 'application/json'
+        },
+        data: normalizeOutgoingActivity(body)
+      }
+      const response = await this._axiosInstance(config)
+      record({ httpStatusCode: response.status?.toString() })
+      return response.data
+    })
   }
 
   /**
@@ -303,18 +329,23 @@ export class ConnectorClient {
     conversationId: string,
     activityId: string
   ): Promise<void> {
-    if (!conversationId || !activityId) {
-      throw ExceptionHelper.generateException(Error, Errors.ConversationIdAndActivityIdRequired)
-    }
-    const config: AxiosRequestConfig = {
-      method: 'delete',
-      url: `v3/conversations/${conversationId}/activities/${activityId}`,
-      headers: {
-        'Content-Type': 'application/json'
+    return trace(ConnectorClientTraceDefinitions.deleteActivity, async ({ record }) => {
+      record({ conversationId, activityId })
+
+      if (!conversationId || !activityId) {
+        throw ExceptionHelper.generateException(Error, Errors.ConversationIdAndActivityIdRequired)
       }
-    }
-    const response = await this._axiosInstance(config)
-    return response.data
+      const config: AxiosRequestConfig = {
+        method: 'delete',
+        url: `v3/conversations/${conversationId}/activities/${activityId}`,
+        headers: {
+          'Content-Type': 'application/json'
+        }
+      }
+      const response = await this._axiosInstance(config)
+      record({ httpStatusCode: response.status?.toString() })
+      return response.data
+    })
   }
 
   /**
@@ -327,19 +358,23 @@ export class ConnectorClient {
     conversationId: string,
     body: AttachmentData
   ): Promise<ResourceResponse> {
-    if (conversationId === undefined) {
-      throw ExceptionHelper.generateException(Error, Errors.ConversationIdRequired)
-    }
-    const config: AxiosRequestConfig = {
-      method: 'post',
-      url: `v3/conversations/${conversationId}/attachments`,
-      headers: {
-        'Content-Type': 'application/json'
-      },
-      data: body
-    }
-    const response = await this._axiosInstance(config)
-    return response.data
+    return trace(ConnectorClientTraceDefinitions.uploadAttachment, async ({ record }) => {
+      record({ conversationId })
+      if (conversationId === undefined) {
+        throw ExceptionHelper.generateException(Error, Errors.ConversationIdRequired)
+      }
+      const config: AxiosRequestConfig = {
+        method: 'post',
+        url: `v3/conversations/${conversationId}/attachments`,
+        headers: {
+          'Content-Type': 'application/json'
+        },
+        data: body
+      }
+      const response = await this._axiosInstance(config)
+      record({ httpStatusCode: response.status?.toString() })
+      return response.data
+    })
   }
 
   /**
@@ -350,18 +385,22 @@ export class ConnectorClient {
   public async getAttachmentInfo (
     attachmentId: string
   ): Promise<AttachmentInfo> {
-    if (attachmentId === undefined) {
-      throw ExceptionHelper.generateException(Error, Errors.AttachmentIdRequired)
-    }
-    const config: AxiosRequestConfig = {
-      method: 'get',
-      url: `v3/attachments/${attachmentId}`,
-      headers: {
-        'Content-Type': 'application/json'
+    return trace(ConnectorClientTraceDefinitions.getAttachmentInfo, async ({ record }) => {
+      record({ attachmentId })
+      if (attachmentId === undefined) {
+        throw ExceptionHelper.generateException(Error, Errors.AttachmentIdRequired)
       }
-    }
-    const response = await this._axiosInstance(config)
-    return response.data
+      const config: AxiosRequestConfig = {
+        method: 'get',
+        url: `v3/attachments/${attachmentId}`,
+        headers: {
+          'Content-Type': 'application/json'
+        }
+      }
+      const response = await this._axiosInstance(config)
+      record({ httpStatusCode: response.status?.toString() })
+      return response.data
+    })
   }
 
   /**
@@ -374,20 +413,24 @@ export class ConnectorClient {
     attachmentId: string,
     viewId: string
   ): Promise<NodeJS.ReadableStream> {
-    if (attachmentId === undefined) {
-      throw ExceptionHelper.generateException(Error, Errors.AttachmentIdRequired)
-    }
-    if (viewId === undefined) {
-      throw ExceptionHelper.generateException(Error, Errors.ViewIdRequired)
-    }
-    const config: AxiosRequestConfig = {
-      method: 'get',
-      url: `v3/attachments/${attachmentId}/views/${viewId}`,
-      headers: {
-        'Content-Type': 'application/json'
+    return trace(ConnectorClientTraceDefinitions.getAttachment, async ({ record }) => {
+      record({ attachmentId, viewId })
+      if (attachmentId === undefined) {
+        throw ExceptionHelper.generateException(Error, Errors.AttachmentIdRequired)
       }
-    }
-    const response = await this._axiosInstance(config)
-    return response.data
+      if (viewId === undefined) {
+        throw ExceptionHelper.generateException(Error, Errors.ViewIdRequired)
+      }
+      const config: AxiosRequestConfig = {
+        method: 'get',
+        url: `v3/attachments/${attachmentId}/views/${viewId}`,
+        headers: {
+          'Content-Type': 'application/json'
+        }
+      }
+      const response = await this._axiosInstance(config)
+      record({ httpStatusCode: response.status?.toString() })
+      return response.data
+    })
   }
 }

package/src/errorHelper.ts

@@ -500,6 +500,22 @@ export const Errors: { [key: string]: AgentErrorDefinition } = {
     description: 'Storage is required for Authorization. Ensure that a storage provider is configured in the app options.'
   },
 
+  /**
+     * Error thrown when the azureBotOAuthConnectionName option is missing for AzureBot authorization.
+     */
+  AzureBotOAuthConnectionNameRequired: {
+    code: -120591,
+    description: "The 'azureBotOAuthConnectionName' option is not available in the app options. Ensure that the app is properly configured."
+  },
+
+  /**
+     * Error thrown when the AzureBot connection token is not exchangeable for an OBO flow.
+     */
+  AzureBotConnectionTokenNotExchangeable: {
+    code: -120592,
+    description: "The current token for the '{connectionName}' AzureBot connection is not exchangeable for an on-behalf-of flow. Ensure the base token audience is for the bot/resource app, such as an App ID URI like 'api://...' or otherwise includes the app's client id."
+  },
+
   // ============================================================================
   // Agent and Client Errors (-120600 to -120630)
   // ============================================================================
@@ -660,6 +676,114 @@ export const Errors: { [key: string]: AgentErrorDefinition } = {
     description: 'Invalid action value: {error}'
   },
 
+  // ============================================================================
+  // Proactive Messaging Errors (-120740 to -120799)
+  // ============================================================================
+
+  /**
+   * Error thrown when Application.proactive is accessed but no storage was configured.
+   */
+  ProactivePropertyUnavailable: {
+    code: -120740,
+    description: 'The Application.proactive property is unavailable because no storage was configured. Set options.storage or options.proactive.storage.'
+  },
+
+  /**
+   * Error thrown when a proactive storage operation is attempted without a storage backend.
+   */
+  ProactiveStorageRequired: {
+    code: -120741,
+    description: 'This proactive operation requires a storage backend. Set options.storage or options.proactive.storage.'
+  },
+
+  /**
+   * Error thrown when a conversation is not found in proactive storage.
+   */
+  ProactiveConversationNotFound: {
+    code: -120742,
+    description: "Conversation '{conversationId}' was not found in proactive storage."
+  },
+
+  /**
+   * Error thrown when sendActivity does not receive a ResourceResponse from the adapter.
+   */
+  ProactiveSendActivityNoResponse: {
+    code: -120743,
+    description: 'sendActivity: adapter did not return a ResourceResponse.'
+  },
+
+  /**
+   * Error thrown when not all token handlers have a signed-in user for proactive continuation.
+   */
+  ProactiveNotAllTokensAcquired: {
+    code: -120744,
+    description: 'Not all token handlers have a signed-in user.'
+  },
+
+  /**
+   * Error thrown when createConversation is called without any members.
+   */
+  ProactiveMembersRequired: {
+    code: -120745,
+    description: 'createConversation: at least one member must be specified in parameters.members.'
+  },
+
+  /**
+   * Error thrown when the adapter passed to createConversation does not support createConversationAsync.
+   */
+  ProactiveCloudAdapterRequired: {
+    code: -120746,
+    description: 'createConversation requires a CloudAdapter. The provided adapter does not implement createConversationAsync().'
+  },
+
+  /**
+   * Error thrown when createConversationAsync completes without invoking its callback.
+   */
+  ProactiveCallbackNotInvoked: {
+    code: -120747,
+    description: 'createConversation: createConversationAsync completed without invoking its callback.'
+  },
+
+  /**
+   * Error thrown when a Conversation reference is missing conversation.id.
+   */
+  ConversationInvalidId: {
+    code: -120748,
+    description: 'Conversation is invalid: reference.conversation.id is required.'
+  },
+
+  /**
+   * Error thrown when a Conversation reference is missing serviceUrl.
+   */
+  ConversationInvalidServiceUrl: {
+    code: -120749,
+    description: 'Conversation is invalid: reference.serviceUrl is required.'
+  },
+
+  /**
+   * Error thrown when a Conversation reference is missing claims.aud.
+   */
+  ConversationInvalidAud: {
+    code: -120750,
+    description: 'Conversation is invalid: claims.aud (agent client ID) is required.'
+  },
+
+  /**
+   * Error thrown when CreateConversationOptionsBuilder.build() is called without any members.
+   */
+  CreateConversationBuilderMembersRequired: {
+    code: -120751,
+    description: 'CreateConversationOptionsBuilder: at least one members entry must be added via withUser().'
+  },
+
+  /**
+   * Error thrown when a proactive operation that requires TurnState load/save is called without app storage.
+   */
+  ProactiveAppStorageRequired: {
+    code: -120752,
+    description: 'This proactive operation requires app storage to load and save TurnState. Set options.storage on AgentApplication.'
+  },
+
   // ============================================================================
   // General Errors (-120990)
   // ============================================================================

package/src/middlewareSet.ts

@@ -1,6 +1,6 @@
 /** * Copyright (c) Microsoft Corporation. All rights reserved. * Licensed under the MIT License. */
 import { TurnContext } from './turnContext'
-import { debug } from '@microsoft/agents-activity/logger'
+import { debug } from '@microsoft/agents-telemetry'
 
 const logger = debug('agents:middleware')