@microsoft/agents-hosting 0.2.9-g361635b71c → 0.2.14

package/src/turnContext.ts

@@ -8,22 +8,37 @@ import { AttachmentInfo } from './connector-client/attachmentInfo'
 import { AttachmentData } from './connector-client/attachmentData'
 
 /**
- * Defines a handler for sending activities.
+ * Defines a handler for processing and sending activities.
+ * Used for middleware that needs to intercept or modify activities being sent.
+ *
+ * @param context The current turn context
+ * @param activities The activities being sent
+ * @param next Function to call to continue the middleware chain
  */
 export type SendActivitiesHandler = (context: TurnContext, activities: Activity[], next: () => Promise<ResourceResponse[]>) => Promise<ResourceResponse[]>
 
 /**
  * Defines a handler for updating an activity.
+ * Used for middleware that needs to intercept or modify activity updates.
+ *
+ * @param context The current turn context
+ * @param activity The activity being updated
+ * @param next Function to call to continue the middleware chain
  */
 export type UpdateActivityHandler = (context: TurnContext, activity: Activity, next: () => Promise<void>) => Promise<void>
 
 /**
  * Defines a handler for deleting an activity.
+ * Used for middleware that needs to intercept or handle activity deletions.
+ *
+ * @param context The current turn context
+ * @param reference Reference to the activity being deleted
+ * @param next Function to call to continue the middleware chain
  */
 export type DeleteActivityHandler = (context: TurnContext, reference: ConversationReference, next: () => Promise<void>) => Promise<void>
 
 /**
- * Key for the agent callback handler.
+ * Key for the agent callback handler in TurnState collection.
  */
 export const AgentCallbackHandlerKey = 'agentCallbackHandler'
 
@@ -33,7 +48,20 @@ export const AgentCallbackHandlerKey = 'agentCallbackHandler'
 export interface TurnContext {}
 
 /**
- * Represents the context object for a turn of an Agent.
+ * Represents the context for a single turn in a conversation between a user and an agent.
+ *
+ * TurnContext is a central concept in the Agents framework - it contains:
+ * - The incoming activity that started the turn
+ * - Access to the adapter that can be used to send responses
+ * - A state collection for storing information during the turn
+ * - Methods for sending, updating, and deleting activities
+ * - Middleware hooks for intercepting activity operations
+ *
+ * The TurnContext object is created by the adapter when an activity is received
+ * and is passed to the agent's logic to process the turn. It maintains information
+ * about the conversation and provides methods to send responses.
+ *
+ * This class follows the builder pattern for registering middleware handlers.
  */
 export class TurnContext {
   private readonly _adapter?: BaseAdapter
@@ -48,8 +76,9 @@ export class TurnContext {
 
   /**
    * Initializes a new instance of the TurnContext class.
-   * @param adapterOrContext The adapter or context for the turn.
-   * @param request The activity for the turn.
+   *
+   * @param adapterOrContext The adapter that created this context, or another TurnContext to clone
+   * @param request The activity for the turn (required when first parameter is an adapter)
    */
   constructor (adapterOrContext: BaseAdapter, request: Activity)
   constructor (adapterOrContext: TurnContext)
@@ -63,17 +92,24 @@ export class TurnContext {
   }
 
   /**
-   * A list of buffered reply activities.
+   * A list of reply activities that are buffered until the end of the turn.
+   *
+   * This is primarily used with the 'expectReplies' delivery mode where all
+   * activities during a turn are collected and returned as a single response.
    */
   readonly bufferedReplyActivities: Activity[] = []
 
   /**
-   * Sends a trace activity.
-   * @param name The name of the trace activity.
-   * @param value The value of the trace activity.
-   * @param valueType The value type of the trace activity.
-   * @param label The label of the trace activity.
-   * @returns The resource response.
+   * Sends a trace activity for debugging purposes.
+   *
+   * Trace activities are typically used for debugging and are only visible in
+   * channels that support them, like the Bot Framework Emulator.
+   *
+   * @param name The name/category of the trace
+   * @param value The value/data to include in the trace
+   * @param valueType Optional type name for the value
+   * @param label Optional descriptive label for the trace
+   * @returns A promise that resolves to the resource response or undefined
    */
   async sendTraceActivity (name: string, value?: any, valueType?: string, label?: string): Promise<ResourceResponse | undefined> {
     const traceActivityObj = {
@@ -89,11 +125,16 @@ export class TurnContext {
   }
 
   /**
-   * Sends an activity.
-   * @param activityOrText The activity or text to send.
-   * @param speak The text to speak.
-   * @param inputHint The input hint.
-   * @returns The resource response.
+   * Sends an activity to the sender of the incoming activity.
+   *
+   * This is the primary method used to respond to the user. It automatically
+   * addresses the response to the correct conversation and recipient using
+   * information from the incoming activity.
+   *
+   * @param activityOrText The activity to send or a string for a simple message
+   * @param speak Optional text to be spoken by the agent
+   * @param inputHint Optional input hint to indicate if the agent is expecting input
+   * @returns A promise that resolves to the resource response or undefined
    */
   async sendActivity (activityOrText: string | Activity, speak?: string, inputHint?: string): Promise<ResourceResponse | undefined> {
     let activityObject: {}
@@ -112,9 +153,14 @@ export class TurnContext {
   }
 
   /**
-   * Sends multiple activities.
-   * @param activities The activities to send.
-   * @returns The resource responses.
+   * Sends multiple activities to the sender of the incoming activity.
+   *
+   * This method applies conversation references to each activity and
+   * emits them through the middleware chain before sending them to
+   * the adapter.
+   *
+   * @param activities The array of activities to send
+   * @returns A promise that resolves to an array of resource responses
    */
   async sendActivities (activities: Activity[]): Promise<ResourceResponse[]> {
     let sentNonTraceActivity = false
@@ -164,9 +210,13 @@ export class TurnContext {
   }
 
   /**
-   * Updates an activity.
-   * @param activity The activity to update.
-   * @returns A promise representing the asynchronous operation.
+   * Updates an existing activity in the conversation.
+   *
+   * This can be used to edit previously sent activities, for example to
+   * update the content of an adaptive card or change a message.
+   *
+   * @param activity The activity to update with its ID specified
+   * @returns A promise that resolves when the activity has been updated
    */
   async updateActivity (activity: Activity): Promise<void> {
     const ref: ConversationReference = this.activity.getConversationReference()
@@ -177,9 +227,10 @@ export class TurnContext {
   }
 
   /**
-   * Deletes an activity.
-   * @param idOrReference The ID or reference of the activity to delete.
-   * @returns A promise representing the asynchronous operation.
+   * Deletes an activity from the conversation.
+   *
+   * @param idOrReference The ID of the activity to delete or a conversation reference
+   * @returns A promise that resolves when the activity has been deleted
    */
   async deleteActivity (idOrReference: string | ConversationReference): Promise<void> {
     let reference: ConversationReference
@@ -193,38 +244,45 @@ export class TurnContext {
   }
 
   /**
-   * Uploads an attachment.
-   * @param conversationId The conversation ID.
-   * @param attachmentData The attachment data.
-   * @returns The resource response.
+   * Uploads an attachment to the conversation.
+   *
+   * @param conversationId The ID of the conversation
+   * @param attachmentData The attachment data to upload
+   * @returns A promise that resolves to the resource response
    */
   async uploadAttachment (conversationId: string, attachmentData: AttachmentData): Promise<ResourceResponse> {
     return await this.adapter.uploadAttachment(conversationId, attachmentData)
   }
 
   /**
-   * Gets attachment information.
-   * @param attachmentId The attachment ID.
-   * @returns The attachment information.
+   * Gets information about an attachment.
+   *
+   * @param attachmentId The ID of the attachment
+   * @returns A promise that resolves to the attachment information
    */
   async getAttachmentInfo (attachmentId: string): Promise<AttachmentInfo> {
     return await this.adapter.getAttachmentInfo(attachmentId)
   }
 
   /**
-   * Gets an attachment.
-   * @param attachmentId The attachment ID.
-   * @param viewId The view ID.
-   * @returns The readable stream of the attachment.
+   * Gets the content of an attachment.
+   *
+   * @param attachmentId The ID of the attachment
+   * @param viewId The view to get
+   * @returns A promise that resolves to a readable stream of the attachment content
    */
   async getAttachment (attachmentId: string, viewId: string): Promise<NodeJS.ReadableStream> {
     return await this.adapter.getAttachment(attachmentId, viewId)
   }
 
   /**
-   * Registers a handler for sending activities.
-   * @param handler The handler to register.
-   * @returns The current TurnContext instance.
+   * Registers a handler for intercepting and processing activities being sent.
+   *
+   * This method follows a middleware pattern, allowing multiple handlers to
+   * be chained together. Handlers can modify activities or inject new ones.
+   *
+   * @param handler The handler to register
+   * @returns The current TurnContext instance for chaining
    */
   onSendActivities (handler: SendActivitiesHandler): this {
     this._onSendActivities.push(handler)
@@ -232,9 +290,10 @@ export class TurnContext {
   }
 
   /**
-   * Registers a handler for updating activities.
-   * @param handler The handler to register.
-   * @returns The current TurnContext instance.
+   * Registers a handler for intercepting activity updates.
+   *
+   * @param handler The handler to register
+   * @returns The current TurnContext instance for chaining
    */
   onUpdateActivity (handler: UpdateActivityHandler): this {
     this._onUpdateActivity.push(handler)
@@ -242,9 +301,10 @@ export class TurnContext {
   }
 
   /**
-   * Registers a handler for deleting activities.
-   * @param handler The handler to register.
-   * @returns The current TurnContext instance.
+   * Registers a handler for intercepting activity deletions.
+   *
+   * @param handler The handler to register
+   * @returns The current TurnContext instance for chaining
    */
   onDeleteActivity (handler: DeleteActivityHandler): this {
     this._onDeleteActivity.push(handler)
@@ -253,28 +313,41 @@ export class TurnContext {
 
   /**
    * Copies the properties of this TurnContext to another TurnContext.
-   * @param context The context to copy to.
+   *
+   * Used internally when cloning contexts.
+   *
+   * @param context The context to copy to
+   * @protected
    */
   protected copyTo (context: TurnContext): void {
     ['_adapter', '_activity', '_respondedRef', '_services', '_onSendActivities', '_onUpdateActivity', '_onDeleteActivity'].forEach((prop: string) => ((context as any)[prop] = (this as any)[prop]))
   }
 
   /**
-   * Gets the adapter for the turn.
+   * Gets the adapter that created this context.
+   *
+   * The adapter is responsible for sending and receiving activities
+   * to and from the user's channel.
    */
   get adapter (): BaseAdapter {
     return this._adapter as BaseAdapter
   }
 
   /**
-   * Gets the activity for the turn.
+   * Gets the incoming activity that started this turn.
+   *
+   * This is the activity that was received from the user or channel
+   * and triggered the creation of this context.
    */
   get activity (): Activity {
     return this._activity as Activity
   }
 
   /**
-   * Gets or sets whether the turn has responded.
+   * Gets or sets whether the turn has sent a response to the user.
+   *
+   * This is used to track whether the agent has responded to the user's
+   * activity. Once set to true, it cannot be set back to false.
    */
   get responded (): boolean {
     return this._respondedRef.responded
@@ -289,6 +362,9 @@ export class TurnContext {
 
   /**
    * Gets or sets the locale for the turn.
+   *
+   * The locale affects language-dependent operations like
+   * formatting dates or numbers.
    */
   get locale (): string | undefined {
     const turnObj = this._turnState.get(this._turn)
@@ -309,18 +385,28 @@ export class TurnContext {
   }
 
   /**
-   * Gets the turn state collection.
+   * Gets the turn state collection for storing data during the turn.
+   *
+   * The turn state collection provides a dictionary-like interface
+   * for storing arbitrary data that needs to be accessible during
+   * the processing of the current turn.
    */
   get turnState (): TurnContextStateCollection {
     return this._turnState
   }
 
   /**
-   * Emits events to the registered handlers.
-   * @param handlers The handlers to emit to.
-   * @param arg The argument to pass to the handlers.
-   * @param next The next function to call.
-   * @returns The result of the handlers.
+   * Emits events to registered middleware handlers.
+   *
+   * This internal method implements the middleware pattern, allowing
+   * handlers to be chained together with each having the option to
+   * short-circuit the chain.
+   *
+   * @param handlers Array of handlers to execute
+   * @param arg The argument to pass to each handler
+   * @param next The function to execute at the end of the middleware chain
+   * @returns A promise that resolves to the result from the handlers or next function
+   * @private
    */
   private async emit<A, T>(handlers: Array<(context: TurnContext, arg: A, next: () => Promise<T>) => Promise<T>>, arg: A, next: () => Promise<T>): Promise<T> {
     const runHandlers = async ([handler, ...remaining]: typeof handlers): Promise<T> => {

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

@@ -1,10 +0,0 @@
-/**
- * Copyright (c) Microsoft Corporation. All rights reserved.
- * Licensed under the MIT License.
- */
-export interface Memory {
-    deleteValue(path: string): void;
-    hasValue(path: string): boolean;
-    getValue<TValue = unknown>(path: string): TValue;
-    setValue(path: string, value: unknown): void;
-}

package/dist/src/app/memory.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"memory.js","sourceRoot":"","sources":["../../../src/app/memory.ts"],"names":[],"mappings":";AAAA;;;GAGG"}

package/src/app/memory.ts

@@ -1,14 +0,0 @@
-/**
- * Copyright (c) Microsoft Corporation. All rights reserved.
- * Licensed under the MIT License.
- */
-
-export interface Memory {
-  deleteValue(path: string): void;
-
-  hasValue(path: string): boolean;
-
-  getValue<TValue = unknown>(path: string): TValue;
-
-  setValue(path: string, value: unknown): void;
-}