@microsoft/agents-hosting 0.2.10-g3ac88ff25e → 0.2.14

package/dist/src/agent-client/agentClient.js

@@ -6,10 +6,30 @@ const agents_activity_1 = require("@microsoft/agents-activity");
 const uuid_1 = require("uuid");
 const logger_1 = require("../logger");
 const logger = (0, logger_1.debug)('agents:agent-client');
+/**
+ * Client for communicating with other agents through HTTP requests.
+ * Manages configuration, authentication, and activity exchange with target agents.
+ */
 class AgentClient {
+    /**
+     * Creates a new instance of the AgentClient class.
+     *
+     * @param agentConfigKey The name of the agent, used to locate configuration in environment variables
+     * @throws Error if required configuration is missing
+     */
     constructor(agentConfigKey) {
         this.agentClientConfig = this.loadAgentClientConfig(agentConfigKey);
     }
+    /**
+     * Sends an activity to another agent and handles the conversation state.
+     *
+     * @param activity The activity to send to the target agent
+     * @param authConfig Authentication configuration used to obtain access tokens
+     * @param conversationState State manager to store conversation data
+     * @param context The current turn context
+     * @returns A promise that resolves to the HTTP status text of the agent response
+     * @throws Error if the request to the agent endpoint fails
+     */
     async postActivity(activity, authConfig, conversationState, context) {
         const activityCopy = activity.clone();
         activityCopy.serviceUrl = this.agentClientConfig.serviceUrl;
@@ -48,6 +68,14 @@ class AgentClient {
         }
         return response.statusText;
     }
+    /**
+     * Loads agent configuration from environment variables based on the agent name.
+     *
+     * @param agentName The name of the agent to load configuration for
+     * @returns The agent client configuration
+     * @throws Error if any required configuration is missing
+     * @private
+     */
     loadAgentClientConfig(agentName) {
         if (agentName) {
             if (process.env[`${agentName}_endpoint`] !== undefined &&

package/dist/src/agent-client/agentClient.js.map

@@ -1 +1 @@
-{"version":3,"file":"agentClient.js","sourceRoot":"","sources":["../../../src/agent-client/agentClient.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agentClient.js","sourceRoot":"","sources":["../../../src/agent-client/agentClient.ts"],"names":[],"mappings":";;;AAAA,kCAA8D;AAC9D,gEAAuF;AACvF,+BAAyB;AACzB,sCAAiC;AAIjC,MAAM,MAAM,GAAG,IAAA,cAAK,EAAC,qBAAqB,CAAC,CAAA;AAkC3C;;;GAGG;AACH,MAAa,WAAW;IAItB;;;;;OAKG;IACH,YAAoB,cAAsB;QACxC,IAAI,CAAC,iBAAiB,GAAG,IAAI,CAAC,qBAAqB,CAAC,cAAc,CAAC,CAAA;IACrE,CAAC;IAED;;;;;;;;;OASG;IACI,KAAK,CAAC,YAAY,CAAE,QAAkB,EAAE,UAA6B,EAAE,iBAAoC,EAAE,OAAoB;QACtI,MAAM,YAAY,GAAG,QAAQ,CAAC,KAAK,EAAE,CAAA;QACrC,YAAY,CAAC,UAAU,GAAG,IAAI,CAAC,iBAAiB,CAAC,UAAU,CAAA;QAC3D,YAAY,CAAC,SAAS,GAAG,EAAE,GAAG,YAAY,CAAC,SAAS,EAAE,IAAI,EAAE,2BAAS,CAAC,KAAK,EAAE,CAAA;QAC7E,YAAY,CAAC,SAAS,GAAG;YACvB,UAAU,EAAE,QAAQ,CAAC,UAAU;YAC/B,UAAU,EAAE,YAAY,CAAC,EAAE;YAC3B,SAAS,EAAE,YAAY,CAAC,SAAU;YAClC,MAAM,EAAE,YAAY,CAAC,MAAM;YAC3B,YAAY,EAAE;gBACZ,EAAE,EAAE,QAAQ,CAAC,YAAa,CAAC,EAAE;gBAC7B,GAAG,YAAY,CAAC,YAAY;aAC7B;SACF,CAAA;QACD,YAAY,CAAC,YAAa,CAAC,EAAE,GAAG,IAAA,SAAE,GAAE,CAAA;QAEpC,MAAM,wBAAwB,GAAG,iBAAiB,CAAC,cAAc,CAAmB,YAAY,CAAC,YAAa,CAAC,EAAE,CAAC,CAAA;QAClH,MAAM,OAAO,GAAG,MAAM,wBAAwB,CAAC,GAAG,CAAC,OAAO,EACxD,EAAE,qBAAqB,EAAE,QAAQ,CAAC,wBAAwB,EAAE,EAAE,aAAa,EAAE,KAAK,EAAE,EACpF,EAAE,SAAS,EAAE,YAAY,CAAC,SAAU,EAAE,cAAc,EAAE,YAAY,CAAC,YAAa,CAAC,EAAE,EAAE,CACtF,CAAA;QAED,MAAM,YAAY,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAA;QAC5C,MAAM,CAAC,KAAK,CAAC,gBAAgB,EAAE,YAAY,CAAC,CAAA;QAE5C,MAAM,YAAY,GAAG,IAAI,wBAAiB,EAAE,CAAA;QAC5C,MAAM,KAAK,GAAG,MAAM,YAAY,CAAC,cAAc,CAAC,UAAU,EAAE,IAAI,CAAC,iBAAiB,CAAC,QAAQ,CAAC,CAAA;QAE5F,MAAM,CAAC,KAAK,CAAC,iBAAiB,EAAE,YAAY,CAAC,CAAA;QAE7C,MAAM,iBAAiB,CAAC,WAAW,CAAC,OAAO,EAAE,KAAK,EAAE,EAAE,SAAS,EAAE,YAAY,CAAC,SAAU,EAAE,cAAc,EAAE,YAAY,CAAC,YAAa,CAAC,EAAE,EAAE,CAAC,CAAA;QAC1I,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,iBAAiB,CAAC,QAAQ,EAAE;YAC5D,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACP,cAAc,EAAE,kBAAkB;gBAClC,aAAa,EAAE,UAAU,KAAK,EAAE;gBAChC,sBAAsB,EAAE,YAAY,CAAC,YAAa,CAAC,EAAE;aACtD;YACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC;SACnC,CAAC,CAAA;QACF,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,MAAM,wBAAwB,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,YAAY,CAAC,SAAU,EAAE,cAAc,EAAE,YAAY,CAAC,YAAa,CAAC,EAAE,EAAE,CAAC,CAAA;YACrI,MAAM,IAAI,KAAK,CAAC,qCAAqC,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAA;QAC7E,CAAC;QACD,OAAO,QAAQ,CAAC,UAAU,CAAA;IAC5B,CAAC;IAED;;;;;;;OAOG;IACK,qBAAqB,CAAE,SAAiB;QAC9C,IAAI,SAAS,EAAE,CAAC;YACd,IAAI,OAAO,CAAC,GAAG,CAAC,GAAG,SAAS,WAAW,CAAC,KAAK,SAAS;gBACpD,OAAO,CAAC,GAAG,CAAC,GAAG,SAAS,WAAW,CAAC,KAAK,SAAS;gBAClD,OAAO,CAAC,GAAG,CAAC,GAAG,SAAS,aAAa,CAAC,KAAK,SAAS,EAAE,CAAC;gBACvD,OAAO;oBACL,QAAQ,EAAE,OAAO,CAAC,GAAG,CAAC,GAAG,SAAS,WAAW,CAAE;oBAC/C,QAAQ,EAAE,OAAO,CAAC,GAAG,CAAC,GAAG,SAAS,WAAW,CAAE;oBAC/C,UAAU,EAAE,OAAO,CAAC,GAAG,CAAC,GAAG,SAAS,aAAa,CAAE;iBACpD,CAAA;YACH,CAAC;iBAAM,CAAC;gBACN,MAAM,IAAI,KAAK,CAAC,yCAAyC,SAAS,EAAE,CAAC,CAAA;YACvE,CAAC;QACH,CAAC;aAAM,CAAC;YACN,MAAM,IAAI,KAAK,CAAC,wBAAwB,CAAC,CAAA;QAC3C,CAAC;IACH,CAAC;CACF;AAhGD,kCAgGC"}

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

@@ -14,7 +14,24 @@ import { AppRoute } from './appRoute';
 import { TurnContext } from '../turnContext';
 import { ResourceResponse } from '../connector-client';
 import { UserIdentity } from './oauth/userIdentity';
-type ApplicationEventHandler<TState extends TurnState> = (context: TurnContext, state: TState) => Promise<boolean>;
+export type ApplicationEventHandler<TState extends TurnState> = (context: TurnContext, state: TState) => Promise<boolean>;
+/**
+ * Executes the application logic for a given turn context.
+ *
+ * @param turnContext - The context for the current turn of the conversation.
+ * @returns A promise that resolves when the application logic has completed.
+ *
+ * @remarks
+ * This method is the entry point for processing a turn in the conversation.
+ * It delegates the actual processing to the `runInternal` method, which handles
+ * the core logic for routing and executing handlers.
+ *
+ * Example usage:
+ * ```typescript
+ * const app = new AgentApplication();
+ * await app.run(turnContext);
+ * ```
+ */
 export declare class AgentApplication<TState extends TurnState> {
     protected readonly _options: AgentApplicationOptions<TState>;
     protected readonly _routes: AppRoute<TState>[];
@@ -27,17 +44,254 @@ export declare class AgentApplication<TState extends TurnState> {
     get adapter(): BaseAdapter;
     get userIdentity(): UserIdentity;
     get options(): AgentApplicationOptions<TState>;
+    /**
+     * Sets an error handler for the application.
+     *
+     * @param handler - The error handler function to be called when an error occurs.
+     * @returns The current instance of the application.
+     *
+     * @remarks
+     * 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:
+     * ```typescript
+     * app.error(async (context, error) => {
+     *   console.error(`An error occurred: ${error.message}`);
+     *   await context.sendActivity('Sorry, something went wrong!');
+     * });
+     * ```
+     */
     error(handler: (context: TurnContext, error: Error) => Promise<void>): this;
+    /**
+     * Adds a new route to the application for handling activities.
+     *
+     * @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.
+     * @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.
+     *
+     * Example usage:
+     * ```typescript
+     * app.addRoute(
+     *   async (context) => context.activity.type === ActivityTypes.Message,
+     *   async (context, state) => {
+     *     await context.sendActivity('I received your message');
+     *   }
+     * );
+     * ```
+     */
     addRoute(selector: RouteSelector, handler: RouteHandler<TState>): 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.
+     * @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:
+     * ```typescript
+     * app.activity(ActivityTypes.Message, async (context, state) => {
+     *   await context.sendActivity('I received your message');
+     * });
+     * ```
+     */
     activity(type: string | RegExp | RouteSelector | (string | RegExp | RouteSelector)[], handler: (context: TurnContext, state: TState) => Promise<void>): 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.
+     * @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:
+     * ```typescript
+     * app.conversationUpdate('membersAdded', async (context, state) => {
+     *   const membersAdded = context.activity.membersAdded;
+     *   for (const member of membersAdded) {
+     *     if (member.id !== context.activity.recipient.id) {
+     *       await context.sendActivity('Hello and welcome!');
+     *     }
+     *   }
+     * });
+     * ```
+     */
     conversationUpdate(event: ConversationUpdateEvents, handler: (context: TurnContext, state: TState) => Promise<void>): this;
+    /**
+     * Continues a conversation asynchronously.
+     * @param conversationReferenceOrContext - The conversation reference or turn context.
+     * @param logic - The logic to execute during the conversation.
+     * @returns A promise that resolves when the conversation logic has completed.
+     * @throws Error if the adapter is not configured.
+     */
     protected continueConversationAsync(conversationReferenceOrContext: ConversationReference | TurnContext, logic: (context: TurnContext) => Promise<void>): Promise<void>;
+    /**
+     * Adds a handler for message activities that match the specified keyword or pattern.
+     *
+     * @param keyword - The keyword, pattern, or selector function to match against message text.
+     *                  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.
+     * @returns The current instance of the application.
+     *
+     * @remarks
+     * This method allows you to register handlers for specific message patterns.
+     * If keyword is a string, it matches messages containing that string.
+     * 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:
+     * ```typescript
+     * app.message('hello', async (context, state) => {
+     *   await context.sendActivity('Hello there!');
+     * });
+     *
+     * app.message(/help., async (context, state) => {
+     *   await context.sendActivity('How can I help you?');
+     * });
+     * ```
+     */
     message(keyword: string | RegExp | RouteSelector | (string | RegExp | RouteSelector)[], handler: (context: TurnContext, state: TState) => Promise<void>): this;
+    /**
+     * Sets a handler to be called when a user successfully signs in.
+     *
+     * @param handler - The handler function to be called after successful sign-in.
+     * @returns The current instance of the application.
+     * @throws Error if authentication options were not configured.
+     *
+     * @remarks
+     * This method allows you to perform actions after a user has successfully authenticated.
+     * The handler will receive the turn context and state.
+     *
+     * Example usage:
+     * ```typescript
+     * app.onSignInSuccess(async (context, state) => {
+     *   await context.sendActivity('You have successfully signed in!');
+     * });
+     * ```
+     */
     onSignInSuccess(handler: (context: TurnContext, state: TurnState) => void): this;
-    run(turnContext: TurnContext): Promise<boolean>;
+    /**
+     * Executes the application logic for a given turn context.
+     *
+     * @param turnContext - The context for the current turn of the conversation.
+     * @returns A promise that resolves when the application logic has completed.
+     *
+     * @remarks
+     * This method is the entry point for processing a turn in the conversation.
+     * It delegates the actual processing to the `runInternal` method, which handles
+     * the core logic for routing and executing handlers.
+     *
+     * Example usage:
+     * ```typescript
+     * const app = new AgentApplication();
+     * await app.run(turnContext);
+     * ```
+     */
+    run(turnContext: TurnContext): Promise<void>;
+    /**
+     * Executes the application logic for a given turn context.
+     * @private
+     * @param turnContext - The context for the current turn of the conversation.
+     * @returns A promise that resolves to true if a handler was executed, false otherwise.
+     *
+     * @remarks
+     * This method is the core logic for processing a turn in the conversation.
+     * It handles routing and executing handlers based on the activity type and content.
+     */
+    runInternal(turnContext: TurnContext): Promise<boolean>;
+    /**
+     * Sends a proactive message to a conversation.
+     *
+     * @param context - The turn context or conversation reference to use.
+     * @param activityOrText - The activity or text to send.
+     * @param speak - Optional text to be spoken by the bot on a speech-enabled channel.
+     * @param inputHint - Optional input hint for the activity.
+     * @returns A promise that resolves to the resource response from sending the activity.
+     *
+     * @remarks
+     * This method allows you to send messages proactively to a conversation, outside the normal turn flow.
+     *
+     * Example usage:
+     * ```typescript
+     * // With conversation reference
+     * await app.sendProactiveActivity(conversationReference, 'Important notification!');
+     *
+     * // From an existing context
+     * await app.sendProactiveActivity(turnContext, 'Important notification!');
+     * ```
+     */
     sendProactiveActivity(context: TurnContext | ConversationReference, activityOrText: string | Activity, speak?: string, inputHint?: string): Promise<ResourceResponse | undefined>;
+    /**
+     * Starts a typing indicator timer for the current turn context.
+     *
+     * @param context - The turn context for the current conversation.
+     * @returns void
+     *
+     * @remarks
+     * This method starts a timer that sends typing activity indicators to the user
+     * at regular intervals. The typing indicator continues until a message is sent
+     * or the timer is explicitly stopped.
+     *
+     * 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:
+     * ```typescript
+     * app.startTypingTimer(turnContext);
+     * // Do some processing...
+     * await turnContext.sendActivity('Response after processing');
+     * // Typing timer automatically stops when sending a message
+     * ```
+     */
     startTypingTimer(context: TurnContext): void;
+    /**
+     * Stops the typing indicator timer if it's currently running.
+     *
+     * @returns void
+     *
+     * @remarks
+     * This method clears the typing indicator timer to prevent further typing indicators
+     * 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:
+     * ```typescript
+     * app.startTypingTimer(turnContext);
+     * // Do some processing...
+     * app.stopTypingTimer(); // Manually stop the typing indicator
+     * ```
+     */
     stopTypingTimer(): void;
+    /**
+     * Adds an event handler for specified turn events.
+     *
+     * @param event - The turn event(s) to handle. Can be 'beforeTurn', 'afterTurn', or other custom events.
+     * @param handler - The handler function that will be called when the event occurs.
+     * @returns The current instance of the application.
+     *
+     * @remarks
+     * Turn events allow you to execute logic before or after the main turn processing.
+     * Handlers added for 'beforeTurn' are executed before routing logic.
+     * Handlers added for 'afterTurn' are executed after routing logic.
+     *
+     * Example usage:
+     * ```typescript
+     * app.turn('beforeTurn', async (context, state) => {
+     *   console.log('Processing before turn');
+     *   return true; // Continue execution
+     * });
+     * ```
+     */
     turn(event: TurnEvents | TurnEvents[], handler: (context: TurnContext, state: TState) => Promise<boolean>): this;
     protected callEventHandlers(context: TurnContext, state: TState, handlers: ApplicationEventHandler<TState>[]): Promise<boolean>;
     protected startLongRunningCall(context: TurnContext, handler: (context: TurnContext) => Promise<boolean>): Promise<boolean>;
@@ -45,4 +299,3 @@ export declare class AgentApplication<TState extends TurnState> {
     private createConversationUpdateSelector;
     private createMessageSelector;
 }
-export {};

package/dist/src/app/agentApplication.js

@@ -12,6 +12,23 @@ const userIdentity_1 = require("./oauth/userIdentity");
 const storage_1 = require("../storage");
 const logger = (0, logger_1.debug)('agents:agent-application');
 const TYPING_TIMER_DELAY = 1000;
+/**
+ * Executes the application logic for a given turn context.
+ *
+ * @param turnContext - The context for the current turn of the conversation.
+ * @returns A promise that resolves when the application logic has completed.
+ *
+ * @remarks
+ * This method is the entry point for processing a turn in the conversation.
+ * It delegates the actual processing to the `runInternal` method, which handles
+ * the core logic for routing and executing handlers.
+ *
+ * Example usage:
+ * ```typescript
+ * const app = new AgentApplication();
+ * await app.run(turnContext);
+ * ```
+ */
 class AgentApplication {
     constructor(options) {
         var _a;
@@ -49,16 +66,72 @@ class AgentApplication {
     get options() {
         return this._options;
     }
+    /**
+     * Sets an error handler for the application.
+     *
+     * @param handler - The error handler function to be called when an error occurs.
+     * @returns The current instance of the application.
+     *
+     * @remarks
+     * 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:
+     * ```typescript
+     * app.error(async (context, error) => {
+     *   console.error(`An error occurred: ${error.message}`);
+     *   await context.sendActivity('Sorry, something went wrong!');
+     * });
+     * ```
+     */
     error(handler) {
         if (this._adapter) {
             this._adapter.onTurnError = handler;
         }
         return this;
     }
+    /**
+     * Adds a new route to the application for handling activities.
+     *
+     * @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.
+     * @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.
+     *
+     * Example usage:
+     * ```typescript
+     * app.addRoute(
+     *   async (context) => context.activity.type === ActivityTypes.Message,
+     *   async (context, state) => {
+     *     await context.sendActivity('I received your message');
+     *   }
+     * );
+     * ```
+     */
     addRoute(selector, handler) {
         this._routes.push({ selector, handler });
         return 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.
+     * @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:
+     * ```typescript
+     * app.activity(ActivityTypes.Message, async (context, state) => {
+     *   await context.sendActivity('I received your message');
+     * });
+     * ```
+     */
     activity(type, handler) {
         (Array.isArray(type) ? type : [type]).forEach((t) => {
             const selector = this.createActivitySelector(t);
@@ -66,6 +139,29 @@ class AgentApplication {
         });
         return 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.
+     * @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:
+     * ```typescript
+     * app.conversationUpdate('membersAdded', async (context, state) => {
+     *   const membersAdded = context.activity.membersAdded;
+     *   for (const member of membersAdded) {
+     *     if (member.id !== context.activity.recipient.id) {
+     *       await context.sendActivity('Hello and welcome!');
+     *     }
+     *   }
+     * });
+     * ```
+     */
     conversationUpdate(event, handler) {
         if (typeof handler !== 'function') {
             throw new Error(`ConversationUpdate 'handler' for ${event} is ${typeof handler}. Type of 'handler' must be a function.`);
@@ -74,6 +170,13 @@ class AgentApplication {
         this.addRoute(selector, handler);
         return this;
     }
+    /**
+     * Continues a conversation asynchronously.
+     * @param conversationReferenceOrContext - The conversation reference or turn context.
+     * @param logic - The logic to execute during the conversation.
+     * @returns A promise that resolves when the conversation logic has completed.
+     * @throws Error if the adapter is not configured.
+     */
     async continueConversationAsync(conversationReferenceOrContext, logic) {
         if (!this._adapter) {
             throw new Error("You must configure the Application with an 'adapter' before calling Application.continueConversationAsync()");
@@ -90,6 +193,31 @@ class AgentApplication {
         }
         await this._adapter.continueConversation(reference, logic);
     }
+    /**
+     * Adds a handler for message activities that match the specified keyword or pattern.
+     *
+     * @param keyword - The keyword, pattern, or selector function to match against message text.
+     *                  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.
+     * @returns The current instance of the application.
+     *
+     * @remarks
+     * This method allows you to register handlers for specific message patterns.
+     * If keyword is a string, it matches messages containing that string.
+     * 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:
+     * ```typescript
+     * app.message('hello', async (context, state) => {
+     *   await context.sendActivity('Hello there!');
+     * });
+     *
+     * app.message(/help., async (context, state) => {
+     *   await context.sendActivity('How can I help you?');
+     * });
+     * ```
+     */
     message(keyword, handler) {
         (Array.isArray(keyword) ? keyword : [keyword]).forEach((k) => {
             const selector = this.createMessageSelector(k);
@@ -97,6 +225,24 @@ class AgentApplication {
         });
         return this;
     }
+    /**
+     * Sets a handler to be called when a user successfully signs in.
+     *
+     * @param handler - The handler function to be called after successful sign-in.
+     * @returns The current instance of the application.
+     * @throws Error if authentication options were not configured.
+     *
+     * @remarks
+     * This method allows you to perform actions after a user has successfully authenticated.
+     * The handler will receive the turn context and state.
+     *
+     * Example usage:
+     * ```typescript
+     * app.onSignInSuccess(async (context, state) => {
+     *   await context.sendActivity('You have successfully signed in!');
+     * });
+     * ```
+     */
     onSignInSuccess(handler) {
         if (this._userIdentity) {
             this._userIdentity.onSignInSuccess(handler);
@@ -106,7 +252,37 @@ class AgentApplication {
         }
         return this;
     }
+    /**
+     * Executes the application logic for a given turn context.
+     *
+     * @param turnContext - The context for the current turn of the conversation.
+     * @returns A promise that resolves when the application logic has completed.
+     *
+     * @remarks
+     * This method is the entry point for processing a turn in the conversation.
+     * It delegates the actual processing to the `runInternal` method, which handles
+     * the core logic for routing and executing handlers.
+     *
+     * Example usage:
+     * ```typescript
+     * const app = new AgentApplication();
+     * await app.run(turnContext);
+     * ```
+     */
     async run(turnContext) {
+        await this.runInternal(turnContext);
+    }
+    /**
+     * Executes the application logic for a given turn context.
+     * @private
+     * @param turnContext - The context for the current turn of the conversation.
+     * @returns A promise that resolves to true if a handler was executed, false otherwise.
+     *
+     * @remarks
+     * This method is the core logic for processing a turn in the conversation.
+     * It handles routing and executing handlers based on the activity type and content.
+     */
+    async runInternal(turnContext) {
         return await this.startLongRunningCall(turnContext, async (context) => {
             var _a, _b;
             this.startTypingTimer(context);
@@ -156,6 +332,27 @@ class AgentApplication {
             }
         });
     }
+    /**
+     * Sends a proactive message to a conversation.
+     *
+     * @param context - The turn context or conversation reference to use.
+     * @param activityOrText - The activity or text to send.
+     * @param speak - Optional text to be spoken by the bot on a speech-enabled channel.
+     * @param inputHint - Optional input hint for the activity.
+     * @returns A promise that resolves to the resource response from sending the activity.
+     *
+     * @remarks
+     * This method allows you to send messages proactively to a conversation, outside the normal turn flow.
+     *
+     * Example usage:
+     * ```typescript
+     * // With conversation reference
+     * await app.sendProactiveActivity(conversationReference, 'Important notification!');
+     *
+     * // From an existing context
+     * await app.sendProactiveActivity(turnContext, 'Important notification!');
+     * ```
+     */
     async sendProactiveActivity(context, activityOrText, speak, inputHint) {
         let response;
         await this.continueConversationAsync(context, async (ctx) => {
@@ -163,6 +360,28 @@ class AgentApplication {
         });
         return response;
     }
+    /**
+     * Starts a typing indicator timer for the current turn context.
+     *
+     * @param context - The turn context for the current conversation.
+     * @returns void
+     *
+     * @remarks
+     * This method starts a timer that sends typing activity indicators to the user
+     * at regular intervals. The typing indicator continues until a message is sent
+     * or the timer is explicitly stopped.
+     *
+     * 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:
+     * ```typescript
+     * app.startTypingTimer(turnContext);
+     * // Do some processing...
+     * await turnContext.sendActivity('Response after processing');
+     * // Typing timer automatically stops when sending a message
+     * ```
+     */
     startTypingTimer(context) {
         if (context.activity.type === agents_activity_1.ActivityTypes.Message && !this._typingTimer) {
             let timerRunning = true;
@@ -199,12 +418,49 @@ class AgentApplication {
             this._typingTimer = setTimeout(onTimeout, TYPING_TIMER_DELAY);
         }
     }
+    /**
+     * Stops the typing indicator timer if it's currently running.
+     *
+     * @returns void
+     *
+     * @remarks
+     * This method clears the typing indicator timer to prevent further typing indicators
+     * 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:
+     * ```typescript
+     * app.startTypingTimer(turnContext);
+     * // Do some processing...
+     * app.stopTypingTimer(); // Manually stop the typing indicator
+     * ```
+     */
     stopTypingTimer() {
         if (this._typingTimer) {
             clearTimeout(this._typingTimer);
             this._typingTimer = undefined;
         }
     }
+    /**
+     * Adds an event handler for specified turn events.
+     *
+     * @param event - The turn event(s) to handle. Can be 'beforeTurn', 'afterTurn', or other custom events.
+     * @param handler - The handler function that will be called when the event occurs.
+     * @returns The current instance of the application.
+     *
+     * @remarks
+     * Turn events allow you to execute logic before or after the main turn processing.
+     * Handlers added for 'beforeTurn' are executed before routing logic.
+     * Handlers added for 'afterTurn' are executed after routing logic.
+     *
+     * Example usage:
+     * ```typescript
+     * app.turn('beforeTurn', async (context, state) => {
+     *   console.log('Processing before turn');
+     *   return true; // Continue execution
+     * });
+     * ```
+     */
     turn(event, handler) {
         (Array.isArray(event) ? event : [event]).forEach((e) => {
             switch (e) {