@microsoft/agents-hosting 1.9.1 → 1.10.0-beta.14.ge6d1defc27

package/src/app/auth/authorization.ts

@@ -16,14 +16,72 @@ import { AuthorizationHandlerTokenOptions } from './types'
 
 const logger = debug('agents:authorization')
 
+/** Provides user authorization, token exchange, and sign-in lifecycle operations. */
 export interface Authorization {
+  /**
+   * Gets the user token for an authorization handler.
+   *
+   * @param context - Context for the current turn.
+   * @param authHandlerId - Authorization handler ID.
+   * @returns The token response.
+   */
   getToken(context: TurnContext, authHandlerId: string): Promise<TokenResponse>
+  /**
+   * Creates a credential backed by the current turn's user token.
+   *
+   * @param context - Context for the current turn.
+   * @param authHandlerId - Authorization handler ID.
+   * @returns A turn-scoped token credential.
+   */
   getTokenAsTokenCredential?(context: TurnContext, authHandlerId: string): TokenCredential
+  /**
+   * Exchanges the user token for the requested scopes.
+   *
+   * @param context - Context for the current turn.
+   * @param scopes - Scopes requested for the exchanged token.
+   * @param authHandlerId - Authorization handler ID.
+   * @returns The exchanged token response.
+   * @deprecated Use the overload that accepts an authorization handler ID followed by options.
+   */
   exchangeToken(context: TurnContext, scopes: string[], authHandlerId: string): Promise<TokenResponse>
+  /**
+   * Exchanges the user token using an authorization handler.
+   *
+   * @param context - Context for the current turn.
+   * @param authHandlerId - Authorization handler ID.
+   * @param options - Optional connection and scope overrides.
+   * @returns The exchanged token response.
+   */
   exchangeToken(context: TurnContext, authHandlerId: string, options?: AuthorizationHandlerTokenOptions): Promise<TokenResponse>
+  /**
+   * Creates a credential that exchanges the current turn's user token.
+   *
+   * @param context - Context for the current turn.
+   * @param authHandlerId - Authorization handler ID.
+   * @param options - Optional connection and scope overrides.
+   * @returns A turn-scoped token credential.
+   */
   exchangeTokenAsTokenCredential?(context: TurnContext, authHandlerId: string, options?: AuthorizationHandlerTokenOptions): TokenCredential
+  /**
+   * Signs out the user from one or all authorization handlers.
+   *
+   * @param context - Context for the current turn.
+   * @param state - State for the current turn.
+   * @param authHandlerId - Handler to sign out from, or `undefined` for all handlers.
+   * @returns A promise that resolves after sign-out completes.
+   */
   signOut(context: TurnContext, state: TurnState, authHandlerId?: string): Promise<void>
+  /**
+   * Registers a callback for successful sign-in.
+   *
+   * @param handler - Callback invoked after sign-in succeeds.
+   */
   onSignInSuccess(handler: (context: TurnContext, state: TurnState, authHandlerId?: string) => Promise<void>): void
+  /**
+   * Registers a callback for failed sign-in.
+   *
+   * @param handler - Callback invoked after sign-in fails.
+   */
   onSignInFailure(handler: (context: TurnContext, state: TurnState, authHandlerId?: string, errorMessage?: string) => Promise<void>): void
 }
 

package/src/app/proactive/conversation.ts

@@ -12,10 +12,15 @@ import { Errors } from '../../errorHelper'
  * `aud` (the agent's client ID) is required; all other fields are optional.
  */
 export interface ConversationClaims {
+  /** Audience identifying the agent client. */
   aud: string
+  /** Authorized-party client ID, when supplied by the token. */
   azp?: string
+  /** Calling application ID, when supplied by the token. */
   appid?: string
+  /** Microsoft Entra tenant ID, when supplied by the token. */
   tid?: string
+  /** Additional string-valued identity claims. */
   [key: string]: string | undefined
 }
 
@@ -28,11 +33,30 @@ export interface ConversationClaims {
  * `adapter.continueConversation()`.
  */
 export class Conversation {
+  /** Reference used to resume the conversation. */
   reference: ConversationReference
+  /** Identity claims used to authenticate proactive operations. */
   claims: ConversationClaims
 
+  /**
+   * Creates a conversation from the current turn.
+   *
+   * @param context - Turn context from which to capture the reference and identity.
+   */
   constructor (context: TurnContext)
+  /**
+   * Creates a conversation from explicit claims and a conversation reference.
+   *
+   * @param claims - Claims used to authenticate proactive operations.
+   * @param reference - Reference used to resume the conversation.
+   */
   constructor (claims: ConversationClaims, reference: ConversationReference)
+  /**
+   * Creates a conversation from a turn context or explicit claims and a reference.
+   *
+   * @param contextOrClaims - Turn context to capture, or authentication claims.
+   * @param reference - Reference paired with explicit claims.
+   */
   constructor (
     contextOrClaims: TurnContext | ConversationClaims,
     reference?: ConversationReference

package/src/app/proactive/conversationBuilder.ts

@@ -55,7 +55,9 @@ export class ConversationBuilder {
     requestorId?: string
   ): ConversationBuilder {
     const claims: ConversationClaims = { aud: agentClientId }
-    if (requestorId) claims.appid = requestorId
+    if (requestorId) {
+      claims.appid = requestorId
+    }
     return new ConversationBuilder(agentClientId, channelId, serviceUrl ?? '', claims, ConversationReferenceBuilder.create(agentClientId, channelId, serviceUrl).build())
   }
 

package/src/app/proactive/conversationReferenceBuilder.ts

@@ -71,8 +71,12 @@ export class ConversationReferenceBuilder {
    * `https://{channelId}.botframework.com/` pattern (matching C# behavior).
    */
   static serviceUrlForChannel (channelId: string): string {
-    if (!channelId) return ''
-    if (channelId === Channels.Msteams) return TeamsServiceEndpoints.publicGlobal
+    if (!channelId) {
+      return ''
+    }
+    if (channelId === Channels.Msteams) {
+      return TeamsServiceEndpoints.publicGlobal
+    }
     if (!knownChannelIds.has(channelId)) {
       logger.warn(
         `serviceUrlForChannel: unrecognized channelId '${channelId}' — constructing fallback URL ` +
@@ -141,8 +145,12 @@ export class ConversationReferenceBuilder {
       user: this._user ?? { role: RoleTypes.User },
     }
 
-    if (this._activityId !== undefined) ref.activityId = this._activityId
-    if (this._locale !== undefined) ref.locale = this._locale
+    if (this._activityId !== undefined) {
+      ref.activityId = this._activityId
+    }
+    if (this._locale !== undefined) {
+      ref.locale = this._locale
+    }
 
     return ref
   }

package/src/app/proactive/createConversationOptionsBuilder.ts

@@ -81,6 +81,8 @@ export class CreateConversationOptionsBuilder {
 
   /** Adds a member (the target user) to `parameters.members`. */
   withUser (userId: string, userName?: string): this
+
+  /** Adds a channel account as a member in `parameters.members`. */
   withUser (account: ChannelAccount): this
   withUser (userIdOrAccount: string | ChannelAccount, userName?: string): this {
     const account: ChannelAccount =
@@ -125,7 +127,9 @@ export class CreateConversationOptionsBuilder {
    * Only has effect on `msteams` channels.
    */
   withTeamsChannelId (teamsChannelId: string): this {
-    if (this._channelId !== Channels.Msteams) return this
+    if (this._channelId !== Channels.Msteams) {
+      return this
+    }
     this._parameters = { ...this._parameters, isGroup: true }
     this.withChannelData({ channel: { id: teamsChannelId } })
     return this

package/src/app/proactive/proactive.ts

@@ -49,6 +49,12 @@ export class Proactive<TState extends TurnState> {
   private readonly _options: ProactiveOptions
   private readonly _storage?: StorageV2
 
+  /**
+   * Creates a proactive conversation manager.
+   *
+   * @param app - Application that owns the proactive operations.
+   * @param options - Proactive messaging configuration.
+   */
   constructor (app: AgentApplication<TState>, options: ProactiveOptions) {
     this._app = app
     this._options = options
@@ -113,6 +119,12 @@ export class Proactive<TState extends TurnState> {
    * ```
    */
   storeConversation (conversation: Conversation): Promise<string>
+  /**
+   * Stores a conversation captured from a turn context or supplied explicitly.
+   *
+   * @param contextOrConversation - Turn context or conversation to store.
+   * @returns The stored conversation ID.
+   */
   async storeConversation (contextOrConversation: TurnContext | Conversation): Promise<string> {
     return trace(ProactiveTraceDefinitions.storeConversation, async ({ record, actions }) => {
       const conv =
@@ -243,6 +255,14 @@ export class Proactive<TState extends TurnState> {
    * ```
    */
   sendActivity (adapter: BaseAdapter, conversation: Conversation, activity: Partial<Activity>): Promise<ResourceResponse>
+  /**
+   * Sends an activity to a stored or explicitly supplied conversation.
+   *
+   * @param adapter - Channel adapter used to continue the conversation.
+   * @param conversationOrId - Conversation or stored conversation ID.
+   * @param activity - Activity fields to send.
+   * @returns The channel resource response.
+   */
   async sendActivity (
     adapter: BaseAdapter,
     conversationOrId: Conversation | string,
@@ -285,7 +305,9 @@ export class Proactive<TState extends TurnState> {
         logger.warn('sendActivity: failed for conversation=%s: %s', id, caughtError)
         throw caughtError
       }
-      if (response === undefined) throw ExceptionHelper.generateException(Error, Errors.ProactiveSendActivityNoResponse)
+      if (response === undefined) {
+        throw ExceptionHelper.generateException(Error, Errors.ProactiveSendActivityNoResponse)
+      }
       logger.debug('sendActivity: sent activity id=%s', response.id)
       return response
     })
@@ -359,6 +381,16 @@ export class Proactive<TState extends TurnState> {
    * ```
    */
   continueConversation (adapter: BaseAdapter, conversation: Conversation, handler: RouteHandler<TState>, autoSignInHandlers?: string[], continuationActivity?: Partial<Activity>): Promise<void>
+  /**
+   * Continues a stored or explicitly supplied conversation.
+   *
+   * @param adapter - Channel adapter used to continue the conversation.
+   * @param conversationOrId - Conversation or stored conversation ID.
+   * @param handler - Handler to execute in the continued turn.
+   * @param autoSignInHandlers - Connections for which tokens are acquired before the handler runs.
+   * @param continuationActivity - Activity fields merged into the continuation activity.
+   * @returns A promise that resolves after the continued turn completes.
+   */
   async continueConversation (
     adapter: BaseAdapter,
     conversationOrId: Conversation | string,

package/src/app/routeList.ts

@@ -9,9 +9,25 @@ import { RouteRank } from './routeRank'
 import { RouteSelector } from './routeSelector'
 import { TurnState } from './turnState'
 
+/**
+ * Maintains application routes in dispatch priority order.
+ *
+ * @typeParam TState - Turn state supplied to route handlers.
+ */
 export class RouteList<TState extends TurnState> {
   private _routes: Array<AppRoute<TState>> = []
 
+  /**
+   * Adds a route and orders it by route kind and rank.
+   *
+   * @param selector - Selector that determines whether the route matches.
+   * @param handler - Handler invoked for a matching route.
+   * @param isInvokeRoute - Whether the route handles invoke activities.
+   * @param rank - Rank used to order routes of the same kind.
+   * @param authHandlers - Authentication handlers required by the route.
+   * @param isAgenticRoute - Whether the route handles agentic requests.
+   * @returns This route list.
+   */
   public addRoute (
     selector: RouteSelector,
     handler: RouteHandler<TState>,
@@ -30,9 +46,15 @@ export class RouteList<TState extends TurnState> {
     // Then by Rank
     this._routes.sort((a, b) => {
       const getPriority = (route: AppRoute<TState>) => {
-        if (route.isAgenticRoute && route.isInvokeRoute) return 0
-        if (route.isInvokeRoute) return 1
-        if (route.isAgenticRoute) return 2
+        if (route.isAgenticRoute && route.isInvokeRoute) {
+          return 0
+        }
+        if (route.isInvokeRoute) {
+          return 1
+        }
+        if (route.isAgenticRoute) {
+          return 2
+        }
         return 3
       }
 
@@ -50,6 +72,11 @@ export class RouteList<TState extends TurnState> {
     return this
   }
 
+  /**
+   * Iterates over routes in dispatch priority order.
+   *
+   * @returns An iterator over the registered routes.
+   */
   public [Symbol.iterator] (): Iterator<AppRoute<TState>> {
     return this._routes[Symbol.iterator]()
   }

package/src/app/teamsAttachmentDownloader.ts

@@ -12,17 +12,26 @@ import { TurnState } from './turnState'
 import { HttpClient } from '../httpClient'
 import { z } from 'zod'
 import { createOutboundHostValidator, OutboundUrlPolicy } from '../outboundHostValidator'
+import { AttachmentDownloadHttpClient } from './attachmentDownloadHttpClient'
 
 const logger = debug('agents:M365AttachmentDownloader')
 
 /**
  * Downloads attachments from Teams and M365 using the bots access token.
+ * Enabled outbound validation requires HTTPS and validates addresses at every redirect.
+ * Initial request credentials are not forwarded to redirects when validation is enabled.
  */
 export class M365AttachmentDownloader<TState extends TurnState = TurnState> implements InputFileDownloader<TState> {
   private _httpClient: HttpClient
   private _stateKey: string
   private readonly _hostValidator: OutboundUrlPolicy
 
+  /**
+   * Creates an attachment downloader.
+   *
+   * @param stateKey - Turn-state key used by {@link downloadAndStoreFiles}.
+   * @param outboundHostValidator - Policy used to validate attachment download URLs.
+   */
   public constructor (stateKey: string = 'inputFiles', outboundHostValidator?: OutboundUrlPolicy) {
     this._httpClient = new HttpClient()
     this._stateKey = stateKey
@@ -46,11 +55,11 @@ export class M365AttachmentDownloader<TState extends TurnState = TurnState> impl
     }
 
     const connectorClient : ConnectorClient = context.turnState.get<ConnectorClient>(context.adapter.ConnectorClientKey)
-    this._httpClient.defaultHeaders = { ...connectorClient.httpClient.defaultHeaders }
+    const headers = { ...connectorClient.httpClient.defaultHeaders }
 
     const files: InputFile[] = []
     for (const attachment of attachments) {
-      const file = await this.downloadFile(attachment)
+      const file = await this.downloadFile(attachment, headers)
       if (file) {
         files.push(file)
       }
@@ -64,7 +73,7 @@ export class M365AttachmentDownloader<TState extends TurnState = TurnState> impl
    * @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> {
+  private async downloadFile (attachment: Attachment, headers: Record<string, string> = {}): Promise<InputFile | undefined> {
     let inputFile: InputFile | undefined
 
     if (attachment.contentUrl && attachment.contentUrl.startsWith('https://')) {
@@ -72,21 +81,19 @@ export class M365AttachmentDownloader<TState extends TurnState = TurnState> impl
         const contentSchema = z.object({ downloadUrl: z.string().url() })
         const parsed = contentSchema.safeParse(attachment.content)
         const downloadUrl = parsed.success ? parsed.data.downloadUrl : attachment.contentUrl
-        if (!this._hostValidator.isAllowed(downloadUrl)) {
-          let host = '[invalid-url]'
-          try { host = new URL(downloadUrl).hostname } catch { /* invalid */ }
-          logger.warn(`Attachment downloadUrl host is not in the configured allowed hosts. Host='${host}'`)
+        const response = await new AttachmentDownloadHttpClient(this._httpClient, this._hostValidator)
+          .get(downloadUrl, headers)
+        if (!response) {
           return undefined
         }
 
-        const response = await this._httpClient.get(downloadUrl, { responseType: 'arraybuffer' })
-
         const content = Buffer.from(response.data as ArrayBuffer)
         const contentTypeHeader = response.headers.get('content-type')
         const contentType = typeof contentTypeHeader === 'string' ? contentTypeHeader : 'application/octet-stream'
         inputFile = { content, contentType, contentUrl: attachment.contentUrl }
       } catch (error) {
-        logger.error(`Failed to download Teams attachment: ${error}`)
+        const code = error instanceof Error && 'code' in error && typeof error.code === 'number' ? error.code : 'unavailable'
+        logger.error(`Failed to download Teams attachment. Error type='${error instanceof Error ? error.name : 'unknown'}', Code='${code}'`)
         return undefined
       }
     } else {

package/src/auth/authConfiguration.ts

@@ -441,6 +441,7 @@ let globalEnv = loadEnv()
  * Optional host-scoped inputs used while resolving authentication settings.
  */
 export interface AuthConfigurationResolutionOptions {
+  /** Host-scoped configuration layers to include during resolution. */
   configurationContext?: ConfigurationContext
 }
 

package/src/auth/authConstants.ts

@@ -2,10 +2,17 @@
  * Copyright (c) Microsoft Corporation. All rights reserved.
  * Licensed under the MIT License.
  */
+/** APX OAuth scope for local development. */
 export const ApxLocalScope: string = 'c16e153d-5d2b-4c21-b7f4-b05ee5d516f1/.default'
+/** APX OAuth scope for the development environment. */
 export const ApxDevScope: string = '0d94caae-b412-4943-8a68-83135ad6d35f/.default'
+/** APX OAuth scope for the production environment. */
 export const ApxProductionScope: string = '5a807f24-c9de-44ee-a3a7-329e88a00ffc/.default'
+/** APX OAuth scope for the US Government Community Cloud environment. */
 export const ApxGCCScope: string = 'c9475445-9789-4fef-9ec5-cde4a9bcd446/.default'
+/** APX OAuth scope for the US Government Community Cloud High environment. */
 export const ApxGCCHScope: string = '6f669b9e-7701-4e2b-b624-82c9207fde26/.default'
+/** APX OAuth scope for the US Department of Defense environment. */
 export const ApxDoDScope: string = '0a069c81-8c7c-4712-886b-9c542d673ffb/.default'
+/** APX OAuth scope for the Microsoft Cloud operated by 21Vianet. */
 export const ApxGallatinScope: string = 'bd004c8e-5acf-4c48-8570-4e7d46b2f63b/.default'

package/src/auth/authProvider.ts

@@ -21,7 +21,20 @@ export interface AuthProvider {
    * @returns A promise that resolves to the access token.
    */
   getAccessToken (authConfig: AuthConfiguration, scope: string): Promise<string>
+  /**
+   * Gets an access token using this provider's connection settings.
+   *
+   * @param scope - Scope for which the access token is requested.
+   * @returns A promise that resolves to the access token.
+   */
   getAccessToken (scope: string): Promise<string>
+  /**
+   * Gets an access token using explicit or provider-level settings.
+   *
+   * @param authConfigOrScope - Authentication configuration, or the scope when using provider settings.
+   * @param scope - Scope used with an explicit authentication configuration.
+   * @returns A promise that resolves to the access token.
+   */
   getAccessToken (authConfigOrScope: AuthConfiguration | string, scope?: string): Promise<string>
 
   /**
@@ -50,8 +63,31 @@ export interface AuthProvider {
    */
   getAgenticUserToken: (tenantId: string, agentAppInstanceId: string, upn: string, scopes: string[]) => Promise<string>
 
+  /**
+   * Acquires a token on behalf of a user using this provider's connection settings.
+   *
+   * @param scopes - Scopes requested for the delegated token.
+   * @param oboAssertion - User assertion exchanged for the token.
+   * @returns A promise that resolves to the delegated access token.
+   */
   acquireTokenOnBehalfOf (scopes: string[], oboAssertion: string): Promise<string>
+  /**
+   * Acquires a token on behalf of a user using explicit authentication settings.
+   *
+   * @param authConfig - Authentication configuration.
+   * @param scopes - Scopes requested for the delegated token.
+   * @param oboAssertion - User assertion exchanged for the token.
+   * @returns A promise that resolves to the delegated access token.
+   */
   acquireTokenOnBehalfOf (authConfig: AuthConfiguration, scopes: string[], oboAssertion: string): Promise<string>
+  /**
+   * Acquires a delegated token using explicit or provider-level settings.
+   *
+   * @param authConfigOrScopes - Authentication configuration, or requested scopes when using provider settings.
+   * @param scopesOrOboAssertion - Requested scopes or the user assertion, depending on the overload.
+   * @param oboAssertion - User assertion used with explicit authentication settings.
+   * @returns A promise that resolves to the delegated access token.
+   */
   acquireTokenOnBehalfOf (
     authConfigOrScopes: AuthConfiguration | string[],
     scopesOrOboAssertion?: string[] | string,

package/src/auth/connectionManager.ts

@@ -146,7 +146,9 @@ export class ConnectionManager implements Connections {
       audience = identity.aud
     }
 
-    if (!audience || !serviceUrl) throw ExceptionHelper.generateException(Error, Errors.AudienceAndServiceUrlRequiredForTokenProvider)
+    if (!audience || !serviceUrl) {
+      throw ExceptionHelper.generateException(Error, Errors.AudienceAndServiceUrlRequiredForTokenProvider)
+    }
 
     if (this._connectionsMap.length === 0) {
       logger.debug('no connectionsMap, using default connection for serviceUrl=%s', serviceUrl)

package/src/auth/connections.ts

@@ -8,6 +8,7 @@ import { AuthConfiguration } from './authConfiguration'
 import { AuthProvider } from './authProvider'
 import { JwtPayload } from 'jsonwebtoken'
 
+/** Provides configured authentication connections and token providers. */
 export interface Connections {
   /**
  * Get the OAuth connection for the agent.

package/src/auth/msal/msalConnectionManager.ts

@@ -14,6 +14,13 @@ import { ConnectionManager, defaultAuthProviderFactory } from '../connectionMana
  * provider factory and applies MSAL-specific connection defaults.
  */
 export class MsalConnectionManager extends ConnectionManager {
+  /**
+   * Creates an MSAL connection manager.
+   *
+   * @param connectionsConfigurations - Authentication settings keyed by connection name.
+   * @param connectionsMap - Rules that map service URLs and audiences to connections.
+   * @param configuration - Default authentication configuration.
+   */
   constructor (
     connectionsConfigurations: Map<string, AuthConfiguration> = new Map(),
     connectionsMap: ConnectionMapItem[] = [],

package/src/auth/msal/msalTokenProvider.ts

@@ -37,8 +37,14 @@ export class MsalTokenProvider implements AuthProvider {
   private static readonly _agenticTokenCache = new MemoryCache<string>()
   private static readonly _confidentialClients = new Map<string, ConfidentialClientApplication>()
   private static readonly _maxConfidentialClients = 100
+  /** Authentication settings used by overloads that do not accept an explicit configuration. */
   public readonly connectionSettings?: AuthConfiguration
 
+  /**
+   * Creates an MSAL token provider.
+   *
+   * @param connectionSettings - Default authentication settings for token acquisition.
+   */
   constructor (connectionSettings?: AuthConfiguration) {
     this.connectionSettings = connectionSettings
   }
@@ -281,6 +287,13 @@ export class MsalTokenProvider implements AuthProvider {
    * @returns A promise that resolves to the access token.
    */
   public async getAccessToken (authConfig: AuthConfiguration, scope: string): Promise<string>
+  /**
+   * Gets an access token using explicit or provider-level settings.
+   *
+   * @param authConfigOrScope - Authentication configuration, or the scope when using provider settings.
+   * @param scope - Scope used with an explicit authentication configuration.
+   * @returns The access token.
+   */
   public async getAccessToken (authConfigOrScope: AuthConfiguration | string, scope?: string): Promise<string> {
     return trace(AuthenticationTraceDefinitions.getAccessToken, async ({ record }) => {
       let authConfig: AuthConfiguration
@@ -368,8 +381,31 @@ export class MsalTokenProvider implements AuthProvider {
     })
   }
 
+  /**
+   * Acquires a delegated token using this provider's connection settings.
+   *
+   * @param scopes - Scopes requested for the delegated token.
+   * @param oboAssertion - User assertion exchanged for the token.
+   * @returns The delegated access token.
+   */
   public async acquireTokenOnBehalfOf (scopes: string[], oboAssertion: string): Promise<string>
+  /**
+   * Acquires a delegated token using explicit authentication settings.
+   *
+   * @param authConfig - Authentication configuration.
+   * @param scopes - Scopes requested for the delegated token.
+   * @param oboAssertion - User assertion exchanged for the token.
+   * @returns The delegated access token.
+   */
   public async acquireTokenOnBehalfOf (authConfig: AuthConfiguration, scopes: string[], oboAssertion: string): Promise<string>
+  /**
+   * Acquires a delegated token using explicit or provider-level settings.
+   *
+   * @param authConfigOrScopes - Authentication configuration, or requested scopes when using provider settings.
+   * @param scopesOrOboAssertion - Requested scopes or the user assertion, depending on the overload.
+   * @param oboAssertion - User assertion used with explicit authentication settings.
+   * @returns The delegated access token.
+   */
   public async acquireTokenOnBehalfOf (
     authConfigOrScopes: AuthConfiguration | string[],
     scopesOrOboAssertion?: string[] | string,
@@ -411,6 +447,13 @@ export class MsalTokenProvider implements AuthProvider {
     })
   }
 
+  /**
+   * Gets a federated token for an agent application instance.
+   *
+   * @param tenantId - Microsoft Entra tenant ID.
+   * @param agentAppInstanceId - Agent application instance ID.
+   * @returns The agent instance token.
+   */
   public async getAgenticInstanceToken (tenantId: string, agentAppInstanceId: string): Promise<string> {
     return trace(AuthenticationTraceDefinitions.getAgenticInstanceToken, async ({ record }) => {
       logger.debug('getAgenticInstanceToken tenantId=%s agentAppInstanceId=%s', tenantId, agentAppInstanceId)
@@ -566,6 +609,15 @@ export class MsalTokenProvider implements AuthProvider {
     return token.access_token
   }
 
+  /**
+   * Gets a delegated token for an agentic user.
+   *
+   * @param tenantId - Microsoft Entra tenant ID.
+   * @param agentAppInstanceId - Agent application instance ID.
+   * @param agenticUserId - ID of the user represented by the token.
+   * @param scopes - Scopes requested for the token.
+   * @returns The agentic user token.
+   */
   public async getAgenticUserToken (tenantId: string, agentAppInstanceId: string, agenticUserId: string, scopes: string[]): Promise<string> {
     return trace(AuthenticationTraceDefinitions.getAgenticUserToken, async ({ record }) => {
       logger.debug('getAgenticUserToken tenantId=%s agentAppInstanceId=%s scopes=%o', tenantId, agentAppInstanceId, scopes)
@@ -597,6 +649,13 @@ export class MsalTokenProvider implements AuthProvider {
     })
   }
 
+  /**
+   * Gets the application token used to authenticate an agent application instance.
+   *
+   * @param tenantId - Microsoft Entra tenant ID.
+   * @param agentAppInstanceId - Agent application instance ID.
+   * @returns The agentic application token.
+   */
   public async getAgenticApplicationToken (tenantId: string, agentAppInstanceId: string): Promise<string> {
     if (!this.connectionSettings?.clientId) {
       throw ExceptionHelper.generateException(Error, Errors.ConnectionSettingsRequiredForGetAgenticApplicationToken)