@microsoft/agents-hosting 1.0.0 → 1.0.7-g73d3d58001

package/src/app/agentApplication.ts

@@ -36,7 +36,9 @@ const TYPING_TIMER_DELAY = 1000
 export type ApplicationEventHandler<TState extends TurnState> = (context: TurnContext, state: TState) => Promise<boolean>
 
 /**
- * @summary Main application class for handling agent conversations and routing.
+ * Main application class for handling agent conversations and routing.
+ *
+ * @typeParam TState - The state type extending TurnState.
  *
  * @remarks
  * The AgentApplication class provides a framework for building conversational agents.
@@ -65,7 +67,6 @@ export type ApplicationEventHandler<TState extends TurnState> = (context: TurnCo
  * await app.run(turnContext);
  * ```
  *
- * @typeParam TState - The state type extending TurnState.
  */
 export class AgentApplication<TState extends TurnState> {
   protected readonly _options: AgentApplicationOptions<TState>
@@ -79,7 +80,7 @@ export class AgentApplication<TState extends TurnState> {
   private readonly _adaptiveCards: AdaptiveCardsActions<TState>
 
   /**
-   * @summary Creates a new instance of AgentApplication.
+   * Creates a new instance of AgentApplication.
    *
    * @param options - Optional configuration options for the application.
    *
@@ -142,7 +143,7 @@ export class AgentApplication<TState extends TurnState> {
   }
 
   /**
-   * @summary Gets the authorization instance for the application.
+   * Gets the authorization instance for the application.
    *
    * @returns The authorization instance.
    * @throws Error if no authentication options were configured.
@@ -155,7 +156,7 @@ export class AgentApplication<TState extends TurnState> {
   }
 
   /**
-   * @summary Gets the options used to configure the application.
+   * Gets the options used to configure the application.
    *
    * @returns The application options.
    */
@@ -164,7 +165,7 @@ export class AgentApplication<TState extends TurnState> {
   }
 
   /**
-   * @summary Gets the adapter used by the application.
+   * Gets the adapter used by the application.
    *
    * @returns The adapter instance.
    */
@@ -173,7 +174,7 @@ export class AgentApplication<TState extends TurnState> {
   }
 
   /**
-   * @summary Gets the adaptive cards actions handler for the application.
+   * Gets the adaptive cards actions handler for the application.
    *
    * @returns The adaptive cards actions instance.
    *
@@ -209,6 +210,7 @@ export class AgentApplication<TState extends TurnState> {
    *   await context.sendActivity('Sorry, something went wrong!');
    * });
    * ```
+   *
    */
   public onError (handler: (context: TurnContext, error: Error) => Promise<void>): this {
     if (this._adapter) {
@@ -243,6 +245,7 @@ export class AgentApplication<TState extends TurnState> {
    *   RouteRank.First // rank
    * );
    * ```
+   *
    */
   public addRoute (selector: RouteSelector, handler: RouteHandler<TState>, isInvokeRoute: boolean = false, rank: number = RouteRank.Unspecified, authHandlers: string[] = []): this {
     this._routes.addRoute(selector, handler, isInvokeRoute, rank, authHandlers)
@@ -268,6 +271,7 @@ export class AgentApplication<TState extends TurnState> {
    *   await context.sendActivity('I received your message');
    * });
    * ```
+   *
    */
   public onActivity (
     type: string | RegExp | RouteSelector | (string | RegExp | RouteSelector)[],
@@ -306,6 +310,7 @@ export class AgentApplication<TState extends TurnState> {
    *   }
    * });
    * ```
+   *
    */
   public onConversationUpdate (
     event: ConversationUpdateEvents,
@@ -383,6 +388,7 @@ export class AgentApplication<TState extends TurnState> {
    *   await context.sendActivity('How can I help you?');
    * });
    * ```
+   *
    */
   public onMessage (
     keyword: string | RegExp | RouteSelector | (string | RegExp | RouteSelector)[],
@@ -414,6 +420,7 @@ export class AgentApplication<TState extends TurnState> {
    *   await context.sendActivity('You have successfully signed in!');
    * });
    * ```
+   *
    */
   public onSignInSuccess (handler: (context: TurnContext, state: TurnState, id?: string) => Promise<void>): this {
     if (this.options.authorization) {
@@ -443,6 +450,7 @@ export class AgentApplication<TState extends TurnState> {
    *   await context.sendActivity('Sign-in failed. Please try again.');
    * });
    * ```
+   *
    */
   public onSignInFailure (handler: (context: TurnContext, state: TurnState, id?: string) => Promise<void>): this {
     if (this.options.authorization) {
@@ -475,6 +483,7 @@ export class AgentApplication<TState extends TurnState> {
    *   }
    * });
    * ```
+   *
    */
   public onMessageReactionAdded (
     handler: (context: TurnContext, state: TState) => Promise<void>,
@@ -509,6 +518,7 @@ export class AgentApplication<TState extends TurnState> {
    *   }
    * });
    * ```
+   *
    */
   public onMessageReactionRemoved (
     handler: (context: TurnContext, state: TState) => Promise<void>,
@@ -539,6 +549,7 @@ export class AgentApplication<TState extends TurnState> {
    * const app = new AgentApplication();
    * await app.run(turnContext);
    * ```
+   *
    */
   public async run (turnContext:TurnContext): Promise<void> {
     await this.runInternal(turnContext)
@@ -573,6 +584,7 @@ export class AgentApplication<TState extends TurnState> {
    *   console.log('No handler matched the activity');
    * }
    * ```
+   *
    */
   public async runInternal (turnContext: TurnContext): Promise<boolean> {
     logger.info('Running application with activity:', turnContext.activity.id!)
@@ -688,6 +700,7 @@ export class AgentApplication<TState extends TurnState> {
    * // From an existing context
    * await app.sendProactiveActivity(turnContext, 'Important notification!');
    * ```
+   *
    */
   public async sendProactiveActivity (
     context: TurnContext | ConversationReference,
@@ -724,6 +737,7 @@ export class AgentApplication<TState extends TurnState> {
    * await turnContext.sendActivity('Response after processing');
    * // Typing timer automatically stops when sending a message
    * ```
+   *
    */
   public startTypingTimer (context: TurnContext): void {
     if (context.activity.type === ActivityTypes.Message && !this._typingTimer) {
@@ -782,6 +796,7 @@ export class AgentApplication<TState extends TurnState> {
    *   console.log('Extension registered:', ext.name);
    * });
    * ```
+   *
    */
   public registerExtension<T extends AgentExtension<TState>> (extension: T, regcb : (ext:T) => void): void {
     if (this._extensions.includes(extension)) {
@@ -807,6 +822,7 @@ export class AgentApplication<TState extends TurnState> {
    * // Do some processing...
    * app.stopTypingTimer(); // Manually stop the typing indicator
    * ```
+   *
    */
   public stopTypingTimer (): void {
     if (this._typingTimer) {
@@ -834,6 +850,7 @@ export class AgentApplication<TState extends TurnState> {
    *   return true; // Continue execution
    * });
    * ```
+   *
    */
   public onTurn (
     event: TurnEvents | TurnEvents[],

package/src/app/agentApplicationOptions.ts

@@ -120,7 +120,7 @@ export interface AgentApplicationOptions<TState extends TurnState> {
    * Whether to automatically normalize mentions in incoming messages.
    * When enabled, user mentions and other entity mentions in messages will be
    * standardized to a consistent format, making them easier to process and understand.
-   * This includes formatting @mentions and channel references consistently.
+   * This includes formatting mentions and channel references consistently.
    *
    * @default true
    */

package/src/app/appRoute.ts

@@ -10,14 +10,14 @@ import { TurnState } from './turnState'
 /**
  * Represents a route configuration for handling bot activities within an application.
  *
+ * @typeParam TState - The type of turn state that extends TurnState, allowing for
+ *                    type-safe access to custom state properties within route handlers
+ *
  * @remarks
  * An AppRoute defines how incoming activities are matched and processed by combining
  * a selector function that determines when the route should be activated with a handler
  * function that processes the matched activities.
  *
- * @typeParam TState - The type of turn state that extends TurnState, allowing for
- *                    type-safe access to custom state properties within route handlers
- *
  * @example
  * ```typescript
  * const echoRoute: AppRoute<MyTurnState> = {
@@ -27,6 +27,7 @@ import { TurnState } from './turnState'
  *   }
  * };
  * ```
+ *
  */
 export interface AppRoute<TState extends TurnState> {
   /**
@@ -53,18 +54,20 @@ export interface AppRoute<TState extends TurnState> {
   /**
    * Indicates whether this route is an invoke route.
    *
+   * @default false
+   *
    * @remarks
    * Invoke routes are used for specific types of activities, such as messaging extensions,
    * adaptive card actions, or other invoke-based interactions. When set to true, this route
    * will be processed differently than regular message routes, typically with special
    * handling for invoke responses.
    *
-   * @default false
    */
   isInvokeRoute?: boolean;
 
   /**
    * Optional rank of the route, used to determine the order in which routes are evaluated.
+   *
    * 0 - number.MAX_VALUE. Ranks of the same value are evaluated in order of addition.
    */
   rank?: number;
@@ -82,6 +85,7 @@ export interface AppRoute<TState extends TurnState> {
    * ```typescript
    * authHandlers: ['oauth', 'admin-only']
    * ```
+   *
    */
   authHandlers?: string[]
 }

package/src/app/attachmentDownloader.ts

@@ -17,11 +17,12 @@ const logger = debug('agents:attachmentDownloader')
 /**
  * A utility class for downloading input files from activity attachments.
  *
+ * @typeParam TState - The type of the turn state used in the application.
+ *
  * @remarks
  * This class provides functionality to filter and download attachments from a turn context,
  * supporting various content types and handling authentication for secure URLs.
  *
- * @typeParam TState - The type of the turn state used in the application.
  */
 export class AttachmentDownloader<TState extends TurnState = TurnState> implements InputFileDownloader<TState> {
   private _httpClient: AxiosInstance
@@ -36,6 +37,7 @@ export class AttachmentDownloader<TState extends TurnState = TurnState> implemen
 
   /**
    * Downloads files from the attachments in the current turn context.
+   *
    * @param context The turn context containing the activity with attachments.
    * @param state The turn state for the current conversation.
    * @returns A promise that resolves to an array of downloaded input files.

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/index.ts

@@ -16,3 +16,5 @@ export * from './inputFileDownloader'
 export * from './appMemory'
 export * from './extensions'
 export * from './adaptiveCards'
+export * from './streaming/streamingResponse'
+export * from './streaming/citation'

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