@microsoft/agents-hosting 0.2.10-g3ac88ff25e → 0.2.14

package/src/logger.ts

@@ -1,6 +1,10 @@
 import createDebug, { Debugger } from 'debug'
 
-class Logger {
+/**
+ * Logger class that provides colored logging functionality using the debug package.
+ * Supports different log levels: info, warn, error, and debug.
+ */
+export class Logger {
   private loggers: { [level: string]: Debugger } = {}
   private readonly levelColors: { [level: string]: string } = {
     info: '2', // Green
@@ -9,6 +13,10 @@ class Logger {
     debug: '4' // Blue
   }
 
+  /**
+   * Creates a new Logger instance with the specified namespace.
+   * @param namespace The namespace to use for the logger
+   */
   constructor (namespace: string = '') {
     this.initializeLoggers(namespace)
   }
@@ -21,23 +29,48 @@ class Logger {
     }
   }
 
+  /**
+   * Logs an informational message.
+   * @param message The message to log
+   * @param args Additional arguments to include in the log
+   */
   info (message: string, ...args: any[]) {
     this.loggers.info(message, ...args)
   }
 
+  /**
+   * Logs a warning message.
+   * @param message The message to log
+   * @param args Additional arguments to include in the log
+   */
   warn (message: string, ...args: any[]) {
     this.loggers.warn(message, ...args)
   }
 
+  /**
+   * Logs an error message.
+   * @param message The message to log
+   * @param args Additional arguments to include in the log
+   */
   error (message: string, ...args: any[]) {
     this.loggers.error(message, ...args)
   }
 
+  /**
+   * Logs a debug message.
+   * @param message The message to log
+   * @param args Additional arguments to include in the log
+   */
   debug (message: string, ...args: any[]) {
     this.loggers.debug(message, ...args)
   }
 }
 
+/**
+ * Creates a new Logger instance with the specified namespace.
+ * @param namespace The namespace to use for the logger
+ * @returns A new Logger instance
+ */
 export function debug (namespace: string): Logger {
   return new Logger(namespace)
 }

package/src/state/agentState.ts

@@ -11,34 +11,63 @@ import { debug } from '../logger'
 
 const logger = debug('agents:state')
 
+/**
+ * Represents agent state that has been cached in the turn context.
+ * Used internally to track state changes and avoid unnecessary storage operations.
+ */
 export interface CachedAgentState {
-  state: { [id: string]: any }
-  hash: string
+  /**
+   * The state object containing all properties and their values
+   */
+  state: { [id: string]: any };
+  /**
+   * Hash of the state used to detect changes
+   */
+  hash: string;
 }
 
+/**
+ * Represents a custom key for storing state in a specific location.
+ * Allows state to be persisted with channel and conversation identifiers
+ * independent of the current context.
+ */
 export interface CustomKey {
+  /**
+   * The ID of the channel where the state should be stored
+   */
   channelId: string;
+  /**
+   * The ID of the conversation where the state should be stored
+   */
   conversationId: string;
   // TODO: namespace needs to be added
 }
 
 /**
- * Manages the state of an Agent.
+ * Manages the state of an Agent across turns in a conversation.
+ *
+ * AgentState provides functionality to persist and retrieve state data using
+ * a storage provider. It handles caching state in the turn context for performance,
+ * calculating change hashes to detect modifications, and managing property accessors
+ * for typed access to state properties.
  */
 export class AgentState {
   private readonly stateKey = Symbol('state')
 
   /**
-    * Creates a new instance of AgentState.
-    * @param storage The storage provider.
-    * @param storageKey The storage key factory.
-    */
+   * Creates a new instance of AgentState.
+   *
+   * @param storage The storage provider used to persist state between turns
+   * @param storageKey A factory function that generates keys for storing state data
+   */
   constructor (protected storage: Storage, protected storageKey: StorageKeyFactory) { }
 
   /**
    * Creates a property accessor for the specified property.
-   * @param name The name of the property.
-   * @returns A property accessor for the specified property.
+   * Property accessors provide typed access to properties within the state object.
+   *
+   * @param name The name of the property to access
+   * @returns A property accessor for the specified property
    */
   createProperty<T = any>(name: string): AgentStatePropertyAccessor<T> {
     const prop: AgentStatePropertyAccessor<T> = new AgentStatePropertyAccessor<T>(this, name)
@@ -46,10 +75,13 @@ export class AgentState {
   }
 
   /**
-   * Loads the state from storage.
-   * @param context The turn context.
-   * @param force Whether to force loading the state.
-   * @returns A promise that resolves to the loaded state.
+   * Loads the state from storage into the turn context.
+   * If state is already cached in the turn context and force is not set, the cached version will be used.
+   *
+   * @param context The turn context to load state into
+   * @param force If true, forces a reload from storage even if state is cached
+   * @param customKey Optional custom storage key to use instead of the default
+   * @returns A promise that resolves to the loaded state object
    */
   public async load (context: TurnContext, force = false, customKey?: CustomKey): Promise<any> {
     const cached: CachedAgentState = context.turnState.get(this.stateKey)
@@ -70,10 +102,13 @@ export class AgentState {
   }
 
   /**
-   * Saves the state to storage.
-   * @param context The turn context.
-   * @param force Whether to force saving the state.
-   * @returns A promise that resolves when the save operation is complete.
+   * Saves the state to storage if it has changed since it was loaded.
+   * Change detection uses a hash of the state object to determine if saving is necessary.
+   *
+   * @param context The turn context containing the state to save
+   * @param force If true, forces a save to storage even if no changes are detected
+   * @param customKey Optional custom storage key to use instead of the default
+   * @returns A promise that resolves when the save operation is complete
    */
   public async saveChanges (context: TurnContext, force = false, customKey?: CustomKey): Promise<void> {
     let cached: CachedAgentState = context.turnState.get(this.stateKey)
@@ -95,6 +130,14 @@ export class AgentState {
     }
   }
 
+  /**
+   * Determines whether to use a custom key or generate one from the context.
+   *
+   * @param customKey Optional custom key with channel and conversation IDs
+   * @param context The turn context used to generate a key if no custom key is provided
+   * @returns The storage key to use
+   * @private
+   */
   private async getStorageOrCustomKey (customKey: CustomKey | undefined, context: TurnContext) {
     let key: string | undefined
     if (customKey && customKey.channelId && customKey.conversationId) {
@@ -107,9 +150,12 @@ export class AgentState {
   }
 
   /**
-   * Clears the state from the turn context.
-   * @param context The turn context.
-   * @returns A promise that resolves when the clear operation is complete.
+   * Clears the state by setting it to an empty object in the turn context.
+   * Note: This does not remove the state from storage, it only clears the in-memory representation.
+   * Call saveChanges() after this to persist the empty state to storage.
+   *
+   * @param context The turn context containing the state to clear
+   * @returns A promise that resolves when the clear operation is complete
    */
   public async clear (context: TurnContext): Promise<void> {
     const emptyObjectToForceSave = { state: {}, hash: '' }
@@ -118,9 +164,11 @@ export class AgentState {
   }
 
   /**
-   * Deletes the state from storage.
-   * @param context The turn context.
-   * @returns A promise that resolves when the delete operation is complete.
+   * Deletes the state from both the turn context and storage.
+   *
+   * @param context The turn context containing the state to delete
+   * @param customKey Optional custom storage key to use instead of the default
+   * @returns A promise that resolves when the delete operation is complete
    */
   public async delete (context: TurnContext, customKey?: CustomKey): Promise<void> {
     if (context.turnState.has(this.stateKey)) {
@@ -132,9 +180,10 @@ export class AgentState {
   }
 
   /**
-   * Gets the state from the turn context.
-   * @param context The turn context.
-   * @returns The state, or undefined if the state is not found.
+   * Gets the state from the turn context without loading it from storage.
+   *
+   * @param context The turn context containing the state to get
+   * @returns The state object, or undefined if no state is found in the turn context
    */
   public get (context: TurnContext): any | undefined {
     const cached: CachedAgentState = context.turnState.get(this.stateKey)
@@ -143,9 +192,12 @@ export class AgentState {
   }
 
   /**
-   * Calculates the change hash for the specified item.
-   * @param item The item to calculate the hash for.
-   * @returns The calculated hash.
+   * Calculates a hash for the specified state object to detect changes.
+   * The eTag property is excluded from the hash calculation.
+   *
+   * @param item The state object to calculate the hash for
+   * @returns A string hash representing the state
+   * @private
    */
   private readonly calculateChangeHash = (item: StoreItem): string => {
     const { eTag, ...rest } = item

package/src/state/agentStatePropertyAccesor.ts

@@ -6,6 +6,15 @@
 import { TurnContext } from '../turnContext'
 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,
+ * 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.
@@ -64,20 +73,56 @@ export interface StatePropertyAccessor<T = any> {
 }
 
 /**
- * Provides access to an Agent state property.
+ * Provides typed access to an Agent state property with automatic state loading.
+ *
+ * The AgentStatePropertyAccessor simplifies working with state by abstracting
+ * the details of loading state from storage and manipulating specific properties.
+ * It automatically handles:
+ *
+ * - Loading state when needed
+ * - Deep cloning of default values to prevent reference issues
+ * - Type checking for properties (when using TypeScript)
+ * - Ensuring properties exist before access
+ *
+ * Property accessors are created through the AgentState.createProperty() method:
+ *
+ * ```typescript
+ * // Create a property accessor for a user profile
+ * const userProfile = userState.createProperty<UserProfile>("userProfile");
+ *
+ * // Get the profile with a default if not exists
+ * const profile = await userProfile.get(context, { name: "", preferences: {} });
+ *
+ * // Update a value
+ * profile.preferences.theme = "dark";
+ *
+ * // Save the change
+ * await userProfile.set(context, profile);
+ *
+ * // Later, call userState.saveChanges(context) to persist to storage
+ * ```
+ *
+ * @typeParam T The type of the property being accessed
  */
 export class AgentStatePropertyAccessor<T = any> implements StatePropertyAccessor<T> {
   /**
    * Creates a new instance of AgentStatePropertyAccessor.
-   * @param state The agent state.
-   * @param name The name of the property.
+   *
+   * @param state The agent state object that will contain this property
+   * @param name The name of the property in the state object
    */
   constructor (protected readonly state: AgentState, public readonly name: string) { }
 
   /**
    * Deletes the property from the state.
-   * @param context The turn context.
-   * @returns A promise that resolves when the delete operation is complete.
+   *
+   * This removes the property from the state object but does not automatically
+   * persist the change to storage. Call state.saveChanges() afterwards to
+   * persist changes.
+   *
+   * @param context The turn context
+   * @param customKey Optional custom key for storing the state in a specific location
+   * @returns A promise that resolves when the delete operation is complete
    */
   async delete (context: TurnContext, customKey?: CustomKey): Promise<void> {
     const obj: any = await this.state.load(context, false, customKey)
@@ -88,9 +133,15 @@ export class AgentStatePropertyAccessor<T = any> implements StatePropertyAccesso
 
   /**
    * Gets the value of the property from the state.
-   * @param context The turn context.
-   * @param defaultValue The default value to return if the property is not found.
-   * @returns A promise that resolves to the value of the property.
+   *
+   * If the property doesn't exist and a default value is provided, a deep clone
+   * of the default value will be stored in state and returned. This ensures that
+   * modifications to the returned object will be properly tracked.
+   *
+   * @param context The turn context
+   * @param defaultValue Optional default value to use if the property doesn't exist
+   * @param customKey Optional custom key for storing the state in a specific location
+   * @returns A promise that resolves to the value of the property or undefined
    */
   async get (context: TurnContext, defaultValue?: T, customKey?: CustomKey): Promise<T> {
     const obj: any = await this.state.load(context, false, customKey)
@@ -107,9 +158,14 @@ export class AgentStatePropertyAccessor<T = any> implements StatePropertyAccesso
 
   /**
    * Sets the value of the property in the state.
-   * @param context The turn context.
-   * @param value The value to set.
-   * @returns A promise that resolves when the set operation is complete.
+   *
+   * This updates the property in the in-memory state object but does not automatically
+   * persist the change to storage. Call state.saveChanges() afterwards to persist changes.
+   *
+   * @param context The turn context
+   * @param value The value to set
+   * @param customKey Optional custom key for storing the state in a specific location
+   * @returns A promise that resolves when the set operation is complete
    */
   async set (context: TurnContext, value: T, customKey?: CustomKey): Promise<void> {
     const obj: any = await this.state.load(context, false, customKey)

package/src/storage/memoryStorage.ts

@@ -9,20 +9,39 @@ import { debug } from '../logger'
 const logger = debug('agents:memory-storage')
 
 /**
- * A simple in-memory storage provider.
+ * A simple in-memory storage provider that implements the Storage interface.
+ *
+ * This class provides a volatile storage solution that keeps data in memory,
+ * which means data is lost when the process terminates. It's primarily useful for:
+ * - Development and testing scenarios
+ * - Simple applications that don't require data persistence across restarts
+ * - Stateless environments where external storage isn't available
+ *
+ * MemoryStorage supports optimistic concurrency control through eTags and
+ * can be used as a singleton through the getSingleInstance() method to
+ * share state across different parts of an application.
  */
 export class MemoryStorage implements Storage {
   private static instance: MemoryStorage
+  /**
+   * Counter used to generate unique eTags for stored items
+   */
   private etag: number = 1
 
   /**
    * Creates a new instance of the MemoryStorage class.
-   * @param memory An optional initial memory store.
+   *
+   * @param memory An optional initial memory store to seed the storage with data
    */
   constructor (private memory: { [k: string]: string } = {}) { }
 
   /**
-   * Gets a single instance of the MemoryStorage class.
+   * Gets a single shared instance of the MemoryStorage class.
+   *
+   * 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) {
@@ -33,9 +52,10 @@ export class MemoryStorage implements Storage {
 
   /**
    * Reads storage items from memory.
-   * @param keys The keys of the items to read.
-   * @returns A promise that resolves to the read items.
-   * @throws Will throw an error if keys are not provided.
+   *
+   * @param keys The keys of the items to read
+   * @returns A promise that resolves to the read items
+   * @throws Will throw an error if keys are not provided or the array is empty
    */
   async read (keys: string[]): Promise<StoreItem> {
     if (!keys || keys.length === 0) {
@@ -56,9 +76,15 @@ export class MemoryStorage implements Storage {
 
   /**
    * Writes storage items to memory.
-   * @param changes The items to write.
-   * @returns A promise that resolves when the write operation is complete.
-   * @throws Will throw an error if changes are not provided.
+   *
+   * 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) {
@@ -83,8 +109,9 @@ export class MemoryStorage implements Storage {
 
   /**
    * Deletes storage items from memory.
-   * @param keys The keys of the items to delete.
-   * @returns A promise that resolves when the delete operation is complete.
+   *
+   * @param keys The keys of the items to delete
+   * @returns A promise that resolves when the delete operation is complete
    */
   async delete (keys: string[]): Promise<void> {
     logger.info(`Deleting keys: ${keys.join(', ')}`)
@@ -94,9 +121,16 @@ export class MemoryStorage implements Storage {
   }
 
   /**
-   * Saves an item to memory.
-   * @param key The key of the item to save.
-   * @param item The item to save.
+   * Saves an item to memory with a new eTag.
+   *
+   * 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 {
     const clone = Object.assign({}, item, { eTag: (this.etag++).toString() })

package/src/storage/storage.ts

@@ -6,47 +6,80 @@
 import { TurnContext } from '../turnContext'
 
 /**
- * Represents an item to be stored.
+ * Represents an item to be stored in a storage provider.
+ * Each item can contain arbitrary data along with an optional eTag for optimistic concurrency control.
  */
 export interface StoreItem {
-  eTag?: string
-  [key: string]: any
+  /**
+   * Optional eTag used for optimistic concurrency control.
+   * 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.
+   * Each storage provider may have specific requirements or limitations on property names and values.
+   */
+  [key: string]: any;
 }
 
 /**
- * Represents a collection of store items.
+ * Represents a collection of store items indexed by key.
+ * Used as the return type for storage read operations.
  */
 export interface StoreItems {
+  /**
+   * Keys are the storage item identifiers, and values are the stored items.
+   * 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 context.
- * @param context The TurnContext for the current turn of conversation.
- * @returns A string key for storage.
+ * 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
  */
-export type StorageKeyFactory = (context: TurnContext) => string
+export type StorageKeyFactory = (context: TurnContext) => string | Promise<string>
 
 /**
- * Defines the interface for storage operations.
+ * Defines the interface for storage operations in the Agents platform.
+ *
+ * Storage providers persist state data across conversation turns, enabling
+ * agents to maintain context over time. Different implementations may store
+ * data in memory, databases, blob storage, or other persistence mechanisms.
+ *
+ * The interface is designed to be simple with just three core operations:
+ * read, write, and delete. All operations are asynchronous to support both
+ * in-memory and remote storage providers.
  */
 export interface Storage {
   /**
    * Reads store items from storage.
-   * @param keys The keys of the items to read.
-   * @returns A promise that resolves to the store items.
+   *
+   * @param keys The keys of the items to read
+   * @returns A promise that resolves to the store items. Items that don't exist in storage will not be included in the result.
+   * @throws If the keys array is empty or undefined
    */
-  read: (keys: string[]) => Promise<StoreItem>
+  read: (keys: string[]) => Promise<StoreItem>;
+
   /**
    * Writes store items to storage.
-   * @param changes The items to write to storage.
-   * @returns A promise that resolves when the write operation is complete.
+   *
+   * @param changes The items to write to storage, indexed by key
+   * @returns A promise that resolves when the write operation is complete
+   * @throws If the changes object is empty or undefined, or if an eTag conflict occurs and optimistic concurrency is enabled
    */
-  write: (changes: StoreItem) => Promise<void>
+  write: (changes: StoreItem) => Promise<void>;
+
   /**
    * Deletes store items from storage.
-   * @param keys The keys of the items to delete.
-   * @returns A promise that resolves when the delete operation is complete.
+   *
+   * @param keys The keys of the items to delete
+   * @returns A promise that resolves when the delete operation is complete
    */
-  delete: (keys: string[]) => Promise<void>
+  delete: (keys: string[]) => Promise<void>;
 }