@microsoft/agents-hosting 0.6.1 → 0.6.16-gc874f0c9d8

package/dist/src/app/agentApplication.d.ts

@@ -8,7 +8,6 @@ import { ResourceResponse } from '../connector-client';
 import { TurnContext } from '../turnContext';
 import { AdaptiveCardsActions } from './adaptiveCards';
 import { AgentApplicationOptions } from './agentApplicationOptions';
-import { AppRoute } from './appRoute';
 import { ConversationUpdateEvents } from './conversationUpdateEvents';
 import { AgentExtension } from './extensions';
 import { Authorization } from './authorization';
@@ -16,6 +15,8 @@ import { RouteHandler } from './routeHandler';
 import { RouteSelector } from './routeSelector';
 import { TurnEvents } from './turnEvents';
 import { TurnState } from './turnState';
+import { RouteRank } from './routeRank';
+import { RouteList } from './routeList';
 /**
  * Event handler function type for application events.
  * @template TState - The state type extending TurnState.
@@ -42,10 +43,10 @@ export type ApplicationEventHandler<TState extends TurnState> = (context: TurnCo
  * - Extensible architecture with custom extensions
  * - Event handlers for before/after turn processing
  *
- * Example usage:
+ * @example
  * ```typescript
  * const app = new AgentApplication<MyState>({
- *   storage: myStorage,
+ *   storage: new MemoryStorage(),
  *   adapter: myAdapter
  * });
  *
@@ -58,7 +59,7 @@ export type ApplicationEventHandler<TState extends TurnState> = (context: TurnCo
  */
 export declare class AgentApplication<TState extends TurnState> {
     protected readonly _options: AgentApplicationOptions<TState>;
-    protected readonly _routes: AppRoute<TState>[];
+    protected readonly _routes: RouteList<TState>;
     protected readonly _beforeTurn: ApplicationEventHandler<TState>[];
     protected readonly _afterTurn: ApplicationEventHandler<TState>[];
     private readonly _adapter?;
@@ -82,13 +83,14 @@ export declare class AgentApplication<TState extends TurnState> {
      * - removeRecipientMention: true
      * - turnStateFactory: Creates a new TurnState instance
      *
-     * Example usage:
+     * @example
      * ```typescript
      * const app = new AgentApplication({
-     *   storage: myStorage,
+     *   storage: new MemoryStorage(),
      *   adapter: myAdapter,
      *   startTypingTimer: true,
-     *   authorization: { connectionName: 'oauth' }
+     *   authorization: { connectionName: 'oauth' },
+     *   transcriptLogger: myTranscriptLogger,
      * });
      * ```
      */
@@ -121,9 +123,9 @@ export declare class AgentApplication<TState extends TurnState> {
      * The adaptive cards actions handler provides functionality for handling
      * adaptive card interactions, such as submit actions and other card-based events.
      *
-     * Example usage:
+     * @example
      * ```typescript
-     * app.adaptiveCards.onSubmit('myCardId', async (context, state, data) => {
+     * app.adaptiveCards.actionSubmit('doStuff', async (context, state, data) => {
      *   await context.sendActivity(`Received data: ${JSON.stringify(data)}`);
      * });
      * ```
@@ -139,7 +141,7 @@ export declare class AgentApplication<TState extends TurnState> {
      * This method allows you to handle any errors that occur during turn processing.
      * The handler will receive the turn context and the error that occurred.
      *
-     * Example usage:
+     * @example
      * ```typescript
      * app.onError(async (context, error) => {
      *   console.error(`An error occurred: ${error.message}`);
@@ -154,56 +156,63 @@ export declare class AgentApplication<TState extends TurnState> {
      * @param selector - The selector function that determines if a route should handle the current activity.
      * @param handler - The handler function that will be called if the selector returns true.
      * @param isInvokeRoute - Whether this route is for invoke activities. Defaults to false.
+     * @param rank - The rank of the route, used to determine the order of evaluation. Defaults to RouteRank.Unspecified.
      * @param authHandlers - Array of authentication handler names for this route. Defaults to empty array.
      * @returns The current instance of the application.
      *
      * @remarks
-     * Routes are evaluated in the order they are added. The first route with a selector that returns true will be used.
+     * Routes are evaluated by rank order (if provided), otherwise, in the order they are added.
+     * Invoke-based activities receive special treatment and are matched separately as they typically
+     * have shorter execution timeouts.
      *
-     * Example usage:
+     * @example
      * ```typescript
      * app.addRoute(
      *   async (context) => context.activity.type === ActivityTypes.Message,
      *   async (context, state) => {
      *     await context.sendActivity('I received your message');
-     *   }
+     *   },
+     *   false, // isInvokeRoute
+     *   RouteRank.First // rank
      * );
      * ```
      */
-    addRoute(selector: RouteSelector, handler: RouteHandler<TState>, isInvokeRoute?: boolean, authHandlers?: string[]): this;
+    addRoute(selector: RouteSelector, handler: RouteHandler<TState>, isInvokeRoute?: boolean, rank?: number, authHandlers?: string[]): this;
     /**
      * Adds a handler for specific activity types.
      *
      * @param type - The activity type(s) to handle. Can be a string, RegExp, RouteSelector, or array of these types.
      * @param handler - The handler function that will be called when the specified activity type is received.
      * @param authHandlers - Array of authentication handler names for this activity. Defaults to empty array.
+     * @param rank - The rank of the route, used to determine the order of evaluation. Defaults to RouteRank.Unspecified.
      * @returns The current instance of the application.
      *
      * @remarks
      * This method allows you to register handlers for specific activity types such as 'message', 'conversationUpdate', etc.
      * You can specify multiple activity types by passing an array.
      *
-     * Example usage:
+     * @example
      * ```typescript
      * app.onActivity(ActivityTypes.Message, async (context, state) => {
      *   await context.sendActivity('I received your message');
      * });
      * ```
      */
-    onActivity(type: string | RegExp | RouteSelector | (string | RegExp | RouteSelector)[], handler: (context: TurnContext, state: TState) => Promise<void>, authHandlers?: string[]): this;
+    onActivity(type: string | RegExp | RouteSelector | (string | RegExp | RouteSelector)[], handler: (context: TurnContext, state: TState) => Promise<void>, authHandlers?: string[], rank?: RouteRank): this;
     /**
      * Adds a handler for conversation update events.
      *
      * @param event - The conversation update event to handle (e.g., 'membersAdded', 'membersRemoved').
      * @param handler - The handler function that will be called when the specified event occurs.
      * @param authHandlers - Array of authentication handler names for this event. Defaults to empty array.
+     * @param rank - The rank of the route, used to determine the order of evaluation. Defaults to RouteRank.Unspecified.
      * @returns The current instance of the application.
      * @throws Error if the handler is not a function.
      *
      * @remarks
      * Conversation update events occur when the state of a conversation changes, such as when members join or leave.
      *
-     * Example usage:
+     * @example
      * ```typescript
      * app.onConversationUpdate('membersAdded', async (context, state) => {
      *   const membersAdded = context.activity.membersAdded;
@@ -215,7 +224,7 @@ export declare class AgentApplication<TState extends TurnState> {
      * });
      * ```
      */
-    onConversationUpdate(event: ConversationUpdateEvents, handler: (context: TurnContext, state: TState) => Promise<void>, authHandlers?: string[]): this;
+    onConversationUpdate(event: ConversationUpdateEvents, handler: (context: TurnContext, state: TState) => Promise<void>, authHandlers?: string[], rank?: RouteRank): this;
     /**
      * Continues a conversation asynchronously.
      *
@@ -232,6 +241,7 @@ export declare class AgentApplication<TState extends TurnState> {
      *                  Can be a string, RegExp, RouteSelector, or array of these types.
      * @param handler - The handler function that will be called when a matching message is received.
      * @param authHandlers - Array of authentication handler names for this message handler. Defaults to empty array.
+     * @param rank - The rank of the route, used to determine the order of evaluation. Defaults to RouteRank.Unspecified.
      * @returns The current instance of the application.
      *
      * @remarks
@@ -240,18 +250,18 @@ export declare class AgentApplication<TState extends TurnState> {
      * If keyword is a RegExp, it tests the message text against the regular expression.
      * If keyword is a function, it calls the function with the context to determine if the message matches.
      *
-     * Example usage:
+     * @example
      * ```typescript
      * app.onMessage('hello', async (context, state) => {
      *   await context.sendActivity('Hello there!');
      * });
      *
-     * app.onMessage(/help/, async (context, state) => {
+     * app.onMessage(/help/i, async (context, state) => {
      *   await context.sendActivity('How can I help you?');
      * });
      * ```
      */
-    onMessage(keyword: string | RegExp | RouteSelector | (string | RegExp | RouteSelector)[], handler: (context: TurnContext, state: TState) => Promise<void>, authHandlers?: string[]): this;
+    onMessage(keyword: string | RegExp | RouteSelector | (string | RegExp | RouteSelector)[], handler: (context: TurnContext, state: TState) => Promise<void>, authHandlers?: string[], rank?: RouteRank): this;
     /**
      * Sets a handler to be called when a user successfully signs in.
      *
@@ -263,7 +273,7 @@ export declare class AgentApplication<TState extends TurnState> {
      * This method allows you to perform actions after a user has successfully authenticated.
      * The handler will receive the turn context and state.
      *
-     * Example usage:
+     * @example
      * ```typescript
      * app.onSignInSuccess(async (context, state) => {
      *   await context.sendActivity('You have successfully signed in!');
@@ -282,7 +292,7 @@ export declare class AgentApplication<TState extends TurnState> {
      * This method allows you to handle cases where a user fails to authenticate,
      * such as when they cancel the sign-in process or an error occurs.
      *
-     * Example usage:
+     * @example
      * ```typescript
      * app.onSignInFailure(async (context, state) => {
      *   await context.sendActivity('Sign-in failed. Please try again.');
@@ -294,13 +304,14 @@ export declare class AgentApplication<TState extends TurnState> {
      * Adds a handler for message reaction added events.
      *
      * @param handler - The handler function that will be called when a message reaction is added.
+     * @param rank - The rank of the route, used to determine the order of evaluation. Defaults to RouteRank.Unspecified.
      * @returns The current instance of the application.
      *
      * @remarks
      * This method registers a handler that will be invoked when a user adds a reaction to a message,
      * such as a like, heart, or other emoji reaction.
      *
-     * Example usage:
+     * @example
      * ```typescript
      * app.onMessageReactionAdded(async (context, state) => {
      *   const reactionsAdded = context.activity.reactionsAdded;
@@ -310,18 +321,19 @@ export declare class AgentApplication<TState extends TurnState> {
      * });
      * ```
      */
-    onMessageReactionAdded(handler: (context: TurnContext, state: TState) => Promise<void>): this;
+    onMessageReactionAdded(handler: (context: TurnContext, state: TState) => Promise<void>, rank?: RouteRank): this;
     /**
      * Adds a handler for message reaction removed events.
      *
      * @param handler - The handler function that will be called when a message reaction is removed.
+     * @param rank - The rank of the route, used to determine the order of evaluation. Defaults to RouteRank.Unspecified.
      * @returns The current instance of the application.
      *
      * @remarks
      * This method registers a handler that will be invoked when a user removes a reaction from a message,
      * such as unliking or removing an emoji reaction.
      *
-     * Example usage:
+     * @example
      * ```typescript
      * app.onMessageReactionRemoved(async (context, state) => {
      *   const reactionsRemoved = context.activity.reactionsRemoved;
@@ -331,7 +343,7 @@ export declare class AgentApplication<TState extends TurnState> {
      * });
      * ```
      */
-    onMessageReactionRemoved(handler: (context: TurnContext, state: TState) => Promise<void>): this;
+    onMessageReactionRemoved(handler: (context: TurnContext, state: TState) => Promise<void>, rank?: RouteRank): this;
     /**
      * Executes the application logic for a given turn context.
      *
@@ -343,7 +355,7 @@ export declare class AgentApplication<TState extends TurnState> {
      * It delegates the actual processing to the `runInternal` method, which handles
      * the core logic for routing and executing handlers.
      *
-     * Example usage:
+     * @example
      * ```typescript
      * const app = new AgentApplication();
      * await app.run(turnContext);
@@ -372,7 +384,7 @@ export declare class AgentApplication<TState extends TurnState> {
      * 8. Executes after-turn event handlers
      * 9. Saves turn state
      *
-     * Example usage:
+     * @example
      * ```typescript
      * const handled = await app.runInternal(turnContext);
      * if (!handled) {
@@ -393,7 +405,7 @@ export declare class AgentApplication<TState extends TurnState> {
      * @remarks
      * This method allows you to send messages proactively to a conversation, outside the normal turn flow.
      *
-     * Example usage:
+     * @example
      * ```typescript
      * // With conversation reference
      * await app.sendProactiveActivity(conversationReference, 'Important notification!');
@@ -417,7 +429,7 @@ export declare class AgentApplication<TState extends TurnState> {
      * The typing indicator helps provide feedback to users that the agent is processing
      * their message, especially when responses might take time to generate.
      *
-     * Example usage:
+     * @example
      * ```typescript
      * app.startTypingTimer(turnContext);
      * // Do some processing...
@@ -438,7 +450,7 @@ export declare class AgentApplication<TState extends TurnState> {
      * Extensions provide a way to add custom functionality to the application.
      * Each extension can only be registered once to prevent conflicts.
      *
-     * Example usage:
+     * @example
      * ```typescript
      * const myExtension = new MyCustomExtension();
      * app.registerExtension(myExtension, (ext) => {
@@ -457,7 +469,7 @@ export declare class AgentApplication<TState extends TurnState> {
      * from being sent. It's typically called automatically when a message is sent, but
      * can also be called manually to stop the typing indicator.
      *
-     * Example usage:
+     * @example
      * ```typescript
      * app.startTypingTimer(turnContext);
      * // Do some processing...
@@ -477,7 +489,7 @@ export declare class AgentApplication<TState extends TurnState> {
      * Handlers added for 'beforeTurn' are executed before routing logic.
      * Handlers added for 'afterTurn' are executed after routing logic.
      *
-     * Example usage:
+     * @example
      * ```typescript
      * app.onTurn('beforeTurn', async (context, state) => {
      *   console.log('Processing before turn');

package/dist/src/app/agentApplication.js

@@ -6,11 +6,14 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AgentApplication = void 0;
 const agents_activity_1 = require("@microsoft/agents-activity");
-const logger_1 = require("../logger");
+const logger_1 = require("@microsoft/agents-activity/logger");
 const turnContext_1 = require("../turnContext");
 const adaptiveCards_1 = require("./adaptiveCards");
 const authorization_1 = require("./authorization");
 const turnState_1 = require("./turnState");
+const routeRank_1 = require("./routeRank");
+const routeList_1 = require("./routeList");
+const transcript_1 = require("../transcript");
 const logger = (0, logger_1.debug)('agents:app');
 const TYPING_TIMER_DELAY = 1000;
 /**
@@ -31,10 +34,10 @@ const TYPING_TIMER_DELAY = 1000;
  * - Extensible architecture with custom extensions
  * - Event handlers for before/after turn processing
  *
- * Example usage:
+ * @example
  * ```typescript
  * const app = new AgentApplication<MyState>({
- *   storage: myStorage,
+ *   storage: new MemoryStorage(),
  *   adapter: myAdapter
  * });
  *
@@ -62,18 +65,20 @@ class AgentApplication {
      * - removeRecipientMention: true
      * - turnStateFactory: Creates a new TurnState instance
      *
-     * Example usage:
+     * @example
      * ```typescript
      * const app = new AgentApplication({
-     *   storage: myStorage,
+     *   storage: new MemoryStorage(),
      *   adapter: myAdapter,
      *   startTypingTimer: true,
-     *   authorization: { connectionName: 'oauth' }
+     *   authorization: { connectionName: 'oauth' },
+     *   transcriptLogger: myTranscriptLogger,
      * });
      * ```
      */
     constructor(options) {
-        this._routes = [];
+        var _a;
+        this._routes = new routeList_1.RouteList();
         this._beforeTurn = [];
         this._afterTurn = [];
         this._extensions = [];
@@ -83,6 +88,7 @@ class AgentApplication {
             startTypingTimer: (options === null || options === void 0 ? void 0 : options.startTypingTimer) !== undefined ? options.startTypingTimer : false,
             longRunningMessages: (options === null || options === void 0 ? void 0 : options.longRunningMessages) !== undefined ? options.longRunningMessages : false,
             removeRecipientMention: (options === null || options === void 0 ? void 0 : options.removeRecipientMention) !== undefined ? options.removeRecipientMention : true,
+            transcriptLogger: (options === null || options === void 0 ? void 0 : options.transcriptLogger) || undefined,
         };
         this._adaptiveCards = new adaptiveCards_1.AdaptiveCardsActions(this);
         if (this._options.adapter) {
@@ -94,6 +100,14 @@ class AgentApplication {
         if (this._options.longRunningMessages && !this._adapter && !this._options.agentAppId) {
             throw new Error('The Application.longRunningMessages property is unavailable because no adapter was configured in the app.');
         }
+        if (this._options.transcriptLogger) {
+            if (!this._options.adapter) {
+                throw new Error('The Application.transcriptLogger property is unavailable because no adapter was configured in the app.');
+            }
+            else {
+                (_a = this._adapter) === null || _a === void 0 ? void 0 : _a.use(new transcript_1.TranscriptLoggerMiddleware(this._options.transcriptLogger));
+            }
+        }
         logger.debug('AgentApplication created with options:', this._options);
     }
     /**
@@ -133,9 +147,9 @@ class AgentApplication {
      * The adaptive cards actions handler provides functionality for handling
      * adaptive card interactions, such as submit actions and other card-based events.
      *
-     * Example usage:
+     * @example
      * ```typescript
-     * app.adaptiveCards.onSubmit('myCardId', async (context, state, data) => {
+     * app.adaptiveCards.actionSubmit('doStuff', async (context, state, data) => {
      *   await context.sendActivity(`Received data: ${JSON.stringify(data)}`);
      * });
      * ```
@@ -153,7 +167,7 @@ class AgentApplication {
      * This method allows you to handle any errors that occur during turn processing.
      * The handler will receive the turn context and the error that occurred.
      *
-     * Example usage:
+     * @example
      * ```typescript
      * app.onError(async (context, error) => {
      *   console.error(`An error occurred: ${error.message}`);
@@ -173,24 +187,29 @@ class AgentApplication {
      * @param selector - The selector function that determines if a route should handle the current activity.
      * @param handler - The handler function that will be called if the selector returns true.
      * @param isInvokeRoute - Whether this route is for invoke activities. Defaults to false.
+     * @param rank - The rank of the route, used to determine the order of evaluation. Defaults to RouteRank.Unspecified.
      * @param authHandlers - Array of authentication handler names for this route. Defaults to empty array.
      * @returns The current instance of the application.
      *
      * @remarks
-     * Routes are evaluated in the order they are added. The first route with a selector that returns true will be used.
+     * Routes are evaluated by rank order (if provided), otherwise, in the order they are added.
+     * Invoke-based activities receive special treatment and are matched separately as they typically
+     * have shorter execution timeouts.
      *
-     * Example usage:
+     * @example
      * ```typescript
      * app.addRoute(
      *   async (context) => context.activity.type === ActivityTypes.Message,
      *   async (context, state) => {
      *     await context.sendActivity('I received your message');
-     *   }
+     *   },
+     *   false, // isInvokeRoute
+     *   RouteRank.First // rank
      * );
      * ```
      */
-    addRoute(selector, handler, isInvokeRoute = false, authHandlers = []) {
-        this._routes.push({ selector, handler, isInvokeRoute, authHandlers });
+    addRoute(selector, handler, isInvokeRoute = false, rank = routeRank_1.RouteRank.Unspecified, authHandlers = []) {
+        this._routes.addRoute(selector, handler, isInvokeRoute, rank, authHandlers);
         return this;
     }
     /**
@@ -199,23 +218,24 @@ class AgentApplication {
      * @param type - The activity type(s) to handle. Can be a string, RegExp, RouteSelector, or array of these types.
      * @param handler - The handler function that will be called when the specified activity type is received.
      * @param authHandlers - Array of authentication handler names for this activity. Defaults to empty array.
+     * @param rank - The rank of the route, used to determine the order of evaluation. Defaults to RouteRank.Unspecified.
      * @returns The current instance of the application.
      *
      * @remarks
      * This method allows you to register handlers for specific activity types such as 'message', 'conversationUpdate', etc.
      * You can specify multiple activity types by passing an array.
      *
-     * Example usage:
+     * @example
      * ```typescript
      * app.onActivity(ActivityTypes.Message, async (context, state) => {
      *   await context.sendActivity('I received your message');
      * });
      * ```
      */
-    onActivity(type, handler, authHandlers = []) {
+    onActivity(type, handler, authHandlers = [], rank = routeRank_1.RouteRank.Unspecified) {
         (Array.isArray(type) ? type : [type]).forEach((t) => {
             const selector = this.createActivitySelector(t);
-            this.addRoute(selector, handler, false, authHandlers);
+            this.addRoute(selector, handler, false, rank, authHandlers);
         });
         return this;
     }
@@ -225,13 +245,14 @@ class AgentApplication {
      * @param event - The conversation update event to handle (e.g., 'membersAdded', 'membersRemoved').
      * @param handler - The handler function that will be called when the specified event occurs.
      * @param authHandlers - Array of authentication handler names for this event. Defaults to empty array.
+     * @param rank - The rank of the route, used to determine the order of evaluation. Defaults to RouteRank.Unspecified.
      * @returns The current instance of the application.
      * @throws Error if the handler is not a function.
      *
      * @remarks
      * Conversation update events occur when the state of a conversation changes, such as when members join or leave.
      *
-     * Example usage:
+     * @example
      * ```typescript
      * app.onConversationUpdate('membersAdded', async (context, state) => {
      *   const membersAdded = context.activity.membersAdded;
@@ -243,12 +264,12 @@ class AgentApplication {
      * });
      * ```
      */
-    onConversationUpdate(event, handler, authHandlers = []) {
+    onConversationUpdate(event, handler, authHandlers = [], rank = routeRank_1.RouteRank.Unspecified) {
         if (typeof handler !== 'function') {
             throw new Error(`ConversationUpdate 'handler' for ${event} is ${typeof handler}. Type of 'handler' must be a function.`);
         }
         const selector = this.createConversationUpdateSelector(event);
-        this.addRoute(selector, handler, false, authHandlers);
+        this.addRoute(selector, handler, false, rank, authHandlers);
         return this;
     }
     /**
@@ -282,6 +303,7 @@ class AgentApplication {
      *                  Can be a string, RegExp, RouteSelector, or array of these types.
      * @param handler - The handler function that will be called when a matching message is received.
      * @param authHandlers - Array of authentication handler names for this message handler. Defaults to empty array.
+     * @param rank - The rank of the route, used to determine the order of evaluation. Defaults to RouteRank.Unspecified.
      * @returns The current instance of the application.
      *
      * @remarks
@@ -290,21 +312,21 @@ class AgentApplication {
      * If keyword is a RegExp, it tests the message text against the regular expression.
      * If keyword is a function, it calls the function with the context to determine if the message matches.
      *
-     * Example usage:
+     * @example
      * ```typescript
      * app.onMessage('hello', async (context, state) => {
      *   await context.sendActivity('Hello there!');
      * });
      *
-     * app.onMessage(/help/, async (context, state) => {
+     * app.onMessage(/help/i, async (context, state) => {
      *   await context.sendActivity('How can I help you?');
      * });
      * ```
      */
-    onMessage(keyword, handler, authHandlers = []) {
+    onMessage(keyword, handler, authHandlers = [], rank = routeRank_1.RouteRank.Unspecified) {
         (Array.isArray(keyword) ? keyword : [keyword]).forEach((k) => {
             const selector = this.createMessageSelector(k);
-            this.addRoute(selector, handler, false, authHandlers);
+            this.addRoute(selector, handler, false, rank, authHandlers);
         });
         return this;
     }
@@ -319,7 +341,7 @@ class AgentApplication {
      * This method allows you to perform actions after a user has successfully authenticated.
      * The handler will receive the turn context and state.
      *
-     * Example usage:
+     * @example
      * ```typescript
      * app.onSignInSuccess(async (context, state) => {
      *   await context.sendActivity('You have successfully signed in!');
@@ -346,7 +368,7 @@ class AgentApplication {
      * This method allows you to handle cases where a user fails to authenticate,
      * such as when they cancel the sign-in process or an error occurs.
      *
-     * Example usage:
+     * @example
      * ```typescript
      * app.onSignInFailure(async (context, state) => {
      *   await context.sendActivity('Sign-in failed. Please try again.');
@@ -366,13 +388,14 @@ class AgentApplication {
      * Adds a handler for message reaction added events.
      *
      * @param handler - The handler function that will be called when a message reaction is added.
+     * @param rank - The rank of the route, used to determine the order of evaluation. Defaults to RouteRank.Unspecified.
      * @returns The current instance of the application.
      *
      * @remarks
      * This method registers a handler that will be invoked when a user adds a reaction to a message,
      * such as a like, heart, or other emoji reaction.
      *
-     * Example usage:
+     * @example
      * ```typescript
      * app.onMessageReactionAdded(async (context, state) => {
      *   const reactionsAdded = context.activity.reactionsAdded;
@@ -382,26 +405,27 @@ class AgentApplication {
      * });
      * ```
      */
-    onMessageReactionAdded(handler) {
+    onMessageReactionAdded(handler, rank = routeRank_1.RouteRank.Unspecified) {
         const selector = async (context) => {
             return context.activity.type === agents_activity_1.ActivityTypes.MessageReaction &&
                 Array.isArray(context.activity.reactionsAdded) &&
                 context.activity.reactionsAdded.length > 0;
         };
-        this.addRoute(selector, handler);
+        this.addRoute(selector, handler, false, rank);
         return this;
     }
     /**
      * Adds a handler for message reaction removed events.
      *
      * @param handler - The handler function that will be called when a message reaction is removed.
+     * @param rank - The rank of the route, used to determine the order of evaluation. Defaults to RouteRank.Unspecified.
      * @returns The current instance of the application.
      *
      * @remarks
      * This method registers a handler that will be invoked when a user removes a reaction from a message,
      * such as unliking or removing an emoji reaction.
      *
-     * Example usage:
+     * @example
      * ```typescript
      * app.onMessageReactionRemoved(async (context, state) => {
      *   const reactionsRemoved = context.activity.reactionsRemoved;
@@ -411,13 +435,13 @@ class AgentApplication {
      * });
      * ```
      */
-    onMessageReactionRemoved(handler) {
+    onMessageReactionRemoved(handler, rank = routeRank_1.RouteRank.Unspecified) {
         const selector = async (context) => {
             return context.activity.type === agents_activity_1.ActivityTypes.MessageReaction &&
                 Array.isArray(context.activity.reactionsRemoved) &&
                 context.activity.reactionsRemoved.length > 0;
         };
-        this.addRoute(selector, handler);
+        this.addRoute(selector, handler, false, rank);
         return this;
     }
     /**
@@ -431,7 +455,7 @@ class AgentApplication {
      * It delegates the actual processing to the `runInternal` method, which handles
      * the core logic for routing and executing handlers.
      *
-     * Example usage:
+     * @example
      * ```typescript
      * const app = new AgentApplication();
      * await app.run(turnContext);
@@ -462,7 +486,7 @@ class AgentApplication {
      * 8. Executes after-turn event handlers
      * 9. Saves turn state
      *
-     * Example usage:
+     * @example
      * ```typescript
      * const handled = await app.runInternal(turnContext);
      * if (!handled) {
@@ -567,7 +591,7 @@ class AgentApplication {
      * @remarks
      * This method allows you to send messages proactively to a conversation, outside the normal turn flow.
      *
-     * Example usage:
+     * @example
      * ```typescript
      * // With conversation reference
      * await app.sendProactiveActivity(conversationReference, 'Important notification!');
@@ -597,7 +621,7 @@ class AgentApplication {
      * The typing indicator helps provide feedback to users that the agent is processing
      * their message, especially when responses might take time to generate.
      *
-     * Example usage:
+     * @example
      * ```typescript
      * app.startTypingTimer(turnContext);
      * // Do some processing...
@@ -653,7 +677,7 @@ class AgentApplication {
      * Extensions provide a way to add custom functionality to the application.
      * Each extension can only be registered once to prevent conflicts.
      *
-     * Example usage:
+     * @example
      * ```typescript
      * const myExtension = new MyCustomExtension();
      * app.registerExtension(myExtension, (ext) => {
@@ -678,7 +702,7 @@ class AgentApplication {
      * from being sent. It's typically called automatically when a message is sent, but
      * can also be called manually to stop the typing indicator.
      *
-     * Example usage:
+     * @example
      * ```typescript
      * app.startTypingTimer(turnContext);
      * // Do some processing...
@@ -703,7 +727,7 @@ class AgentApplication {
      * Handlers added for 'beforeTurn' are executed before routing logic.
      * Handlers added for 'afterTurn' are executed after routing logic.
      *
-     * Example usage:
+     * @example
      * ```typescript
      * app.onTurn('beforeTurn', async (context, state) => {
      *   console.log('Processing before turn');