@microsoft/agents-hosting 0.2.9-g361635b71c → 0.2.14

package/src/activityHandler.ts

@@ -17,106 +17,219 @@ import { tokenResponseEventName } from './tokenResponseEventName'
 /** Symbol key for invoke response */
 export const INVOKE_RESPONSE_KEY = Symbol('invokeResponse')
 
-/** Type definition for agent handler function */
+/**
+ * Type definition for agent handler function
+ * @param context - The turn context for the current turn of conversation
+ * @param next - The function to call to continue to the next middleware or handler
+ * @returns A promise representing the asynchronous operation
+ */
 export type AgentHandler = (context: TurnContext, next: () => Promise<void>) => Promise<any>
 
 const logger = debug('agents:activity-handler')
 
-/** * Handles various activity types and dispatches them to the appropriate handlers. */
+/**
+ * Handles incoming activities from channels and dispatches them to the appropriate handlers.
+ *
+ * The ActivityHandler provides a foundation for handling different types of activities
+ * in an agent application. It processes various activity types such as messages, conversation updates,
+ * message reactions, etc., and routes them to the appropriate handler methods.
+ *
+ * Developers can extend this class to implement custom handlers for specific activity types
+ * or override existing ones to customize the behavior.
+ */
 export class ActivityHandler {
+  /**
+   * Collection of handlers registered for different activity types
+   * @protected
+   */
   protected readonly handlers: { [type: string]: AgentHandler[] } = {}
 
-  /** * Registers a handler for the Turn activity type. */
+  /**
+   * Registers a handler for the Turn activity type.
+   * This is called for all activities regardless of type.
+   * @param handler - The handler to register
+   * @returns The current instance for method chaining
+   */
   onTurn (handler: AgentHandler): this {
     return this.on('Turn', handler)
   }
 
-  /** * Registers a handler for the MembersAdded activity type. */
+  /**
+   * Registers a handler for the MembersAdded activity type.
+   * This is called when new members are added to the conversation.
+   * @param handler - The handler to register
+   * @returns The current instance for method chaining
+   */
   onMembersAdded (handler: AgentHandler): this {
     return this.on('MembersAdded', handler)
   }
 
-  /** * Registers a handler for the MembersRemoved activity type. */
+  /**
+   * Registers a handler for the MembersRemoved activity type.
+   * This is called when members are removed from the conversation.
+   * @param handler - The handler to register
+   * @returns The current instance for method chaining
+   */
   onMembersRemoved (handler: AgentHandler): this {
     return this.on('MembersRemoved', handler)
   }
 
-  /** * Registers a handler for the Message activity type. */
+  /**
+   * Registers a handler for the Message activity type.
+   * This is called when a message is received from the user.
+   * @param handler - The handler to register
+   * @returns The current instance for method chaining
+   */
   onMessage (handler: AgentHandler): this {
     return this.on('Message', handler)
   }
 
-  /** * Registers a handler for the MessageUpdate activity type. */
+  /**
+   * Registers a handler for the MessageUpdate activity type.
+   * This is called when a message is updated.
+   * @param handler - The handler to register
+   * @returns The current instance for method chaining
+   */
   onMessageUpdate (handler: AgentHandler): this {
     return this.on('MessageUpdate', handler)
   }
 
-  /** * Registers a handler for the MessageDelete activity type. */
+  /**
+   * Registers a handler for the MessageDelete activity type.
+   * This is called when a message is deleted.
+   * @param handler - The handler to register
+   * @returns The current instance for method chaining
+   */
   onMessageDelete (handler: AgentHandler): this {
     return this.on('MessageDelete', handler)
   }
 
-  /** * Registers a handler for the ConversationUpdate activity type. */
+  /**
+   * Registers a handler for the ConversationUpdate activity type.
+   * This is called when the conversation is updated, such as when members are added or removed.
+   * @param handler - The handler to register
+   * @returns The current instance for method chaining
+   */
   onConversationUpdate (handler: AgentHandler): this {
     return this.on('ConversationUpdate', handler)
   }
 
-  /** * Registers a handler for the MessageReaction activity type. */
+  /**
+   * Registers a handler for the MessageReaction activity type.
+   * This is called when reactions are added or removed from messages.
+   * @param handler - The handler to register
+   * @returns The current instance for method chaining
+   */
   onMessageReaction (handler: AgentHandler): this {
     return this.on('MessageReaction', handler)
   }
 
-  /** * Registers a handler for the ReactionsAdded activity type. */
+  /**
+   * Registers a handler for the ReactionsAdded activity type.
+   * This is called when reactions are added to messages.
+   * @param handler - The handler to register
+   * @returns The current instance for method chaining
+   */
   onReactionsAdded (handler: AgentHandler): this {
     return this.on('ReactionsAdded', handler)
   }
 
-  /** * Registers a handler for the ReactionsRemoved activity type. */
+  /**
+   * Registers a handler for the ReactionsRemoved activity type.
+   * This is called when reactions are removed from messages.
+   * @param handler - The handler to register
+   * @returns The current instance for method chaining
+   */
   onReactionsRemoved (handler: AgentHandler): this {
     return this.on('ReactionsRemoved', handler)
   }
 
-  /** * Registers a handler for the Typing activity type. */
+  /**
+   * Registers a handler for the Typing activity type.
+   * This is called when a typing indicator is received.
+   * @param handler - The handler to register
+   * @returns The current instance for method chaining
+   */
   onTyping (handler: AgentHandler): this {
     return this.on('Typing', handler)
   }
 
-  /** * Registers a handler for the InstallationUpdate activity type. */
+  /**
+   * Registers a handler for the InstallationUpdate activity type.
+   * This is called when an agent is installed or uninstalled.
+   * @param handler - The handler to register
+   * @returns The current instance for method chaining
+   */
   onInstallationUpdate (handler: AgentHandler): this {
     return this.on('InstallationUpdate', handler)
   }
 
-  /** * Registers a handler for the InstallationUpdateAdd activity type. */
+  /**
+   * Registers a handler for the InstallationUpdateAdd activity type.
+   * This is called when an agent is installed or upgraded.
+   * @param handler - The handler to register
+   * @returns The current instance for method chaining
+   */
   onInstallationUpdateAdd (handler: AgentHandler): this {
     return this.on('InstallationUpdateAdd', handler)
   }
 
-  /** * Registers a handler for the InstallationUpdateRemove activity type. */
+  /**
+   * Registers a handler for the InstallationUpdateRemove activity type.
+   * This is called when an agent is uninstalled or downgraded.
+   * @param handler - The handler to register
+   * @returns The current instance for method chaining
+   */
   onInstallationUpdateRemove (handler: AgentHandler): this {
     return this.on('InstallationUpdateRemove', handler)
   }
 
-  /** * Registers a handler for the EndOfConversation activity type. */
+  /**
+   * Registers a handler for the EndOfConversation activity type.
+   * This is called when the conversation ends.
+   * @param handler - The handler to register
+   * @returns The current instance for method chaining
+   */
   onEndOfConversation (handler: AgentHandler): this {
     return this.on('EndOfConversation', handler)
   }
 
-  /** * Registers a handler for the SignInInvoke activity type. */
+  /**
+   * Registers a handler for the SignInInvoke activity type.
+   * This is called when a sign-in is requested.
+   * @param handler - The handler to register
+   * @returns The current instance for method chaining
+   */
   onSignInInvoke (handler: AgentHandler): this {
     return this.on('SignInInvoke', handler)
   }
 
-  /** * Registers a handler for unrecognized activity types. */
+  /**
+   * Registers a handler for unrecognized activity types.
+   * This is called when an activity type is not recognized.
+   * @param handler - The handler to register
+   * @returns The current instance for method chaining
+   */
   onUnrecognizedActivityType (handler: AgentHandler): this {
     return this.on('UnrecognizedActivityType', handler)
   }
 
-  /** * Registers an activity event handler for the _dialog_ event, emitted as the last event for an incoming activity. */
+  /**
+   * Registers an activity event handler for the _dialog_ event, emitted as the last event for an incoming activity.
+   * This handler is called after all other handlers have been processed.
+   * @param handler - The handler to register
+   * @returns The current instance for method chaining
+   */
   onDialog (handler: AgentHandler): this {
     return this.on('Default', handler)
   }
 
-  /** * Runs the activity handler pipeline. */
+  /**
+   * Runs the activity handler pipeline.
+   * This method is called to process an incoming activity through the registered handlers.
+   * @param context - The turn context for the current turn of conversation
+   * @throws Error if context is missing, activity is missing, or activity type is missing
+   */
   async run (context: TurnContext): Promise<void> {
     if (!context) throw new Error('Missing TurnContext parameter')
     if (!context.activity) throw new Error('TurnContext does not include an activity')
@@ -125,7 +238,12 @@ export class ActivityHandler {
     await this.onTurnActivity(context)
   }
 
-  /** * Handles the Turn activity. */
+  /**
+   * Handles the Turn activity.
+   * This method is called for every activity type and dispatches to the appropriate handler.
+   * @param context - The turn context for the current turn of conversation
+   * @protected
+   */
   protected async onTurnActivity (context: TurnContext): Promise<void> {
     switch (context.activity.type) {
       case ActivityTypes.Message:
@@ -167,38 +285,69 @@ export class ActivityHandler {
     }
   }
 
-  /** * Handles the Message activity. */
+  /**
+   * Handles the Message activity.
+   * This method processes incoming message activities.
+   * @param context - The turn context for the current turn of conversation
+   * @protected
+   */
   protected async onMessageActivity (context: TurnContext): Promise<void> {
     await this.handle(context, 'Message', this.defaultNextEvent(context))
   }
 
-  /** * Handles the MessageUpdate activity. */
+  /**
+   * Handles the MessageUpdate activity.
+   * This method processes message update activities.
+   * @param context - The turn context for the current turn of conversation
+   * @protected
+   */
   protected async onMessageUpdateActivity (context: TurnContext): Promise<void> {
     await this.handle(context, 'MessageUpdate', async () => {
       await this.dispatchMessageUpdateActivity(context)
     })
   }
 
-  /** * Handles the MessageDelete activity. */
+  /**
+   * Handles the MessageDelete activity.
+   * This method processes message deletion activities.
+   * @param context - The turn context for the current turn of conversation
+   * @protected
+   */
   protected async onMessageDeleteActivity (context: TurnContext): Promise<void> {
     await this.handle(context, 'MessageDelete', async () => {
       await this.dispatchMessageDeleteActivity(context)
     })
   }
 
-  /** * Handles the ConversationUpdate activity. */
+  /**
+   * Handles the ConversationUpdate activity.
+   * This method processes conversation update activities.
+   * @param context - The turn context for the current turn of conversation
+   * @protected
+   */
   protected async onConversationUpdateActivity (context: TurnContext): Promise<void> {
     await this.handle(context, 'ConversationUpdate', async () => {
       await this.dispatchConversationUpdateActivity(context)
     })
   }
 
-  /** * Handles the SignInInvoke activity. */
+  /**
+   * Handles the SignInInvoke activity.
+   * This method processes sign-in invoke activities.
+   * @param context - The turn context for the current turn of conversation
+   * @protected
+   */
   protected async onSigninInvokeActivity (context: TurnContext): Promise<void> {
     await this.handle(context, 'SignInInvoke', this.defaultNextEvent(context))
   }
 
-  /** * Handles the Invoke activity. */
+  /**
+   * Handles the Invoke activity.
+   * This method processes various invoke activities based on their name.
+   * @param context - The turn context for the current turn of conversation
+   * @returns An invoke response object with status and body
+   * @protected
+   */
   protected async onInvokeActivity (context: TurnContext): Promise<InvokeResponse> {
     try {
       switch (context.activity.name) {
@@ -233,7 +382,14 @@ export class ActivityHandler {
     }
   }
 
-  /** * Handles the AdaptiveCardInvoke activity. */
+  /**
+   * Handles the AdaptiveCardInvoke activity.
+   * This method processes adaptive card invoke activities.
+   * @param _context - The turn context for the current turn of conversation
+   * @param _invokeValue - The adaptive card invoke value
+   * @returns A promise that resolves to an adaptive card invoke response
+   * @protected
+   */
   protected async onAdaptiveCardInvoke (
     _context: TurnContext,
     _invokeValue: AdaptiveCardInvokeValue
@@ -241,12 +397,25 @@ export class ActivityHandler {
     return await Promise.reject(new InvokeException(StatusCodes.NOT_IMPLEMENTED))
   }
 
-  /** * Handles the SearchInvoke activity. */
+  /**
+   * Handles the SearchInvoke activity.
+   * This method processes search invoke activities.
+   * @param _context - The turn context for the current turn of conversation
+   * @param _invokeValue - The search invoke value
+   * @returns A promise that resolves to a search invoke response
+   * @protected
+   */
   protected async onSearchInvoke (_context: TurnContext, _invokeValue: SearchInvokeValue): Promise<SearchInvokeResponse> {
     return await Promise.reject(new InvokeException(StatusCodes.NOT_IMPLEMENTED))
   }
 
-  /** * Retrieves the SearchInvoke value from the activity. */
+  /**
+   * Retrieves the SearchInvoke value from the activity.
+   * This method extracts and validates the search invoke value from an activity.
+   * @param activity - The activity to extract the search invoke value from
+   * @returns The validated search invoke value
+   * @private
+   */
   private getSearchInvokeValue (activity: Activity): SearchInvokeValue {
     const value = activity.value as SearchInvokeValue
     if (!value) {
@@ -280,7 +449,13 @@ export class ActivityHandler {
     return value
   }
 
-  /** * Retrieves the AdaptiveCardInvoke value from the activity. */
+  /**
+   * Retrieves the AdaptiveCardInvoke value from the activity.
+   * This method extracts and validates the adaptive card invoke value from an activity.
+   * @param activity - The activity to extract the adaptive card invoke value from
+   * @returns The validated adaptive card invoke value
+   * @private
+   */
   private getAdaptiveCardInvokeValue (activity: Activity): AdaptiveCardInvokeValue {
     const value = activity.value as AdaptiveCardInvokeValue
     if (!value) {
@@ -318,7 +493,15 @@ export class ActivityHandler {
     }
   }
 
-  /** * Creates an error response for AdaptiveCardInvoke. */
+  /**
+   * Creates an error response for AdaptiveCardInvoke.
+   * This method creates an error response for adaptive card invoke activities.
+   * @param statusCode - The HTTP status code for the response
+   * @param code - The error code
+   * @param message - The error message
+   * @returns An adaptive card invoke error response
+   * @private
+   */
   private createAdaptiveCardInvokeErrorResponse (
     statusCode: StatusCodes,
     code: string,
@@ -331,24 +514,44 @@ export class ActivityHandler {
     }
   }
 
-  /** * Handles the MessageReaction activity. */
+  /**
+   * Handles the MessageReaction activity.
+   * This method processes message reaction activities.
+   * @param context - The turn context for the current turn of conversation
+   * @protected
+   */
   protected async onMessageReactionActivity (context: TurnContext): Promise<void> {
     await this.handle(context, 'MessageReaction', async () => {
       await this.dispatchMessageReactionActivity(context)
     })
   }
 
-  /** * Handles the EndOfConversation activity. */
+  /**
+   * Handles the EndOfConversation activity.
+   * This method processes end of conversation activities.
+   * @param context - The turn context for the current turn of conversation
+   * @protected
+   */
   protected async onEndOfConversationActivity (context: TurnContext): Promise<void> {
     await this.handle(context, 'EndOfConversation', this.defaultNextEvent(context))
   }
 
-  /** * Handles the Typing activity. */
+  /**
+   * Handles the Typing activity.
+   * This method processes typing indicator activities.
+   * @param context - The turn context for the current turn of conversation
+   * @protected
+   */
   protected async onTypingActivity (context: TurnContext): Promise<void> {
     await this.handle(context, 'Typing', this.defaultNextEvent(context))
   }
 
-  /** * Handles the InstallationUpdate activity. */
+  /**
+   * Handles the InstallationUpdate activity.
+   * This method processes installation update activities.
+   * @param context - The turn context for the current turn of conversation
+   * @protected
+   */
   protected async onInstallationUpdateActivity (context: TurnContext): Promise<void> {
     switch (context.activity.action) {
       case 'add':
@@ -361,12 +564,22 @@ export class ActivityHandler {
     }
   }
 
-  /** * Handles unrecognized activity types. */
+  /**
+   * Handles unrecognized activity types.
+   * This method processes activities with unrecognized types.
+   * @param context - The turn context for the current turn of conversation
+   * @protected
+   */
   protected async onUnrecognizedActivity (context: TurnContext): Promise<void> {
     await this.handle(context, 'UnrecognizedActivityType', this.defaultNextEvent(context))
   }
 
-  /** * Dispatches the ConversationUpdate activity. */
+  /**
+   * Dispatches the ConversationUpdate activity.
+   * This method dispatches conversation update activities to the appropriate handlers.
+   * @param context - The turn context for the current turn of conversation
+   * @protected
+   */
   protected async dispatchConversationUpdateActivity (context: TurnContext): Promise<void> {
     if ((context.activity.membersAdded != null) && context.activity.membersAdded.length > 0) {
       await this.handle(context, 'MembersAdded', this.defaultNextEvent(context))
@@ -377,7 +590,12 @@ export class ActivityHandler {
     }
   }
 
-  /** * Dispatches the MessageReaction activity. */
+  /**
+   * Dispatches the MessageReaction activity.
+   * This method dispatches message reaction activities to the appropriate handlers.
+   * @param context - The turn context for the current turn of conversation
+   * @protected
+   */
   protected async dispatchMessageReactionActivity (context: TurnContext): Promise<void> {
     if ((context.activity.reactionsAdded != null) || (context.activity.reactionsRemoved != null)) {
       if (context.activity.reactionsAdded?.length) {
@@ -391,18 +609,32 @@ export class ActivityHandler {
     }
   }
 
-  /** * Dispatches the MessageUpdate activity. */
+  /**
+   * Dispatches the MessageUpdate activity.
+   * This method dispatches message update activities to the appropriate handlers.
+   * @param context - The turn context for the current turn of conversation
+   * @protected
+   */
   protected async dispatchMessageUpdateActivity (context: TurnContext): Promise<void> {
     await this.defaultNextEvent(context)()
   }
 
-  /** * Dispatches the MessageDelete activity. */
+  /**
+   * Dispatches the MessageDelete activity.
+   * This method dispatches message delete activities to the appropriate handlers.
+   * @param context - The turn context for the current turn of conversation
+   * @protected
+   */
   protected async dispatchMessageDeleteActivity (context: TurnContext): Promise<void> {
     await this.defaultNextEvent(context)()
   }
 
   /**
    * Returns the default next event handler.
+   * This method creates a function that calls the default handler.
+   * @param context - The turn context for the current turn of conversation
+   * @returns A function that calls the default handler
+   * @protected
    */
   protected defaultNextEvent (context: TurnContext): () => Promise<void> {
     const defaultHandler = async (): Promise<void> => {
@@ -413,7 +645,14 @@ export class ActivityHandler {
     return defaultHandler
   }
 
-  /** * Registers a handler for a specific activity type. */
+  /**
+   * Registers a handler for a specific activity type.
+   * This method adds a handler to the list of handlers for a specific activity type.
+   * @param type - The activity type to register the handler for
+   * @param handler - The handler to register
+   * @returns The current instance for method chaining
+   * @protected
+   */
   protected on (type: string, handler: AgentHandler) {
     if (!this.handlers[type]) {
       this.handlers[type] = [handler]
@@ -423,7 +662,15 @@ export class ActivityHandler {
     return this
   }
 
-  /** * Executes the handlers for a specific activity type. */
+  /**
+   * Executes the handlers for a specific activity type.
+   * This method calls each registered handler for the specified activity type.
+   * @param context - The turn context for the current turn of conversation
+   * @param type - The activity type to handle
+   * @param onNext - The function to call when all handlers have been executed
+   * @returns The value returned by the last handler
+   * @protected
+   */
   protected async handle (context: TurnContext, type: string, onNext: () => Promise<void>): Promise<any> {
     let returnValue: any = null
     async function runHandler (index: number): Promise<void> {
@@ -445,12 +692,23 @@ export class ActivityHandler {
     return returnValue
   }
 
-  /** * Creates an InvokeResponse object. */
+  /**
+   * Creates an InvokeResponse object.
+   * This static method creates an invoke response with the specified body.
+   * @param body - The body of the response
+   * @returns An invoke response object with status and body
+   * @protected
+   */
   protected static createInvokeResponse (body?: any): InvokeResponse {
     return { status: 200, body }
   }
 
-  /** * Dispatches the Event activity. */
+  /**
+   * Dispatches the Event activity.
+   * This method dispatches event activities to the appropriate handlers.
+   * @param context - The turn context for the current turn of conversation
+   * @protected
+   */
   protected async dispatchEventActivity (context: TurnContext): Promise<void> {
     if (context.activity.name === tokenResponseEventName) {
       await this.handle(context, 'TokenResponseEvent', this.defaultNextEvent(context))

package/src/agent-client/agentClient.ts

@@ -7,24 +7,66 @@ import { TurnContext } from '../turnContext'
 
 const logger = debug('agents:agent-client')
 
+/**
+ * Configuration settings required to connect to an agent endpoint.
+ */
 export interface AgentClientConfig {
-  endPoint: string
-  clientId: string
-  serviceUrl: string
+  /**
+   * The URL endpoint where activities will be sent to the agent
+   */
+  endPoint: string;
+  /**
+   * The client ID of the target agent
+   */
+  clientId: string;
+  /**
+   * The service URL used for communication with the agent
+   */
+  serviceUrl: string;
 }
 
+/**
+ * Data structure to store conversation state for agent interactions
+ */
 export interface ConversationData {
-  nameRequested: boolean
-  conversationReference: ConversationReference
+  /**
+   * Flag indicating whether a name was requested from the agent
+   */
+  nameRequested: boolean;
+  /**
+   * Reference to the conversation for maintaining context across interactions
+   */
+  conversationReference: ConversationReference;
 }
 
+/**
+ * Client for communicating with other agents through HTTP requests.
+ * Manages configuration, authentication, and activity exchange with target agents.
+ */
 export class AgentClient {
+  /** Configuration settings for the agent client */
   agentClientConfig: AgentClientConfig
 
+  /**
+   * 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
+   */
   public constructor (agentConfigKey: string) {
     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
+   */
   public async postActivity (activity: Activity, authConfig: AuthConfiguration, conversationState: ConversationState, context: TurnContext): Promise<string> {
     const activityCopy = activity.clone()
     activityCopy.serviceUrl = this.agentClientConfig.serviceUrl
@@ -72,6 +114,14 @@ export 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
+   */
   private loadAgentClientConfig (agentName: string): AgentClientConfig {
     if (agentName) {
       if (process.env[`${agentName}_endpoint`] !== undefined &&