@microsoft/agents-hosting 1.0.0 → 1.0.7-g73d3d58001

package/src/state/agentStatePropertyAccesor.ts

@@ -9,29 +9,36 @@ import { AgentState, CustomKey } from './agentState'
 /**
  * Interface for accessing a property in state storage with type safety.
  *
- * The interface defines standard methods for working with persisted state properties,
+ * @typeParam T The type of the property being accessed
+ *
+ * @remarks
+ * This interface defines standard methods for working with persisted state properties,
  * allowing property access with strong typing to reduce errors when working with
  * complex state objects.
  *
- * @typeParam T The type of the property being accessed
  */
 export interface StatePropertyAccessor<T = any> {
   /**
    * Deletes the persisted property from its backing storage object.
    *
+   * @param context Context for the current turn of conversation with the user.
+   *
    * @remarks
    * The properties backing storage object SHOULD be loaded into memory on first access.
    *
-   * ```JavaScript
+   * @example
+   * ```javascript
    * await myProperty.delete(context);
    * ```
-   * @param context Context for the current turn of conversation with the user.
+   *
    */
   delete(context: TurnContext): Promise<void>;
 
   /**
    * Reads a persisted property from its backing storage object.
    *
+   * @param context Context for the current turn of conversation with the user.
+   *
    * @remarks
    * The properties backing storage object SHOULD be loaded into memory on first access.
    *
@@ -39,10 +46,11 @@ export interface StatePropertyAccessor<T = any> {
    * specified, a clone of the `defaultValue` SHOULD be copied to the storage object. If a
    * `defaultValue` has not been specified then a value of `undefined` SHOULD be returned.
    *
-   * ```JavaScript
+   * @example
+   * ```javascript
    * const value = await myProperty.get(context, { count: 0 });
    * ```
-   * @param context Context for the current turn of conversation with the user.
+   *
    */
   get(context: TurnContext): Promise<T | undefined>;
 
@@ -57,26 +65,31 @@ export interface StatePropertyAccessor<T = any> {
   /**
    * Assigns a new value to the properties backing storage object.
    *
+   * @param context Context for the current turn of conversation with the user.
+   * @param value Value to assign.
+   *
    * @remarks
    * The properties backing storage object SHOULD be loaded into memory on first access.
    *
    * Depending on the state systems implementation, an additional step may be required to
    * persist the actual changes to disk.
    *
-   * ```JavaScript
+   * @example
+   * ```javascript
    * await myProperty.set(context, value);
    * ```
-   * @param context Context for the current turn of conversation with the user.
-   * @param value Value to assign.
+   *
    */
   set(context: TurnContext, value: T): Promise<void>;
 }
 
 /**
- * @summary Provides typed access to an Agent state property with automatic state loading and persistence management.
+ * Provides typed access to an Agent state property with automatic state loading and persistence management.
+ *
+ * @typeParam T The type of the property being accessed. Can be any serializable type.
  *
  * @remarks
- * AgentStatePropertyAccessor simplifies working with persisted state by abstracting
+ * `AgentStatePropertyAccessor` simplifies working with persisted state by abstracting
  * the complexity of loading state from storage and manipulating specific properties.
  * It provides a type-safe interface for state management with automatic handling of:
  *
@@ -88,6 +101,11 @@ export interface StatePropertyAccessor<T = any> {
  *
  * ### Key Features
  *
+ * Key features of `AgentStatePropertyAccessor` include:
+ * - [Type Safety](#type-safety)
+ * - [Automatic Default Value Handling](#automatic-default-value-handling)
+ * - [Explicit Persistence Control](#explicit-persistence-control)
+ *
  * #### Type Safety
  * The accessor provides compile-time type checking when using TypeScript:
  * ```typescript
@@ -178,8 +196,6 @@ export interface StatePropertyAccessor<T = any> {
  * - **Persistence**: Always call `state.saveChanges(context)` to persist changes to storage.
  * - **Deep Cloning**: Default values are deep cloned using JSON serialization, which may not work with complex objects containing functions or circular references.
  *
- * @typeParam T The type of the property being accessed. Can be any serializable type.
- *
  * @see {@link AgentState.createProperty} for creating property accessors
  * @see {@link StatePropertyAccessor} for the interface definition
  */
@@ -187,13 +203,13 @@ export class AgentStatePropertyAccessor<T = any> implements StatePropertyAccesso
   /**
    * Creates a new instance of AgentStatePropertyAccessor.
    *
+   * @param state The agent state object that manages the backing storage for this property
+   * @param name The unique name of the property within the state object. This name is used as the key in the state storage.
+   *
    * @remarks
    * This constructor is typically not called directly. Instead, use {@link AgentState.createProperty}
    * to create property accessors, which ensures proper integration with the state management system.
    *
-   * @param state The agent state object that manages the backing storage for this property
-   * @param name The unique name of the property within the state object. This name is used as the key in the state storage.
-   *
    * @example
    * ```typescript
    * // Recommended way - use AgentState.createProperty
@@ -202,11 +218,18 @@ export class AgentStatePropertyAccessor<T = any> implements StatePropertyAccesso
    * // Direct construction (not recommended)
    * const accessor = new AgentStatePropertyAccessor<UserProfile>(userState, "userProfile");
    * ```
+   *
    */
   constructor (protected readonly state: AgentState, public readonly name: string) { }
 
   /**
-   * @summary Deletes the property from the state storage.
+   * Deletes the property from the state storage.
+   *
+   * @param context The turn context for the current conversation turn
+   * @param customKey Optional custom key for accessing state in a specific storage location.
+   * Useful for multi-tenant scenarios or when state needs to be partitioned.
+   * @returns A promise that resolves when the delete operation is complete
+   *
    * @remarks
    * This operation removes the property from the in-memory state object but does not
    * automatically persist the change to the underlying storage. You must call
@@ -216,13 +239,7 @@ export class AgentStatePropertyAccessor<T = any> implements StatePropertyAccesso
    * - The deletion only affects the in-memory state until `saveChanges()` is called
    * - After deletion, subsequent `get()` calls will return `undefined` (or the default value if provided)
    *
-   * @param context The turn context for the current conversation turn
-   * @param customKey Optional custom key for accessing state in a specific storage location.
-   * Useful for multi-tenant scenarios or when state needs to be partitioned.
-   *
-   * @returns A promise that resolves when the delete operation is complete
-   *
-   * @example
+   * @example Basic usage
    * ```typescript
    * const userSettings = userState.createProperty<UserSettings>("settings");
    *
@@ -242,6 +259,7 @@ export class AgentStatePropertyAccessor<T = any> implements StatePropertyAccesso
    * await userSettings.delete(context, tenantKey);
    * await userState.saveChanges(context);
    * ```
+   *
    */
   async delete (context: TurnContext, customKey?: CustomKey): Promise<void> {
     const obj: any = await this.state.load(context, false, customKey)
@@ -251,7 +269,16 @@ export class AgentStatePropertyAccessor<T = any> implements StatePropertyAccesso
   }
 
   /**
-   * @summary Retrieves the value of the property from state storage.
+   * Retrieves the value of the property from state storage.
+   *
+   * @param context The turn context for the current conversation turn
+   * @param defaultValue Optional default value to use if the property doesn't exist.
+   *                    When provided, this value is deep cloned and stored in state.
+   * @param customKey Optional custom key for accessing state in a specific storage location.
+   *                  Useful for multi-tenant scenarios or when state needs to be partitioned.
+   *
+   * @returns A promise that resolves to the property value, the cloned default value, or `undefined`
+   *
    * @remarks
    * This method provides intelligent default value handling:
    * - If the property exists, its value is returned
@@ -268,14 +295,6 @@ export class AgentStatePropertyAccessor<T = any> implements StatePropertyAccesso
    * **Performance**: The first access loads state from storage; subsequent accesses use
    * the in-memory cached version until the context is disposed.
    *
-   * @param context The turn context for the current conversation turn
-   * @param defaultValue Optional default value to use if the property doesn't exist.
-   *                    When provided, this value is deep cloned and stored in state.
-   * @param customKey Optional custom key for accessing state in a specific storage location.
-   *                  Useful for multi-tenant scenarios or when state needs to be partitioned.
-   *
-   * @returns A promise that resolves to the property value, the cloned default value, or `undefined`
-   *
    * @example Basic usage
    * ```typescript
    * const counterProperty = userState.createProperty<number>("counter");
@@ -314,6 +333,7 @@ export class AgentStatePropertyAccessor<T = any> implements StatePropertyAccesso
    * const tenantKey = { key: `tenant_${tenantId}` };
    * const tenantData = await dataProperty.get(context, defaultData, tenantKey);
    * ```
+   *
    */
   async get (context: TurnContext, defaultValue?: T, customKey?: CustomKey): Promise<T> {
     const obj: any = await this.state.load(context, false, customKey)
@@ -329,7 +349,15 @@ export class AgentStatePropertyAccessor<T = any> implements StatePropertyAccesso
   }
 
   /**
-   * @summary Sets the value of the property in state storage.
+   * Sets the value of the property in state storage.
+   *
+   * @param context The turn context for the current conversation turn
+   * @param value The value to assign to the property. Can be any serializable value.
+   * @param customKey Optional custom key for accessing state in a specific storage location.
+   *                  Useful for multi-tenant scenarios or when state needs to be partitioned.
+   *
+   * @returns A promise that resolves when the set operation is complete
+   *
    * @remarks
    * This operation updates the property in the in-memory state object but does not
    * automatically persist the change to the underlying storage. You must call
@@ -346,13 +374,6 @@ export class AgentStatePropertyAccessor<T = any> implements StatePropertyAccesso
    * **Type Safety**: When using TypeScript, the value must match the property's
    * declared type parameter.
    *
-   * @param context The turn context for the current conversation turn
-   * @param value The value to assign to the property. Can be any serializable value.
-   * @param customKey Optional custom key for accessing state in a specific storage location.
-   *                  Useful for multi-tenant scenarios or when state needs to be partitioned.
-   *
-   * @returns A promise that resolves when the set operation is complete
-   *
    * @example Basic usage
    * ```typescript
    * const counterProperty = userState.createProperty<number>("counter");
@@ -394,6 +415,7 @@ export class AgentStatePropertyAccessor<T = any> implements StatePropertyAccesso
    * await dataProperty.set(context, updatedData, tenantKey);
    * await userState.saveChanges(context);
    * ```
+   *
    */
   async set (context: TurnContext, value: T, customKey?: CustomKey): Promise<void> {
     const obj: any = await this.state.load(context, false, customKey)

package/src/storage/fileStorage.ts

@@ -8,7 +8,7 @@ import fs from 'fs'
 import { Storage, StoreItem } from './storage'
 
 /**
- * @summary A file-based storage implementation that persists data to the local filesystem.
+ * A file-based storage implementation that persists data to the local filesystem.
  *
  * @remarks
  * FileStorage stores all data in a single JSON file named 'state.json' within a specified folder.
@@ -47,7 +47,6 @@ import { Storage, StoreItem } from './storage'
  * await storage.delete(['conversation456']);
  * ```
  *
-
  */
 export class FileStorage implements Storage {
   private _folder: string
@@ -57,6 +56,7 @@ export class FileStorage implements Storage {
    * Creates a new FileStorage instance that stores data in the specified folder.
    *
    * @param folder The absolute or relative path to the folder where the state.json file will be stored
+   * @throws May throw filesystem errors if the folder cannot be created or accessed
    *
    * @remarks
    * The constructor performs the following initialization steps:
@@ -64,7 +64,6 @@ export class FileStorage implements Storage {
    * 2. Creates an empty state.json file if it doesn't exist
    * 3. Loads existing data from state.json into memory for fast access
    *
-   * @throws May throw filesystem errors if the folder cannot be created or accessed
    */
   constructor (folder: string) {
     this._folder = folder
@@ -83,13 +82,13 @@ export class FileStorage implements Storage {
    *
    * @param keys Array of keys to read from storage
    * @returns Promise resolving to an object containing the requested items (keys that don't exist are omitted)
-   *
    * @throws ReferenceError if keys array is empty or undefined
    *
    * @remarks
    * This method reads from the in-memory cache that was loaded during construction,
    * making it very fast but potentially returning stale data if the file was
    * modified by external processes.
+   *
    */
   read (keys: string[]) : Promise<StoreItem> {
     return new Promise((resolve, reject) => {
@@ -119,8 +118,10 @@ export class FileStorage implements Storage {
    * to the state.json file. The file is written with pretty-printing (2-space indentation)
    * for better readability during development and debugging.
    *
-   * Note: This implementation does not support eTag-based optimistic concurrency control.
-   * Any eTag values in the changes object are ignored.
+   * > [!NOTE]
+   * > This implementation does not support eTag-based optimistic concurrency control.
+   * > Any eTag values in the changes object are ignored.
+   *
    */
   write (changes: StoreItem) : Promise<void> {
     const keys = Object.keys(changes)
@@ -143,6 +144,7 @@ export class FileStorage implements Storage {
    * This method removes the specified keys from both the in-memory cache
    * and writes the updated state to the state.json file. Keys that don't
    * exist in storage are silently ignored.
+   *
    */
   delete (keys: string[]) : Promise<void> {
     return new Promise((resolve, reject) => {

package/src/storage/memoryStorage.ts

@@ -39,10 +39,12 @@ export class MemoryStorage implements Storage {
   /**
    * Gets a single shared instance of the MemoryStorage class.
    *
+   * @returns The singleton instance of MemoryStorage
+   *
+   * @remarks
    * Using this method ensures that the same storage instance is used across
    * the application, allowing for shared state without passing references.
    *
-   * @returns The singleton instance of MemoryStorage
    */
   static getSingleInstance (): MemoryStorage {
     if (!MemoryStorage.instance) {
@@ -78,14 +80,15 @@ export class MemoryStorage implements Storage {
   /**
    * Writes storage items to memory.
    *
+   * @param changes The items to write, indexed by key
+   * @returns A promise that resolves when the write operation is complete
+   * @throws Will throw an error if changes are not provided or if there's an eTag conflict
+   *
+   * @remarks
    * This method supports optimistic concurrency control through eTags.
    * If an item has an eTag, it will only be updated if the existing item
    * has the same eTag. If an item has an eTag of '*' or no eTag, it will
    * always be written regardless of the current state.
-   *
-   * @param changes The items to write, indexed by key
-   * @returns A promise that resolves when the write operation is complete
-   * @throws Will throw an error if changes are not provided or if there's an eTag conflict
    */
   async write (changes: StoreItem): Promise<void> {
     if (!changes || changes.length === 0) {
@@ -124,13 +127,15 @@ export class MemoryStorage implements Storage {
   /**
    * Saves an item to memory with a new eTag.
    *
+   * @param key The key of the item to save
+   * @param item The item to save
+   *
+   * @remarks
    * This private method handles the details of:
    * - Creating a clone of the item to prevent modification of the original
    * - Generating a new eTag for optimistic concurrency control
    * - Converting the item to a JSON string for storage
    *
-   * @param key The key of the item to save
-   * @param item The item to save
    * @private
    */
   private saveItem (key: string, item: unknown): void {

package/src/storage/storage.ts

@@ -7,41 +7,58 @@ import { TurnContext } from '../turnContext'
 
 /**
  * Represents an item to be stored in a storage provider.
+ *
+ * @remarks
  * Each item can contain arbitrary data along with an optional eTag for optimistic concurrency control.
  */
 export interface StoreItem {
   /**
    * Optional eTag used for optimistic concurrency control.
+   *
+   * @remarks
    * When set to '*', it indicates that the write should proceed regardless of existing data.
    * When comparing eTags, exact string matching is used to determine if data has changed.
+   *
    */
   eTag?: string;
 
   /**
    * Additional properties can be stored in the item.
+   *
+   * @remarks
    * Each storage provider may have specific requirements or limitations on property names and values.
+   *
    */
   [key: string]: any;
 }
 
 /**
  * Represents a collection of store items indexed by key.
+ *
+ * @remarks
  * Used as the return type for storage read operations.
+ *
  */
 export interface StoreItems {
   /**
    * Keys are the storage item identifiers, and values are the stored items.
+   *
+   * @remarks
    * If a requested key is not found during a read operation, it will not appear in this collection.
+   *
    */
   [key: string]: any;
 }
 
 /**
  * A factory function to generate storage keys based on the conversation context.
- * Allows different storage strategies based on the conversation state.
  *
  * @param context The TurnContext for the current turn of conversation
  * @returns A string key for storage that uniquely identifies where to store the data
+ *
+ * @remarks
+ * Allows different storage strategies based on the conversation state.
+ *
  */
 export type StorageKeyFactory = (context: TurnContext) => string | Promise<string>
 

package/src/turnContext.ts

@@ -43,11 +43,6 @@ export type DeleteActivityHandler = (context: TurnContext, reference: Conversati
  */
 export const AgentCallbackHandlerKey = 'agentCallbackHandler'
 
-/**
- * Interface for TurnContext.
- */
-export interface TurnContext {}
-
 /**
  * Represents the context for a single turn in a conversation between a user and an agent.
  *
@@ -105,14 +100,15 @@ export class TurnContext {
   /**
    * 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
+   *
+   * @remarks
+   * Trace activities are typically used for debugging and are only visible in
+   * channels that support them, like the Bot Framework Emulator.
    */
   async sendTraceActivity (name: string, value?: any, valueType?: string, label?: string): Promise<ResourceResponse | undefined> {
     const traceActivityObj = {
@@ -130,14 +126,15 @@ export class TurnContext {
   /**
    * 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
+   *
+   * @remarks
+   * 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.
    */
   async sendActivity (activityOrText: string | Activity, speak?: string, inputHint?: string): Promise<ResourceResponse | undefined> {
     let activityObject: {}
@@ -158,12 +155,13 @@ export class TurnContext {
   /**
    * Sends multiple activities to the sender of the incoming activity.
    *
+   * @param activities The array of activities to send
+   * @returns A promise that resolves to an array of resource responses
+   *
+   * @remarks
    * 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
@@ -215,11 +213,12 @@ export class TurnContext {
   /**
    * 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
+   *
+   * @remarks
+   * This can be used to edit previously sent activities, for example to
+   * update the content of an adaptive card or change a message.
    */
   async updateActivity (activity: Activity): Promise<void> {
     const ref: ConversationReference = this.activity.getConversationReference()
@@ -281,11 +280,12 @@ export class TurnContext {
   /**
    * 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
+   *
+   * @remarks
+   * This method follows a middleware pattern, allowing multiple handlers to
+   * be chained together. Handlers can modify activities or inject new ones.
    */
   onSendActivities (handler: SendActivitiesHandler): this {
     this._onSendActivities.push(handler)
@@ -329,6 +329,7 @@ export class TurnContext {
   /**
    * Gets the adapter that created this context.
    *
+   * @remarks
    * The adapter is responsible for sending and receiving activities
    * to and from the user's channel.
    */
@@ -339,6 +340,7 @@ export class TurnContext {
   /**
    * Gets the incoming activity that started this turn.
    *
+   * @remarks
    * This is the activity that was received from the user or channel
    * and triggered the creation of this context.
    */
@@ -349,6 +351,7 @@ export class TurnContext {
   /**
    * Gets or sets whether the turn has sent a response to the user.
    *
+   * @remarks
    * 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.
    */
@@ -366,6 +369,7 @@ export class TurnContext {
   /**
    * Gets or sets the locale for the turn.
    *
+   * @remarks
    * The locale affects language-dependent operations like
    * formatting dates or numbers.
    */
@@ -390,6 +394,7 @@ export class TurnContext {
   /**
    * Gets the turn state collection for storing data during the turn.
    *
+   * @remarks
    * 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.
@@ -405,15 +410,16 @@ export class TurnContext {
   /**
    * 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
+   *
+   * @remarks
+   * This internal method implements the middleware pattern, allowing
+   * handlers to be chained together with each having the option to
+   * short-circuit the chain.
    */
   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> => {