@microsoft/agents-hosting 0.2.10-g3ac88ff25e → 0.3.5

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 {@link 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/statusCodes.ts

@@ -4,17 +4,68 @@
  */
 
 export enum StatusCodes {
+  /**
+   * The request has succeeded.
+   */
   OK = 200,
+
+  /**
+   * The request has been fulfilled and resulted in a new resource being created.
+   */
   CREATED = 201,
+
+  /**
+   * Indicates multiple options for the resource that the client may follow.
+   */
   MULTIPLE_CHOICES = 300,
+
+  /**
+   * The server cannot or will not process the request due to a client error.
+   */
   BAD_REQUEST = 400,
+
+  /**
+   * The request requires user authentication.
+   */
   UNAUTHORIZED = 401,
+
+  /**
+   * The requested resource could not be found.
+   */
   NOT_FOUND = 404,
+
+  /**
+   * The request method is not allowed for the requested resource.
+   */
   METHOD_NOT_ALLOWED = 405,
+
+  /**
+   * The request could not be completed due to a conflict with the current state of the resource.
+   */
   CONFLICT = 409,
+
+  /**
+   * The server does not meet one of the preconditions specified by the client.
+   */
   PRECONDITION_FAILED = 412,
+
+  /**
+   * The client should switch to a different protocol.
+   */
   UPGRADE_REQUIRED = 426,
+
+  /**
+   * The server encountered an unexpected condition that prevented it from fulfilling the request.
+   */
   INTERNAL_SERVER_ERROR = 500,
+
+  /**
+   * The server does not support the functionality required to fulfill the request.
+   */
   NOT_IMPLEMENTED = 501,
+
+  /**
+   * The server received an invalid response from the upstream server.
+   */
   BAD_GATEWAY = 502,
 }

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

package/src/tokenResponseEventName.ts

@@ -3,4 +3,7 @@
  * Licensed under the MIT License.
  */
 
+/**
+ * The event name used for token response activities.
+ */
 export const tokenResponseEventName = 'tokens/response'