@microsoft/agents-hosting 1.0.0 → 1.0.3-g444d99f704

package/src/app/authorization.ts

@@ -67,7 +67,7 @@ export interface AuthorizationHandlers extends Record<string, AuthHandler> {}
  * - Sign-in success/failure event handling
  * - Automatic configuration from environment variables
  *
- * Example usage:
+ * @example
  * ```typescript
  * const auth = new Authorization(storage, {
  *   'microsoft': {
@@ -81,6 +81,7 @@ export interface AuthorizationHandlers extends Record<string, AuthHandler> {}
  *   await context.sendActivity('Welcome! You are now signed in.');
  * });
  * ```
+ *
  */
 export class Authorization {
   /**
@@ -92,10 +93,6 @@ export class Authorization {
   /**
    * Creates a new instance of Authorization.
    *
-   * @param storage - The storage system to use for state management.
-   * @param authHandlers - Configuration for OAuth providers.
-   * @throws {Error} If storage is null/undefined or no auth handlers are provided.
-   *
    * @remarks
    * The constructor initializes all configured auth handlers and sets up OAuth flows.
    * It automatically configures handler properties from environment variables if not provided:
@@ -103,7 +100,7 @@ export class Authorization {
    * - Connection title: {handlerId}_connectionTitle
    * - Connection text: {handlerId}_connectionText
    *
-   * Example usage:
+   * @example
    * ```typescript
    * const auth = new Authorization(storage, {
    *   'microsoft': {
@@ -115,6 +112,11 @@ export class Authorization {
    *   }
    * });
    * ```
+   *
+   * @param storage - The storage system to use for state management.
+   * @param authHandlers - Configuration for OAuth providers.
+   * @throws {Error} If storage is null/undefined or no auth handlers are provided.
+   *
    */
   constructor (private storage: Storage, authHandlers: AuthorizationHandlers, userTokenClient: UserTokenClient) {
     if (storage === undefined || storage === null) {
@@ -145,19 +147,20 @@ export class Authorization {
    * @param authHandlerId - ID of the auth handler to use.
    * @returns A promise that resolves to the token response from the OAuth provider.
    * @throws {Error} If the auth handler is not configured.
-   * @public
    *
    * @remarks
    * This method retrieves an existing token for the specified auth handler.
    * The token may be cached and will be retrieved from the OAuth provider if needed.
    *
-   * Example usage:
+   * @example
    * ```typescript
    * const tokenResponse = await auth.getToken(context, 'microsoft');
    * if (tokenResponse.token) {
    *   console.log('User is authenticated');
    * }
    * ```
+   *
+   * @public
    */
   public async getToken (context: TurnContext, authHandlerId: string): Promise<TokenResponse> {
     logger.info('getToken from user token service for authHandlerId:', authHandlerId)
@@ -188,14 +191,13 @@ export class Authorization {
    * @param authHandlerId - ID of the auth handler to use.
    * @returns A promise that resolves to the exchanged token response.
    * @throws {Error} If the auth handler is not configured.
-   * @public
    *
    * @remarks
    * This method handles token exchange scenarios, particularly for on-behalf-of (OBO) flows.
    * It checks if the current token is exchangeable (e.g., has audience starting with 'api://')
    * and performs the appropriate token exchange using MSAL.
    *
-   * Example usage:
+   * @example
    * ```typescript
    * const exchangedToken = await auth.exchangeToken(
    *   context,
@@ -203,6 +205,8 @@ export class Authorization {
    *   'microsoft'
    * );
    * ```
+   *
+   * @public
    */
   public async exchangeToken (context: TurnContext, scopes: string[], authHandlerId: string): Promise<TokenResponse> {
     logger.info('exchangeToken from user token service for authHandlerId:', authHandlerId)
@@ -256,7 +260,6 @@ export class Authorization {
    * @param authHandlerId - ID of the auth handler to use.
    * @returns A promise that resolves to the token response from the OAuth provider.
    * @throws {Error} If the auth handler is not configured.
-   * @public
    *
    * @remarks
    * This method manages the complete OAuth authentication flow:
@@ -267,7 +270,7 @@ export class Authorization {
    * The method automatically manages the sign-in state and continuation activities,
    * allowing the conversation to resume after successful authentication.
    *
-   * Example usage:
+   * @example
    * ```typescript
    * const tokenResponse = await auth.beginOrContinueFlow(context, state, 'microsoft');
    * if (tokenResponse && tokenResponse.token) {
@@ -275,6 +278,8 @@ export class Authorization {
    *   await context.sendActivity('Authentication successful!');
    * }
    * ```
+   *
+   * @public
    */
   public async beginOrContinueFlow (context: TurnContext, state: TurnState, authHandlerId: string, secRoute: boolean = true) : Promise<TokenResponse> {
     const authHandler = this.getAuthHandlerOrThrow(authHandlerId)
@@ -329,14 +334,13 @@ export class Authorization {
    * @param authHandlerId - Optional ID of the auth handler to use for sign out. If not provided, signs out from all handlers.
    * @returns A promise that resolves when sign out is complete.
    * @throws {Error} If the specified auth handler is not configured.
-   * @public
    *
    * @remarks
    * This method clears the user's token and resets the authentication state.
    * If no specific authHandlerId is provided, it signs out from all configured handlers.
    * This ensures complete cleanup of authentication state across all providers.
    *
-   * Example usage:
+   * @example
    * ```typescript
    * // Sign out from specific handler
    * await auth.signOut(context, state, 'microsoft');
@@ -344,6 +348,8 @@ export class Authorization {
    * // Sign out from all handlers
    * await auth.signOut(context, state);
    * ```
+   *
+   * @public
    */
   async signOut (context: TurnContext, state: TurnState, authHandlerId?: string) : Promise<void> {
     logger.info('signOut for authHandlerId:', authHandlerId)
@@ -368,20 +374,21 @@ export class Authorization {
    * Sets a handler to be called when sign-in is successfully completed.
    *
    * @param handler - The handler function to call on successful sign-in.
-   * @public
    *
    * @remarks
    * This method allows you to register a callback that will be invoked whenever
    * a user successfully completes the authentication process. The handler receives
    * the turn context, state, and the ID of the auth handler that was used.
    *
-   * Example usage:
+   * @example
    * ```typescript
    * auth.onSignInSuccess(async (context, state, authHandlerId) => {
    *   await context.sendActivity(`Welcome! You signed in using ${authHandlerId}.`);
    *   // Perform any post-authentication setup
    * });
    * ```
+   *
+   * @public
    */
   public onSignInSuccess (handler: (context: TurnContext, state: TurnState, authHandlerId?: string) => Promise<void>) {
     this._signInSuccessHandler = handler
@@ -397,7 +404,6 @@ export class Authorization {
    * Sets a handler to be called when sign-in fails.
    *
    * @param handler - The handler function to call on sign-in failure.
-   * @public
    *
    * @remarks
    * This method allows you to register a callback that will be invoked whenever
@@ -410,13 +416,15 @@ export class Authorization {
    * - Network connectivity issues
    * - OAuth provider errors
    *
-   * Example usage:
+   * @example
    * ```typescript
    * auth.onSignInFailure(async (context, state, authHandlerId, errorMessage) => {
    *   await context.sendActivity(`Sign-in failed: ${errorMessage || 'Unknown error'}`);
    *   await context.sendActivity('Please try signing in again.');
    * });
    * ```
+   *
+   * @public
    */
   public onSignInFailure (handler: (context: TurnContext, state: TurnState, authHandlerId?: string, errorMessage?: string) => Promise<void>) {
     this._signInFailureHandler = handler

package/src/app/routeRank.ts

@@ -26,10 +26,13 @@
  * this.onMessage('dupText', handler1, undefined, RouteRank.Last);
  * this.onMessage('dupText', handler2, undefined, RouteRank.First); // This executes first
  * ```
+ *
  */
 export enum RouteRank {
   /**
-   * Highest priority rank (value: 0). Routes with this rank are evaluated first
+   * Highest priority rank (value: 0).
+   *
+   * Routes with this rank are evaluated
    * before any other routes. Use this for critical routes that must take precedence
    * over all others, such as high-priority message handlers or override handlers
    * that should execute before any other matching routes.
@@ -37,7 +40,9 @@ export enum RouteRank {
   First = 0,
 
   /**
-   * Lowest priority rank (value: Number.MAX_VALUE). Routes with this rank are
+   * Lowest priority rank (value: Number.MAX_VALUE).
+   *
+   * Routes with this rank are
    * evaluated last, after all other routes have been considered. Ideal for
    * catch-all message handlers, fallback activity handlers, or default responses
    * that should only match when no other routes apply.
@@ -45,7 +50,9 @@ export enum RouteRank {
   Last = Number.MAX_VALUE,
 
   /**
-   * Default priority rank (value: Number.MAX_VALUE / 2). This is the standard
+   * Default priority rank (value: Number.MAX_VALUE / 2).
+   *
+   * This is the standard
    * rank for most routes that don't require special ordering. Routes with this
    * rank are evaluated after high-priority routes but before low-priority ones.
    * Use this when you don't need to specify a particular evaluation order.

package/src/app/streaming/streamingResponse.ts

@@ -13,6 +13,7 @@ const logger = debug('agents:streamingResponse')
 
 /**
  * A helper class for streaming responses to the client.
+ *
  * @remarks
  * This class is used to send a series of updates to the client in a single response. The expected
  * sequence of calls is:
@@ -43,6 +44,7 @@ export class StreamingResponse {
 
   /**
      * Creates a new StreamingResponse instance.
+     *
      * @param {TurnContext} context - Context for the current turn of conversation with the user.
      * @returns {TurnContext} - The context for the current turn of conversation with the user.
      */
@@ -52,7 +54,9 @@ export class StreamingResponse {
 
   /**
      * Gets the stream ID of the current response.
+     *
      * @returns {string | undefined} - The stream ID of the current response.
+     *
      * @remarks
      * Assigned after the initial update is sent.
      */
@@ -69,6 +73,7 @@ export class StreamingResponse {
 
   /**
      * Gets the number of updates sent for the stream.
+     *
      * @returns {number} - The number of updates sent for the stream.
      */
   public get updatesSent (): number {
@@ -77,6 +82,7 @@ export class StreamingResponse {
 
   /**
      * Queues an informative update to be sent to the client.
+     *
      * @param {string} text Text of the update to send.
      */
   public queueInformativeUpdate (text: string): void {
@@ -98,11 +104,14 @@ export class StreamingResponse {
 
   /**
      * Queues a chunk of partial message text to be sent to the client
+     *
+     * @param {string} text Partial text of the message to send.
+     * @param {Citation[]} citations Citations to be included in the message.
+     *
      * @remarks
      * The text we be sent as quickly as possible to the client. Chunks may be combined before
      * delivery to the client.
-     * @param {string} text Partial text of the message to send.
-     * @param {Citation[]} citations Citations to be included in the message.
+     *
      */
   public queueTextChunk (text: string, citations?: Citation[]): void {
     if (this._ended) {
@@ -121,6 +130,7 @@ export class StreamingResponse {
 
   /**
      * Ends the stream by sending the final message to the client.
+     *
      * @returns {Promise<void>} - A promise representing the async operation
      */
   public endStream (): Promise<void> {
@@ -138,6 +148,7 @@ export class StreamingResponse {
 
   /**
      * Sets the attachments to attach to the final chunk.
+     *
      * @param attachments List of attachments.
      */
   public setAttachments (attachments: Attachment[]): void {
@@ -146,6 +157,7 @@ export class StreamingResponse {
 
   /**
      * Sets the sensitivity label to attach to the final chunk.
+     *
      * @param sensitivityLabel The sensitivty label.
      */
   public setSensitivityLabel (sensitivityLabel: SensitivityUsageInfo): void {
@@ -154,6 +166,7 @@ export class StreamingResponse {
 
   /**
      * Sets the citations for the full message.
+     *
      * @param {Citation[]} citations Citations to be included in the message.
      */
   public setCitations (citations: Citation[]): void {
@@ -183,6 +196,7 @@ export class StreamingResponse {
      * Sets the Feedback Loop in Teams that allows a user to
      * give thumbs up or down to a response.
      * Default is `false`.
+     *
      * @param enableFeedbackLoop If true, the feedback loop is enabled.
      */
   public setFeedbackLoop (enableFeedbackLoop: boolean): void {
@@ -191,6 +205,7 @@ export class StreamingResponse {
 
   /**
      * Sets the type of UI to use for the feedback loop.
+     *
      * @param feedbackLoopType The type of the feedback loop.
      */
   public setFeedbackLoopType (feedbackLoopType: 'default' | 'custom'): void {
@@ -200,6 +215,7 @@ export class StreamingResponse {
   /**
      * Sets the the Generated by AI label in Teams
      * Default is `false`.
+     *
      * @param enableGeneratedByAILabel If true, the label is added.
      */
   public setGeneratedByAILabel (enableGeneratedByAILabel: boolean): void {
@@ -208,6 +224,7 @@ export class StreamingResponse {
 
   /**
      * Returns the most recently streamed message.
+     *
      * @returns The streamed message.
      */
   public getMessage (): string {
@@ -216,6 +233,7 @@ export class StreamingResponse {
 
   /**
      * Waits for the outgoing activity queue to be empty.
+     *
      * @returns {Promise<void>} - A promise representing the async operation.
      */
   public waitForQueue (): Promise<void> {
@@ -224,6 +242,7 @@ export class StreamingResponse {
 
   /**
      * Queues the next chunk of text to be sent to the client.
+     *
      * @private
      */
   private queueNextChunk (): void {
@@ -280,6 +299,7 @@ export class StreamingResponse {
 
   /**
      * Sends any queued activities to the client until the queue is empty.
+     *
      * @returns {Promise<void>} - A promise that will be resolved once the queue is empty.
      * @private
      */
@@ -305,6 +325,7 @@ export class StreamingResponse {
 
   /**
      * Sends an activity to the client and saves the stream ID returned.
+     *
      * @param {Activity} activity - The activity to send.
      * @returns {Promise<void>} - A promise representing the async operation.
      * @private

package/src/app/turnState.ts

@@ -40,12 +40,18 @@ export interface DefaultTempState {
 }
 
 /**
- * @summary Base class defining a collection of turn state scopes.
+ * Base class defining a collection of turn state scopes.
+ *
+ * @typeParam TConversationState - Type for conversation-scoped state
+ * @typeParam TUserState - Type for user-scoped state
+ * @typeParam TTempState - Type for temporary state that exists only for the current turn
+ * @typeParam TSSOState - Type for Single Sign-On (SSO) state
+ *
  * @remarks
  * Developers can create a derived class that extends `TurnState` to add additional state scopes.
  *
  * @example
- * ```JavaScript
+ * ```javascript
  * class MyTurnState extends TurnState {
  *   protected async onComputeStorageKeys(context) {
  *     const keys = await super.onComputeStorageKeys(context);
@@ -70,10 +76,7 @@ export interface DefaultTempState {
  *   }
  * }
  * ```
- * @typeParam TConversationState - Type for conversation-scoped state
- * @typeParam TUserState - Type for user-scoped state
- * @typeParam TTempState - Type for temporary state that exists only for the current turn
- * @typeParam TSSOState - Type for Single Sign-On (SSO) state
+ *
  */
 export class TurnState<
     TConversationState = DefaultConversationState,
@@ -87,9 +90,12 @@ export class TurnState<
 
   /**
    * Gets the conversation-scoped state.
-   * This state is shared by all users in the same conversation.
+   *
    * @returns The conversation state object
    * @throws Error if state hasn't been loaded
+   *
+   * @remarks
+   * This state is shared by all users in the same conversation.
    */
   public get conversation (): TConversationState {
     const scope = this.getScope(CONVERSATION_SCOPE)
@@ -101,6 +107,7 @@ export class TurnState<
 
   /**
    * Sets the conversation-scoped state.
+   *
    * @param value - The new conversation state object
    * @throws Error if state hasn't been loaded
    */
@@ -114,6 +121,7 @@ export class TurnState<
 
   /**
    * Gets whether the state has been loaded from storage
+   *
    * @returns True if the state has been loaded, false otherwise
    */
   public get isLoaded (): boolean {
@@ -122,9 +130,12 @@ export class TurnState<
 
   /**
    * Gets the temporary state for the current turn.
-   * This state is not persisted between turns.
+   *
    * @returns The temporary state object
    * @throws Error if state hasn't been loaded
+   *
+   * @remarks
+   * This state is not persisted between turns.
    */
   public get temp (): TTempState {
     const scope = this.getScope(TEMP_SCOPE)
@@ -136,6 +147,7 @@ export class TurnState<
 
   /**
    * Sets the temporary state for the current turn.
+   *
    * @param value - The new temporary state object
    * @throws Error if state hasn't been loaded
    */
@@ -149,9 +161,12 @@ export class TurnState<
 
   /**
    * Gets the user-scoped state.
-   * This state is unique to each user and persists across conversations.
+   *
    * @returns The user state object
    * @throws Error if state hasn't been loaded
+   *
+   * @remarks
+   * This state is unique to each user and persists across conversations.
    */
   public get user (): TUserState {
     const scope = this.getScope(USER_SCOPE)
@@ -163,6 +178,7 @@ export class TurnState<
 
   /**
    * Sets the user-scoped state.
+   *
    * @param value - The new user state object
    * @throws Error if state hasn't been loaded
    */
@@ -176,8 +192,11 @@ export class TurnState<
 
   /**
    * Marks the conversation state for deletion.
-   * The state will be deleted from storage on the next call to save().
+   *
    * @throws Error if state hasn't been loaded
+   *
+   * @remarks
+   * The state will be deleted from storage on the next call to save().
    */
   public deleteConversationState (): void {
     const scope = this.getScope(CONVERSATION_SCOPE)
@@ -189,8 +208,11 @@ export class TurnState<
 
   /**
    * Marks the temporary state for deletion.
-   * Since temporary state is not persisted, this just clears the in-memory object.
+   *
    * @throws Error if state hasn't been loaded
+   *
+   * @remarks
+   * Since temporary state is not persisted, this just clears the in-memory object.
    */
   public deleteTempState (): void {
     const scope = this.getScope(TEMP_SCOPE)
@@ -202,8 +224,11 @@ export class TurnState<
 
   /**
    * Marks the user state for deletion.
-   * The state will be deleted from storage on the next call to save().
+   *
    * @throws Error if state hasn't been loaded
+   *
+   * @remarks
+   * The state will be deleted from storage on the next call to save().
    */
   public deleteUserState (): void {
     const scope = this.getScope(USER_SCOPE)
@@ -215,6 +240,7 @@ export class TurnState<
 
   /**
    * Gets a specific state scope by name.
+   *
    * @param scope - The name of the scope to retrieve
    * @returns The state entry for the scope, or undefined if not found
    */
@@ -224,8 +250,11 @@ export class TurnState<
 
   /**
    * Deletes a value from state by dot-notation path.
-   * Format: "scope.property" or just "property" (defaults to temp scope)
+   *
    * @param path - The path to the value to delete
+   *
+   * @remarks
+   * Format: "scope.property" or just "property" (defaults to temp scope)
    */
   public deleteValue (path: string): void {
     const { scope, name } = this.getScopeAndName(path)
@@ -236,9 +265,12 @@ export class TurnState<
 
   /**
    * Checks if a value exists in state by dot-notation path.
-   * Format: "scope.property" or just "property" (defaults to temp scope)
+   *
    * @param path - The path to check
    * @returns True if the value exists, false otherwise
+   *
+   * @remarks
+   * Format: "scope.property" or just "property" (defaults to temp scope)
    */
   public hasValue (path: string): boolean {
     const { scope, name } = this.getScopeAndName(path)
@@ -247,10 +279,13 @@ export class TurnState<
 
   /**
    * Gets a value from state by dot-notation path.
-   * Format: "scope.property" or just "property" (defaults to temp scope)
+   *
    * @typeParam TValue - The type of the value to retrieve
    * @param path - The path to the value
    * @returns The value at the specified path
+   *
+   * @remarks
+   * Format: "scope.property" or just "property" (defaults to temp scope)
    */
   public getValue<TValue = unknown>(path: string): TValue {
     const { scope, name } = this.getScopeAndName(path)
@@ -259,9 +294,12 @@ export class TurnState<
 
   /**
    * Sets a value in state by dot-notation path.
-   * Format: "scope.property" or just "property" (defaults to temp scope)
+   *
    * @param path - The path to set
    * @param value - The value to set
+   *
+   * @remarks
+   * Format: "scope.property" or just "property" (defaults to temp scope)
    */
   public setValue (path: string, value: unknown): void {
     const { scope, name } = this.getScopeAndName(path)
@@ -270,6 +308,7 @@ export class TurnState<
 
   /**
    * Loads state from storage into memory.
+   *
    * @param context - The turn context
    * @param storage - Optional storage provider (if not provided, state will be in-memory only)
    * @param force - If true, forces a reload from storage even if state is already loaded
@@ -321,11 +360,14 @@ export class TurnState<
 
   /**
    * Saves state changes to storage.
-   * Only changed scopes will be persisted.
+   *
    * @param context - The turn context
    * @param storage - Optional storage provider (if not provided, state changes won't be persisted)
    * @returns Promise that resolves when the save operation is complete
    * @throws Error if state hasn't been loaded
+   *
+   * @remarks
+   * Only changed scopes will be persisted.
    */
   public async save (context: TurnContext, storage?: Storage): Promise<void> {
     if (!this._isLoaded && this._loadingPromise) {
@@ -378,9 +420,13 @@ export class TurnState<
 
   /**
    * Computes the storage keys for each scope based on the turn context.
-   * Override this method in derived classes to add or modify storage keys.
+   *
    * @param context - The turn context
    * @returns Promise that resolves to a dictionary of scope names to storage keys
+   *
+   * @remarks
+   * Override this method in derived classes to add or modify storage keys.
+   *
    * @protected
    */
   protected onComputeStorageKeys (context: TurnContext): Promise<Record<string, string>> {
@@ -414,9 +460,13 @@ export class TurnState<
 
   /**
    * Parses a dot-notation path into scope and property name.
-   * If no scope is specified, defaults to the temp scope.
+   *
    * @param path - The path to parse (format: "scope.property" or just "property")
    * @returns Object containing the scope entry and property name
+   *
+   * @remarks
+   * If no scope is specified, defaults to the temp scope.
+   *
    * @private
    */
   private getScopeAndName (path: string): { scope: TurnStateEntry; name: string } {

package/src/auth/authConfiguration.ts

@@ -48,10 +48,12 @@ export interface AuthConfiguration {
   FICClientId?: string,
 
   /**
-   * Entra Authentication Endpoint to use,  If not populated the Entra Public Cloud endpoint is assumed.
+   * Entra Authentication Endpoint to use.
+   *
+   * @remarks
+   * If not populated the Entra Public Cloud endpoint is assumed.
    * This example of Public Cloud Endpoint is https://login.microsoftonline.com
-   @remarks
-   see also https://learn.microsoft.com/entra/identity-platform/authentication-national-cloud
+   * see also https://learn.microsoft.com/entra/identity-platform/authentication-national-cloud
    */
   authority?: string
 }
@@ -59,6 +61,12 @@ export interface AuthConfiguration {
 /**
  * Loads the authentication configuration from environment variables.
  *
+ * @returns The authentication configuration.
+ * @throws Will throw an error if clientId is not provided in production.
+ *
+ * @remarks
+ * - `clientId` is required
+ *
  * @example
  * ```
  * tenantId=your-tenant-id
@@ -73,10 +81,7 @@ export interface AuthConfiguration {
  * connectionName=your-connection-name
  * authority=your-authority-endpoint
  * ```
- * @remarks
- * - `clientId` is required
- * @returns The authentication configuration.
- * @throws Will throw an error if clientId is not provided in production.
+ *
  */
 export const loadAuthConfigFromEnv: (cnxName?: string) => AuthConfiguration = (cnxName?: string) => {
   if (cnxName === undefined) {
@@ -122,14 +127,16 @@ export const loadAuthConfigFromEnv: (cnxName?: string) => AuthConfiguration = (c
 /**
  * Loads the agent authentication configuration from previous version environment variables.
  *
+ * @returns The agent authentication configuration.
+ * @throws Will throw an error if MicrosoftAppId is not provided in production.
+ *
  * @example
  * ```
  * MicrosoftAppId=your-client-id
  * MicrosoftAppPassword=your-client-secret
  * MicrosoftAppTenantId=your-tenant-id
  * ```
- * @returns The agent authentication configuration.
- * @throws Will throw an error if MicrosoftAppId is not provided in production.
+ *
  */
 export const loadPrevAuthConfigFromEnv: () => AuthConfiguration = () => {
   if (process.env.MicrosoftAppId === undefined && process.env.NODE_ENV === 'production') {