@microsoft/agents-hosting 0.2.10-g3ac88ff25e → 0.3.5

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/dist/src/app/oauth/userIdentity.d.ts

@@ -1,43 +0,0 @@
-/**
- * Copyright (c) Microsoft Corporation. All rights reserved.
- * Licensed under the MIT License.
- */
-import { TurnContext } from '../../turnContext';
-import { TurnState } from '../turnState';
-import { Storage } from '../../storage';
-import { OAuthFlow, TokenResponse } from '../../oauth';
-/**
- * Options for configuring user identity.
- * Contains settings related to Single Sign-On (SSO) authentication.
- */
-export interface UserIdentityOptions {
-    /**
-     * Determines whether Single Sign-On (SSO) is enabled for user authentication.
-     */
-    enableSSO: boolean;
-    /**
-     * The name of the SSO connection to use when SSO is enabled.
-     * Only applicable when enableSSO is set to true.
-     */
-    ssoConnectionName?: string;
-}
-export declare class UserIdentity {
-    oAuthFlow: OAuthFlow;
-    /**
-     * Creates a new instance of UserAuthorization.
-     * @param {Storage} storage - The storage system to use for state management.
-     */
-    constructor(storage: Storage, connectionName: string);
-    getToken(context: TurnContext): Promise<TokenResponse>;
-    authenticate(context: TurnContext, state: TurnState): Promise<TokenResponse>;
-    /**
-     * Signs out the current user.
-     * This method clears the user's token and resets the SSO state.
-     *
-     * @param {TurnContext} context - The context object for the current turn.
-     * @param {TurnState} state - The state object for the current turn.
-     */
-    signOut(context: TurnContext, state: TurnState): Promise<void>;
-    _signInHandler: ((context: TurnContext, state: TurnState) => void) | null;
-    onSignInSuccess(handler: (context: TurnContext, state: TurnState) => void): void;
-}

package/dist/src/app/oauth/userIdentity.js

@@ -1,54 +0,0 @@
-"use strict";
-/**
- * Copyright (c) Microsoft Corporation. All rights reserved.
- * Licensed under the MIT License.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.UserIdentity = void 0;
-const oauth_1 = require("../../oauth");
-const state_1 = require("../../state");
-class UserIdentity {
-    /**
-     * Creates a new instance of UserAuthorization.
-     * @param {Storage} storage - The storage system to use for state management.
-     */
-    constructor(storage, connectionName) {
-        this._signInHandler = null;
-        const userState = new state_1.UserState(storage);
-        this.oAuthFlow = new oauth_1.OAuthFlow(userState, connectionName);
-    }
-    async getToken(context) {
-        return await this.oAuthFlow.getUserToken(context);
-    }
-    async authenticate(context, state) {
-        var _a;
-        let tokenResponse;
-        if (((_a = this.oAuthFlow.state) === null || _a === void 0 ? void 0 : _a.flowStarted) === false) {
-            tokenResponse = await this.oAuthFlow.beginFlow(context);
-        }
-        else {
-            tokenResponse = await this.oAuthFlow.continueFlow(context);
-            if (tokenResponse.status === oauth_1.TokenRequestStatus.Success) {
-                if (this._signInHandler) {
-                    await this._signInHandler(context, state);
-                }
-            }
-        }
-        return tokenResponse;
-    }
-    /**
-     * Signs out the current user.
-     * This method clears the user's token and resets the SSO state.
-     *
-     * @param {TurnContext} context - The context object for the current turn.
-     * @param {TurnState} state - The state object for the current turn.
-     */
-    async signOut(context, state) {
-        await this.oAuthFlow.signOut(context);
-    }
-    onSignInSuccess(handler) {
-        this._signInHandler = handler;
-    }
-}
-exports.UserIdentity = UserIdentity;
-//# sourceMappingURL=userIdentity.js.map

package/dist/src/app/oauth/userIdentity.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"userIdentity.js","sourceRoot":"","sources":["../../../../src/app/oauth/userIdentity.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAMH,uCAA0E;AAC1E,uCAAuC;AAqBvC,MAAa,YAAY;IAGvB;;;OAGG;IACH,YAAa,OAAgB,EAAE,cAAsB;QAmCrD,mBAAc,GAA8D,IAAI,CAAA;QAlC9E,MAAM,SAAS,GAAG,IAAI,iBAAS,CAAC,OAAO,CAAC,CAAA;QACxC,IAAI,CAAC,SAAS,GAAG,IAAI,iBAAS,CAAC,SAAS,EAAE,cAAc,CAAC,CAAA;IAC3D,CAAC;IAEM,KAAK,CAAC,QAAQ,CAAE,OAAoB;QACzC,OAAO,MAAM,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,OAAO,CAAC,CAAA;IACnD,CAAC;IAEM,KAAK,CAAC,YAAY,CAAE,OAAoB,EAAE,KAAgB;;QAC/D,IAAI,aAA4B,CAAA;QAChC,IAAI,CAAA,MAAA,IAAI,CAAC,SAAS,CAAC,KAAK,0CAAE,WAAW,MAAK,KAAK,EAAE,CAAC;YAChD,aAAa,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,OAAO,CAAC,CAAA;QACzD,CAAC;aAAM,CAAC;YACN,aAAa,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,OAAO,CAAC,CAAA;YAC1D,IAAI,aAAa,CAAC,MAAM,KAAK,0BAAkB,CAAC,OAAO,EAAE,CAAC;gBACxD,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;oBACxB,MAAM,IAAI,CAAC,cAAc,CAAC,OAAO,EAAE,KAAK,CAAC,CAAA;gBAC3C,CAAC;YACH,CAAC;QACH,CAAC;QACD,OAAO,aAAa,CAAA;IACtB,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,OAAO,CAAE,OAAoB,EAAE,KAAgB;QACnD,MAAM,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,OAAO,CAAC,CAAA;IACvC,CAAC;IAGM,eAAe,CAAE,OAAyD;QAC/E,IAAI,CAAC,cAAc,GAAG,OAAO,CAAA;IAC/B,CAAC;CACF;AA9CD,oCA8CC"}

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;
-}

package/src/app/oauth/userIdentity.ts

@@ -1,78 +0,0 @@
-/**
- * Copyright (c) Microsoft Corporation. All rights reserved.
- * Licensed under the MIT License.
- */
-
-import { TurnContext } from '../../turnContext'
-// import { debug } from '../../logger'
-import { TurnState } from '../turnState'
-import { Storage } from '../../storage'
-import { OAuthFlow, TokenRequestStatus, TokenResponse } from '../../oauth'
-import { UserState } from '../../state'
-
-// const logger = debug('agents:user-identity')
-
-/**
- * Options for configuring user identity.
- * Contains settings related to Single Sign-On (SSO) authentication.
- */
-export interface UserIdentityOptions {
-  /**
-   * Determines whether Single Sign-On (SSO) is enabled for user authentication.
-   */
-  enableSSO: boolean;
-
-  /**
-   * The name of the SSO connection to use when SSO is enabled.
-   * Only applicable when enableSSO is set to true.
-   */
-  ssoConnectionName?: string;
-}
-
-export class UserIdentity {
-  oAuthFlow: OAuthFlow
-
-  /**
-   * Creates a new instance of UserAuthorization.
-   * @param {Storage} storage - The storage system to use for state management.
-   */
-  constructor (storage: Storage, connectionName: string) {
-    const userState = new UserState(storage)
-    this.oAuthFlow = new OAuthFlow(userState, connectionName)
-  }
-
-  public async getToken (context: TurnContext): Promise<TokenResponse> {
-    return await this.oAuthFlow.getUserToken(context)
-  }
-
-  public async authenticate (context: TurnContext, state: TurnState) : Promise<TokenResponse> {
-    let tokenResponse: TokenResponse
-    if (this.oAuthFlow.state?.flowStarted === false) {
-      tokenResponse = await this.oAuthFlow.beginFlow(context)
-    } else {
-      tokenResponse = await this.oAuthFlow.continueFlow(context)
-      if (tokenResponse.status === TokenRequestStatus.Success) {
-        if (this._signInHandler) {
-          await this._signInHandler(context, state)
-        }
-      }
-    }
-    return tokenResponse
-  }
-
-  /**
-   * Signs out the current user.
-   * This method clears the user's token and resets the SSO state.
-   *
-   * @param {TurnContext} context - The context object for the current turn.
-   * @param {TurnState} state - The state object for the current turn.
-   */
-  async signOut (context: TurnContext, state: TurnState) {
-    await this.oAuthFlow.signOut(context)
-  }
-
-  _signInHandler: ((context: TurnContext, state: TurnState) => void) | null = null
-  public onSignInSuccess (handler: (context: TurnContext, state: TurnState) => void) {
-    this._signInHandler = handler
-  }
-}