@microsoft/agents-hosting 1.6.0-beta.9.gce9d8facd2 → 1.7.0-beta.1.g8bcd4f11a7

package/src/connector-client/connectorClient.ts

@@ -1,5 +1,8 @@
-/** * Copyright (c) Microsoft Corporation. All rights reserved. * Licensed under the MIT License. */
-import axios, { AxiosInstance, AxiosRequestConfig, AxiosResponse } from 'axios'
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
 import { AuthConfiguration } from '../auth/authConfiguration'
 import { AuthProvider } from '../auth/authProvider'
 import { debug } from '@microsoft/agents-telemetry'
@@ -11,72 +14,47 @@ import { ResourceResponse } from './resourceResponse'
 import { AttachmentInfo } from './attachmentInfo'
 import { AttachmentData } from './attachmentData'
 import { normalizeOutgoingActivity } from '../activityWireCompat'
-import { getProductInfo } from '../getProductInfo'
+import { applyUserAgentHeader, getProductInfo } from '../getProductInfo'
 import { HeaderPropagation, HeaderPropagationCollection } from '../headerPropagation'
 import { trace } from '@microsoft/agents-telemetry'
 import { ConnectorClientTraceDefinitions } from '../observability'
+import { parseIntEnv } from '../utils/env'
+import { HttpClient, HttpRequestConfig, HttpResponse, HttpError } from '../httpClient'
 
 const logger = debug('agents:connector-client')
 
+function formatHttpErrorMessage (error: HttpError): string {
+  const responseData = error.response?.data
+  if (responseData === undefined) {
+    return error.message
+  }
+
+  try {
+    const serializedResponseData = JSON.stringify(responseData)
+    return serializedResponseData === undefined ? error.message : `${error.message}: ${serializedResponseData}`
+  } catch {
+    return error.message
+  }
+}
+
 export { getProductInfo }
 
 /**
  * ConnectorClient is a client for interacting with the Microsoft Connector API.
  */
 export class ConnectorClient {
-  protected readonly _axiosInstance: AxiosInstance
+  protected readonly _httpClient: HttpClient
 
   /**
    * Private constructor for the ConnectorClient.
-   * @param axInstance - The AxiosInstance to use for HTTP requests.
+   * @param httpClient - The HttpClient instance to use for HTTP requests.
    */
-  protected constructor (axInstance: AxiosInstance) {
-    this._axiosInstance = axInstance
-    this._axiosInstance.interceptors.request.use((config) => {
-      const { method, url, data, headers, params } = config
-      // Clone headers and remove Authorization before logging
-      const { Authorization, authorization, ...headersToLog } = headers || {}
-      logger.debug('Request: ', {
-        host: this._axiosInstance.getUri(),
-        url,
-        data,
-        method,
-        params,
-        headers: headersToLog
-      })
-      return config
-    })
-    this._axiosInstance.interceptors.response.use(
-      (config) => {
-        const { status, statusText, config: requestConfig } = config
-        logger.debug('Response: ', {
-          status,
-          statusText,
-          host: this._axiosInstance.getUri(),
-          url: requestConfig?.url,
-          data: config.config.data,
-          method: requestConfig?.method,
-        })
-        return config
-      },
-      (error) => {
-        const { code, message, stack, response } = error
-        const errorDetails = {
-          code,
-          host: this._axiosInstance.getUri(),
-          url: error.config.url,
-          method: error.config.method,
-          data: error.config.data,
-          message: message + JSON.stringify(response?.data),
-          stack,
-        }
-        return Promise.reject(errorDetails)
-      }
-    )
+  protected constructor (httpClient: HttpClient) {
+    this._httpClient = httpClient
   }
 
-  public get axiosInstance (): AxiosInstance {
-    return this._axiosInstance
+  public get httpClient (): HttpClient {
+    return this._httpClient
   }
 
   /**
@@ -112,28 +90,23 @@ export class ConnectorClient {
     headers?: HeaderPropagationCollection
   ): ConnectorClient {
     const headerPropagation = headers ?? new HeaderPropagation({})
-    const userAgent = headerPropagation.outgoing['user-agent']
-    const productInfo = getProductInfo()
-    if (!userAgent) {
-      headerPropagation.add({ 'User-Agent': productInfo })
-    } else if (!userAgent.includes(productInfo)) {
-      headerPropagation.concat({ 'User-Agent': productInfo })
-    }
+    applyUserAgentHeader(headerPropagation)
     headerPropagation.override({
       Accept: 'application/json',
-      'Content-Type': 'application/json', // Required by transformRequest
-    })
-
-    const axiosInstance = axios.create({
-      baseURL,
-      headers: headerPropagation.outgoing,
+      'Content-Type': 'application/json',
     })
 
+    const clientHeaders: Record<string, string> = { ...headerPropagation.outgoing }
     if (token && token.length > 1) {
-      axiosInstance.defaults.headers.common.Authorization = `Bearer ${token}`
+      clientHeaders.Authorization = `Bearer ${token}`
     }
 
-    return new ConnectorClient(axiosInstance)
+    const httpClient = new HttpClient({
+      baseURL,
+      headers: clientHeaders,
+    })
+
+    return new ConnectorClient(httpClient)
   }
 
   /**
@@ -143,12 +116,12 @@ export class ConnectorClient {
    */
   public async getConversations (continuationToken?: string): Promise<ConversationsResult> {
     return trace(ConnectorClientTraceDefinitions.getConversations, async ({ record }) => {
-      const config: AxiosRequestConfig = {
+      const config: HttpRequestConfig = {
         method: 'get',
         url: '/v3/conversations',
         params: continuationToken ? { continuationToken } : undefined
       }
-      const response = await this._axiosInstance(config)
+      const response = await this.executeRequest<ConversationsResult>(config)
       record({ httpStatusCode: response.status?.toString() })
       return response.data
     })
@@ -159,14 +132,14 @@ export class ConnectorClient {
       if (!userId || !conversationId) {
         throw ExceptionHelper.generateException(Error, Errors.UserIdAndConversationIdRequired)
       }
-      const config: AxiosRequestConfig = {
+      const config: HttpRequestConfig = {
         method: 'get',
         url: `v3/conversations/${conversationId}/members/${userId}`,
         headers: {
           'Content-Type': 'application/json'
         }
       }
-      const response = await this._axiosInstance(config)
+      const response = await this.executeRequest<ChannelAccount>(config)
       record({ httpStatusCode: response.status?.toString() })
       return response.data
     })
@@ -183,7 +156,7 @@ export class ConnectorClient {
         ...body,
         activity: normalizeOutgoingActivity(body.activity)
       }
-      const config: AxiosRequestConfig = {
+      const config: HttpRequestConfig = {
         method: 'post',
         url: '/v3/conversations',
         headers: {
@@ -191,7 +164,7 @@ export class ConnectorClient {
         },
         data: payload
       }
-      const response: AxiosResponse = await this._axiosInstance(config)
+      const response = await this.executeRequest<ConversationResourceResponse>(config)
       record({ httpStatusCode: response.status?.toString() })
       return response.data
     })
@@ -219,7 +192,7 @@ export class ConnectorClient {
 
       const trimmedConversationId: string = this.conditionallyTruncateConversationId(conversationId, body)
 
-      const config: AxiosRequestConfig = {
+      const config: HttpRequestConfig = {
         method: 'post',
         url: `v3/conversations/${trimmedConversationId}/activities/${encodeURIComponent(activityId)}`,
         headers: {
@@ -228,7 +201,7 @@ export class ConnectorClient {
         data: normalizeOutgoingActivity(body),
         ...(body.channelId === Channels.Msteams && body.isTargetedActivity() ? { params: { isTargetedActivity: 'true' } } : {})
       }
-      const response = await this._axiosInstance(config)
+      const response = await this.executeRequest<ResourceResponse>(config)
       record({ httpStatusCode: response.status?.toString() })
       logger.info('Reply to conversation/activity: ', response.data.id!, activityId)
       return response.data
@@ -236,20 +209,19 @@ export class ConnectorClient {
   }
 
   /**
-   * Trim the conversationId to a fixed length when creating the URL. This is applied only in specific API calls for agentic calls.
+   * Trim and sanitize the conversationId when creating the URL for agentic calls in agents channels.
    * @param conversationId The ID of the conversation to potentially truncate.
    * @param activity The activity object used to determine if truncation is necessary.
-   * @returns The original or truncated conversationId, depending on the channel and activity role.
+   * @returns The original conversationId for non-agents channels/non-agentic roles, otherwise a trimmed and sanitized value.
    */
   private conditionallyTruncateConversationId (conversationId: string, activity: Activity): string {
     if (
-      (activity.channelIdChannel === Channels.Msteams || activity.channelIdChannel === Channels.Agents) &&
+      activity.channelIdChannel === Channels.Agents &&
       (activity.from?.role === RoleTypes.AgenticIdentity || activity.from?.role === RoleTypes.AgenticUser)) {
-      let maxLength = 150
-      if (process.env.MAX_APX_CONVERSATION_ID_LENGTH && !isNaN(parseInt(process.env.MAX_APX_CONVERSATION_ID_LENGTH, 10))) {
-        maxLength = parseInt(process.env.MAX_APX_CONVERSATION_ID_LENGTH, 10)
-      }
-      return conversationId.length > maxLength ? conversationId.substring(0, maxLength) : conversationId
+      const maxLength = parseIntEnv(process.env.MAX_APX_CONVERSATION_ID_LENGTH, 150)
+      const trimmedConversationId = conversationId.length > maxLength ? conversationId.substring(0, maxLength) : conversationId
+
+      return trimmedConversationId.replace(/[/\\#?]/g, '_')
     } else {
       return conversationId
     }
@@ -275,7 +247,7 @@ export class ConnectorClient {
 
       const trimmedConversationId: string = this.conditionallyTruncateConversationId(conversationId, body)
 
-      const config: AxiosRequestConfig = {
+      const config: HttpRequestConfig = {
         method: 'post',
         url: `v3/conversations/${trimmedConversationId}/activities`,
         headers: {
@@ -285,7 +257,7 @@ export class ConnectorClient {
         ...(body.channelId === Channels.Msteams && body.isTargetedActivity() ? { params: { isTargetedActivity: 'true' } } : {})
 
       }
-      const response = await this._axiosInstance(config)
+      const response = await this.executeRequest<ResourceResponse>(config)
       record({ httpStatusCode: response.status?.toString() })
       return response.data
     })
@@ -308,7 +280,7 @@ export class ConnectorClient {
         throw ExceptionHelper.generateException(Error, Errors.ConversationIdAndActivityIdRequired)
       }
       record({ conversationId, activityId })
-      const config: AxiosRequestConfig = {
+      const config: HttpRequestConfig = {
         method: 'put',
         url: `v3/conversations/${conversationId}/activities/${activityId}`,
         headers: {
@@ -317,7 +289,7 @@ export class ConnectorClient {
         data: normalizeOutgoingActivity(body),
         ...(body.channelId === Channels.Msteams && body.isTargetedActivity() ? { params: { isTargetedActivity: 'true' } } : {})
       }
-      const response = await this._axiosInstance(config)
+      const response = await this.executeRequest<ResourceResponse>(config)
       record({ httpStatusCode: response.status?.toString() })
       return response.data
     })
@@ -341,7 +313,7 @@ export class ConnectorClient {
       if (!conversationId || !activityId) {
         throw ExceptionHelper.generateException(Error, Errors.ConversationIdAndActivityIdRequired)
       }
-      const config: AxiosRequestConfig = {
+      const config: HttpRequestConfig = {
         method: 'delete',
         url: `v3/conversations/${conversationId}/activities/${activityId}`,
         headers: {
@@ -349,7 +321,7 @@ export class ConnectorClient {
         },
         ...(isTargetedActivity ? { params: { isTargetedActivity: 'true' } } : {})
       }
-      const response = await this._axiosInstance(config)
+      const response = await this.executeRequest<void>(config)
       record({ httpStatusCode: response.status?.toString() })
       return response.data
     })
@@ -370,7 +342,7 @@ export class ConnectorClient {
       if (conversationId === undefined) {
         throw ExceptionHelper.generateException(Error, Errors.ConversationIdRequired)
       }
-      const config: AxiosRequestConfig = {
+      const config: HttpRequestConfig = {
         method: 'post',
         url: `v3/conversations/${conversationId}/attachments`,
         headers: {
@@ -378,7 +350,7 @@ export class ConnectorClient {
         },
         data: body
       }
-      const response = await this._axiosInstance(config)
+      const response = await this.executeRequest<ResourceResponse>(config)
       record({ httpStatusCode: response.status?.toString() })
       return response.data
     })
@@ -397,14 +369,14 @@ export class ConnectorClient {
       if (attachmentId === undefined) {
         throw ExceptionHelper.generateException(Error, Errors.AttachmentIdRequired)
       }
-      const config: AxiosRequestConfig = {
+      const config: HttpRequestConfig = {
         method: 'get',
         url: `v3/attachments/${attachmentId}`,
         headers: {
           'Content-Type': 'application/json'
         }
       }
-      const response = await this._axiosInstance(config)
+      const response = await this.executeRequest<AttachmentInfo>(config)
       record({ httpStatusCode: response.status?.toString() })
       return response.data
     })
@@ -428,16 +400,66 @@ export class ConnectorClient {
       if (viewId === undefined) {
         throw ExceptionHelper.generateException(Error, Errors.ViewIdRequired)
       }
-      const config: AxiosRequestConfig = {
+      const config: HttpRequestConfig = {
         method: 'get',
         url: `v3/attachments/${attachmentId}/views/${viewId}`,
         headers: {
           'Content-Type': 'application/json'
-        }
+        },
+        responseType: 'stream'
       }
-      const response = await this._axiosInstance(config)
+      const response = await this.executeRequest<NodeJS.ReadableStream>(config)
       record({ httpStatusCode: response.status?.toString() })
       return response.data
     })
   }
+
+  private async executeRequest<T = unknown> (config: HttpRequestConfig): Promise<HttpResponse<T>> {
+    const { method, url, data, headers, params } = config
+    const { Authorization, authorization, ...headersToLog } = { ...this._httpClient.defaultHeaders, ...headers } as Record<string, string>
+    logger.debug('Request: ', {
+      host: this._httpClient.baseURL,
+      url,
+      data,
+      method,
+      params,
+      headers: headersToLog
+    })
+
+    try {
+      const response = await this._httpClient.request<T>(config)
+      logger.debug('Response: ', {
+        status: response.status,
+        statusText: response.statusText,
+        host: this._httpClient.baseURL,
+        url: response.config?.url,
+        data: response.config?.data,
+        method: response.config?.method,
+      })
+      return response
+    } catch (error) {
+      if (error instanceof HttpError) {
+        const message = formatHttpErrorMessage(error)
+        logger.debug('Response error: ', {
+          host: this._httpClient.baseURL,
+          url: error.config.url,
+          method: error.config.method,
+          data: error.config.data,
+          message,
+          stack: error.stack,
+        })
+
+        Object.assign(error, {
+          host: this._httpClient.baseURL,
+          url: error.config.url,
+          method: error.config.method,
+          data: error.config.data,
+          message,
+        })
+
+        throw error
+      }
+      throw error
+    }
+  }
 }

package/src/errorHelper.ts

@@ -232,6 +232,14 @@ export const Errors: { [key: string]: AgentErrorDefinition } = {
     description: 'attachmentId is required'
   },
 
+  /**
+     * Error thrown when attachment is null or undefined.
+     */
+  AttachmentNullOrUndefined: {
+    code: -120265,
+    description: 'attachment cannot be null or undefined.'
+  },
+
   /**
      * Error thrown when viewId is required but missing.
      */
@@ -256,6 +264,14 @@ export const Errors: { [key: string]: AgentErrorDefinition } = {
     description: 'request.body parameter required'
   },
 
+  /**
+   * Error thrown when HttpClient is given a relative URL without a configured base URL.
+   */
+  HttpClientRelativeUrlRequiresBaseUrl: {
+    code: -120291,
+    description: 'HttpClient requires baseURL when using a relative URL: {url}'
+  },
+
   // ============================================================================
   // Connection and Authentication Errors (-120300 to -120590)
   // ============================================================================
@@ -516,8 +532,166 @@ export const Errors: { [key: string]: AgentErrorDefinition } = {
     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."
   },
 
+  /**
+   * Error thrown when an unsupported authentication type is specified in authConfig.
+   */
+  UnsupportedAuthType: {
+    code: -120593,
+    description: 'Unsupported authentication type: {authType}'
+  },
+
+  /**
+     * Error thrown when WorkloadIdentity authentication requires `federatedTokenFile` or the deprecated `WIDAssertionFile` to be configured.
+     */
+  WorkloadIdentityTokenFileRequired: {
+    code: -120594,
+    description: 'WorkloadIdentity authentication requires `federatedTokenFile` or the deprecated `WIDAssertionFile` to be configured'
+  },
+
+  /**
+   * Error thrown when ClientSecret authentication is specified but `clientSecret` is not configured.
+   */
+  ClientSecretRequired: {
+    code: -120595,
+    description: 'ClientSecret authentication requires `clientSecret` to be configured'
+  },
+
+  /**
+   * Error thrown when Certificate authentication is specified but `certPemFile` or `certKeyFile` is not configured.
+   */
+  CertificateFilesRequired: {
+    code: -120596,
+    description: 'Certificate authentication requires both `certPemFile` and `certKeyFile` to be configured'
+  },
+
+  /**
+   * Error thrown when FederatedCredentials authentication is specified but `federatedClientId` or the deprecated `FICClientId` is not configured.
+   */
+  FICClientIdRequired: {
+    code: -120597,
+    description: 'FederatedCredentials authentication requires `federatedClientId` or the deprecated `FICClientId` to be configured'
+  },
+
+  /**
+   * Error thrown when UserManagedIdentity authentication is specified but `clientId` is not configured.
+   */
+  ClientIdRequiredForUserManagedIdentity: {
+    code: -120598,
+    description: 'UserManagedIdentity authentication requires `clientId` to be configured'
+  },
+
+  /**
+   * Error thrown when there's a timeout during a token request.
+   */
+  TokenRequestTimeout: {
+    code: -120599,
+    description: 'Token request timed out after {timeoutMs} ms'
+  },
+
   // ============================================================================
-  // Agent and Client Errors (-120600 to -120630)
+  // Entra Agent ID Sidecar Authentication Errors (-120800 to -120849)
+  // ============================================================================
+
+  /**
+   * Error thrown when the Entra sidecar auth provider is used without connection settings.
+   */
+  SidecarConnectionSettingsRequired: {
+    code: -120800,
+    description: 'Connection settings must be provided when using the Entra sidecar auth provider'
+  },
+
+  /**
+   * Error thrown when the resolved sidecar base URL is not a valid absolute URL.
+   */
+  SidecarBaseUrlInvalid: {
+    code: -120801,
+    description: 'The resolved sidecar base URL `{url}` is not a valid absolute URL'
+  },
+
+  /**
+   * Error thrown when the resolved sidecar base URL does not use the http or https scheme.
+   */
+  SidecarBaseUrlInsecureScheme: {
+    code: -120802,
+    description: 'The resolved sidecar base URL `{url}` must use the http or https scheme'
+  },
+
+  /**
+   * Error thrown when the resolved sidecar base URL contains userinfo (credentials).
+   */
+  SidecarBaseUrlUserInfo: {
+    code: -120803,
+    description: 'The resolved sidecar base URL `{url}` must not contain userinfo (credentials)'
+  },
+
+  /**
+   * Error thrown when the resolved sidecar base URL points to a non-loopback, non-private address.
+   */
+  SidecarBaseUrlNotLocal: {
+    code: -120804,
+    description: 'The resolved sidecar base URL `{url}` points to a non-loopback, non-private address. The Entra Agent ID sidecar (agent container) must be reachable only from within the agent\'s network boundary. Set `bypassLocalNetworkRestriction` to true in the connection configuration to override this safety check (UNSAFE: only for carefully validated private-network configurations)'
+  },
+
+  /**
+   * Error thrown when both AgentUsername and AgentUserId are supplied on a sidecar request (mutually exclusive).
+   */
+  SidecarUserIdentityMutuallyExclusive: {
+    code: -120805,
+    description: 'AgentUsername and AgentUserId are mutually exclusive; set only one on the sidecar request options'
+  },
+
+  /**
+   * Error thrown when a sidecar request fails after exhausting all retry attempts.
+   */
+  SidecarRequestFailed: {
+    code: -120806,
+    description: 'Sidecar request failed after {attempts} attempt(s): {message}'
+  },
+
+  /**
+   * Error thrown when the sidecar responds with a non-success status code.
+   */
+  SidecarErrorResponse: {
+    code: -120807,
+    description: 'Sidecar returned error status {status}: {message}'
+  },
+
+  /**
+   * Error thrown when the sidecar response is missing the authorizationHeader field.
+   */
+  SidecarResponseMissingAuthorizationHeader: {
+    code: -120808,
+    description: 'Sidecar response missing `authorizationHeader` field'
+  },
+
+  /**
+   * Error thrown when the sidecar response body cannot be parsed.
+   */
+  SidecarResponseUnparsable: {
+    code: -120809,
+    description: 'Sidecar returned an unparsable response body'
+  },
+
+  /**
+   * Error thrown when acquireTokenOnBehalfOf is called on the sidecar provider, which does not support OBO in Phase 1.
+   */
+  OnBehalfOfNotSupportedBySidecar: {
+    code: -120810,
+    description: 'acquireTokenOnBehalfOf is not supported by the Entra sidecar auth provider in Phase 1'
+  },
+
+  /**
+   * Error thrown when the sidecar returns a token with an authorization scheme other than Bearer.
+   * The hosting stack always transmits tokens as `Bearer {token}`, so a non-Bearer scheme cannot be
+   * honored and is rejected rather than silently sent as an invalid Authorization header.
+   */
+  SidecarUnsupportedAuthScheme: {
+    code: -120811,
+    description: 'The Entra Agent ID sidecar returned an unsupported authorization scheme `{scheme}`. Only the Bearer scheme is supported'
+  },
+
+  // ============================================================================
+  // Agent and Client Errors (-120600 to -120650)
   // ============================================================================
 
   /**
@@ -537,18 +711,34 @@ export const Errors: { [key: string]: AgentErrorDefinition } = {
   },
 
   /**
-     * Error thrown when failed to post activity to agent.
-     */
-  FailedToPostActivityToAgent: {
+   * Error thrown when agent ID is required.
+   */
+  AgentIdRequired: {
     code: -120620,
+    description: 'Agent ID is required to apply outbound agent headers'
+  },
+
+  /**
+   * Error thrown when agent name contains invalid characters.
+   */
+  AgentNameInvalid: {
+    code: -120630,
+    description: 'Agent name contains invalid characters: {agentName}'
+  },
+
+  /**
+   * Error thrown when failed to post activity to agent.
+   */
+  FailedToPostActivityToAgent: {
+    code: -120640,
     description: 'Failed to post activity to agent: {statusText}'
   },
 
   /**
-     * Error thrown when logic parameter must be defined.
-     */
+   * Error thrown when logic parameter must be defined.
+   */
   LogicParameterRequired: {
-    code: -120630,
+    code: -120650,
     description: 'logic must be defined'
   },
 
@@ -784,6 +974,15 @@ export const Errors: { [key: string]: AgentErrorDefinition } = {
     description: 'This proactive operation requires app storage to load and save TurnState. Set options.storage on AgentApplication.'
   },
 
+  /**
+   * Error thrown when CreateConversationOptionsBuilder.build() is called for a Teams channel
+   * conversation (withTeamsChannelId) without an activity set via withActivity().
+   */
+  CreateConversationBuilderChannelActivityRequired: {
+    code: -120753,
+    description: 'CreateConversationOptionsBuilder: Teams channel conversations require an initial activity. Call withActivity() before build().'
+  },
+
   // ============================================================================
   // General Errors (-120990)
   // ============================================================================